/* * Copyright (C) Internet Systems Consortium, Inc. ("ISC") * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, you can obtain one at https://mozilla.org/MPL/2.0/. * * See the COPYRIGHT file distributed with this work for additional * information regarding copyright ownership. */ #ifndef ISC_LEX_H #define ISC_LEX_H 1 /***** ***** Module Info *****/ /*! \file isc/lex.h * \brief The "lex" module provides a lightweight tokenizer. It can operate * on files or buffers, and can handle "include". It is designed for * parsing of DNS master files and the BIND configuration file, but * should be general enough to tokenize other things, e.g. HTTP. * * \li MP: * No synchronization is provided. Clients must ensure exclusive * access. * * \li Reliability: * No anticipated impact. * * \li Resources: * TBS * * \li Security: * No anticipated impact. * * \li Standards: * None. */ /*** *** Imports ***/ #include <stdbool.h> #include <stdio.h> #include <isc/lang.h> #include <isc/region.h> #include <isc/types.h> ISC_LANG_BEGINDECLS /*** *** Options ***/ /*@{*/ /*! * Various options for isc_lex_gettoken(). */ #define ISC_LEXOPT_EOL 0x0001 /*%< Want end-of-line token. */ #define ISC_LEXOPT_EOF 0x0002 /*%< Want end-of-file token. */ #define ISC_LEXOPT_INITIALWS 0x0004 /*%< Want initial whitespace. */ #define ISC_LEXOPT_NUMBER 0x0008 /*%< Recognize numbers. */ #define ISC_LEXOPT_QSTRING 0x0010 /*%< Recognize qstrings. */ /*@}*/ /*@{*/ /*! * The ISC_LEXOPT_DNSMULTILINE option handles the processing of '(' and ')' in * the DNS master file format. If this option is set, then the * ISC_LEXOPT_INITIALWS and ISC_LEXOPT_EOL options will be ignored when * the paren count is > 0. To use this option, '(' and ')' must be special * characters. */ #define ISC_LEXOPT_DNSMULTILINE 0x0020 /*%< Handle '(' and ')'. */ #define ISC_LEXOPT_NOMORE 0x0040 /*%< Want "no more" token. */ #define ISC_LEXOPT_CNUMBER 0x0080 /*%< Recognize octal and hex. */ #define ISC_LEXOPT_ESCAPE 0x0100 /*%< Recognize escapes. */ #define ISC_LEXOPT_QSTRINGMULTILINE 0x0200 /*%< Allow multiline "" strings */ #define ISC_LEXOPT_OCTAL 0x0400 /*%< Expect a octal number. */ #define ISC_LEXOPT_BTEXT 0x0800 /*%< Bracketed text. */ #define ISC_LEXOPT_VPAIR 0x1000 /*%< Recognize value pair. */ #define ISC_LEXOPT_QVPAIR 0x2000 /*%< Recognize quoted value pair. */ /*@}*/ /*@{*/ /*! * Various commenting styles, which may be changed at any time with * isc_lex_setcomments(). */ #define ISC_LEXCOMMENT_C 0x01 #define ISC_LEXCOMMENT_CPLUSPLUS 0x02 #define ISC_LEXCOMMENT_SHELL 0x04 #define ISC_LEXCOMMENT_DNSMASTERFILE 0x08 /*@}*/ /*** *** Types ***/ /*! Lex */ typedef char isc_lexspecials_t[256]; /* Tokens */ typedef enum { isc_tokentype_unknown = 0, isc_tokentype_string = 1, isc_tokentype_number = 2, isc_tokentype_qstring = 3, isc_tokentype_eol = 4, isc_tokentype_eof = 5, isc_tokentype_initialws = 6, isc_tokentype_special = 7, isc_tokentype_nomore = 8, isc_tokentype_btext = 9, isc_tokentype_vpair = 10, isc_tokentype_qvpair = 11, } isc_tokentype_t; typedef union { char as_char; unsigned long as_ulong; isc_region_t as_region; isc_textregion_t as_textregion; void *as_pointer; } isc_tokenvalue_t; typedef struct isc_token { isc_tokentype_t type; isc_tokenvalue_t value; } isc_token_t; /*** *** Functions ***/ isc_result_t isc_lex_create(isc_mem_t *mctx, size_t max_token, isc_lex_t **lexp); /*%< * Create a lexer. * * 'max_token' is a hint of the number of bytes in the largest token. * * Requires: *\li '*lexp' is a valid lexer. * * Ensures: *\li On success, *lexp is attached to the newly created lexer. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMEMORY */ void isc_lex_destroy(isc_lex_t **lexp); /*%< * Destroy the lexer. * * Requires: *\li '*lexp' is a valid lexer. * * Ensures: *\li *lexp == NULL */ unsigned int isc_lex_getcomments(isc_lex_t *lex); /*%< * Return the current lexer commenting styles. * * Requires: *\li 'lex' is a valid lexer. * * Returns: *\li The commenting styles which are currently allowed. */ void isc_lex_setcomments(isc_lex_t *lex, unsigned int comments); /*%< * Set allowed lexer commenting styles. * * Requires: *\li 'lex' is a valid lexer. * *\li 'comments' has meaningful values. */ void isc_lex_getspecials(isc_lex_t *lex, isc_lexspecials_t specials); /*%< * Put the current list of specials into 'specials'. * * Requires: *\li 'lex' is a valid lexer. */ void isc_lex_setspecials(isc_lex_t *lex, isc_lexspecials_t specials); /*!< * The characters in 'specials' are returned as tokens. Along with * whitespace, they delimit strings and numbers. * * Note: *\li Comment processing takes precedence over special character * recognition. * * Requires: *\li 'lex' is a valid lexer. */ isc_result_t isc_lex_openfile(isc_lex_t *lex, const char *filename); /*%< * Open 'filename' and make it the current input source for 'lex'. * * Requires: *\li 'lex' is a valid lexer. * *\li filename is a valid C string. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMEMORY Out of memory *\li #ISC_R_NOTFOUND File not found *\li #ISC_R_NOPERM No permission to open file *\li #ISC_R_FAILURE Couldn't open file, not sure why *\li #ISC_R_UNEXPECTED */ isc_result_t isc_lex_openstream(isc_lex_t *lex, FILE *stream); /*%< * Make 'stream' the current input source for 'lex'. * * Requires: *\li 'lex' is a valid lexer. * *\li 'stream' is a valid C stream. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMEMORY Out of memory */ isc_result_t isc_lex_openbuffer(isc_lex_t *lex, isc_buffer_t *buffer); /*%< * Make 'buffer' the current input source for 'lex'. * * Requires: *\li 'lex' is a valid lexer. * *\li 'buffer' is a valid buffer. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMEMORY Out of memory */ isc_result_t isc_lex_close(isc_lex_t *lex); /*%< * Close the most recently opened object (i.e. file or buffer). * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMORE No more input sources */ isc_result_t isc_lex_gettoken(isc_lex_t *lex, unsigned int options, isc_token_t *tokenp); /*%< * Get the next token. * * Requires: *\li 'lex' is a valid lexer. * *\li 'lex' has an input source. * *\li 'options' contains valid options. * *\li '*tokenp' is a valid pointer. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_UNEXPECTEDEND *\li #ISC_R_NOMEMORY * * These two results are returned only if their corresponding lexer * options are not set. * *\li #ISC_R_EOF End of input source *\li #ISC_R_NOMORE No more input sources */ isc_result_t isc_lex_getmastertoken(isc_lex_t *lex, isc_token_t *token, isc_tokentype_t expect, bool eol); /*%< * Get the next token from a DNS master file type stream. This is a * convenience function that sets appropriate options and handles quoted * strings and end of line correctly for master files. It also ungets * unexpected tokens. If `eol` is set then expect end-of-line otherwise * eol is a error. * * Requires: *\li 'lex' is a valid lexer. * *\li 'token' is a valid pointer * * Returns: * * \li any return code from isc_lex_gettoken(). */ isc_result_t isc_lex_getoctaltoken(isc_lex_t *lex, isc_token_t *token, bool eol); /*%< * Get the next token from a DNS master file type stream. This is a * convenience function that sets appropriate options and handles end * of line correctly for master files. It also ungets unexpected tokens. * If `eol` is set then expect end-of-line otherwise eol is a error. * * Requires: *\li 'lex' is a valid lexer. * *\li 'token' is a valid pointer * * Returns: * * \li any return code from isc_lex_gettoken(). */ void isc_lex_ungettoken(isc_lex_t *lex, isc_token_t *tokenp); /*%< * Unget the current token. * * Requires: *\li 'lex' is a valid lexer. * *\li 'lex' has an input source. * *\li 'tokenp' points to a valid token. * *\li There is no ungotten token already. */ void isc_lex_getlasttokentext(isc_lex_t *lex, isc_token_t *tokenp, isc_region_t *r); /*%< * Returns a region containing the text of the last token returned. * * Requires: *\li 'lex' is a valid lexer. * *\li 'lex' has an input source. * *\li 'tokenp' points to a valid token. * *\li A token has been gotten and not ungotten. */ char * isc_lex_getsourcename(isc_lex_t *lex); /*%< * Return the input source name. * * Requires: *\li 'lex' is a valid lexer. * * Returns: * \li source name or NULL if no current source. *\li result valid while current input source exists. */ unsigned long isc_lex_getsourceline(isc_lex_t *lex); /*%< * Return the input source line number. * * Requires: *\li 'lex' is a valid lexer. * * Returns: *\li Current line number or 0 if no current source. */ isc_result_t isc_lex_setsourcename(isc_lex_t *lex, const char *name); /*%< * Assigns a new name to the input source. * * Requires: * * \li 'lex' is a valid lexer. * * Returns: * \li #ISC_R_SUCCESS * \li #ISC_R_NOMEMORY * \li #ISC_R_NOTFOUND - there are no sources. */ isc_result_t isc_lex_setsourceline(isc_lex_t *lex, unsigned long line); /*%< * Assigns a new line number to the input source. This can be used * when parsing a buffer that's been excerpted from the middle a file, * allowing logged messages to display the correct line number, * rather than the line number within the buffer. * * Requires: * * \li 'lex' is a valid lexer. * * Returns: * \li #ISC_R_SUCCESS * \li #ISC_R_NOTFOUND - there are no sources. */ bool isc_lex_isfile(isc_lex_t *lex); /*%< * Return whether the current input source is a file. * * Requires: *\li 'lex' is a valid lexer. * * Returns: * \li #true if the current input is a file, *\li #false otherwise. */ ISC_LANG_ENDDECLS #endif /* ISC_LEX_H */