| 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 */ |