lib/silcutil/silcregex.h

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