diff options
Diffstat (limited to 'libalee')
| -rw-r--r-- | libalee/corewords.hpp | 81 | ||||
| -rw-r--r-- | libalee/ctype.hpp | 44 | ||||
| -rw-r--r-- | libalee/dictionary.hpp | 197 | ||||
| -rw-r--r-- | libalee/parser.hpp | 79 | ||||
| -rw-r--r-- | libalee/state.hpp | 117 | ||||
| -rw-r--r-- | libalee/types.hpp | 116 |
6 files changed, 437 insertions, 197 deletions
diff --git a/libalee/corewords.hpp b/libalee/corewords.hpp index 25f6a6e..d134bbb 100644 --- a/libalee/corewords.hpp +++ b/libalee/corewords.hpp @@ -1,20 +1,22 @@ -/** - * Alee Forth: A portable and concise Forth implementation in modern C++. - * Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see <https://www.gnu.org/licenses/>. - */ +// +/// @file corewords.hpp +/// @brief Manages the fundamental word-set and its execution. +// +// Alee Forth: A portable and concise Forth implementation in modern C++. +// Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Lesser General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. #ifndef ALEEFORTH_COREWORDS_HPP #define ALEEFORTH_COREWORDS_HPP @@ -27,29 +29,56 @@ /** * To be implemented by the user, this function is called when the `sys` word * is executed. + * @param state Current execution state object. */ -void user_sys(State&); +void user_sys(State& state); +/** + * @class CoreWords + * @brief Provides the fundamental word-set and manages its execution. + */ class CoreWords { public: + /** + * Count of total fundamental words. + */ constexpr static Cell WordCount = 37; + + /** + * Token/index of the semicolon word (";"). + */ constexpr static Cell Semicolon = 26; /** - * Finds execution token that corresponds to the given word. - * Returns -1 if not found. + * Searches for the token/index of the given word if it is part of the + * fundamental word-set. + * @param state Current execution state object. + * @param word Word (stored in state's dictionary memory) to look up. + * @return The token/index of the word or -1 if not found. + */ + static Cell findi(State& state, Word word); + + /** + * Looks up the token/index of the given fundamental word. + * Can evaluate at compile-time. + * @param word The word to look up. + * @return The token/index of the word or -1 if not found. */ - static Cell findi(State&, Word); consteval static Cell findi(const char *word) { return findi(word, std::strlen(word)); } /** - * Executes the given CoreWord execution token using the given state. + * Executes the given execution token using the given state. + * @param token Any valid execution token (word, fundamental, constant...). + * @param state The state object to execute with. */ - static void run(Cell, State&); + static void run(Cell token, State& state); + /** + * String lookup table for the fundamental word-set. + */ constexpr static char wordsarr[] = "_lit\0drop\0dup\0swap\0pick\0sys\0" "+\0-\0m*\0_/\0_%\0" @@ -61,6 +90,12 @@ public: "_uma\0u<\0um/mod\0"; private: + /** + * Generic implementation of findi(). Private; use public implementations. + * @param it Beginning iterator of the word to search for. + * @param size Size of the searched-for word i.e. end == it + size. + * @return The token/index of the word or -1 if not found. + */ template<typename Iter> constexpr static Cell findi(Iter it, std::size_t size) { diff --git a/libalee/ctype.hpp b/libalee/ctype.hpp index 878c747..5252eda 100644 --- a/libalee/ctype.hpp +++ b/libalee/ctype.hpp @@ -1,42 +1,44 @@ -/** - * Alee Forth: A portable and concise Forth implementation in modern C++. - * Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see <https://www.gnu.org/licenses/>. - */ +// +/// @file ctype.hpp +/// @brief Simple implementations of character comparison functions. +// +// Alee Forth: A portable and concise Forth implementation in modern C++. +// Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Lesser General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. #ifndef ALEEFORTH_CTYPE_HPP #define ALEEFORTH_CTYPE_HPP -/** - * We implement our own character comparison functions to keep them lean. - */ - #include <cstdint> +/** Tests if given character represents whitespace. */ constexpr inline bool isspace(uint8_t c) { return c == ' ' || c == '\t' || c == '\r' || c == '\n'; } +/** Tests if given character is a numerical digit. */ constexpr inline bool isdigit(uint8_t c) { return c >= '0' && c <= '9'; } +/** Tests if given character is an uppercase letter. */ constexpr inline bool isupper(uint8_t c) { return c >= 'A' && c <= 'Z'; } +/** Tests if given character is a letter. */ constexpr inline bool isalpha(uint8_t c) { return isupper(c) || (c >= 'a' && c <= 'z'); } diff --git a/libalee/dictionary.hpp b/libalee/dictionary.hpp index 2b7afdf..7cf1c9d 100644 --- a/libalee/dictionary.hpp +++ b/libalee/dictionary.hpp @@ -1,20 +1,22 @@ -/** - * Alee Forth: A portable and concise Forth implementation in modern C++. - * Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see <https://www.gnu.org/licenses/>. - */ +// +/// @file dictionary.hpp +/// @brief Defines the dictionary interface and common functionality. +// +// Alee Forth: A portable and concise Forth implementation in modern C++. +// Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Lesser General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. #ifndef ALEEFORTH_DICTIONARY_HPP #define ALEEFORTH_DICTIONARY_HPP @@ -27,103 +29,175 @@ #include <cstdint> /** - * Dictionary entry format: - * - 1 information byte - * bits 0..4: Length of name (L) - * bit 5: Immediate? - * bits 6..15: Distance to next entry (negative) - * - L bytes of name - * - 0+ bytes for address alignment - * - 0+ bytes of entry's data... + * @class Dictionary + * @brief Provides an interface and essential funcitonality for a dictionary. + * @details The core read and write functionality is left virtual so that + * dictionaries can be stored in any medium. So, this class cannot be used + * directly; the programmer must define a dictionary class that inherits this + * one. + * + * Dictionary entry format (for a 16-bit implementation): + * - One information cell: + * - bits 0..4: Length of name + * - bit 5: Set if word is immediate + * - bits 6..15: Distance (backwards) to the next entry + * - If bits 6..15 are all one-bits then distance is in the following cell. + * - "Length" bytes of name + * - Zero or more bytes for address alignment + * - Zero or more bytes of the definition's contents */ - class Dictionary { public: - /** - * The beginning of the dictionary is used for "internal" variables. - */ + /** Stores Numerical base to use for input/output. */ constexpr static Addr Base = 0; + /** Stores the current `here` address. */ constexpr static Addr Here = sizeof(Cell); + /** Stores the address of the most recently defined word. */ constexpr static Addr Latest = sizeof(Cell) * 2; + /** Stores a boolean indication of compiling state. */ constexpr static Addr Compiling = sizeof(Cell) * 3; + /** Stores the address of the last execution token determined by colon. */ constexpr static Addr CompToken = sizeof(Cell) * 4; + /** Stores the address of the current interpreter input source. */ constexpr static Addr Source = sizeof(Cell) * 5; + /** Stores the size in bytes of the interpreter input source. */ constexpr static Addr SourceLen = sizeof(Cell) * 6; - constexpr static Addr Input = sizeof(Cell) * 7; // len data... - constexpr static Addr InputCells = 80; // bytes! + /** Stores the dictionary's input buffer (a counted string). */ + constexpr static Addr Input = sizeof(Cell) * 7; + /** Stores the size of the dictionary's input buffer in bytes. */ + constexpr static Addr InputCells = 80; + /** Stores the dictionary's "beginning" i.e. where new definitions begin. */ constexpr static Addr Begin = sizeof(Cell) * 8 + InputCells; - constexpr static Cell Immediate = (1 << 5); - /** - * Dictionary data can be stored on any read-write interface. - * You must create a dictionary class that inherits Dictionary and - * implement these functions. See `memdict.hpp` for a simple block-of- - * memory implementation. + * The "immediate" identifier bit used in a definition's information cell. */ + constexpr static Cell Immediate = (1 << 5); + + /** Returns the value of the cell at the given address. */ virtual Cell read(Addr) const noexcept = 0; + + /** Writes the given value to the cell at the given address. */ virtual void write(Addr, Cell) noexcept = 0; + + /** Returns the byte stored at the given address. */ virtual uint8_t readbyte(Addr) const noexcept = 0; + + /** Writes the given byte to the given address. */ virtual void writebyte(Addr, uint8_t) noexcept = 0; + + /** Returns the total capacity of the dictionary in bytes. */ virtual unsigned long int capacity() const noexcept = 0; /** - * Does initial dictionary setup, required before use for execution. + * Initializes essential dictionary values. + * Must be called before dictionary use. */ void initialize(); + /** + * Gets the address stored in `here`. + */ Addr here() const noexcept { return read(Here); } + + /** + * Sets the address stored in `here`. + */ void here(Addr l) noexcept { write(Here, l); } + /** + * Gets the value of `latest`. + */ Addr latest() const noexcept { return read(Latest); } + + /** + * Sets the value of `latest`. + */ void latest(Addr l) noexcept { write(Latest, l); } - // Aligns the given address. - static Addr aligned(Addr); - // Aligns `here`. + /** + * Aligns the given address to the next Cell boundary if necessary. + * @param addr The address to align. + * @return The resulting aligned address. + */ + static Addr aligned(Addr addr); + + /** + * Aligns `here` to the next Cell boundary if necessary. + * @return The new aligned address stored in `here`. + */ Addr alignhere() noexcept; - // Advances `here` by the given number of bytes. - Addr allot(Cell) noexcept; - // Stores value to `here`, then adds sizeof(Cell) to `here`. - void add(Cell) noexcept; /** - * Uses add() to store a new definition entry starting at `here`. - * The entry does not become active until a semicolon is executed. + * Allocates memory by returning and then increasing the current `here`. + * @param count The number of bytes to increase `here` by. + * @return The address stored in `here` before the increase. + */ + Addr allot(Cell count) noexcept; + + /** + * Stores the given value to `here` then calls allot to "save" that cell. + * @param value The value to store. + * @see allot(Cell) */ - void addDefinition(Word) noexcept; + void add(Cell value) noexcept; + + /** + * Stores the beginning of a new word definition in the dictionary. + * The word must eventually have its definition concluded via semicolon. + * @param word The dictionary-stored name of the new word. + */ + void addDefinition(Word word) noexcept; /** * Searches the dictionary for an entry for the given word. - * Returns zero if not found. + * @param word The dictionary-stored word to search for. + * @return The beginning address of the word or zero if not found. */ - Addr find(Word) noexcept; + Addr find(Word word) noexcept; /** - * Given the address of a dictionary entry, produces the execution token - * for that entry. + * Produces the execution token for the given dictionary entry. + * @param addr The beginning address of a defined word. + * @return The execution token for the given word. + * @see find(Word) */ - Addr getexec(Addr) noexcept; + Addr getexec(Addr addr) noexcept; /** * Reads the next word from the input buffer. - * Returns an empty word if the buffer is empty or entirely read. + * @return The next word or an empty word if one is not available. */ Word input() noexcept; + + /** + * Returns true if the dictionary's input buffer has immediately available + * data. + */ bool hasInput() const noexcept; /** - * Checks if this dictionary's word is equivalent to the given string/size. + * Checks if the dictionary-stored word is equivalent to the given string. + * @param word Dictionary-stored word to compare against. + * @param str String to compare to. + * @param size Size of the string to compare to. + * @return True if the two words are equivalent. */ - bool equal(Word, const char *, unsigned) const noexcept; + bool equal(Word word, const char *str, unsigned size) const noexcept; /** - * Checks if two words in this dictionary's word are equivalent. + * Checks if two words stored in this dictionary are equivalent. + * @param word1 First word to compare + * @param word2 Second word to compare + * @return True if the words are equivalent. */ - bool equal(Word, Word) const noexcept; + bool equal(Word word1, Word word2) const noexcept; - // Used for case-insensitive comparison between two iterators. + /** + * Generic equality comparison using our own case-insensitive comparator. + * Arguments and return value identical to std::equal. + */ template<typename Iter1, typename Iter2> constexpr static bool equal(Iter1 b1, Iter1 e1, Iter2 b2) { return std::equal(b1, e1, b2, eqchars); @@ -132,7 +206,10 @@ public: virtual ~Dictionary() = default; private: - // Case-insensitive comparison. + /** + * Case-insensitive character comparison used for dictionary lookup. + * @return True if the characters are equivalent. + */ constexpr static bool eqchars(char c1, char c2) { if (isalpha(static_cast<uint8_t>(c1))) c1 |= 32; diff --git a/libalee/parser.hpp b/libalee/parser.hpp index f868afb..06ba8fc 100644 --- a/libalee/parser.hpp +++ b/libalee/parser.hpp @@ -1,20 +1,22 @@ -/** - * Alee Forth: A portable and concise Forth implementation in modern C++. - * Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see <https://www.gnu.org/licenses/>. - */ +// +/// @file parser.hpp +/// @brief Provides functions to parse text for interpretation/execution. +// +// Alee Forth: A portable and concise Forth implementation in modern C++. +// Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Lesser General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. #ifndef ALEEFORTH_PARSER_HPP #define ALEEFORTH_PARSER_HPP @@ -23,37 +25,60 @@ #include <string_view> +/** + * @class Parser + * @brief Provides routines for parsing Forth code. + */ class Parser { public: + /** + * Pointer to a user-provided function that + */ static Error (*customParse)(State&, Word); /** - * Parses (and evaluates) the given string using the given state. - * The string is stored in the state's input buffer, then parseSource() - * works through that using parseWord(). parseWord() will compile or - * execute as necessary. + * Parses and evaluates the given string using the given state. + * The string is stored in the state's input buffer before parseSource() + * is called. + * @param state The state to parse and evaluate with. + * @param str The string to parse. + * @return Error token to indicate if parsing was successful. + * @see parseSource(State&) */ - static Error parse(State&, const char *); + static Error parse(State& state, const char *str); /** - * Parses (and evaluates) through the words stored in the state's input - * buffer. + * Parses through and compiles or evaluates the words stored in the state's + * input source. + * @param state The state to parse with. + * @return Error token to indicate if parsing was successful. + * @see parseWord(State&, Word) */ - static Error parseSource(State&); + static Error parseSource(State& state); - static void processLiteral(State&, Cell); + /** + * Parses the given value and either pushes it to the stack or compiles + * that functionality. + * @param state The state to give the value to. + * @param value The value to process. + */ + static void processLiteral(State& state, Cell value); private: /** * Parses the given word using the given state. + * @return Error token to indicate if parsing was successful. */ static Error parseWord(State&, Word); /** * Attempts to parse the given word into a number. + * @param state The state object with the dictionary containing the word. + * @param word The dictionary-stored word (number) to parse. + * @return Error token to indicate if parsing was successful. */ - static Error parseNumber(State&, Word); + static Error parseNumber(State& state, Word word); }; #endif // ALEEFORTH_PARSER_HPP diff --git a/libalee/state.hpp b/libalee/state.hpp index e77a223..60ff95f 100644 --- a/libalee/state.hpp +++ b/libalee/state.hpp @@ -1,20 +1,22 @@ -/** - * Alee Forth: A portable and concise Forth implementation in modern C++. - * Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see <https://www.gnu.org/licenses/>. - */ +// +/// @file state.hpp +/// @brief Provides object to manage execution and interpretation state. +// +// Alee Forth: A portable and concise Forth implementation in modern C++. +// Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Lesser General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. #ifndef ALEEFORTH_STATE_HPP #define ALEEFORTH_STATE_HPP @@ -25,31 +27,53 @@ #include <csetjmp> #include <cstddef> +/** + * Size of the primary data stack, number of cells. + */ constexpr unsigned DataStackSize = 64; + +/** + * Size of the return stack, number of cells. + */ constexpr unsigned ReturnStackSize = 64; +/** + * @class State + * Object to track execution state. + */ class State { + /** Input functions should add input to the input buffer when available. */ using InputFunc = void (*)(State&); + /** Context object that defines a state of execution. */ struct Context { - Addr ip = 0; - std::jmp_buf jmpbuf = {}; + Addr ip = 0; /** Instruction pointer */ + std::jmp_buf jmpbuf = {}; /** setjmp() buffer for exiting execute() */ }; public: + /** Reference to dictionary used by this state. */ Dictionary& dict; + /** + * Constructs a state object that uses the given dictionary and input + * function. + * @param d The dictionary to be used by this state + * @param i The input collection function to be used by this state + */ constexpr State(Dictionary& d, InputFunc i): dict(d), inputfunc(i), context() {} /** - * Begins execution at the given execution token. + * Begins execution starting from the given execution token. * If the token is a CoreWord, this function exits after its execution. * Otherwise, execution continues until the word's execution completes. * Encountering an error will cause this function to exit immediately. + * @param addr The token to be executed + * @return An error token to indicate if execution was successful */ - Error execute(Addr); + Error execute(Addr addr); /** * Clears the data and return stacks, sets ip to zero, and clears the @@ -57,23 +81,28 @@ public: */ void reset(); + /** Returns a reference to the instruction pointer. */ Addr& ip() noexcept { return context.ip; } + /** Calls the user input function with this state as the argument. */ void input() noexcept { inputfunc(*this); } + /** Returns true if currently in a compiling state. */ bool compiling() const; + /** Sets the compiling state. True if compiling, false if interpreting. */ void compiling(bool); + /** Returns the number of values stored on the data stack. */ std::size_t size() const noexcept; + /** Returns the number of values stored on the return stack. */ std::size_t rsize() const noexcept; /** - * Saves execution state so that a new execution can begin. - * Used for EVALUATE. + * Returns the current execution state. Usually followed by a load() call. */ Context save(); @@ -82,55 +111,83 @@ public: */ void load(const Context&); + /** + * Pushes the given value to the data stack. + */ inline void push(Cell value) { verify(dsp < dstack + DataStackSize, Error::push); *dsp++ = value; } + /** + * Pops a value from the data stack and returns that value. + */ inline Cell pop() { verify(dsp > dstack, Error::pop); return *--dsp; } + /** + * Pushes the given value to the return stack. + */ inline void pushr(Cell value) { verify(rsp < rstack + ReturnStackSize, Error::pushr); *rsp++ = value; } + /** + * Pops a value from the return stack and returns that value. + */ inline Cell popr() { verify(rsp > rstack, Error::popr); return *--rsp; } + /** + * Returns the value stored at the current data stack position. + */ inline Cell& top() { verify(dsp > dstack, Error::top); return *(dsp - 1); } + /** + * Picks a value currently stored on the data stack. + * @param i Index from current position to fetch from + * @return The value stored at the given index + */ inline Cell& pick(std::size_t i) { verify(dsp - i > dstack, Error::pick); return *(dsp - i - 1); } - // Advances the instruction pointer and returns that cell's contents. + /** + * Advances the instruction pointer and returns that cell's contents. + */ inline Cell beyondip() { context.ip += sizeof(Cell); return dict.read(context.ip); } + /** + * Asserts the given condition is true, longjmp-ing if false. + * Used as an exception handler and the method of exiting execution. + * @param condition Condition to be tested + * @param error Error code to report via longjmp() on false condition + */ inline void verify(bool condition, Error error) { if (!condition) std::longjmp(context.jmpbuf, static_cast<int>(error)); } private: - InputFunc inputfunc; // User-provided function to collect "stdin" input. - Context context; + InputFunc inputfunc; /** User-provided function to collect user input. */ + Context context; /** State's current execution context. */ - Cell dstack[DataStackSize] = {}; - Cell rstack[ReturnStackSize] = {}; - Cell *dsp = dstack; - Cell *rsp = rstack; + Cell dstack[DataStackSize] = {}; /** Data stack */ + Cell rstack[ReturnStackSize] = {}; /** Return stack */ + Cell *dsp = dstack; /** Current data stack position */ + Cell *rsp = rstack; /** Current return stack position */ }; #endif // ALEEFORTH_STATE_HPP diff --git a/libalee/types.hpp b/libalee/types.hpp index 4d86c5d..a122c84 100644 --- a/libalee/types.hpp +++ b/libalee/types.hpp @@ -1,20 +1,22 @@ -/** - * Alee Forth: A portable and concise Forth implementation in modern C++. - * Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see <https://www.gnu.org/licenses/>. - */ +// +/// @file types.hpp +/// @brief Defines common types used throughout Alee Forth. +// +// Alee Forth: A portable and concise Forth implementation in modern C++. +// Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Lesser General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. #ifndef ALEEFORTH_TYPES_HPP #define ALEEFORTH_TYPES_HPP @@ -22,54 +24,85 @@ #include <cstdint> #include <iterator> -/** - * Configure the below types for your platform. - */ +/** Dictionary address type. Must be equivalent to "unsigned Cell". */ using Addr = uint16_t; +/** Data cell type. Dictionary is basically an array of this type. */ using Cell = int16_t; +/** Double-width cell type. Must be twice the size of Cell. */ using DoubleCell = int32_t; -using DoubleAddr = uint32_t; // Only used for um/mod. +/** Double-width addr type. Must be twice the size of Addr. Used by um/mod. */ +using DoubleAddr = uint32_t; struct Dictionary; struct State; -using Func = void (*)(State&); - +/** + * Error enum to report success or failure of parsing or execution. + */ enum class Error : int { - none = 0, - push, - pop, - pushr, - popr, - top, - pick, - exit, - noword + none = 0, /** No error */ + push, /** Could not push (data stack overflow) */ + pop, /** Could not pop (data stack underflow) */ + pushr, /** Could not push (return stack overflow) */ + popr, /** Could not pop (return stack underflow) */ + top, /** Could not fetch data stack top (data stack underflow) */ + pick, /** Could not pick data stack value (data stack underflow) */ + exit, /** No error, exited from State::execute() */ + noword /** Parsing failed because the word was not found */ }; /** - * Stores the start and past-the-end addresses of a dictionary's word. + * @class Word + * Stores the beginning and end indices of a dictionary-defined word. */ class Word { + /** Beginning (inclusive) index */ Addr start; + /** End (exclusive) index */ Addr wend; public: struct iterator; + /** + * Constructs a word with the given start and end indices. + * @param s Start/beginning index + * @param e (past-the-)end index + */ constexpr explicit Word(Addr s = 0, Addr e = 0): start(s), wend(e) {} + /** + * Constructs a word using beginning index and length. + * @param s Beginning/start index of word + * @param l Count of bytes until end of word + * @return Resulting Word object + */ static constexpr Word fromLength(Addr s, Addr l) { return Word(s, s + l); } + /** Returns the size of this word in bytes. */ Addr size() const noexcept; - iterator begin(const Dictionary *); - iterator end(const Dictionary *); - + /** + * Creates a beginning iterator for the word. + * @param dict Pointer to dictionary object containing this word + * @return Iterator pointing to this word's beginning + */ + iterator begin(const Dictionary *dict); + + /** + * Creates an end iterator for the word. + * @param dict Pointer to dictionary object containing this word + * @return Iterator pointing to past-the-end of this word + */ + iterator end(const Dictionary *dict); + + /** + * Forward-iterator for iterating through the letters of this word. + */ struct iterator { using iterator_category = std::input_iterator_tag; using value_type = uint8_t; @@ -77,15 +110,26 @@ public: using reference = void; using difference_type = Cell; + /** Iterator's current address within its containing dictionary. */ Addr addr; + /** Pointer to dictionary that contains this word. */ const Dictionary *dict; + /** + * Constructs a word iterator. + * @param a The address the iterator points to + * @param d The dictionary that contains this word + */ constexpr iterator(Addr a, const Dictionary *d): addr(a), dict(d) {} + /** Prefix increment */ iterator& operator++(); + /** Postfix increment */ iterator operator++(int); + /** Returns value pointed to by iterator */ value_type operator*(); + /** Iterator comparison function (case-insensitive) */ bool operator!=(const iterator&); }; }; |