contrib/bind-9.3/lib/isc/include/isc/lex.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1998-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: lex.h,v 1.26.2.2.8.3 2004/03/08 09:04:51 marka Exp $ */
  19
  20 #ifndef ISC_LEX_H
  21 #define ISC_LEX_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * Lex
  29  *
  30  * The "lex" module provides a lightweight tokenizer.  It can operate
  31  * on files or buffers, and can handle "include".  It is designed for
  32  * parsing of DNS master files and the BIND configuration file, but
  33  * should be general enough to tokenize other things, e.g. HTTP.
  34  *
  35  * MP:
  36  *      No synchronization is provided.  Clients must ensure exclusive
  37  *      access.
  38  *
  39  * Reliability:
  40  *      No anticipated impact.
  41  *
  42  * Resources:
  43  *      <TBS>
  44  *
  45  * Security:
  46  *      No anticipated impact.
  47  *
  48  * Standards:
  49  *      None.
  50  */
  51
  52 /***
  53  *** Imports
  54  ***/
  55
  56 #include <stdio.h>
  57
  58 #include <isc/lang.h>
  59 #include <isc/region.h>
  60 #include <isc/types.h>
  61
  62 ISC_LANG_BEGINDECLS
  63
  64 /***
  65  *** Options
  66  ***/
  67
  68 /*
  69  * Various options for isc_lex_gettoken().
  70  */
  71
  72 #define ISC_LEXOPT_EOL                  0x01    /* Want end-of-line token. */
  73 #define ISC_LEXOPT_EOF                  0x02    /* Want end-of-file token. */
  74 #define ISC_LEXOPT_INITIALWS            0x04    /* Want initial whitespace. */
  75 #define ISC_LEXOPT_NUMBER               0x08    /* Recognize numbers. */
  76 #define ISC_LEXOPT_QSTRING              0x10    /* Recognize qstrings. */
  77
  78 /*
  79  * The ISC_LEXOPT_DNSMULTILINE option handles the processing of '(' and ')' in
  80  * the DNS master file format.  If this option is set, then the
  81  * ISC_LEXOPT_INITIALWS and ISC_LEXOPT_EOL options will be ignored when
  82  * the paren count is > 0.  To use this option, '(' and ')' must be special
  83  * characters.
  84  */
  85 #define ISC_LEXOPT_DNSMULTILINE         0x20    /* Handle '(' and ')'. */
  86 #define ISC_LEXOPT_NOMORE               0x40    /* Want "no more" token. */
  87
  88 #define ISC_LEXOPT_CNUMBER              0x80    /* Regognise octal and hex */
  89 #define ISC_LEXOPT_ESCAPE               0x100   /* Recognize escapes. */
  90 #define ISC_LEXOPT_QSTRINGMULTILINE     0x200   /* Allow multiline "" strings */
  91
  92 /*
  93  * Various commenting styles, which may be changed at any time with
  94  * isc_lex_setcomments().
  95  */
  96
  97 #define ISC_LEXCOMMENT_C                0x01
  98 #define ISC_LEXCOMMENT_CPLUSPLUS        0x02
  99 #define ISC_LEXCOMMENT_SHELL            0x04
 100 #define ISC_LEXCOMMENT_DNSMASTERFILE    0x08
 101
 102 /***
 103  *** Types
 104  ***/
 105
 106 /* Lex */
 107
 108 typedef char isc_lexspecials_t[256];
 109
 110 /* Tokens */
 111
 112 typedef enum {
 113         isc_tokentype_unknown = 0,
 114         isc_tokentype_string = 1,
 115         isc_tokentype_number = 2,
 116         isc_tokentype_qstring = 3,
 117         isc_tokentype_eol = 4,
 118         isc_tokentype_eof = 5,
 119         isc_tokentype_initialws = 6,
 120         isc_tokentype_special = 7,
 121         isc_tokentype_nomore = 8
 122 } isc_tokentype_t;
 123
 124 typedef union {
 125         char                            as_char;
 126         unsigned long                   as_ulong;
 127         isc_region_t                    as_region;
 128         isc_textregion_t                as_textregion;
 129         void *                          as_pointer;
 130 } isc_tokenvalue_t;
 131
 132 typedef struct isc_token {
 133         isc_tokentype_t                 type;
 134         isc_tokenvalue_t                value;
 135 } isc_token_t;
 136
 137 /***
 138  *** Functions
 139  ***/
 140
 141 isc_result_t
 142 isc_lex_create(isc_mem_t *mctx, size_t max_token, isc_lex_t **lexp);
 143 /*
 144  * Create a lexer.
 145  *
 146  * 'max_token' is a hint of the number of bytes in the largest token.
 147  *
 148  * Requires:
 149  *      '*lexp' is a valid lexer.
 150  *
 151  *      max_token > 0.
 152  *
 153  * Ensures:
 154  *      On success, *lexp is attached to the newly created lexer.
 155  *
 156  * Returns:
 157  *      ISC_R_SUCCESS
 158  *      ISC_R_NOMEMORY
 159  */
 160
 161 void
 162 isc_lex_destroy(isc_lex_t **lexp);
 163 /*
 164  * Destroy the lexer.
 165  *
 166  * Requires:
 167  *      '*lexp' is a valid lexer.
 168  *
 169  * Ensures:
 170  *      *lexp == NULL
 171  */
 172
 173 unsigned int
 174 isc_lex_getcomments(isc_lex_t *lex);
 175 /*
 176  * Return the current lexer commenting styles.
 177  *
 178  * Requires:
 179  *      'lex' is a valid lexer.
 180  *
 181  * Returns:
 182  *      The commenting sytles which are currently allowed.
 183  */
 184
 185 void
 186 isc_lex_setcomments(isc_lex_t *lex, unsigned int comments);
 187 /*
 188  * Set allowed lexer commenting styles.
 189  *
 190  * Requires:
 191  *      'lex' is a valid lexer.
 192  *
 193  *      'comments' has meaningful values.
 194  */
 195
 196 void
 197 isc_lex_getspecials(isc_lex_t *lex, isc_lexspecials_t specials);
 198 /*
 199  * Put the current list of specials into 'specials'.
 200  *
 201  * Requires:
 202  *      'lex' is a valid lexer.
 203  */
 204
 205 void
 206 isc_lex_setspecials(isc_lex_t *lex, isc_lexspecials_t specials);
 207 /*
 208  * The characters in 'specials' are returned as tokens.  Along with
 209  * whitespace, they delimit strings and numbers.
 210  *
 211  * Note:
 212  *      Comment processing takes precedence over special character
 213  *      recognition.
 214  *
 215  * Requires:
 216  *      'lex' is a valid lexer.
 217  */
 218
 219 isc_result_t
 220 isc_lex_openfile(isc_lex_t *lex, const char *filename);
 221 /*
 222  * Open 'filename' and make it the current input source for 'lex'.
 223  *
 224  * Requires:
 225  *      'lex' is a valid lexer.
 226  *
 227  *      filename is a valid C string.
 228  *
 229  * Returns:
 230  *      ISC_R_SUCCESS
 231  *      ISC_R_NOMEMORY                  Out of memory
 232  *      ISC_R_NOTFOUND                  File not found
 233  *      ISC_R_NOPERM                    No permission to open file
 234  *      ISC_R_FAILURE                   Couldn't open file, not sure why
 235  *      ISC_R_UNEXPECTED
 236  */
 237
 238 isc_result_t
 239 isc_lex_openstream(isc_lex_t *lex, FILE *stream);
 240 /*
 241  * Make 'stream' the current input source for 'lex'.
 242  *
 243  * Requires:
 244  *      'lex' is a valid lexer.
 245  *
 246  *      'stream' is a valid C stream.
 247  *
 248  * Returns:
 249  *      ISC_R_SUCCESS
 250  *      ISC_R_NOMEMORY                  Out of memory
 251  */
 252
 253 isc_result_t
 254 isc_lex_openbuffer(isc_lex_t *lex, isc_buffer_t *buffer);
 255 /*
 256  * Make 'buffer' the current input source for 'lex'.
 257  *
 258  * Requires:
 259  *      'lex' is a valid lexer.
 260  *
 261  *      'buffer' is a valid buffer.
 262  *
 263  * Returns:
 264  *      ISC_R_SUCCESS
 265  *      ISC_R_NOMEMORY                  Out of memory
 266  */
 267
 268 isc_result_t
 269 isc_lex_close(isc_lex_t *lex);
 270 /*
 271  * Close the most recently opened object (i.e. file or buffer).
 272  *
 273  * Returns:
 274  *      ISC_R_SUCCESS
 275  *      ISC_R_NOMORE                    No more input sources
 276  */
 277
 278 isc_result_t
 279 isc_lex_gettoken(isc_lex_t *lex, unsigned int options, isc_token_t *tokenp);
 280 /*
 281  * Get the next token.
 282  *
 283  * Requires:
 284  *      'lex' is a valid lexer.
 285  *
 286  *      'lex' has an input source.
 287  *
 288  *      'options' contains valid options.
 289  *
 290  *      '*tokenp' is a valid pointer.
 291  *
 292  * Returns:
 293  *      ISC_R_SUCCESS
 294  *      ISC_R_UNEXPECTEDEND
 295  *      ISC_R_NOMEMORY
 296  *
 297  *      These two results are returned only if their corresponding lexer
 298  *      options are not set.
 299  *
 300  *      ISC_R_EOF                       End of input source
 301  *      ISC_R_NOMORE                    No more input sources
 302  */
 303
 304 isc_result_t
 305 isc_lex_getmastertoken(isc_lex_t *lex, isc_token_t *token,
 306                        isc_tokentype_t expect, isc_boolean_t eol);
 307 /*
 308  * Get the next token from a DNS master file type stream.  This is a
 309  * convenience function that sets appropriate options and handles quoted
 310  * strings and end of line correctly for master files.  It also ungets
 311  * unexpected tokens.
 312  *
 313  * Requires:
 314  *      'lex' is a valid lexer.
 315  *
 316  *      'token' is a valid pointer
 317  *
 318  * Returns:
 319  *
 320  *      any return code from isc_lex_gettoken.
 321  */
 322
 323 void
 324 isc_lex_ungettoken(isc_lex_t *lex, isc_token_t *tokenp);
 325 /*
 326  * Unget the current token.
 327  *
 328  * Requires:
 329  *      'lex' is a valid lexer.
 330  *
 331  *      'lex' has an input source.
 332  *
 333  *      'tokenp' points to a valid token.
 334  *
 335  *      There is no ungotten token already.
 336  */
 337
 338 void
 339 isc_lex_getlasttokentext(isc_lex_t *lex, isc_token_t *tokenp, isc_region_t *r);
 340 /*
 341  * Returns a region containing the text of the last token returned.
 342  *
 343  * Requires:
 344  *      'lex' is a valid lexer.
 345  *
 346  *      'lex' has an input source.
 347  *
 348  *      'tokenp' points to a valid token.
 349  *
 350  *      A token has been gotten and not ungotten.
 351  */
 352
 353 char *
 354 isc_lex_getsourcename(isc_lex_t *lex);
 355 /*
 356  * Return the input source name.
 357  *
 358  * Requires:
 359  *      'lex' is a valid lexer.
 360  *
 361  * Returns:
 362  *      source name or NULL if no current source.
 363  *      result valid while current input source exists.
 364  */
 365
 366
 367 unsigned long
 368 isc_lex_getsourceline(isc_lex_t *lex);
 369 /*
 370  * Return the input source line number.
 371  *
 372  * Requires:
 373  *      'lex' is a valid lexer.
 374  *
 375  * Returns:
 376  *      Current line number or 0 if no current source.
 377  */
 378
 379 isc_result_t
 380 isc_lex_setsourcename(isc_lex_t *lex, const char *name);
 381 /*
 382  * Assigns a new name to the input source.
 383  *
 384  * Requires:
 385  *
 386  *      'lex' is a valid lexer.
 387  *
 388  * Returns:
 389  *      ISC_R_SUCCESS
 390  *      ISC_R_NOMEMORY
 391  *      ISC_R_NOTFOUND - there are no sources.
 392  */
 393
 394 isc_boolean_t
 395 isc_lex_isfile(isc_lex_t *lex);
 396 /*
 397  * Return whether the current input source is a file.
 398  *
 399  * Requires:
 400  *      'lex' is a valid lexer.
 401  *
 402  * Returns:
 403  *      ISC_TRUE if the current input is a file,
 404  *      ISC_FALSE otherwise.
 405  */
 406
 407
 408 ISC_LANG_ENDDECLS
 409
 410 #endif /* ISC_LEX_H */