bitgloo/alee-forth
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

add doxygen support

Browse Source
This commit is contained in:
Clyne 2023-11-08 07:37:43 -05:00
parent d6ee894c13
commit 6496152f57
Signed by: clyne
GPG Key ID: 1B74EE6C49C96795
10 changed files with 2781 additions and 219 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -8,5 +8,6 @@ alee-msp430
alee-standalone
libalee.a
core.fth.h
doc/
msp430/lzss
msp430/msp430fr2476_all.h

2303
Doxyfile Normal file
View File

File diff suppressed because it is too large Load Diff

3
alee.hpp
View File

@ -1,3 +1,6 @@
/// @file alee.hpp
/// @brief Single header to include all of Alee Forth
#include "libalee/parser.hpp"
#include "libalee/state.hpp"

81
libalee/corewords.hpp
View File

@ -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)
{

44
libalee/ctype.hpp
View File

@ -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');
}

209
libalee/dictionary.hpp
View File

@ -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;
/**
* The "immediate" identifier bit used in a definition's information cell.
*/
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.
*/
/** 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); }
void here(Addr l) noexcept { write(Here, l); }
Addr latest() const noexcept { return read(Latest); }
void latest(Addr l) noexcept { write(Latest, l); }
// Aligns the given address.
static Addr aligned(Addr);
// Aligns `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.
* Sets the address stored in `here`.
*/
void addDefinition(Word) noexcept;
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 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;
/**
* 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 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;

79
libalee/parser.hpp
View File

@ -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

117
libalee/state.hpp
View File

@ -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

114
libalee/types.hpp
View File

@ -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&);
};
};

49
memdict.hpp
View File

@ -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 memdict.hpp
/// @brief Simple dictionary implementation using a large memory block.
//
// 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_MEMDICT_HPP
#define ALEEFORTH_MEMDICT_HPP
@ -22,31 +24,44 @@
#include "alee.hpp"
#ifndef MEMDICTSIZE
/** Default dictionary size in bytes. */
#define MEMDICTSIZE (65536)
#endif
/** Size in bytes of a MemDict. */
constexpr unsigned long int MemDictSize = MEMDICTSIZE;
/**
* @class MemDict
* Dictionary implementation that uses a large block of memory.
*/
class MemDict : public Dictionary
{
/** Block of memory to contain dictionary's contents. */
uint8_t dict[MemDictSize] = {0};
public:
/** Returns the value of the cell at the given address. */
virtual Cell read(Addr addr) const noexcept final {
return *reinterpret_cast<const Cell *>(dict + addr);
}
/** Writes the given value to the cell at the given address. */
virtual void write(Addr addr, Cell value) noexcept final {
*reinterpret_cast<Cell *>(dict + addr) = value;
}
/** Returns the value of the byte at the given address. */
virtual uint8_t readbyte(Addr addr) const noexcept final {
return dict[addr];
}
/** Writes the given value to the byte at the given address. */
virtual void writebyte(Addr addr, uint8_t value) noexcept final {
dict[addr] = value;
}
/** Returns the size of the dictionary's memory block. */
virtual unsigned long int capacity() const noexcept final {
return sizeof(dict);
}