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

Merge branch 'documentation'

Browse Source
master
Clyne 1 year ago
parent 23d746d646 0810456e9c
commit ebbde43fa9
12 changed files with 2879 additions and 300 deletions
Show Stats Download Patch File Download Diff File

1
.gitignore vendored
Unescape Escape View File

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

2303
Doxyfile
View File

File diff suppressed because it is too large Load Diff

152
libalee/corewords.cpp
Unescape Escape View File

@ -20,22 +20,9 @@
#include <utility> #include <utility>
LIBALEE_SECTION static void find(State&, Word);
void find(State& state, Word word) static DoubleCell popd(State&);
{ static void pushd(State&, DoubleCell);
Cell tok = 0;
Cell imm = 0;
if (auto j = state.dict.find(word); j > 0) {
tok = state.dict.getexec(j);
imm = (state.dict.read(j) & Dictionary::Immediate) ? 1 : -1;
} else if (tok = CoreWords::findi(state, word); tok >= 0) {
imm = (tok == CoreWords::Semicolon) ? 1 : -1;
}
state.push(tok);
state.push(imm);
}
LIBALEE_SECTION LIBALEE_SECTION
void CoreWords::run(Cell ins, State& state) void CoreWords::run(Cell ins, State& state)
@ -44,21 +31,8 @@ void CoreWords::run(Cell ins, State& state)
DoubleCell dcell; DoubleCell dcell;
Addr index = ins; Addr index = ins;
auto& ip = state.ip(); auto& ip = state.ip();
auto popd = [](State& s) {
DoubleCell dcell = s.pop();
dcell <<= sizeof(Cell) * 8;
dcell |= static_cast<Addr>(s.pop());
return dcell;
};
auto pushd = [](State& s, DoubleCell d) {
s.push(static_cast<Cell>(d));
s.push(static_cast<Cell>(d >> (sizeof(Cell) * 8)));
};
execute: execute:
if (index >= Dictionary::Begin) { if (index >= Dictionary::Begin) {
// must be calling a defined subroutine // must be calling a defined subroutine
@ -66,95 +40,95 @@ execute:
ip = index; ip = index;
return; return;
} else switch (index) { } else switch (index) {
case 0: // _lit case token("_lit"): // Execution semantics of `literal`.
state.push(state.beyondip()); state.push(state.beyondip());
break; break;
case 1: // drop case token("drop"):
state.pop(); state.pop();
break; break;
case 2: // dup case token("dup"):
state.push(state.top()); state.push(state.top());
break; break;
case 3: // swap case token("swap"):
std::swap(state.top(), state.pick(1)); std::swap(state.top(), state.pick(1));
break; break;
case 4: // pick case token("pick"):
state.push(state.pick(state.pop())); state.push(state.pick(state.pop()));
break; break;
case 5: // sys case token("sys"): // Calls user-defined "system" handler.
user_sys(state); user_sys(state);
break; break;
case 6: // add case token("+"):
cell = state.pop(); cell = state.pop();
state.top() += cell; state.top() += cell;
break; break;
case 7: // sub case token("-"):
cell = state.pop(); cell = state.pop();
state.top() -= cell; state.top() -= cell;
break; break;
case 8: // mul ( n n -- d ) case token("m*"): // ( n n -- d )
cell = state.pop(); cell = state.pop();
dcell = state.pop() * cell; dcell = state.pop() * cell;
pushd(state, dcell); pushd(state, dcell);
break; break;
case 9: // div ( d n -- n ) case token("_/"): // ( d n -- n )
cell = state.pop(); cell = state.pop();
dcell = popd(state); dcell = popd(state);
state.push(static_cast<Cell>(dcell / cell)); state.push(static_cast<Cell>(dcell / cell));
break; break;
case 10: // mod ( d n -- n ) case token("_%"): // ( d n -- n )
cell = state.pop(); cell = state.pop();
dcell = popd(state); dcell = popd(state);
state.push(static_cast<Cell>(dcell % cell)); state.push(static_cast<Cell>(dcell % cell));
break; break;
case 11: // peek case token("_@"): // ( addr cell? -- n )
if (state.pop()) if (state.pop())
state.push(state.dict.read(state.pop())); state.push(state.dict.read(state.pop()));
else else
state.push(state.dict.readbyte(state.pop())); state.push(state.dict.readbyte(state.pop()));
break; break;
case 12: // poke case token("_!"): // ( n addr cell? -- )
cell = state.pop(); cell = state.pop();
if (auto addr = state.pop(); cell) if (auto addr = state.pop(); cell)
state.dict.write(addr, state.pop()); state.dict.write(addr, state.pop());
else else
state.dict.writebyte(addr, state.pop() & 0xFFu); state.dict.writebyte(addr, state.pop() & 0xFFu);
break; break;
case 13: // pushr case token(">r"):
state.pushr(state.pop()); state.pushr(state.pop());
break; break;
case 14: // popr case token("r>"):
state.push(state.popr()); state.push(state.popr());
break; break;
case 15: // equal case token("="):
cell = state.pop(); cell = state.pop();
state.top() = state.top() == cell ? -1 : 0; state.top() = state.top() == cell ? -1 : 0;
break; break;
case 16: // lt case token("<"):
cell = state.pop(); cell = state.pop();
state.top() = state.top() < cell ? -1 : 0; state.top() = state.top() < cell ? -1 : 0;
break; break;
case 17: // and case token("&"):
cell = state.pop(); cell = state.pop();
state.top() &= cell; state.top() &= cell;
break; break;
case 18: // or case token("|"):
cell = state.pop(); cell = state.pop();
state.top() |= cell; state.top() |= cell;
break; break;
case 19: // xor case token("^"):
cell = state.pop(); cell = state.pop();
state.top() ^= cell; state.top() ^= cell;
break; break;
case 20: // shl case token("<<"):
cell = state.pop(); cell = state.pop();
reinterpret_cast<Addr&>(state.top()) <<= static_cast<Addr>(cell); reinterpret_cast<Addr&>(state.top()) <<= static_cast<Addr>(cell);
break; break;
case 21: // shr case token(">>"):
cell = state.pop(); cell = state.pop();
reinterpret_cast<Addr&>(state.top()) >>= static_cast<Addr>(cell); reinterpret_cast<Addr&>(state.top()) >>= static_cast<Addr>(cell);
break; break;
case 22: // colon case token(":"): // Begins definition/compilation of new word.
state.push(state.dict.alignhere()); state.push(state.dict.alignhere());
state.dict.write(Dictionary::CompToken, state.top()); state.dict.write(Dictionary::CompToken, state.top());
while (!state.dict.hasInput()) while (!state.dict.hasInput())
@ -162,50 +136,53 @@ execute:
state.dict.addDefinition(state.dict.input()); state.dict.addDefinition(state.dict.input());
state.compiling(true); state.compiling(true);
break; break;
case 23: // tick case token("_'"): // Collects input word and finds execution token.
while (!state.dict.hasInput()) while (!state.dict.hasInput())
state.input(); state.input();
find(state, state.dict.input()); find(state, state.dict.input());
break; break;
case 24: // execute case token("execute"):
index = state.pop(); index = state.pop();
goto execute; goto execute;
case 25: // exit case token("exit"):
ip = state.popr(); ip = state.popr();
state.verify(ip != 0, Error::exit); state.verify(ip != 0, Error::exit);
break; break;
case 26: // semic case token(";"): // Concludes word definition.
state.dict.add(findi("exit")); state.dict.add(token("exit"));
state.compiling(false); state.compiling(false);
cell = state.pop(); cell = state.pop();
dcell = cell - state.dict.latest(); dcell = cell - state.dict.latest();
if (dcell > (1 << (sizeof(Cell) * 8 - 6)) - 1) { if (dcell >= Dictionary::MaxDistance) {
state.dict.write(static_cast<Addr>(cell) + sizeof(Cell), static_cast<Cell>(dcell)); // Large distance to previous entry: store in dedicated cell.
dcell = ((1 << (sizeof(Cell) * 8 - 6)) - 1); state.dict.write(static_cast<Addr>(cell) + sizeof(Cell),
static_cast<Cell>(dcell));
dcell = Dictionary::MaxDistance;
} }
state.dict.write(cell, (state.dict.read(cell) & 0x1F) | static_cast<Cell>(dcell << 6)); state.dict.write(cell,
(state.dict.read(cell) & 0x1F) | static_cast<Cell>(dcell << 6));
state.dict.latest(cell); state.dict.latest(cell);
break; break;
case 27: // _jmp0 case token("_jmp0"): // Jump if popped value equals zero.
if (state.pop()) { if (state.pop()) {
state.beyondip(); state.beyondip();
break; break;
} }
[[fallthrough]]; [[fallthrough]];
case 28: // _jmp case token("_jmp"): // Unconditional jump.
ip = state.beyondip(); ip = state.beyondip();
return; return;
case 29: // depth case token("depth"):
state.push(static_cast<Cell>(state.size())); state.push(static_cast<Cell>(state.size()));
break; break;
case 30: // _rdepth case token("_rdepth"):
state.push(static_cast<Cell>(state.rsize())); state.push(static_cast<Cell>(state.rsize()));
break; break;
case 31: // _in case token("_in"): // Fetches more input from the user input source.
state.input(); state.input();
break; break;
case 32: // _ex case token("_ev"): // Evaluates words from current input source.
{ {
const auto st = state.save(); const auto st = state.save();
ip = 0; ip = 0;
@ -213,13 +190,13 @@ execute:
state.load(st); state.load(st);
} }
break; break;
case 33: // find case token("find"):
cell = state.pop(); cell = state.pop();
find(state, find(state,
Word::fromLength(static_cast<Addr>(cell + 1), Word::fromLength(static_cast<Addr>(cell + 1),
state.dict.readbyte(cell))); state.dict.readbyte(cell)));
break; break;
case 34: // _uma case token("_uma"): // ( d u u -- d ): Unsigned multiply-add.
{ {
const auto plus = state.pop(); const auto plus = state.pop();
cell = state.pop(); cell = state.pop();
@ -229,12 +206,12 @@ execute:
pushd(state, dcell); pushd(state, dcell);
} }
break; break;
case 35: // u< case token("u<"):
cell = state.pop(); cell = state.pop();
state.top() = static_cast<Addr>(state.top()) < state.top() = static_cast<Addr>(state.top()) <
static_cast<Addr>(cell) ? -1 : 0; static_cast<Addr>(cell) ? -1 : 0;
break; break;
case 36: // um/mod case token("um/mod"):
cell = state.pop(); cell = state.pop();
dcell = popd(state); dcell = popd(state);
@ -245,7 +222,7 @@ execute:
static_cast<DoubleAddr>(dcell) / static_cast<DoubleAddr>(dcell) /
static_cast<Addr>(cell))); static_cast<Addr>(cell)));
break; break;
default: default: // Compacted literals (WordCount <= ins < Begin).
state.push(ins - WordCount); state.push(ins - WordCount);
break; break;
} }
@ -259,3 +236,34 @@ Cell CoreWords::findi(State& state, Word word)
return findi(word.begin(&state.dict), word.size()); return findi(word.begin(&state.dict), word.size());
} }
LIBALEE_SECTION
void find(State& state, Word word)
{
Cell tok = 0;
Cell imm = 0;
if (auto j = state.dict.find(word); j > 0) {
tok = state.dict.getexec(j);
imm = (state.dict.read(j) & Dictionary::Immediate) ? 1 : -1;
} else if (tok = CoreWords::findi(state, word); tok >= 0) {
imm = (tok == CoreWords::token(";")) ? 1 : -1;
}
state.push(tok);
state.push(imm);
}
DoubleCell popd(State& s)
{
DoubleCell dcell = s.pop();
dcell <<= sizeof(Cell) * 8;
dcell |= static_cast<Addr>(s.pop());
return dcell;
}
void pushd(State& s, DoubleCell d)
{
s.push(static_cast<Cell>(d));
s.push(static_cast<Cell>(d >> (sizeof(Cell) * 8)));
}

90
libalee/corewords.hpp
Unescape Escape View File

@ -1,54 +1,78 @@
/** //
* Alee Forth: A portable and concise Forth implementation in modern C++. /// @file corewords.hpp
* Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> /// @brief Manages the fundamental word-set and its execution.
* //
* This program is free software: you can redistribute it and/or modify // Alee Forth: A portable and concise Forth implementation in modern C++.
* it under the terms of the GNU Lesser General Public License as published by // Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com>
* the Free Software Foundation, either version 3 of the License, or //
* (at your option) any later version. // 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
* This program is distributed in the hope that it will be useful, // the Free Software Foundation, either version 3 of the License, or
* but WITHOUT ANY WARRANTY; without even the implied warranty of // (at your option) any later version.
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
* GNU Lesser General Public License for more details. // This program is distributed in the hope that it will be useful,
* // but WITHOUT ANY WARRANTY; without even the implied warranty of
* You should have received a copy of the GNU Lesser General Public License // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* along with this program. If not, see <https://www.gnu.org/licenses/>. // 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 #ifndef ALEEFORTH_COREWORDS_HPP
#define ALEEFORTH_COREWORDS_HPP #define ALEEFORTH_COREWORDS_HPP
#include "config.hpp" #include "config.hpp"
#include "types.hpp"
#include "dictionary.hpp" #include "dictionary.hpp"
#include "types.hpp"
#include <algorithm>
class State;
/** /**
* To be implemented by the user, this function is called when the `sys` word * To be implemented by the user, this function is called when the `sys` word
* is executed. * 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 class CoreWords
{ {
public: public:
constexpr static Cell WordCount = 37; /**
constexpr static Cell Semicolon = 26; * 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);
/** /**
* Finds execution token that corresponds to the given word. * Looks up the token/index of the given fundamental word.
* Returns -1 if not found. * Primarily used for compile-time lookup.
* @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 token(const char *word) {
consteval static Cell findi(const char *word) {
return findi(word, strlen(word)); return findi(word, 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.
* This also determines the opcode (index) of these words.
*/
constexpr static char wordsarr[] = constexpr static char wordsarr[] =
"_lit\0drop\0dup\0swap\0pick\0sys\0" "_lit\0drop\0dup\0swap\0pick\0sys\0"
"+\0-\0m*\0_/\0_%\0" "+\0-\0m*\0_/\0_%\0"
@ -59,7 +83,19 @@ public:
"depth\0_rdepth\0_in\0_ev\0find\0" "depth\0_rdepth\0_in\0_ev\0find\0"
"_uma\0u<\0um/mod\0"; "_uma\0u<\0um/mod\0";
/**
* Count of total fundamental words.
*/
constexpr static Cell WordCount = [] {
return std::count(wordsarr, wordsarr + sizeof(wordsarr), '\0'); }();
private: 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> template<typename Iter>
LIBALEE_SECTION LIBALEE_SECTION
constexpr static Cell findi(Iter it, std::size_t size) constexpr static Cell findi(Iter it, std::size_t size)

46
libalee/ctype.hpp
Unescape Escape View File

@ -1,52 +1,56 @@
/** //
* Alee Forth: A portable and concise Forth implementation in modern C++. /// @file ctype.hpp
* Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> /// @brief Simple implementations of character comparison functions.
* //
* This program is free software: you can redistribute it and/or modify // Alee Forth: A portable and concise Forth implementation in modern C++.
* it under the terms of the GNU Lesser General Public License as published by // Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com>
* the Free Software Foundation, either version 3 of the License, or //
* (at your option) any later version. // 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
* This program is distributed in the hope that it will be useful, // the Free Software Foundation, either version 3 of the License, or
* but WITHOUT ANY WARRANTY; without even the implied warranty of // (at your option) any later version.
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
* GNU Lesser General Public License for more details. // This program is distributed in the hope that it will be useful,
* // but WITHOUT ANY WARRANTY; without even the implied warranty of
* You should have received a copy of the GNU Lesser General Public License // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* along with this program. If not, see <https://www.gnu.org/licenses/>. // 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 #ifndef ALEEFORTH_CTYPE_HPP
#define ALEEFORTH_CTYPE_HPP #define ALEEFORTH_CTYPE_HPP
/**
* We implement our own character comparison functions to keep them lean.
*/
#include <cstdint> #include <cstdint>
/** Determines the length of a null-terminated string. */
constexpr inline unsigned strlen(const char * const s) { constexpr inline unsigned strlen(const char * const s) {
unsigned i = 0; unsigned i = 0;
while (s[i]) i++; while (s[i]) i++;
return i; return i;
} }
/** Tests if given character represents whitespace. */
constexpr inline bool isspace(uint8_t c) { constexpr inline bool isspace(uint8_t c) {
return c == ' ' || c == '\t' || c == '\r' || c == '\n'; return c == ' ' || c == '\t' || c == '\r' || c == '\n';
} }
/** Tests if given character is a numerical digit. */
constexpr inline bool isdigit(uint8_t c) { constexpr inline bool isdigit(uint8_t c) {
return c >= '0' && c <= '9'; return c >= '0' && c <= '9';
} }
/** Tests if given character is an uppercase letter. */
constexpr inline bool isupper(uint8_t c) { constexpr inline bool isupper(uint8_t c) {
return c >= 'A' && c <= 'Z'; return c >= 'A' && c <= 'Z';
} }
/** Tests if given character is a lowercase letter. */
constexpr inline bool islower(uint8_t c) { constexpr inline bool islower(uint8_t c) {
return c >= 'a' && c <= 'z'; return c >= 'a' && c <= 'z';
} }
/** Tests if given character is a letter. */
constexpr inline bool isalpha(uint8_t c) { constexpr inline bool isalpha(uint8_t c) {
return isupper(c) || (c >= 'a' && c <= 'z'); return isupper(c) || (c >= 'a' && c <= 'z');
} }

12
libalee/dictionary.cpp
Unescape Escape View File

@ -37,7 +37,7 @@ Addr Dictionary::allot(Cell amount) noexcept
if (neww < capacity()) { if (neww < capacity()) {
write(Here, static_cast<Addr>(neww)); write(Here, static_cast<Addr>(neww));
} else { } else {
// TODO // TODO how to handle allot failure? Error code?
} }
return old; return old;
@ -68,7 +68,7 @@ void Dictionary::addDefinition(Word word) noexcept
Cell wsize = word.size(); Cell wsize = word.size();
add(wsize); add(wsize);
if (alignhere() - latest() >= ((1 << (sizeof(Cell) * 8 - 6)) - 1)) if (alignhere() - latest() >= MaxDistance)
add(0); add(0);
auto addr = allot(wsize); auto addr = allot(wsize);
@ -91,7 +91,7 @@ Addr Dictionary::find(Word word) noexcept
const Addr len = l & 0x1F; const Addr len = l & 0x1F;
Word lw; Word lw;
if ((l >> 6) < 1023) { if ((l >> 6) < MaxDistance) {
lw = Word::fromLength(lt + sizeof(Cell), len); lw = Word::fromLength(lt + sizeof(Cell), len);
if (equal(word, lw)) if (equal(word, lw))
return lt; return lt;
@ -120,7 +120,7 @@ Addr Dictionary::getexec(Addr addr) noexcept
const Addr len = l & 0x1Fu; const Addr len = l & 0x1Fu;
addr += sizeof(Cell); addr += sizeof(Cell);
if ((l >> 6) == 1023) if ((l >> 6) == MaxDistance)
addr += sizeof(Cell); addr += sizeof(Cell);
addr += len; addr += len;
@ -132,7 +132,7 @@ bool Dictionary::hasInput() const noexcept
{ {
const Addr src = read(Dictionary::Source); const Addr src = read(Dictionary::Source);
const Addr end = read(Dictionary::SourceLen); const Addr end = read(Dictionary::SourceLen);
uint8_t idx = read(Dictionary::Input) & 0xFFu; auto idx = static_cast<uint8_t>(read(Dictionary::Input));
while (idx < end) { while (idx < end) {
auto ch = readbyte(src + idx); auto ch = readbyte(src + idx);
@ -154,7 +154,7 @@ Word Dictionary::input() noexcept
{ {
const Addr src = read(Dictionary::Source); const Addr src = read(Dictionary::Source);
const Addr end = read(Dictionary::SourceLen); const Addr end = read(Dictionary::SourceLen);
uint8_t idx = read(Dictionary::Input) & 0xFFu; auto idx = static_cast<uint8_t>(read(Dictionary::Input));
Addr wstart = src + idx; Addr wstart = src + idx;
Addr wend = wstart; Addr wend = wstart;

200
libalee/dictionary.hpp
Unescape Escape View File

@ -1,20 +1,22 @@
/** //
* Alee Forth: A portable and concise Forth implementation in modern C++. /// @file dictionary.hpp
* Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> /// @brief Defines the dictionary interface and common functionality.
* //
* This program is free software: you can redistribute it and/or modify // Alee Forth: A portable and concise Forth implementation in modern C++.
* it under the terms of the GNU Lesser General Public License as published by // Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com>
* the Free Software Foundation, either version 3 of the License, or //
* (at your option) any later version. // 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
* This program is distributed in the hope that it will be useful, // the Free Software Foundation, either version 3 of the License, or
* but WITHOUT ANY WARRANTY; without even the implied warranty of // (at your option) any later version.
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
* GNU Lesser General Public License for more details. // This program is distributed in the hope that it will be useful,
* // but WITHOUT ANY WARRANTY; without even the implied warranty of
* You should have received a copy of the GNU Lesser General Public License // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* along with this program. If not, see <https://www.gnu.org/licenses/>. // 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 #ifndef ALEEFORTH_DICTIONARY_HPP
#define ALEEFORTH_DICTIONARY_HPP #define ALEEFORTH_DICTIONARY_HPP
@ -28,106 +30,179 @@
#include <cstdint> #include <cstdint>
/** /**
* Dictionary entry format: * @class Dictionary
* - 1 information byte * @brief Provides an interface and essential funcitonality for a dictionary.
* bits 0..4: Length of name (L) * @details The core read and write functionality is left virtual so that
* bit 5: Immediate? * dictionaries can be stored in any medium. So, this class cannot be used
* bits 6..15: Distance to next entry (negative) * directly; the programmer must define a dictionary class that inherits this
* - L bytes of name * one.
* - 0+ bytes for address alignment *
* - 0+ bytes of entry's data... * 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 "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
*/ */
class Dictionary
struct 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; constexpr static Addr Base = 0;
/** Stores the current `here` address. */
constexpr static Addr Here = sizeof(Cell); constexpr static Addr Here = sizeof(Cell);
/** Stores the address of the most recently defined word. */
constexpr static Addr Latest = sizeof(Cell) * 2; constexpr static Addr Latest = sizeof(Cell) * 2;
/** Stores a boolean indication of compiling state. */
constexpr static Addr Compiling = sizeof(Cell) * 3; 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; constexpr static Addr CompToken = sizeof(Cell) * 4;
/** Stores the address of the current interpreter input source. */
constexpr static Addr Source = sizeof(Cell) * 5; 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 SourceLen = sizeof(Cell) * 6;
constexpr static Addr Input = sizeof(Cell) * 7; // len data... /** Stores the dictionary's input buffer (a counted string). */
constexpr static Addr InputCells = 80; // bytes! 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 Addr Begin = sizeof(Cell) * 8 + InputCells;
/** "Immediate" marker bit for a word's definition. */
constexpr static Cell Immediate = (1 << 5); 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. */
* 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.
*/
virtual Cell read(Addr) const noexcept = 0; 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; virtual void write(Addr, Cell) noexcept = 0;
/** Returns the byte stored at the given address. */
virtual uint8_t readbyte(Addr) const noexcept = 0; virtual uint8_t readbyte(Addr) const noexcept = 0;
/** Writes the given byte to the given address. */
virtual void writebyte(Addr, uint8_t) noexcept = 0; 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; 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(); void initialize();
/**
* Gets the address stored in `here`.
*/
LIBALEE_SECTION LIBALEE_SECTION
Addr here() const noexcept { return read(Here); } Addr here() const noexcept { return read(Here); }
/**
* Sets the address stored in `here`.
*/
LIBALEE_SECTION LIBALEE_SECTION
void here(Addr l) noexcept { write(Here, l); } void here(Addr l) noexcept { write(Here, l); }
/**
* Gets the value of `latest`.
*/
LIBALEE_SECTION LIBALEE_SECTION
Addr latest() const noexcept { return read(Latest); } Addr latest() const noexcept { return read(Latest); }
/**
* Sets the value of `latest`.
*/
LIBALEE_SECTION LIBALEE_SECTION
void latest(Addr l) noexcept { write(Latest, l); } void latest(Addr l) noexcept { write(Latest, l); }
// Aligns the given address. /**
static Addr aligned(Addr); * Aligns the given address to the next Cell boundary if necessary.
// Aligns `here`. * @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; 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`. * Allocates memory by returning and then increasing the current `here`.
* The entry does not become active until a semicolon is executed. * @param count The number of bytes to increase `here` by.
* @return The address stored in `here` before the increase.
*/ */
void addDefinition(Word) noexcept; 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. * 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 * Produces the execution token for the given dictionary entry.
* for that 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. * 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; Word input() noexcept;
/**
* Returns true if the dictionary's input buffer has immediately available
* data.
*/
bool hasInput() const noexcept; 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> template<typename Iter1, typename Iter2>
LIBALEE_SECTION LIBALEE_SECTION
constexpr static bool equal(Iter1 b1, Iter1 e1, Iter2 b2) { constexpr static bool equal(Iter1 b1, Iter1 e1, Iter2 b2) {
@ -137,7 +212,10 @@ struct Dictionary
virtual ~Dictionary() {}; virtual ~Dictionary() {};
private: private:
// Case-insensitive comparison. /**
* Case-insensitive character comparison used for dictionary lookup.
* @return True if the characters are equivalent.
*/
LIBALEE_SECTION LIBALEE_SECTION
constexpr static bool eqchars(char c1, char c2) { constexpr static bool eqchars(char c1, char c2) {
if (isalpha(static_cast<uint8_t>(c1))) if (isalpha(static_cast<uint8_t>(c1)))

14
libalee/parser.cpp
Unescape Escape View File

@ -25,14 +25,17 @@ Error Parser::parse(State& state, const char *str)
{ {
auto addr = Dictionary::Input; auto addr = Dictionary::Input;
// Set source and input length
const auto len = static_cast<Cell>(strlen(str)); const auto len = static_cast<Cell>(strlen(str));
state.dict.write(addr, 0); state.dict.write(addr, 0);
state.dict.write(Dictionary::SourceLen, len); state.dict.write(Dictionary::SourceLen, len);
// Fill input buffer with string contents
addr += sizeof(Cell); addr += sizeof(Cell);
while (*str) while (*str)
state.dict.writebyte(addr++, *str++); state.dict.writebyte(addr++, *str++);
// Zero the remaining input buffer
while (addr < Dictionary::Input + Dictionary::InputCells) while (addr < Dictionary::Input + Dictionary::InputCells)
state.dict.writebyte(addr++, '\0'); state.dict.writebyte(addr++, '\0');
@ -54,8 +57,10 @@ LIBALEE_SECTION
Error Parser::parseWord(State& state, Word word) Error Parser::parseWord(State& state, Word word)
{ {
bool imm; 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) { if (ins == 0) {
auto cw = CoreWords::findi(state, word); auto cw = CoreWords::findi(state, word);
@ -67,7 +72,7 @@ Error Parser::parseWord(State& state, Word word)
return r; return r;
} else { } else {
ins = cw; ins = cw;
imm = ins == CoreWords::Semicolon; imm = ins == CoreWords::token(";");
} }
} else { } else {
imm = state.dict.read(ins) & Dictionary::Immediate; imm = state.dict.read(ins) & Dictionary::Immediate;
@ -119,8 +124,11 @@ LIBALEE_SECTION
void Parser::processLiteral(State& state, Cell value) void Parser::processLiteral(State& state, Cell value)
{ {
if (state.compiling()) { if (state.compiling()) {
constexpr auto ins = CoreWords::findi("_lit"); 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; const Cell maxlit = Dictionary::Begin - CoreWords::WordCount;
if (value >= 0 && value < maxlit) if (value >= 0 && value < maxlit)
value += CoreWords::WordCount; value += CoreWords::WordCount;

79
libalee/parser.hpp
Unescape Escape View File

@ -1,20 +1,22 @@
/** //
* Alee Forth: A portable and concise Forth implementation in modern C++. /// @file parser.hpp
* Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> /// @brief Provides functions to parse text for interpretation/execution.
* //
* This program is free software: you can redistribute it and/or modify // Alee Forth: A portable and concise Forth implementation in modern C++.
* it under the terms of the GNU Lesser General Public License as published by // Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com>
* the Free Software Foundation, either version 3 of the License, or //
* (at your option) any later version. // 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
* This program is distributed in the hope that it will be useful, // the Free Software Foundation, either version 3 of the License, or
* but WITHOUT ANY WARRANTY; without even the implied warranty of // (at your option) any later version.
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
* GNU Lesser General Public License for more details. // This program is distributed in the hope that it will be useful,
* // but WITHOUT ANY WARRANTY; without even the implied warranty of
* You should have received a copy of the GNU Lesser General Public License // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* along with this program. If not, see <https://www.gnu.org/licenses/>. // 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 #ifndef ALEEFORTH_PARSER_HPP
#define ALEEFORTH_PARSER_HPP #define ALEEFORTH_PARSER_HPP
@ -25,37 +27,60 @@
#include <string_view> #include <string_view>
/**
* @class Parser
* @brief Provides routines for parsing Forth code.
*/
class Parser class Parser
{ {
public: public:
/**
* Pointer to a user-provided function that
*/
static Error (*customParse)(State&, Word); static Error (*customParse)(State&, Word);
/** /**
* Parses (and evaluates) the given string using the given state. * Parses and evaluates the given string using the given state.
* The string is stored in the state's input buffer, then parseSource() * The string is stored in the state's input buffer before parseSource()
* works through that using parseWord(). parseWord() will compile or * is called.
* execute as necessary. * @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 * Parses through and compiles or evaluates the words stored in the state's
* buffer. * 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: private:
/** /**
* Parses the given word using the given state. * Parses the given word using the given state.
* @return Error token to indicate if parsing was successful.
*/ */
static Error parseWord(State&, Word); static Error parseWord(State&, Word);
/** /**
* Attempts to parse the given word into a number. * 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 #endif // ALEEFORTH_PARSER_HPP

117
libalee/state.hpp
Unescape Escape View File

@ -1,20 +1,22 @@
/** //
* Alee Forth: A portable and concise Forth implementation in modern C++. /// @file state.hpp
* Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> /// @brief Provides object to manage execution and interpretation state.
* //
* This program is free software: you can redistribute it and/or modify // Alee Forth: A portable and concise Forth implementation in modern C++.
* it under the terms of the GNU Lesser General Public License as published by // Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com>
* the Free Software Foundation, either version 3 of the License, or //
* (at your option) any later version. // 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
* This program is distributed in the hope that it will be useful, // the Free Software Foundation, either version 3 of the License, or
* but WITHOUT ANY WARRANTY; without even the implied warranty of // (at your option) any later version.
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
* GNU Lesser General Public License for more details. // This program is distributed in the hope that it will be useful,
* // but WITHOUT ANY WARRANTY; without even the implied warranty of
* You should have received a copy of the GNU Lesser General Public License // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* along with this program. If not, see <https://www.gnu.org/licenses/>. // 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 #ifndef ALEEFORTH_STATE_HPP
#define ALEEFORTH_STATE_HPP #define ALEEFORTH_STATE_HPP
@ -26,31 +28,53 @@
#include <csetjmp> #include <csetjmp>
#include <cstddef> #include <cstddef>
/**
* Size of the primary data stack, number of cells.
*/
constexpr unsigned DataStackSize = 64; constexpr unsigned DataStackSize = 64;
/**
* Size of the return stack, number of cells.
*/
constexpr unsigned ReturnStackSize = 64; constexpr unsigned ReturnStackSize = 64;
/**
* @class State
* Object to track execution state.
*/
class State class State
{ {
/** Input functions should add input to the input buffer when available. */
using InputFunc = void (*)(State&); using InputFunc = void (*)(State&);
/** Context object that defines a state of execution. */
struct Context { struct Context {
Addr ip = 0; Addr ip = 0; /** Instruction pointer */
std::jmp_buf jmpbuf = {}; std::jmp_buf jmpbuf = {}; /** setjmp() buffer for exiting execute() */
}; };
public: public:
/** Reference to dictionary used by this state. */
Dictionary& dict; 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): constexpr State(Dictionary& d, InputFunc i):
dict(d), inputfunc(i), context() {} 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. * If the token is a CoreWord, this function exits after its execution.
* Otherwise, execution continues until the word's execution completes. * Otherwise, execution continues until the word's execution completes.
* Encountering an error will cause this function to exit immediately. * 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 * Clears the data and return stacks, sets ip to zero, and clears the
@ -58,25 +82,30 @@ public:
*/ */
void reset(); void reset();
/** Returns a reference to the instruction pointer. */
LIBALEE_SECTION LIBALEE_SECTION
Addr& ip() noexcept { Addr& ip() noexcept {
return context.ip; return context.ip;
} }
/** Calls the user input function with this state as the argument. */
LIBALEE_SECTION LIBALEE_SECTION
void input() noexcept { void input() noexcept {
inputfunc(*this); inputfunc(*this);
} }
/** Returns true if currently in a compiling state. */
bool compiling() const; bool compiling() const;
/** Sets the compiling state. True if compiling, false if interpreting. */
void compiling(bool); void compiling(bool);
/** Returns the number of values stored on the data stack. */
std::size_t size() const noexcept; std::size_t size() const noexcept;
/** Returns the number of values stored on the return stack. */
std::size_t rsize() const noexcept; std::size_t rsize() const noexcept;
/** /**
* Saves execution state so that a new execution can begin. * Returns the current execution state. Usually followed by a load() call.
* Used for EVALUATE.
*/ */
Context save(); Context save();
@ -85,49 +114,77 @@ public:
*/ */
void load(const Context&); void load(const Context&);
/**
* Pushes the given value to the data stack.
*/
LIBALEE_SECTION LIBALEE_SECTION
inline void push(Cell value) { inline void push(Cell value) {
verify(dsp < dstack + DataStackSize, Error::push); verify(dsp < dstack + DataStackSize, Error::push);
*dsp++ = value; *dsp++ = value;
} }
/**
* Pops a value from the data stack and returns that value.
*/
LIBALEE_SECTION LIBALEE_SECTION
inline Cell pop() { inline Cell pop() {
verify(dsp > dstack, Error::pop); verify(dsp > dstack, Error::pop);
return *--dsp; return *--dsp;
} }
/**
* Pushes the given value to the return stack.
*/
LIBALEE_SECTION LIBALEE_SECTION
inline void pushr(Cell value) { inline void pushr(Cell value) {
verify(rsp < rstack + ReturnStackSize, Error::pushr); verify(rsp < rstack + ReturnStackSize, Error::pushr);
*rsp++ = value; *rsp++ = value;
} }
/**
* Pops a value from the return stack and returns that value.
*/
LIBALEE_SECTION LIBALEE_SECTION
inline Cell popr() { inline Cell popr() {
verify(rsp > rstack, Error::popr); verify(rsp > rstack, Error::popr);
return *--rsp; return *--rsp;
} }
/**
* Returns the value stored at the current data stack position.
*/
LIBALEE_SECTION LIBALEE_SECTION
inline Cell& top() { inline Cell& top() {
verify(dsp > dstack, Error::top); verify(dsp > dstack, Error::top);
return *(dsp - 1); 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
*/
LIBALEE_SECTION LIBALEE_SECTION
inline Cell& pick(std::size_t i) { inline Cell& pick(std::size_t i) {
verify(dsp - i > dstack, Error::pick); verify(dsp - i > dstack, Error::pick);
return *(dsp - i - 1); return *(dsp - i - 1);
} }
// Advances the instruction pointer and returns that cell's contents. /**
* Advances the instruction pointer and returns that cell's contents.
*/
LIBALEE_SECTION LIBALEE_SECTION
inline Cell beyondip() { inline Cell beyondip() {
context.ip += sizeof(Cell); context.ip += sizeof(Cell);
return dict.read(context.ip); 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
*/
LIBALEE_SECTION LIBALEE_SECTION
inline void verify(bool condition, Error error) { inline void verify(bool condition, Error error) {
if (!condition) if (!condition)
@ -135,13 +192,13 @@ public:
} }
private: private:
InputFunc inputfunc; // User-provided function to collect "stdin" input. InputFunc inputfunc; /** User-provided function to collect user input. */
Context context; Context context; /** State's current execution context. */
Cell dstack[DataStackSize] = {}; Cell dstack[DataStackSize] = {}; /** Data stack */
Cell rstack[ReturnStackSize] = {}; Cell rstack[ReturnStackSize] = {}; /** Return stack */
Cell *dsp = dstack; Cell *dsp = dstack; /** Current data stack position */
Cell *rsp = rstack; Cell *rsp = rstack; /** Current return stack position */
}; };
#endif // ALEEFORTH_STATE_HPP #endif // ALEEFORTH_STATE_HPP

116
libalee/types.hpp
Unescape Escape View File

@ -1,20 +1,22 @@
/** //
* Alee Forth: A portable and concise Forth implementation in modern C++. /// @file types.hpp
* Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> /// @brief Defines common types used throughout Alee Forth.
* //
* This program is free software: you can redistribute it and/or modify // Alee Forth: A portable and concise Forth implementation in modern C++.
* it under the terms of the GNU Lesser General Public License as published by // Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com>
* the Free Software Foundation, either version 3 of the License, or //
* (at your option) any later version. // 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
* This program is distributed in the hope that it will be useful, // the Free Software Foundation, either version 3 of the License, or
* but WITHOUT ANY WARRANTY; without even the implied warranty of // (at your option) any later version.
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
* GNU Lesser General Public License for more details. // This program is distributed in the hope that it will be useful,
* // but WITHOUT ANY WARRANTY; without even the implied warranty of
* You should have received a copy of the GNU Lesser General Public License // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* along with this program. If not, see <https://www.gnu.org/licenses/>. // 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 #ifndef ALEEFORTH_TYPES_HPP
#define ALEEFORTH_TYPES_HPP #define ALEEFORTH_TYPES_HPP
@ -22,55 +24,86 @@
#include <cstdint> #include <cstdint>
#include <iterator> #include <iterator>
/** /** Dictionary address type. Must be equivalent to "unsigned Cell". */
* Configure the below types for your platform.
*/
using Addr = uint16_t; using Addr = uint16_t;
/** Data cell type. Dictionary is basically an array of this type. */
using Cell = int16_t; using Cell = int16_t;
/** Double-width cell type. Must be twice the size of Cell. */
using DoubleCell = int32_t; 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 Dictionary;
struct State; struct State;
using Func = void (*)(State&); /**
* Error enum to report success or failure of parsing or execution.
*/
enum class Error : int { enum class Error : int {
none = 0, none = 0, /** No error */
push, push, /** Could not push (data stack overflow) */
pop, pop, /** Could not pop (data stack underflow) */
pushr, pushr, /** Could not push (return stack overflow) */
popr, popr, /** Could not pop (return stack underflow) */
top, top, /** Could not fetch data stack top (data stack underflow) */
pick, pick, /** Could not pick data stack value (data stack underflow) */
exit, exit, /** No error, exited from State::execute() */
noword 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 class Word
{ {
/** Beginning (inclusive) index */
Addr start; Addr start;
/** End (exclusive) index */
Addr wend; Addr wend;
public: public:
struct iterator; 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): constexpr explicit Word(Addr s = 0, Addr e = 0):
start(s), wend(e) {} 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
*/
LIBALEE_SECTION LIBALEE_SECTION
static constexpr Word fromLength(Addr s, Addr l) { static constexpr Word fromLength(Addr s, Addr l) {
return Word(s, s + l); return Word(s, s + l);
} }
/** Returns the size of this word in bytes. */
Addr size() const noexcept; 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 { struct iterator {
using iterator_category = std::input_iterator_tag; using iterator_category = std::input_iterator_tag;
using value_type = uint8_t; using value_type = uint8_t;
@ -78,15 +111,26 @@ public:
using reference = void; using reference = void;
using difference_type = Cell; using difference_type = Cell;
/** Iterator's current address within its containing dictionary. */
Addr addr; Addr addr;
/** Pointer to dictionary that contains this word. */
const Dictionary *dict; 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): constexpr iterator(Addr a, const Dictionary *d):
addr(a), dict(d) {} addr(a), dict(d) {}
/** Prefix increment */
iterator& operator++(); iterator& operator++();
/** Postfix increment */
iterator operator++(int); iterator operator++(int);
/** Returns value pointed to by iterator */
value_type operator*(); value_type operator*();
/** Iterator comparison function (case-insensitive) */
bool operator!=(const iterator&); bool operator!=(const iterator&);
}; };
}; };

49
memdict.hpp
Unescape Escape View File

@ -1,20 +1,22 @@
/** //
* Alee Forth: A portable and concise Forth implementation in modern C++. /// @file memdict.hpp
* Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com> /// @brief Simple dictionary implementation using a large memory block.
* //
* This program is free software: you can redistribute it and/or modify // Alee Forth: A portable and concise Forth implementation in modern C++.
* it under the terms of the GNU Lesser General Public License as published by // Copyright (C) 2023 Clyne Sullivan <clyne@bitgloo.com>
* the Free Software Foundation, either version 3 of the License, or //
* (at your option) any later version. // 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
* This program is distributed in the hope that it will be useful, // the Free Software Foundation, either version 3 of the License, or
* but WITHOUT ANY WARRANTY; without even the implied warranty of // (at your option) any later version.
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
* GNU Lesser General Public License for more details. // This program is distributed in the hope that it will be useful,
* // but WITHOUT ANY WARRANTY; without even the implied warranty of
* You should have received a copy of the GNU Lesser General Public License // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* along with this program. If not, see <https://www.gnu.org/licenses/>. // 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 #ifndef ALEEFORTH_MEMDICT_HPP
#define ALEEFORTH_MEMDICT_HPP #define ALEEFORTH_MEMDICT_HPP
@ -22,31 +24,44 @@
#include "libalee/alee.hpp" #include "libalee/alee.hpp"
#ifndef MEMDICTSIZE #ifndef MEMDICTSIZE
/** Default dictionary size in bytes. */
#define MEMDICTSIZE (65536) #define MEMDICTSIZE (65536)
#endif #endif
/** Size in bytes of a MemDict. */
constexpr unsigned long int MemDictSize = MEMDICTSIZE; constexpr unsigned long int MemDictSize = MEMDICTSIZE;
/**
* @class MemDict
* Dictionary implementation that uses a large block of memory.
*/
class MemDict : public Dictionary class MemDict : public Dictionary
{ {
/** Block of memory to contain dictionary's contents. */
uint8_t dict[MemDictSize] = {0}; uint8_t dict[MemDictSize] = {0};
public: public:
/** Returns the value of the cell at the given address. */
virtual Cell read(Addr addr) const noexcept final { virtual Cell read(Addr addr) const noexcept final {
return *reinterpret_cast<const Cell *>(dict + addr); 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 { virtual void write(Addr addr, Cell value) noexcept final {
*reinterpret_cast<Cell *>(dict + addr) = value; *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 { virtual uint8_t readbyte(Addr addr) const noexcept final {
return dict[addr]; return dict[addr];
} }
/** Writes the given value to the byte at the given address. */
virtual void writebyte(Addr addr, uint8_t value) noexcept final { virtual void writebyte(Addr addr, uint8_t value) noexcept final {
dict[addr] = value; dict[addr] = value;
} }
/** Returns the size of the dictionary's memory block. */
virtual unsigned long int capacity() const noexcept final { virtual unsigned long int capacity() const noexcept final {
return sizeof(dict); return sizeof(dict);
} }

Write Preview
Loading…
Cancel
Save