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's return; it pops an executing string off of the stack.
283 /// Unconditionally execute a string.
286 /// Conditionally execute a string.
289 /// Prints each item on the results stack, separated by newlines.
292 /// Pops everything off of the results stack.
295 /// Pushes the current length of a register stack onto the results stack.
296 BC_INST_REG_STACK_LEN,
298 /// Pushes the current length of the results stack onto the results stack.
301 /// Pushes a copy of the item on the top of the results stack onto the
305 /// Copies the value in a register and pushes the copy onto the results
309 /// Pops an item off of a register stack and pushes it onto the results
313 /// Pops an item off of the results stack and pushes it onto a register's
320 /// Quit executing some number of strings.
323 /// Push the depth of the execution stack onto the stack.
324 BC_INST_EXEC_STACK_LEN,
328 /// Invalid instruction.
334 _Static_assert(BC_INST_INVALID <= UCHAR_MAX,
335 "Too many instructions to fit into an unsigned char");
338 /// Used by maps to identify where items are in the array.
341 /// The name of the item.
344 /// The index into the array where the item is.
349 /// The location of a var, array, or array element.
352 /// The index of the var or array.
355 /// The index of the array or variable in the array stack. This is to
356 /// prevent a bug with getting the wrong array element or variable after a
357 /// function call. See the tests/bc/scripts/array.bc test for the array
358 /// case; the variable case is in various variable tests.
361 /// The index of the array element. Only used for array elements.
366 /// An entry for a constant.
367 typedef struct BcConst
369 /// The original string as parsed from the source code.
372 /// The last base that the constant was parsed in.
375 /// The parsed constant.
380 /// A function. This is also used in dc, not just bc. The reason is that strings
381 /// are executed in dc, and they are converted to functions in order to be
383 typedef struct BcFunc
385 /// The bytecode instructions.
390 /// The labels. This is a vector of indices. The index is the index into
391 /// the bytecode vector where the label is.
394 /// The autos for the function. The first items are the parameters, and the
395 /// arguments to the parameters must match the types in this vector.
398 /// The number of parameters the function takes.
403 /// The function's name.
407 /// True if the function is a void function.
413 /// Types of results that can be pushed onto the results stack.
414 typedef enum BcResultType
416 /// Result is a variable.
419 /// Result is an array element.
420 BC_RESULT_ARRAY_ELEM,
422 /// Result is an array. This is only allowed for function arguments or
423 /// returning the length of the array.
426 /// Result is a string.
429 /// Result is a temporary. This is used for the result of almost all
433 /// Special casing the two below gave performance improvements.
438 /// Result is a 1. Useful for inc/dec operators.
443 /// Result is the special "last" variable.
446 /// Result is the return value of a void function.
450 /// Result is the value of ibase.
453 /// Result is the value of obase.
456 /// Result is the value of scale.
459 #if BC_ENABLE_EXTRA_MATH
461 /// Result is the value of seed.
464 #endif // BC_ENABLE_EXTRA_MATH
468 /// A union to store data for various result types.
469 typedef union BcResultData
471 /// A number. Strings are stored here too; they are numbers with
472 /// cap == 0 && num == NULL. The string's index into the strings vector is
473 /// stored in the scale field. But this is only used for strings stored in
480 /// A variable, array, or array element reference. This could also be a
481 /// string if a string is not stored in a variable (dc only).
486 /// A tagged union for results.
487 typedef struct BcResult
489 /// The tag. The type of the result.
492 /// The data. The data for the result.
497 /// An instruction pointer. This is how bc knows where in the bytecode vector,
498 /// and which function, the current execution is.
499 typedef struct BcInstPtr
501 /// The index of the currently executing function in the fns vector.
504 /// The index into the bytecode vector of the *next* instruction.
507 /// The length of the results vector when this function started executing.
508 /// This is mostly used for bc where functions should not affect the results
509 /// of their callers.
514 /// Types of identifiers.
533 /// An auto variable in bc.
534 typedef struct BcAuto
536 /// The index of the variable in the vars or arrs vectors.
539 /// The type of the variable.
545 /// Forward declaration.
549 * Initializes a function.
550 * @param f The function to initialize.
551 * @param name The name of the function. The string is assumed to be owned by
555 bc_func_init(BcFunc* f, const char* name);
558 * Inserts an auto into the function.
559 * @param f The function to insert into.
560 * @param p The program. This is to search for the variable or array name.
561 * @param name The name of the auto to insert.
562 * @param type The type of the auto.
563 * @param line The line in the source code where the insert happened. This is
564 * solely for error reporting.
567 bc_func_insert(BcFunc* f, struct BcProgram* p, char* name, BcType type,
571 * Resets a function in preparation for it to be reused. This can happen in bc
572 * because it is a dynamic language and functions can be redefined.
573 * @param f The functio to reset.
576 bc_func_reset(BcFunc* f);
580 * Frees a function. This is a destructor. This is only used in debug builds
581 * because all functions are freed at exit. We free them in debug builds to
582 * check for memory leaks.
583 * @param func The function to free as a void pointer.
586 bc_func_free(void* func);
590 * Initializes an array, which is the array type in bc and dc source code. Since
591 * variables and arrays are both arrays (see the development manual,
592 * manuals/development.md#execution, for more information), the @a nums
593 * parameter tells bc whether to initialize an array of numbers or an array of
594 * arrays of numbers. If the latter, it does a recursive call with nums set to
596 * @param a The array to initialize.
597 * @param nums True if the array should be for numbers, false if it should be
601 bc_array_init(BcVec* a, bool nums);
604 * Copies an array to another array. This is used to do pass arrays to functions
605 * that do not take references to arrays. The arrays are passed entirely by
606 * value, which means that they need to be copied.
607 * @param d The destination array.
608 * @param s The source array.
611 bc_array_copy(BcVec* d, const BcVec* s);
614 * Frees a string stored in a function. This is a destructor.
615 * @param string The string to free as a void pointer.
618 bc_string_free(void* string);
621 * Frees a constant stored in a function. This is a destructor.
622 * @param constant The constant to free as a void pointer.
625 bc_const_free(void* constant);
628 * Clears a result. It sets the type to BC_RESULT_TEMP and clears the union by
629 * clearing the BcNum in the union. This is to ensure that bc does not use
630 * uninitialized data.
631 * @param r The result to clear.
634 bc_result_clear(BcResult* r);
637 * Copies a result into another. This is done for things like duplicating the
638 * top of the results stack or copying the result of an assignment to put back
639 * on the results stack.
640 * @param d The destination result.
641 * @param src The source result.
644 bc_result_copy(BcResult* d, BcResult* src);
647 * Frees a result. This is a destructor.
648 * @param result The result to free as a void pointer.
651 bc_result_free(void* result);
654 * Expands an array to @a len. This can happen because in bc, you do not have to
655 * explicitly initialize elements of an array. If you access an element that is
656 * not initialized, the array is expanded to fit it, and all missing elements
657 * are initialized to 0 if they are numbers, or arrays with one element of 0.
658 * This function does that expansion.
659 * @param a The array to expand.
660 * @param len The length to expand to.
663 bc_array_expand(BcVec* a, size_t len);
668 * Returns non-zero if the bytecode instruction i is an assignment instruction.
669 * @param i The instruction to test.
670 * @return Non-zero if i is an assignment instruction, zero otherwise.
672 #define BC_INST_IS_ASSIGN(i) \
673 ((i) == BC_INST_ASSIGN || (i) == BC_INST_ASSIGN_NO_VAL)
676 * Returns true if the bytecode instruction @a i requires the value to be
678 * @param i The instruction to test.
679 * @return True if @a i requires the value to be returned for use, false
682 #define BC_INST_USE_VAL(i) ((i) <= BC_INST_ASSIGN)
687 * Returns non-zero if the bytecode instruction i is an assignment instruction.
688 * @param i The instruction to test.
689 * @return Non-zero if i is an assignment instruction, zero otherwise.
691 #define BC_INST_IS_ASSIGN(i) ((i) == BC_INST_ASSIGN_NO_VAL)
694 * Returns true if the bytecode instruction @a i requires the value to be
696 * @param i The instruction to test.
697 * @return True if @a i requires the value to be returned for use, false
700 #define BC_INST_USE_VAL(i) (false)
705 /// Reference to string names for all of the instructions. For debugging.
706 extern const char* bc_inst_names[];
707 #endif // BC_DEBUG_CODE
709 /// References to the names of the main and read functions.
710 extern const char bc_func_main[];
711 extern const char bc_func_read[];