From 6496152f573d6b1e2e93d0a9b546403d8b183f8e Mon Sep 17 00:00:00 2001 From: Clyne Sullivan Date: Wed, 8 Nov 2023 07:37:43 -0500 Subject: add doxygen support --- libalee/dictionary.hpp | 197 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 137 insertions(+), 60 deletions(-) (limited to 'libalee/dictionary.hpp') 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 - * - * 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 . - */ +// +/// @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 +// +// 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 . #ifndef ALEEFORTH_DICTIONARY_HPP #define ALEEFORTH_DICTIONARY_HPP @@ -27,103 +29,175 @@ #include /** - * 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 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(c1))) c1 |= 32; -- cgit v1.2.3 From 0810456e9c5c19a47511a682eeabc71008632a2c Mon Sep 17 00:00:00 2001 From: Clyne Sullivan Date: Thu, 9 Nov 2023 06:39:02 -0500 Subject: MaxDistance constant; some .cpp comments --- libalee/corewords.cpp | 4 ++-- libalee/dictionary.cpp | 12 ++++++------ libalee/dictionary.hpp | 8 ++++---- libalee/parser.cpp | 10 +++++++++- libalee/types.cpp | 1 + 5 files changed, 22 insertions(+), 13 deletions(-) (limited to 'libalee/dictionary.hpp') diff --git a/libalee/corewords.cpp b/libalee/corewords.cpp index 534f1da..661590f 100644 --- a/libalee/corewords.cpp +++ b/libalee/corewords.cpp @@ -154,11 +154,11 @@ execute: cell = state.pop(); dcell = cell - state.dict.latest(); - if (dcell > (1 << (sizeof(Cell) * 8 - 6)) - 1) { + if (dcell >= Dictionary::MaxDistance) { // Large distance to previous entry: store in dedicated cell. state.dict.write(static_cast(cell) + sizeof(Cell), static_cast(dcell)); - dcell = ((1 << (sizeof(Cell) * 8 - 6)) - 1); + dcell = Dictionary::MaxDistance; } state.dict.write(cell, (state.dict.read(cell) & 0x1F) | static_cast(dcell << 6)); diff --git a/libalee/dictionary.cpp b/libalee/dictionary.cpp index 6c359bd..f2ad231 100644 --- a/libalee/dictionary.cpp +++ b/libalee/dictionary.cpp @@ -37,7 +37,7 @@ Addr Dictionary::allot(Cell amount) noexcept if (neww < capacity()) { write(Here, static_cast(neww)); } else { - // TODO + // TODO how to handle allot failure? Error code? } return old; @@ -64,7 +64,7 @@ void Dictionary::addDefinition(Word word) noexcept Cell wsize = word.size(); add(wsize); - if (alignhere() - latest() >= ((1 << (sizeof(Cell) * 8 - 6)) - 1)) + if (alignhere() - latest() >= MaxDistance) add(0); auto addr = allot(wsize); @@ -86,7 +86,7 @@ Addr Dictionary::find(Word word) noexcept const Addr len = l & 0x1F; Word lw; - if ((l >> 6) < 1023) { + if ((l >> 6) < MaxDistance) { lw = Word::fromLength(lt + sizeof(Cell), len); if (equal(word, lw)) return lt; @@ -114,7 +114,7 @@ Addr Dictionary::getexec(Addr addr) noexcept const Addr len = l & 0x1Fu; addr += sizeof(Cell); - if ((l >> 6) == 1023) + if ((l >> 6) == MaxDistance) addr += sizeof(Cell); addr += len; @@ -125,7 +125,7 @@ bool Dictionary::hasInput() const noexcept { const Addr src = read(Dictionary::Source); const Addr end = read(Dictionary::SourceLen); - uint8_t idx = read(Dictionary::Input) & 0xFFu; + auto idx = static_cast(read(Dictionary::Input)); while (idx < end) { auto ch = readbyte(src + idx); @@ -146,7 +146,7 @@ Word Dictionary::input() noexcept { const Addr src = read(Dictionary::Source); const Addr end = read(Dictionary::SourceLen); - uint8_t idx = read(Dictionary::Input) & 0xFFu; + auto idx = static_cast(read(Dictionary::Input)); Addr wstart = src + idx; Addr wend = wstart; diff --git a/libalee/dictionary.hpp b/libalee/dictionary.hpp index 7cf1c9d..f6f6bbe 100644 --- a/libalee/dictionary.hpp +++ b/libalee/dictionary.hpp @@ -41,7 +41,7 @@ * - 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. + * - If bits 6..15 are all one-bits then "long" distance in following cell. * - "Length" bytes of name * - Zero or more bytes for address alignment * - Zero or more bytes of the definition's contents @@ -70,10 +70,10 @@ public: /** Stores the dictionary's "beginning" i.e. where new definitions begin. */ constexpr static Addr Begin = sizeof(Cell) * 8 + InputCells; - /** - * The "immediate" identifier bit used in a definition's information cell. - */ + /** "Immediate" marker bit for a word's definition. */ constexpr static Cell Immediate = (1 << 5); + /** Maximum "short" distance between two definitions. */ + constexpr static Cell MaxDistance = (1 << (sizeof(Cell) * 8 - 6)) - 1; /** Returns the value of the cell at the given address. */ virtual Cell read(Addr) const noexcept = 0; diff --git a/libalee/parser.cpp b/libalee/parser.cpp index 328198a..3699d5f 100644 --- a/libalee/parser.cpp +++ b/libalee/parser.cpp @@ -29,14 +29,17 @@ Error Parser::parse(State& state, const char *str) { auto addr = Dictionary::Input; + // Set source and input length const auto len = static_cast(std::strlen(str)); state.dict.write(addr, 0); state.dict.write(Dictionary::SourceLen, len); + // Fill input buffer with string contents addr += sizeof(Cell); while (*str) state.dict.writebyte(addr++, *str++); + // Zero the remaining input buffer while (addr < Dictionary::Input + Dictionary::InputCells) state.dict.writebyte(addr++, '\0'); @@ -56,8 +59,10 @@ Error Parser::parseSource(State& state) Error Parser::parseWord(State& state, Word word) { bool imm; - Addr ins = state.dict.find(word); + Addr ins; + // Search order: dictionary, core word-set, number, custom parse. + ins = state.dict.find(word); if (ins == 0) { auto cw = CoreWords::findi(state, word); @@ -121,6 +126,9 @@ void Parser::processLiteral(State& state, Cell value) if (state.compiling()) { constexpr auto ins = CoreWords::token("_lit"); + // Literal compression: opcodes between WordCount and Begin are unused, + // so we assign literals to them to save space. Opcode "WordCount" + // pushes zero to the stack, "WordCount + 1" pushes a one, etc. const Cell maxlit = Dictionary::Begin - CoreWords::WordCount; if (value >= 0 && value < maxlit) value += CoreWords::WordCount; diff --git a/libalee/types.cpp b/libalee/types.cpp index 83cf1f7..bfff2ae 100644 --- a/libalee/types.cpp +++ b/libalee/types.cpp @@ -56,3 +56,4 @@ bool Word::iterator::operator!=(const iterator& other) { return dict != other.dict || addr != other.addr; } + -- cgit v1.2.3