lib/silcutil/silcregex.h

   1 /*
   2
   3   regexpr.h
   4
   5   Author: Tatu Ylonen <ylo@ngs.fi>
   6
   7   Copyright (c) 1991 Tatu Ylonen, Espoo, Finland
   8
   9   Permission to use, copy, modify, distribute, and sell this software
  10   and its documentation is hereby granted without fee, provided that the
  11   above copyright notice appears in all source code copies, the name of
  12   Tatu Ylonen is not used to advertise products containing this software
  13   or a derivation thereof, and all modified versions are clearly marked
  14   as such.
  15
  16   This software is provided "as is" without express or implied warranty.
  17
  18   Created: Thu Sep 26 17:15:36 1991 ylo
  19   Last modified: Fri Jan  3 12:05:45 1992 ylo
  20
  21   The SILC Regex API by Pekka Riikonen, under the same license as the original
  22   code.
  23
  24 */
  25
  26 /****h* silcutil/SILC Regular Expression Interface
  27  *
  28  * DESCRIPTION
  29  *
  30  * SILC regular expression interface provides Unix and POSIX compliant
  31  * regular expression compilation and matching.
  32  *
  33  * EXAMPLE
  34  *
  35  * SilcRegexStruct reg;
  36  *
  37  * // Compile regular expression
  38  * if (!silc_regex_compile(&reg, "foo[0-9]*", 0))
  39  *   error;
  40  *
  41  * // Match string against the compiled regex
  42  * if (!silc_regex_match(&reg, "foo20", 0, NULL, 0))
  43  *   no_match;
  44  *
  45  * // Free the compiled regular expression
  46  * silc_regex_free(&reg);
  47  *
  48  ***/
  49
  50 #ifndef SILCREGEX_H
  51 #define SILCREGEX_H
  52
  53 /****s* silcutil/SilcRegexAPI/SilcRegex
  54  *
  55  * NAME
  56  *
  57  *    typedef struct { ... } *SilcRegex, SilcRegexStruct;
  58  *
  59  * DESCRIPTION
  60  *
  61  *    The regular expression context.  This context is given as argument
  62  *    to all silc_regex_* functions.  It is usually statically allocated
  63  *    but can be dynamically allocated by silc_malloc.
  64  *
  65  ***/
  66 typedef struct SilcRegexObject {
  67   char *buffer;                /* compiled pattern */
  68   int allocated;               /* allocated size of compiled pattern */
  69   int used;                    /* actual length of compiled pattern */
  70   char *fastmap;               /* fastmap[ch] is true if ch can start pattern */
  71   char *translate;             /* translation to apply during comp/match */
  72   char fastmap_accurate;       /* true if fastmap is valid */
  73   char can_be_null;            /* true if can match empty string */
  74   char uses_registers;         /* registers used and need to be initialized */
  75   char anchor;                 /* anchor: 0=none 1=begline 2=begbuf */
  76 } *SilcRegex, SilcRegexStruct;
  77
  78 /****s* silcutil/SilcRegexAPI/SilcRegexMatch
  79  *
  80  * NAME
  81  *
  82  *    typedef struct { ... } *SilcRegexMatch, SilcRegexMatchStruct;
  83  *
  84  * DESCRIPTION
  85  *
  86  *    The regular expression match context that provides information on the
  87  *    found match.  It provides the start offset and end offset of the
  88  *    found match.
  89  *
  90  * SOURCE
  91  */
  92 typedef struct SilcRegexMatchObject {
  93   int start;                   /* Start offset of region */
  94   int end;                     /* End offset of region */
  95 } *SilcRegexMatch, SilcRegexMatchStruct;
  96 /***/
  97
  98 /****d* silcutil/SilcRegexAPI/SilcRegexFlags
  99  *
 100  * NAME
 101  *
 102  *    typedef enum { ... } SilcRegexFlags;
 103  *
 104  * DESCRIPTION
 105  *
 106  *    Regular expression feature flags.
 107  *
 108  * SOURCE
 109  */
 110 typedef enum {
 111   SILC_REGEX_FLAG_DEFAULT            = 0,
 112 } SilcRegexFlags;
 113 /***/
 114
 115 /****f* silcutil/SilcRegexAPI/silc_regex_compile
 116  *
 117  * SYNOPSIS
 118  *
 119  *    SilcBool silc_regex_compile(SilcRegex regexp, const char *regex,
 120  *                                SilcRegexFlags flags);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    Compiles the regular expression string `regex'.  The `regexp' is a
 125  *    pre-allocated regular expression context.  The `flags' define
 126  *    various feature flags.  This function must be called before the
 127  *    silc_regex_match can be used to find matches.
 128  *
 129  *    Returns TRUE after the compilation is completed.  Returns FALSE on
 130  *    error and sets silc_errno.
 131  *
 132  ***/
 133 SilcBool silc_regex_compile(SilcRegex regexp, const char *regex,
 134                             SilcRegexFlags flags);
 135
 136 /****f* silcutil/SilcRegexAPI/silc_regex_compile
 137  *
 138  * SYNOPSIS
 139  *
 140  *    SilcBool silc_regex_match(SilcRegex regexp, const char *string,
 141  *                              SilcUInt32 num_match, SilcRegexMatch match,
 142  *                              SilcRegexFlags flags);
 143  *
 144  * DESCRIPTION
 145  *
 146  *    Finds one or more matches from the `string' using the pre-compiled
 147  *    regular expression `regexp'.  It must be compiled by calling the
 148  *    silc_regex_compile before calling this function.  The `flags' defines
 149  *    various feature flags.
 150  *
 151  *    If only one match is needed the `num_match' may be set to 0 and the
 152  *    `match' is set to NULL.  If multiple matches (substrings) are needed the
 153  *    `num_match' defines the size of the `match' array, where each of the
 154  *    matches (with parenthesized regular expression) will be stored.  The
 155  *    `match' provides information on where the match was found in `string',
 156  *    providing the start offset and end offset of the match.  Unused entires
 157  *    in the array will have -1 as the offset values.
 158  *
 159  *    Returns TRUE if the string matched the regular expression or FALSE
 160  *    if it did not match or error occurred.  The silc_errno will indicate
 161  *    the error.  The silc_errno is set to SILC_ERR_NOT_FOUND if the regular
 162  *    expression did not match.
 163  *
 164  * EXAMPLE
 165  *
 166  *    // Find first match (check if string matches)
 167  *    if (!silc_regex_match(&reg, "foo20", 0, NULL, 0))
 168  *      no_match;
 169  *
 170  *    // Find multiple matches, one by one
 171  *    SilcRegexMatchStruct match;
 172  *
 173  *    while (silc_regex_match(&reg, string, 1, &match, 0)) {
 174  *      match_string = silc_memdup(string + match.start,
 175  *                                 match.end - match.start);
 176  *      string += match.end;
 177  *    }
 178  *
 179  *    // Parse URI into its components, available in the match[] array
 180  *    SilcRegexStruct reg;
 181  *    SilcRegexMatchStruct match[7];
 182  *
 183  *    silc_regex_compile(&reg, "^(([^:]+)://)?([^:/]+)(:([0-9]+))?(/.*)", 0);
 184  *    silc_regex_match(&reg, "http://example.com/page.html", 7, match, 0);
 185  *
 186  ***/
 187 SilcBool silc_regex_match(SilcRegex regexp, const char *string,
 188                           SilcUInt32 num_match, SilcRegexMatch match,
 189                           SilcRegexFlags flags);
 190
 191 /****f* silcutil/SilcRegexAPI/silc_regex_free
 192  *
 193  * SYNOPSIS
 194  *
 195  *    void silc_regex_free(SilcRegex regexp);
 196  *
 197  * DESCRIPTION
 198  *
 199  *    Free's the compiled regular expression context `regexp'.  This must
 200  *    be called even if `regexp' is statically allocated.  If the
 201  *    silc_regex_compile has been called this function must be called.
 202  *
 203  ***/
 204 void silc_regex_free(SilcRegex regexp);
 205
 206 #endif /* SILCREGEX_H */