/contrib/bind9/lib/isc/include/isc/lex.h

https://bitbucket.org/freebsd/freebsd-head/ · C++ Header · 431 lines · 86 code · 45 blank · 300 comment · 0 complexity · 1b053a79b34c5640e9d57a7c7c3e4182 MD5 · raw file

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