2 * *****************************************************************************
4 * SPDX-License-Identifier: BSD-2-Clause
6 * Copyright (c) 2018-2023 Gavin D. Howard and contributors.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are met:
11 * * Redistributions of source code must retain the above copyright notice, this
12 * list of conditions and the following disclaimer.
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.
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.
30 * *****************************************************************************
32 * Definitions for program data.
41 // These have to come first to silence a warning on BC_C11 below.
50 /// The instructions for bytecode.
54 /// Postfix increment and decrement. Prefix are translated into
55 /// BC_INST_ONE with either BC_INST_ASSIGN_PLUS or BC_INST_ASSIGN_MINUS.
66 #if BC_ENABLE_EXTRA_MATH
67 /// Truncation operator.
69 #endif // BC_ENABLE_EXTRA_MATH
71 /// These should be self-explanatory.
79 #if BC_ENABLE_EXTRA_MATH
86 #endif // BC_ENABLE_EXTRA_MATH
88 /// Comparison operators.
96 /// Boolean or and and.
101 /// Same as the normal operators, but assigment. So ^=, *=, /=, etc.
102 BC_INST_ASSIGN_POWER,
103 BC_INST_ASSIGN_MULTIPLY,
104 BC_INST_ASSIGN_DIVIDE,
105 BC_INST_ASSIGN_MODULUS,
107 BC_INST_ASSIGN_MINUS,
108 #if BC_ENABLE_EXTRA_MATH
109 /// Places and shift assignment operators.
110 BC_INST_ASSIGN_PLACES,
111 BC_INST_ASSIGN_LSHIFT,
112 BC_INST_ASSIGN_RSHIFT,
113 #endif // BC_ENABLE_EXTRA_MATH
115 /// Normal assignment.
118 /// bc and dc detect when the value from an assignment is not necessary.
119 /// For example, a plain assignment statement means the value is never used.
120 /// In those cases, we can get lots of performance back by not even creating
121 /// a copy at all. In fact, it saves a copy, a push onto the results stack,
122 /// a pop from the results stack, and a free. Definitely worth it to detect.
123 BC_INST_ASSIGN_POWER_NO_VAL,
124 BC_INST_ASSIGN_MULTIPLY_NO_VAL,
125 BC_INST_ASSIGN_DIVIDE_NO_VAL,
126 BC_INST_ASSIGN_MODULUS_NO_VAL,
127 BC_INST_ASSIGN_PLUS_NO_VAL,
128 BC_INST_ASSIGN_MINUS_NO_VAL,
129 #if BC_ENABLE_EXTRA_MATH
131 BC_INST_ASSIGN_PLACES_NO_VAL,
132 BC_INST_ASSIGN_LSHIFT_NO_VAL,
133 BC_INST_ASSIGN_RSHIFT_NO_VAL,
134 #endif // BC_ENABLE_EXTRA_MATH
137 /// Normal assignment that pushes no value on the stack.
138 BC_INST_ASSIGN_NO_VAL,
140 /// Push a constant onto the results stack.
143 /// Push a variable onto the results stack.
146 /// Push an array element onto the results stack.
149 /// Push an array onto the results stack. This is different from pushing an
150 /// array *element* onto the results stack; it pushes a reference to the
151 /// whole array. This is needed in bc for function arguments that are
152 /// arrays. It is also needed for returning the length of an array.
155 /// Push a zero or a one onto the stack. These are special cased because it
156 /// does help performance, particularly for one since inc/dec operators
162 /// Push the last printed value onto the stack.
166 /// Push the value of any of the globals onto the stack.
171 #if BC_ENABLE_EXTRA_MATH
172 /// Push the value of the seed global onto the stack.
174 #endif // BC_ENABLE_EXTRA_MATH
176 /// These are builtin functions.
184 #if BC_ENABLE_EXTRA_MATH
185 /// Another builtin function.
187 #endif // BC_ENABLE_EXTRA_MATH
192 /// Another builtin function.
195 #if BC_ENABLE_EXTRA_MATH
196 /// Another builtin function.
198 #endif // BC_ENABLE_EXTRA_MATH
200 /// Return the max for the various globals.
204 #if BC_ENABLE_EXTRA_MATH
205 /// Return the max value returned by rand().
207 #endif // BC_ENABLE_EXTRA_MATH
209 /// bc line_length() builtin function.
214 /// bc global_stacks() builtin function.
215 BC_INST_GLOBAL_STACKS,
219 /// bc leading_zero() builtin function.
220 BC_INST_LEADING_ZERO,
222 /// This is slightly misnamed versus BC_INST_PRINT_POP. Well, it is in bc.
223 /// dc uses this instruction to print, but not pop. That's valid in dc.
224 /// However, in bc, it is *never* valid to print without popping. In bc,
225 /// BC_INST_PRINT_POP is used to indicate when a string should be printed
226 /// because of a print statement or whether it should be printed raw. The
227 /// reason for this is because a print statement handles escaped characters.
228 /// So BC_INST_PRINT_POP is for printing a string from a print statement,
229 /// BC_INST_PRINT_STR is for printing a string by itself.
231 /// In dc, BC_INST_PRINT_POP prints and pops, and BC_INST_PRINT just prints.
233 /// Oh, and BC_INST_STR pushes a string onto the results stack.
240 /// Jumps unconditionally.
243 /// Jumps if the top of the results stack is zero (condition failed). It
244 /// turns out that we only want to jump when conditions fail to "skip" code.
250 /// Return the top of the stack to the caller.
253 /// Return 0 to the caller.
256 /// Special return instruction for void functions.
259 /// Special halt instruction.
263 /// Pop an item off of the results stack.
266 /// Swaps the top two items on the results stack.
269 /// Modular exponentiation.
272 /// Do divide and modulus at the same time.
275 /// Turns a number into a string and prints it.
276 BC_INST_PRINT_STREAM,
280 /// dc extended registers command.
281 BC_INST_EXTENDED_REGISTERS,
283 /// dc's return; it pops an executing string off of the stack.
286 /// Unconditionally execute a string.
289 /// Conditionally execute a string.
292 /// Prints each item on the results stack, separated by newlines.
295 /// Pops everything off of the results stack.
298 /// Pushes the current length of a register stack onto the results stack.
299 BC_INST_REG_STACK_LEN,
301 /// Pushes the current length of the results stack onto the results stack.
304 /// Pushes a copy of the item on the top of the results stack onto the
308 /// Copies the value in a register and pushes the copy onto the results
312 /// Pops an item off of a register stack and pushes it onto the results
316 /// Pops an item off of the results stack and pushes it onto a register's
323 /// Quit executing some number of strings.
326 /// Push the depth of the execution stack onto the stack.
327 BC_INST_EXEC_STACK_LEN,
331 /// Invalid instruction.
337 _Static_assert(BC_INST_INVALID <= UCHAR_MAX,
338 "Too many instructions to fit into an unsigned char");
341 /// Used by maps to identify where items are in the array.
344 /// The name of the item.
347 /// The index into the array where the item is.
352 /// The location of a var, array, or array element.
355 /// The index of the var or array.
358 /// The index of the array or variable in the array stack. This is to
359 /// prevent a bug with getting the wrong array element or variable after a
360 /// function call. See the tests/bc/scripts/array.bc test for the array
361 /// case; the variable case is in various variable tests.
364 /// The index of the array element. Only used for array elements.
369 /// An entry for a constant.
370 typedef struct BcConst
372 /// The original string as parsed from the source code.
375 /// The last base that the constant was parsed in.
378 /// The parsed constant.
383 /// A function. This is also used in dc, not just bc. The reason is that strings
384 /// are executed in dc, and they are converted to functions in order to be
386 typedef struct BcFunc
388 /// The bytecode instructions.
393 /// The labels. This is a vector of indices. The index is the index into
394 /// the bytecode vector where the label is.
397 /// The autos for the function. The first items are the parameters, and the
398 /// arguments to the parameters must match the types in this vector.
401 /// The number of parameters the function takes.
406 /// The function's name.
410 /// True if the function is a void function.
416 /// Types of results that can be pushed onto the results stack.
417 typedef enum BcResultType
419 /// Result is a variable.
422 /// Result is an array element.
423 BC_RESULT_ARRAY_ELEM,
425 /// Result is an array. This is only allowed for function arguments or
426 /// returning the length of the array.
429 /// Result is a string.
432 /// Result is a temporary. This is used for the result of almost all
436 /// Special casing the two below gave performance improvements.
441 /// Result is a 1. Useful for inc/dec operators.
446 /// Result is the special "last" variable.
449 /// Result is the return value of a void function.
453 /// Result is the value of ibase.
456 /// Result is the value of obase.
459 /// Result is the value of scale.
462 #if BC_ENABLE_EXTRA_MATH
464 /// Result is the value of seed.
467 #endif // BC_ENABLE_EXTRA_MATH
471 /// A union to store data for various result types.
472 typedef union BcResultData
474 /// A number. Strings are stored here too; they are numbers with
475 /// cap == 0 && num == NULL. The string's index into the strings vector is
476 /// stored in the scale field. But this is only used for strings stored in
483 /// A variable, array, or array element reference. This could also be a
484 /// string if a string is not stored in a variable (dc only).
489 /// A tagged union for results.
490 typedef struct BcResult
492 /// The tag. The type of the result.
495 /// The data. The data for the result.
500 /// An instruction pointer. This is how bc knows where in the bytecode vector,
501 /// and which function, the current execution is.
502 typedef struct BcInstPtr
504 /// The index of the currently executing function in the fns vector.
507 /// The index into the bytecode vector of the *next* instruction.
510 /// The length of the results vector when this function started executing.
511 /// This is mostly used for bc where functions should not affect the results
512 /// of their callers.
517 /// Types of identifiers.
536 /// An auto variable in bc.
537 typedef struct BcAuto
539 /// The index of the variable in the vars or arrs vectors.
542 /// The type of the variable.
548 /// Forward declaration.
552 * Initializes a function.
553 * @param f The function to initialize.
554 * @param name The name of the function. The string is assumed to be owned by
558 bc_func_init(BcFunc* f, const char* name);
561 * Inserts an auto into the function.
562 * @param f The function to insert into.
563 * @param p The program. This is to search for the variable or array name.
564 * @param name The name of the auto to insert.
565 * @param type The type of the auto.
566 * @param line The line in the source code where the insert happened. This is
567 * solely for error reporting.
570 bc_func_insert(BcFunc* f, struct BcProgram* p, char* name, BcType type,
574 * Resets a function in preparation for it to be reused. This can happen in bc
575 * because it is a dynamic language and functions can be redefined.
576 * @param f The functio to reset.
579 bc_func_reset(BcFunc* f);
583 * Frees a function. This is a destructor. This is only used in debug builds
584 * because all functions are freed at exit. We free them in debug builds to
585 * check for memory leaks.
586 * @param func The function to free as a void pointer.
589 bc_func_free(void* func);
593 * Initializes an array, which is the array type in bc and dc source code. Since
594 * variables and arrays are both arrays (see the development manual,
595 * manuals/development.md#execution, for more information), the @a nums
596 * parameter tells bc whether to initialize an array of numbers or an array of
597 * arrays of numbers. If the latter, it does a recursive call with nums set to
599 * @param a The array to initialize.
600 * @param nums True if the array should be for numbers, false if it should be
604 bc_array_init(BcVec* a, bool nums);
607 * Copies an array to another array. This is used to do pass arrays to functions
608 * that do not take references to arrays. The arrays are passed entirely by
609 * value, which means that they need to be copied.
610 * @param d The destination array.
611 * @param s The source array.
614 bc_array_copy(BcVec* d, const BcVec* s);
617 * Frees a string stored in a function. This is a destructor.
618 * @param string The string to free as a void pointer.
621 bc_string_free(void* string);
624 * Frees a constant stored in a function. This is a destructor.
625 * @param constant The constant to free as a void pointer.
628 bc_const_free(void* constant);
631 * Clears a result. It sets the type to BC_RESULT_TEMP and clears the union by
632 * clearing the BcNum in the union. This is to ensure that bc does not use
633 * uninitialized data.
634 * @param r The result to clear.
637 bc_result_clear(BcResult* r);
640 * Copies a result into another. This is done for things like duplicating the
641 * top of the results stack or copying the result of an assignment to put back
642 * on the results stack.
643 * @param d The destination result.
644 * @param src The source result.
647 bc_result_copy(BcResult* d, BcResult* src);
650 * Frees a result. This is a destructor.
651 * @param result The result to free as a void pointer.
654 bc_result_free(void* result);
657 * Expands an array to @a len. This can happen because in bc, you do not have to
658 * explicitly initialize elements of an array. If you access an element that is
659 * not initialized, the array is expanded to fit it, and all missing elements
660 * are initialized to 0 if they are numbers, or arrays with one element of 0.
661 * This function does that expansion.
662 * @param a The array to expand.
663 * @param len The length to expand to.
666 bc_array_expand(BcVec* a, size_t len);
671 * Returns non-zero if the bytecode instruction i is an assignment instruction.
672 * @param i The instruction to test.
673 * @return Non-zero if i is an assignment instruction, zero otherwise.
675 #define BC_INST_IS_ASSIGN(i) \
676 ((i) == BC_INST_ASSIGN || (i) == BC_INST_ASSIGN_NO_VAL)
679 * Returns true if the bytecode instruction @a i requires the value to be
681 * @param i The instruction to test.
682 * @return True if @a i requires the value to be returned for use, false
685 #define BC_INST_USE_VAL(i) ((i) <= BC_INST_ASSIGN)
690 * Returns non-zero if the bytecode instruction i is an assignment instruction.
691 * @param i The instruction to test.
692 * @return Non-zero if i is an assignment instruction, zero otherwise.
694 #define BC_INST_IS_ASSIGN(i) ((i) == BC_INST_ASSIGN_NO_VAL)
697 * Returns true if the bytecode instruction @a i requires the value to be
699 * @param i The instruction to test.
700 * @return True if @a i requires the value to be returned for use, false
703 #define BC_INST_USE_VAL(i) (false)
708 /// Reference to string names for all of the instructions. For debugging.
709 extern const char* bc_inst_names[];
710 #endif // BC_DEBUG_CODE
712 /// References to the names of the main and read functions.
713 extern const char bc_func_main[];
714 extern const char bc_func_read[];