contrib/bc/include/parse.h

   1 /*
   2  * *****************************************************************************
   3  *
   4  * SPDX-License-Identifier: BSD-2-Clause
   5  *
   6  * Copyright (c) 2018-2021 Gavin D. Howard and contributors.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are met:
  10  *
  11  * * Redistributions of source code must retain the above copyright notice, this
  12  *   list of conditions and the following disclaimer.
  13  *
  14  * * Redistributions in binary form must reproduce the above copyright notice,
  15  *   this list of conditions and the following disclaimer in the documentation
  16  *   and/or other materials provided with the distribution.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28  * POSSIBILITY OF SUCH DAMAGE.
  29  *
  30  * *****************************************************************************
  31  *
  32  * Definitions for bc's parser.
  33  *
  34  */
  35
  36 #ifndef BC_PARSE_H
  37 #define BC_PARSE_H
  38
  39 #include <limits.h>
  40 #include <stdbool.h>
  41 #include <stdint.h>
  42
  43 #include <status.h>
  44 #include <vector.h>
  45 #include <lex.h>
  46 #include <lang.h>
  47
  48 // The following are flags that can be passed to @a BcParseExpr functions. They
  49 // define the requirements that the parsed expression must meet to not have an
  50 // error thrown.
  51
  52 /// A flag that requires that the expression is valid for conditionals in for
  53 /// loops, while loops, and if statements. This is because POSIX requires that
  54 /// certain operators are *only* used in those cases. It's whacked, but that's
  55 /// how it is.
  56 #define BC_PARSE_REL (UINTMAX_C(1)<<0)
  57
  58 /// A flag that requires that the expression is valid for a print statement.
  59 #define BC_PARSE_PRINT (UINTMAX_C(1)<<1)
  60
  61 /// A flag that requires that the expression does *not* have any function call.
  62 #define BC_PARSE_NOCALL (UINTMAX_C(1)<<2)
  63
  64 /// A flag that requires that the expression does *not* have a read() expression.
  65 #define BC_PARSE_NOREAD (UINTMAX_C(1)<<3)
  66
  67 /// A flag that *allows* (rather than requires) that an array appear in the
  68 /// expression. This is mostly used as parameters in bc.
  69 #define BC_PARSE_ARRAY (UINTMAX_C(1)<<4)
  70
  71 /// A flag that requires that the expression is not empty and returns a value.
  72 #define BC_PARSE_NEEDVAL (UINTMAX_C(1)<<5)
  73
  74 /**
  75  * Returns true if the parser has been initialized.
  76  * @param p    The parser.
  77  * @param prg  The program.
  78  * @return     True if @a p has been initialized, false otherwise.
  79  */
  80 #define BC_PARSE_IS_INITED(p, prg) ((p)->prog == (prg))
  81
  82 #if BC_ENABLED
  83
  84 /**
  85  * Returns true if the current parser state allows parsing, false otherwise.
  86  * @param p  The parser.
  87  * @return   True if parsing can proceed, false otherwise.
  88  */
  89 #define BC_PARSE_CAN_PARSE(p) \
  90         ((p).l.t != BC_LEX_EOF && (p).l.t != BC_LEX_KW_DEFINE)
  91
  92 #else // BC_ENABLED
  93
  94 /**
  95  * Returns true if the current parser state allows parsing, false otherwise.
  96  * @param p  The parser.
  97  * @return   True if parsing can proceed, false otherwise.
  98  */
  99 #define BC_PARSE_CAN_PARSE(p) ((p).l.t != BC_LEX_EOF)
 100
 101 #endif // BC_ENABLED
 102
 103 /**
 104  * Pushes the instruction @a i onto the bytecode vector for the current
 105  * function.
 106  * @param p  The parser.
 107  * @param i  The instruction to push onto the bytecode vector.
 108  */
 109 #define bc_parse_push(p, i) (bc_vec_pushByte(&(p)->func->code, (uchar) (i)))
 110
 111 /**
 112  * Pushes an index onto the bytecode vector. For more information, see
 113  * @a bc_vec_pushIndex() in src/vector.c and @a bc_program_index() in
 114  * src/program.c.
 115  * @param p    The parser.
 116  * @param idx  The index to push onto the bytecode vector.
 117  */
 118 #define bc_parse_pushIndex(p, idx) (bc_vec_pushIndex(&(p)->func->code, (idx)))
 119
 120 /**
 121  * A convenience macro for throwing errors in parse code. They take care of
 122  * plumbing like passing in the current line the lexer is on.
 123  * @param p  The parser.
 124  * @param e  The error.
 125  */
 126 #define bc_parse_err(p, e) (bc_vm_handleError((e), (p)->l.line))
 127
 128 /**
 129  * A convenience macro for throwing errors in parse code. They take care of
 130  * plumbing like passing in the current line the lexer is on.
 131  * @param p    The parser.
 132  * @param e    The error.
 133  * @param ...  The varags that are needed.
 134  */
 135 #define bc_parse_verr(p, e, ...) \
 136         (bc_vm_handleError((e), (p)->l.line, __VA_ARGS__))
 137
 138 // Forward declarations.
 139 struct BcParse;
 140 struct BcProgram;
 141
 142 /**
 143  * A function pointer to call when more parsing is needed.
 144  * @param p  The parser.
 145  */
 146 typedef void (*BcParseParse)(struct BcParse* p);
 147
 148 /**
 149  * A function pointer to call when an expression needs to be parsed. This can
 150  * happen for read() expressions or dc strings.
 151  * @param p      The parser.
 152  * @param flags  The flags for what is allowed or required. (See flags above.)
 153  */
 154 typedef void (*BcParseExpr)(struct BcParse* p, uint8_t flags);
 155
 156 /// The parser struct.
 157 typedef struct BcParse {
 158
 159         /// The lexer.
 160         BcLex l;
 161
 162 #if BC_ENABLED
 163         /// The stack of flags for bc. (See comments in include/bc.h.) This stack is
 164         /// *required* to have one item at all times. Not maintaining that invariant
 165         /// will cause problems.
 166         BcVec flags;
 167
 168         /// The stack of exits. These are indices into the bytecode vector where
 169         /// blocks for loops and if statements end. Basically, these are the places
 170         /// to jump to when skipping code.
 171         BcVec exits;
 172
 173         /// The stack of conditionals. Unlike exits, which are indices to jump
 174         /// *forward* to, this is a vector of indices to jump *backward* to, usually
 175         /// to the conditional of a loop, hence the name.
 176         BcVec conds;
 177
 178         /// A stack of operators. When parsing expressions, the bc parser uses the
 179         /// Shunting-Yard algorithm, which requires a stack of operators. This can
 180         /// hold the stack for multiple expressions at once because the expressions
 181         /// stack as well. For more information, see the Expression Parsing section
 182         /// of the Development manual (manuals/development.md).
 183         BcVec ops;
 184
 185         /// A buffer to temporarily store a string in. This is because the lexer
 186         /// might generate a string as part of its work, and the parser needs that
 187         /// string, but it also needs the lexer to continue lexing, which might
 188         /// overwrite the string stored in the lexer. This buffer is for copying
 189         /// that string from the lexer to keep it safe.
 190         BcVec buf;
 191 #endif // BC_ENABLED
 192
 193         /// A reference to the program to grab the current function when necessary.
 194         struct BcProgram *prog;
 195
 196         /// A reference to the current function. The function is what holds the
 197         /// bytecode vector that the parser is filling.
 198         BcFunc *func;
 199
 200         /// The index of the function.
 201         size_t fidx;
 202
 203 #if BC_ENABLED
 204         /// True if the bc parser just entered a function and an auto statement
 205         /// would be valid.
 206         bool auto_part;
 207 #endif // BC_ENABLED
 208
 209 } BcParse;
 210
 211 /**
 212  * Initializes a parser.
 213  * @param p     The parser to initialize.
 214  * @param prog  A referenc to the program.
 215  * @param func  The index of the current function.
 216  */
 217 void bc_parse_init(BcParse *p, struct BcProgram *prog, size_t func);
 218
 219 /**
 220  * Frees a parser. This is not guarded by #ifndef NDEBUG because a separate
 221  * parser is created at runtime to parse read() expressions and dc strings.
 222  * @param p  The parser to free.
 223  */
 224 void bc_parse_free(BcParse *p);
 225
 226 /**
 227  * Resets the parser. Resetting means erasing all state to the point that the
 228  * parser would think it was just initialized.
 229  * @param p  The parser to reset.
 230  */
 231 void bc_parse_reset(BcParse *p);
 232
 233 /**
 234  * Adds a string. See @a BcProgram in include/program.h for more details.
 235  * @param p  The parser that parsed the string.
 236  */
 237 void bc_parse_addString(BcParse *p);
 238
 239 /**
 240  * Adds a number. See @a BcProgram in include/program.h for more details.
 241  * @param p  The parser that parsed the number.
 242  */
 243 void bc_parse_number(BcParse *p);
 244
 245 /**
 246  * Update the current function in the parser.
 247  * @param p     The parser.
 248  * @param fidx  The index of the new function.
 249  */
 250 void bc_parse_updateFunc(BcParse *p, size_t fidx);
 251
 252 /**
 253  * Adds a new variable or array. See @a BcProgram in include/program.h for more
 254  * details.
 255  * @param p     The parser that parsed the variable or array name.
 256  * @param name  The name of the variable or array to add.
 257  * @param var   True if the name is for a variable, false if it's for an array.
 258  */
 259 void bc_parse_pushName(const BcParse* p, char *name, bool var);
 260
 261 /**
 262  * Sets the text that the parser will parse.
 263  * @param p         The parser.
 264  * @param text      The text to lex.
 265  * @param is_stdin  True if the text is from stdin, false otherwise.
 266  */
 267 void bc_parse_text(BcParse *p, const char *text, bool is_stdin);
 268
 269 // References to const 0 and 1 strings for special cases. bc and dc have
 270 // specific instructions for 0 and 1 because they pop up so often and (in the
 271 // case of 1), increment/decrement operators.
 272 extern const char bc_parse_zero[2];
 273 extern const char bc_parse_one[2];
 274
 275 #endif // BC_PARSE_H