/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef ISC_LEX_H

[12] Fix | Delete

#define ISC_LEX_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file isc/lex.h

[19] Fix | Delete

* \brief The "lex" module provides a lightweight tokenizer. It can operate

[20] Fix | Delete

* on files or buffers, and can handle "include". It is designed for

[21] Fix | Delete

* parsing of DNS master files and the BIND configuration file, but

[22] Fix | Delete

* should be general enough to tokenize other things, e.g. HTTP.

[23] Fix | Delete

*

[24] Fix | Delete

* \li MP:

[25] Fix | Delete

* No synchronization is provided. Clients must ensure exclusive

[26] Fix | Delete

* access.

[27] Fix | Delete

*

[28] Fix | Delete

* \li Reliability:

[29] Fix | Delete

* No anticipated impact.

[30] Fix | Delete

*

[31] Fix | Delete

* \li Resources:

[32] Fix | Delete

* TBS

[33] Fix | Delete

*

[34] Fix | Delete

* \li Security:

[35] Fix | Delete

* No anticipated impact.

[36] Fix | Delete

*

[37] Fix | Delete

* \li Standards:

[38] Fix | Delete

* None.

[39] Fix | Delete

*/

[40] Fix | Delete

[41] Fix | Delete

/***

[42] Fix | Delete

*** Imports

[43] Fix | Delete

***/

[44] Fix | Delete

[45] Fix | Delete

#include <stdbool.h>

[46] Fix | Delete

#include <stdio.h>

[47] Fix | Delete

[48] Fix | Delete

#include <isc/lang.h>

[49] Fix | Delete

#include <isc/region.h>

[50] Fix | Delete

#include <isc/types.h>

[51] Fix | Delete

[52] Fix | Delete

ISC_LANG_BEGINDECLS

[53] Fix | Delete

[54] Fix | Delete

/***

[55] Fix | Delete

*** Options

[56] Fix | Delete

***/

[57] Fix | Delete

[58] Fix | Delete

/*@{*/

[59] Fix | Delete

/*!

[60] Fix | Delete

* Various options for isc_lex_gettoken().

[61] Fix | Delete

*/

[62] Fix | Delete

[63] Fix | Delete

#define ISC_LEXOPT_EOL 0x01 /*%< Want end-of-line token. */

[64] Fix | Delete

#define ISC_LEXOPT_EOF 0x02 /*%< Want end-of-file token. */

[65] Fix | Delete

#define ISC_LEXOPT_INITIALWS 0x04 /*%< Want initial whitespace. */

[66] Fix | Delete

#define ISC_LEXOPT_NUMBER 0x08 /*%< Recognize numbers. */

[67] Fix | Delete

#define ISC_LEXOPT_QSTRING 0x10 /*%< Recognize qstrings. */

[68] Fix | Delete

/*@}*/

[69] Fix | Delete

[70] Fix | Delete

/*@{*/

[71] Fix | Delete

/*!

[72] Fix | Delete

* The ISC_LEXOPT_DNSMULTILINE option handles the processing of '(' and ')' in

[73] Fix | Delete

* the DNS master file format. If this option is set, then the

[74] Fix | Delete

* ISC_LEXOPT_INITIALWS and ISC_LEXOPT_EOL options will be ignored when

[75] Fix | Delete

* the paren count is > 0. To use this option, '(' and ')' must be special

[76] Fix | Delete

* characters.

[77] Fix | Delete

*/

[78] Fix | Delete

#define ISC_LEXOPT_DNSMULTILINE 0x20 /*%< Handle '(' and ')'. */

[79] Fix | Delete

#define ISC_LEXOPT_NOMORE 0x40 /*%< Want "no more" token. */

[80] Fix | Delete

[81] Fix | Delete

#define ISC_LEXOPT_CNUMBER 0x80 /*%< Recognize octal and hex. */

[82] Fix | Delete

#define ISC_LEXOPT_ESCAPE 0x100 /*%< Recognize escapes. */

[83] Fix | Delete

#define ISC_LEXOPT_QSTRINGMULTILINE 0x200 /*%< Allow multiline "" strings */

[84] Fix | Delete

#define ISC_LEXOPT_OCTAL 0x400 /*%< Expect a octal number. */

[85] Fix | Delete

#define ISC_LEXOPT_BTEXT 0x800 /*%< Bracketed text. */

[86] Fix | Delete

/*@}*/

[87] Fix | Delete

/*@{*/

[88] Fix | Delete

/*!

[89] Fix | Delete

* Various commenting styles, which may be changed at any time with

[90] Fix | Delete

* isc_lex_setcomments().

[91] Fix | Delete

*/

[92] Fix | Delete

[93] Fix | Delete

#define ISC_LEXCOMMENT_C 0x01

[94] Fix | Delete

#define ISC_LEXCOMMENT_CPLUSPLUS 0x02

[95] Fix | Delete

#define ISC_LEXCOMMENT_SHELL 0x04

[96] Fix | Delete

#define ISC_LEXCOMMENT_DNSMASTERFILE 0x08

[97] Fix | Delete

/*@}*/

[98] Fix | Delete

[99] Fix | Delete

/***

[100] Fix | Delete

*** Types

[101] Fix | Delete

***/

[102] Fix | Delete

[103] Fix | Delete

/*! Lex */

[104] Fix | Delete

[105] Fix | Delete

typedef char isc_lexspecials_t[256];

[106] Fix | Delete

[107] Fix | Delete

/* Tokens */

[108] Fix | Delete

[109] Fix | Delete

typedef enum {

[110] Fix | Delete

isc_tokentype_unknown = 0,

[111] Fix | Delete

isc_tokentype_string = 1,

[112] Fix | Delete

isc_tokentype_number = 2,

[113] Fix | Delete

isc_tokentype_qstring = 3,

[114] Fix | Delete

isc_tokentype_eol = 4,

[115] Fix | Delete

isc_tokentype_eof = 5,

[116] Fix | Delete

isc_tokentype_initialws = 6,

[117] Fix | Delete

isc_tokentype_special = 7,

[118] Fix | Delete

isc_tokentype_nomore = 8,

[119] Fix | Delete

isc_tokentype_btext = 8

[120] Fix | Delete

} isc_tokentype_t;

[121] Fix | Delete

[122] Fix | Delete

typedef union {

[123] Fix | Delete

char as_char;

[124] Fix | Delete

unsigned long as_ulong;

[125] Fix | Delete

isc_region_t as_region;

[126] Fix | Delete

isc_textregion_t as_textregion;

[127] Fix | Delete

void * as_pointer;

[128] Fix | Delete

} isc_tokenvalue_t;

[129] Fix | Delete

[130] Fix | Delete

typedef struct isc_token {

[131] Fix | Delete

isc_tokentype_t type;

[132] Fix | Delete

isc_tokenvalue_t value;

[133] Fix | Delete

} isc_token_t;

[134] Fix | Delete

[135] Fix | Delete

/***

[136] Fix | Delete

*** Functions

[137] Fix | Delete

***/

[138] Fix | Delete

[139] Fix | Delete

isc_result_t

[140] Fix | Delete

isc_lex_create(isc_mem_t *mctx, size_t max_token, isc_lex_t **lexp);

[141] Fix | Delete

/*%<

[142] Fix | Delete

* Create a lexer.

[143] Fix | Delete

*

[144] Fix | Delete

* 'max_token' is a hint of the number of bytes in the largest token.

[145] Fix | Delete

*

[146] Fix | Delete

* Requires:

[147] Fix | Delete

*\li '*lexp' is a valid lexer.

[148] Fix | Delete

*

[149] Fix | Delete

* Ensures:

[150] Fix | Delete

*\li On success, *lexp is attached to the newly created lexer.

[151] Fix | Delete

*

[152] Fix | Delete

* Returns:

[153] Fix | Delete

*\li #ISC_R_SUCCESS

[154] Fix | Delete

*\li #ISC_R_NOMEMORY

[155] Fix | Delete

*/

[156] Fix | Delete

[157] Fix | Delete

void

[158] Fix | Delete

isc_lex_destroy(isc_lex_t **lexp);

[159] Fix | Delete

/*%<

[160] Fix | Delete

* Destroy the lexer.

[161] Fix | Delete

*

[162] Fix | Delete

* Requires:

[163] Fix | Delete

*\li '*lexp' is a valid lexer.

[164] Fix | Delete

*

[165] Fix | Delete

* Ensures:

[166] Fix | Delete

*\li *lexp == NULL

[167] Fix | Delete

*/

[168] Fix | Delete

[169] Fix | Delete

unsigned int

[170] Fix | Delete

isc_lex_getcomments(isc_lex_t *lex);

[171] Fix | Delete

/*%<

[172] Fix | Delete

* Return the current lexer commenting styles.

[173] Fix | Delete

*

[174] Fix | Delete

* Requires:

[175] Fix | Delete

*\li 'lex' is a valid lexer.

[176] Fix | Delete

*

[177] Fix | Delete

* Returns:

[178] Fix | Delete

*\li The commenting styles which are currently allowed.

[179] Fix | Delete

*/

[180] Fix | Delete

[181] Fix | Delete

void

[182] Fix | Delete

isc_lex_setcomments(isc_lex_t *lex, unsigned int comments);

[183] Fix | Delete

/*%<

[184] Fix | Delete

* Set allowed lexer commenting styles.

[185] Fix | Delete

*

[186] Fix | Delete

* Requires:

[187] Fix | Delete

*\li 'lex' is a valid lexer.

[188] Fix | Delete

*

[189] Fix | Delete

*\li 'comments' has meaningful values.

[190] Fix | Delete

*/

[191] Fix | Delete

[192] Fix | Delete

void

[193] Fix | Delete

isc_lex_getspecials(isc_lex_t *lex, isc_lexspecials_t specials);

[194] Fix | Delete

/*%<

[195] Fix | Delete

* Put the current list of specials into 'specials'.

[196] Fix | Delete

*

[197] Fix | Delete

* Requires:

[198] Fix | Delete

*\li 'lex' is a valid lexer.

[199] Fix | Delete

*/

[200] Fix | Delete

[201] Fix | Delete

void

[202] Fix | Delete

isc_lex_setspecials(isc_lex_t *lex, isc_lexspecials_t specials);

[203] Fix | Delete

/*!<

[204] Fix | Delete

* The characters in 'specials' are returned as tokens. Along with

[205] Fix | Delete

* whitespace, they delimit strings and numbers.

[206] Fix | Delete

*

[207] Fix | Delete

* Note:

[208] Fix | Delete

*\li Comment processing takes precedence over special character

[209] Fix | Delete

* recognition.

[210] Fix | Delete

*

[211] Fix | Delete

* Requires:

[212] Fix | Delete

*\li 'lex' is a valid lexer.

[213] Fix | Delete

*/

[214] Fix | Delete

[215] Fix | Delete

isc_result_t

[216] Fix | Delete

isc_lex_openfile(isc_lex_t *lex, const char *filename);

[217] Fix | Delete

/*%<

[218] Fix | Delete

* Open 'filename' and make it the current input source for 'lex'.

[219] Fix | Delete

*

[220] Fix | Delete

* Requires:

[221] Fix | Delete

*\li 'lex' is a valid lexer.

[222] Fix | Delete

*

[223] Fix | Delete

*\li filename is a valid C string.

[224] Fix | Delete

*

[225] Fix | Delete

* Returns:

[226] Fix | Delete

*\li #ISC_R_SUCCESS

[227] Fix | Delete

*\li #ISC_R_NOMEMORY Out of memory

[228] Fix | Delete

*\li #ISC_R_NOTFOUND File not found

[229] Fix | Delete

*\li #ISC_R_NOPERM No permission to open file

[230] Fix | Delete

*\li #ISC_R_FAILURE Couldn't open file, not sure why

[231] Fix | Delete

*\li #ISC_R_UNEXPECTED

[232] Fix | Delete

*/

[233] Fix | Delete

[234] Fix | Delete

isc_result_t

[235] Fix | Delete

isc_lex_openstream(isc_lex_t *lex, FILE *stream);

[236] Fix | Delete

/*%<

[237] Fix | Delete

* Make 'stream' the current input source for 'lex'.

[238] Fix | Delete

*

[239] Fix | Delete

* Requires:

[240] Fix | Delete

*\li 'lex' is a valid lexer.

[241] Fix | Delete

*

[242] Fix | Delete

*\li 'stream' is a valid C stream.

[243] Fix | Delete

*

[244] Fix | Delete

* Returns:

[245] Fix | Delete

*\li #ISC_R_SUCCESS

[246] Fix | Delete

*\li #ISC_R_NOMEMORY Out of memory

[247] Fix | Delete

*/

[248] Fix | Delete

[249] Fix | Delete

isc_result_t

[250] Fix | Delete

isc_lex_openbuffer(isc_lex_t *lex, isc_buffer_t *buffer);

[251] Fix | Delete

/*%<

[252] Fix | Delete

* Make 'buffer' the current input source for 'lex'.

[253] Fix | Delete

*

[254] Fix | Delete

* Requires:

[255] Fix | Delete

*\li 'lex' is a valid lexer.

[256] Fix | Delete

*

[257] Fix | Delete

*\li 'buffer' is a valid buffer.

[258] Fix | Delete

*

[259] Fix | Delete

* Returns:

[260] Fix | Delete

*\li #ISC_R_SUCCESS

[261] Fix | Delete

*\li #ISC_R_NOMEMORY Out of memory

[262] Fix | Delete

*/

[263] Fix | Delete

[264] Fix | Delete

isc_result_t

[265] Fix | Delete

isc_lex_close(isc_lex_t *lex);

[266] Fix | Delete

/*%<

[267] Fix | Delete

* Close the most recently opened object (i.e. file or buffer).

[268] Fix | Delete

*

[269] Fix | Delete

* Returns:

[270] Fix | Delete

*\li #ISC_R_SUCCESS

[271] Fix | Delete

*\li #ISC_R_NOMORE No more input sources

[272] Fix | Delete

*/

[273] Fix | Delete

[274] Fix | Delete

isc_result_t

[275] Fix | Delete

isc_lex_gettoken(isc_lex_t *lex, unsigned int options, isc_token_t *tokenp);

[276] Fix | Delete

/*%<

[277] Fix | Delete

* Get the next token.

[278] Fix | Delete

*

[279] Fix | Delete

* Requires:

[280] Fix | Delete

*\li 'lex' is a valid lexer.

[281] Fix | Delete

*

[282] Fix | Delete

*\li 'lex' has an input source.

[283] Fix | Delete

*

[284] Fix | Delete

*\li 'options' contains valid options.

[285] Fix | Delete

*

[286] Fix | Delete

*\li '*tokenp' is a valid pointer.

[287] Fix | Delete

*

[288] Fix | Delete

* Returns:

[289] Fix | Delete

*\li #ISC_R_SUCCESS

[290] Fix | Delete

*\li #ISC_R_UNEXPECTEDEND

[291] Fix | Delete

*\li #ISC_R_NOMEMORY

[292] Fix | Delete

*

[293] Fix | Delete

* These two results are returned only if their corresponding lexer

[294] Fix | Delete

* options are not set.

[295] Fix | Delete

*

[296] Fix | Delete

*\li #ISC_R_EOF End of input source

[297] Fix | Delete

*\li #ISC_R_NOMORE No more input sources

[298] Fix | Delete

*/

[299] Fix | Delete

[300] Fix | Delete

isc_result_t

[301] Fix | Delete

isc_lex_getmastertoken(isc_lex_t *lex, isc_token_t *token,

[302] Fix | Delete

isc_tokentype_t expect, bool eol);

[303] Fix | Delete

/*%<

[304] Fix | Delete

* Get the next token from a DNS master file type stream. This is a

[305] Fix | Delete

* convenience function that sets appropriate options and handles quoted

[306] Fix | Delete

* strings and end of line correctly for master files. It also ungets

[307] Fix | Delete

* unexpected tokens. If `eol` is set then expect end-of-line otherwise

[308] Fix | Delete

* eol is a error.

[309] Fix | Delete

*

[310] Fix | Delete

* Requires:

[311] Fix | Delete

*\li 'lex' is a valid lexer.

[312] Fix | Delete

*

[313] Fix | Delete

*\li 'token' is a valid pointer

[314] Fix | Delete

*

[315] Fix | Delete

* Returns:

[316] Fix | Delete

*

[317] Fix | Delete

* \li any return code from isc_lex_gettoken().

[318] Fix | Delete

*/

[319] Fix | Delete

[320] Fix | Delete

isc_result_t

[321] Fix | Delete

isc_lex_getoctaltoken(isc_lex_t *lex, isc_token_t *token, bool eol);

[322] Fix | Delete

/*%<

[323] Fix | Delete

* Get the next token from a DNS master file type stream. This is a

[324] Fix | Delete

* convenience function that sets appropriate options and handles end

[325] Fix | Delete

* of line correctly for master files. It also ungets unexpected tokens.

[326] Fix | Delete

* If `eol` is set then expect end-of-line otherwise eol is a error.

[327] Fix | Delete

*

[328] Fix | Delete

* Requires:

[329] Fix | Delete

*\li 'lex' is a valid lexer.

[330] Fix | Delete

*

[331] Fix | Delete

*\li 'token' is a valid pointer

[332] Fix | Delete

*

[333] Fix | Delete

* Returns:

[334] Fix | Delete

*

[335] Fix | Delete

* \li any return code from isc_lex_gettoken().

[336] Fix | Delete

*/

[337] Fix | Delete

[338] Fix | Delete

void

[339] Fix | Delete

isc_lex_ungettoken(isc_lex_t *lex, isc_token_t *tokenp);

[340] Fix | Delete

/*%<

[341] Fix | Delete

* Unget the current token.

[342] Fix | Delete

*

[343] Fix | Delete

* Requires:

[344] Fix | Delete

*\li 'lex' is a valid lexer.

[345] Fix | Delete

*

[346] Fix | Delete

*\li 'lex' has an input source.

[347] Fix | Delete

*

[348] Fix | Delete

*\li 'tokenp' points to a valid token.

[349] Fix | Delete

*

[350] Fix | Delete

*\li There is no ungotten token already.

[351] Fix | Delete

*/

[352] Fix | Delete

[353] Fix | Delete

void

[354] Fix | Delete

isc_lex_getlasttokentext(isc_lex_t *lex, isc_token_t *tokenp, isc_region_t *r);

[355] Fix | Delete

/*%<

[356] Fix | Delete

* Returns a region containing the text of the last token returned.

[357] Fix | Delete

*

[358] Fix | Delete

* Requires:

[359] Fix | Delete

*\li 'lex' is a valid lexer.

[360] Fix | Delete

*

[361] Fix | Delete

*\li 'lex' has an input source.

[362] Fix | Delete

*

[363] Fix | Delete

*\li 'tokenp' points to a valid token.

[364] Fix | Delete

*

[365] Fix | Delete

*\li A token has been gotten and not ungotten.

[366] Fix | Delete

*/

[367] Fix | Delete

[368] Fix | Delete

char *

[369] Fix | Delete

isc_lex_getsourcename(isc_lex_t *lex);

[370] Fix | Delete

/*%<

[371] Fix | Delete

* Return the input source name.

[372] Fix | Delete

*

[373] Fix | Delete

* Requires:

[374] Fix | Delete

*\li 'lex' is a valid lexer.

[375] Fix | Delete

*

[376] Fix | Delete

* Returns:

[377] Fix | Delete

* \li source name or NULL if no current source.

[378] Fix | Delete

*\li result valid while current input source exists.

[379] Fix | Delete

*/

[380] Fix | Delete

[381] Fix | Delete

[382] Fix | Delete

unsigned long

[383] Fix | Delete

isc_lex_getsourceline(isc_lex_t *lex);

[384] Fix | Delete

/*%<

[385] Fix | Delete

* Return the input source line number.

[386] Fix | Delete

*

[387] Fix | Delete

* Requires:

[388] Fix | Delete

*\li 'lex' is a valid lexer.

[389] Fix | Delete

*

[390] Fix | Delete

* Returns:

[391] Fix | Delete

*\li Current line number or 0 if no current source.

[392] Fix | Delete

*/

[393] Fix | Delete

[394] Fix | Delete

isc_result_t

[395] Fix | Delete

isc_lex_setsourcename(isc_lex_t *lex, const char *name);

[396] Fix | Delete

/*%<

[397] Fix | Delete

* Assigns a new name to the input source.

[398] Fix | Delete

*

[399] Fix | Delete

* Requires:

[400] Fix | Delete

*

[401] Fix | Delete

* \li 'lex' is a valid lexer.

[402] Fix | Delete

*

[403] Fix | Delete

* Returns:

[404] Fix | Delete

* \li #ISC_R_SUCCESS

[405] Fix | Delete

* \li #ISC_R_NOMEMORY

[406] Fix | Delete

* \li #ISC_R_NOTFOUND - there are no sources.

[407] Fix | Delete

*/

[408] Fix | Delete

[409] Fix | Delete

isc_result_t

[410] Fix | Delete

isc_lex_setsourceline(isc_lex_t *lex, unsigned long line);

[411] Fix | Delete

/*%<

[412] Fix | Delete

* Assigns a new line number to the input source. This can be used

[413] Fix | Delete

* when parsing a buffer that's been excerpted from the middle a file,

[414] Fix | Delete

* allowing logged messages to display the correct line number,

[415] Fix | Delete

* rather than the line number within the buffer.

[416] Fix | Delete

*

[417] Fix | Delete

* Requires:

[418] Fix | Delete

*

[419] Fix | Delete

* \li 'lex' is a valid lexer.

[420] Fix | Delete

*

[421] Fix | Delete

* Returns:

[422] Fix | Delete

* \li #ISC_R_SUCCESS

[423] Fix | Delete

* \li #ISC_R_NOTFOUND - there are no sources.

[424] Fix | Delete

*/

[425] Fix | Delete

[426] Fix | Delete

bool

[427] Fix | Delete

isc_lex_isfile(isc_lex_t *lex);

[428] Fix | Delete

/*%<

[429] Fix | Delete

* Return whether the current input source is a file.

[430] Fix | Delete

*

[431] Fix | Delete

* Requires:

[432] Fix | Delete

*\li 'lex' is a valid lexer.

[433] Fix | Delete

*

[434] Fix | Delete

* Returns:

[435] Fix | Delete

* \li #true if the current input is a file,

[436] Fix | Delete

*\li #false otherwise.

[437] Fix | Delete

*/

[438] Fix | Delete

[439] Fix | Delete

[440] Fix | Delete

ISC_LANG_ENDDECLS

[441] Fix | Delete

[442] Fix | Delete

#endif /* ISC_LEX_H */

[443] Fix | Delete

[444] Fix | Delete