Debian Codegraph @

libdrgn/lexer.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * Lexer interface.
8 *
9 * See @ref Lexer.
10 */
11
12 #ifndef DRGN_LEXER_H
13 #define DRGN_LEXER_H
14
15 #include <stddef.h>
16
17 #include "vector.h"
18
19 /**
20 * @ingroup Internals
21 *
22 * @defgroup Lexer Lexer
23 *
24 * Lexical analysis.
25 *
26 * This is a convenient interface for lexical analysis. @ref drgn_lexer provides
27 * the abstraction of a stack of tokens (@ref drgn_token) on top of a raw @ref
28 * drgn_lexer_func.
29 *
30 * @{
31 */
32
33 struct drgn_lexer;
34 struct drgn_token;
35
36 /**
37 * Lexer function.
38 *
39 * A lexer function does the work of lexing the next token in a string. It
40 * should initialize the passed in token and advance @ref drgn_lexer::p.
41 */
42 typedef struct drgn_error *(*drgn_lexer_func)(struct drgn_lexer *,
43 struct drgn_token *);
44
45 /** Lexical token. */
46 struct drgn_token {
47 /** Kind of token as defined by the lexer function. */
48 int kind;
49 /**
50 * String value of the token (i.e., the lexeme).
51 *
52 * This points to the contents of the original string, so it isn't
53 * null-terminated.
54 */
55 const char *value;
56 /** Length of the token value. */
57 size_t len;
58 };
59
60 DEFINE_VECTOR_TYPE(drgn_token_vector, struct drgn_token);
61
62 /**
63 * Lexer instance.
64 *
65 * A lexer comprises a lexer function, a position, and a stack of tokens. Tokens
66 * can be pushed and popped onto the stack. When the stack is empty, a pop calls
67 * the lexer function instead.
68 */
69 struct drgn_lexer {
70 /** Lexer function. */
71 drgn_lexer_func func;
72 /** Current position in the string. */
73 const char *p;
74 /** Stack of tokens. */
75 struct drgn_token_vector stack;
76 };
77
78 /**
79 * @ref drgn_lexer initializer.
80 *
81 * @param[in] lexer_func Lexer function.
82 * @param[in] str String to lex.
83 */
84 #define DRGN_LEXER_INIT(lexer_func, str) \
85 { .func = (lexer_func), .p = (str), .stack = VECTOR_INIT }
86
87 /**
88 * Free memory allocated by a @ref drgn_lexer.
89 *
90 * @param[in] lexer Lexer to deinitialize.
91 */
92 void drgn_lexer_deinit(struct drgn_lexer *lexer);
93
94 /**
95 * Define and initialize a @ref drgn_lexer named @p lexer that is automatically
96 * deinitialized when it goes out of scope.
97 *
98 * @param[in] lexer_func Lexer function.
99 * @param[in] str String to lex.
100 */
101 #define DRGN_LEXER(lexer, lexer_func, str) \
102 __attribute__((__cleanup__(drgn_lexer_deinit))) \
103 struct drgn_lexer lexer = DRGN_LEXER_INIT(lexer_func, str)
104
105 /**
106 * Return the next token from a @ref drgn_lexer.
107 *
108 * If there are tokens on the stack, this pops and returns the top token.
109 * Otherwise, this calls the lexer function to get the next token.
110 *
111 * @return @c NULL on success, non-@c NULL on error.
112 */
113 struct drgn_error *drgn_lexer_pop(struct drgn_lexer *lexer,
114 struct drgn_token *token);
115
116 /**
117 * Push a token onto the stack of a @ref drgn_lexer.
118 *
119 * This token must have been returned by @ref drgn_lexer_pop().
120 *
121 * @return @c NULL on success, non-@c NULL on error.
122 */
123 struct drgn_error *drgn_lexer_push(struct drgn_lexer *lexer,
124 const struct drgn_token *token);
125
126 /**
127 * Return the next token from a @ref drgn_lexer and leave it on top of the
128 * stack.
129 *
130 * This is equivalent to a call to @ref drgn_lexer_pop() immediately followed by
131 * a call to @ref drgn_lexer_push().
132 *
133 * @return @c NULL on success, non-@c NULL on error.
134 */
135 struct drgn_error *drgn_lexer_peek(struct drgn_lexer *lexer,
136 struct drgn_token *token);
137
138 /** @} */
139
140 #endif /* DRGN_LEXER_H */