+
Customizing the Build
+ Building Alternative Systems
+ Obtaining Retro
+ Building on BSD, Linux, macOS, and other Unix Targets
+ Building Retro on Windows
+ Basic Interactions
+ Deprecation Policy
+ Retro: a Modern, Pragmatic Forth
+ Retro's Markdown Syntax
+ A Quick Tutorial
+ Unu: Simple, Literate Source Files
+ Starting Retro
+ Calling Retro from C
+ Internals: The Retro Image
+ Internals: Interface Layers
+ I/O Devices
+ Internals: I/O
+ Internals: Nga Virtual Machine
+ The Code It Yourself Manifesto
+ Historical Papers and Notes
+ On The Kernel Wordset
+ Metacompilation and Assembly
+ On The Evolution Of Ngaro Into Nga
+ Sigils as a Language Element
+ Retro 11 (2011 - 2019): A Look Back
+ Security Concerns
+ The Path to Self Hosting
+ On The Use Of Underscores In Word Names
+ Working With Arrays
+ Working With Assembly Language
+ Working With a Buffer
+ Working With Characters
+ Checking The Version
+ Defining Words
+ Working With The Dictionary
+ Working With Files
+ Working With Floating Point
+ Lexical Scope
+ Multiple Cores
+ Naming Conventions
+ Working With Numbers
+ Working With Pointers
+ The Return Stack
+ Unix Scripting
+ Stack Diagrams
+ Working With Strings
+ The Stacks
+ Using Combinators
+ Word Classes
+ Additional Tools
+ The Optional Retro Compiler
+
While a simple make will suffice for building Retro, there
are a number of ways to customize the build to your needs.
@@ -51,10 +52,11 @@ In this chapter, replace Makefile with
are using GNU Make (most Linux and macOS users will probably
be using this).
+I/O Devices
Many of the I/O devices are optional. The most common ones are
-enabled by default in the Makefile. Look near the end of the top
-section for lines starting with ENABLED:
+enabled by default in the Configuration.mk. Look for the lines
+starting with ENABLED:
ENABLED ?=
ENABLED += -DENABLE_FLOATS
@@ -86,11 +88,13 @@ If you want to build with sockets support, uncomment the
# ENABLED += -DENABLE_SOCKETS and DEVICES += interface/sockets.retro
lines before building.
+Compiler Flags
You may need or want to adjust the compiler flags. In the first
section of the Makefile, look for CFLAGS and add/change as
desired to override the defaults.
+VM Tweaks
64-Bit
@@ -99,6 +103,7 @@ this to 64-bit though. For a one-off build:
make OPTIONS=-DBIT64
+Stack Size
You can alter the stack sizes by defining STACK_DEPTH and
ADDRESSES. For a one-off build with a max stack depth of 4000
@@ -106,6 +111,7 @@ items and 500 addresses on the return stack:
make OPTIONS="-DSTACK_DEPTH=4000 -DADDRESSES=500
+Image Size
You can also alter the image size. Again, for a one-off build:
@@ -113,6 +119,7 @@ You can also alter the image size. Again, for a one-off build:
Would build a system with a maximum image size of 4,000,000 cells.
+Update the Makefile
If you do any of these routinely, edit the Makefile to include them.
@@ -122,6 +129,7 @@ If you do any of these routinely, edit the Makefile to include them.
OPTIONS += -DADDRESSES=500
OPTIONS += -DIMAGE_SIZE=4000000
+Further Image Customization
You can customize the image further by having the build process
include your code in the image.
diff --git a/doc/html/chapters/building/alternatives.html b/doc/html/chapters/building/alternatives.html
index 5e1382e..6fdc44c 100644
--- a/doc/html/chapters/building/alternatives.html
+++ b/doc/html/chapters/building/alternatives.html
@@ -1,7 +1,7 @@
-
+
In addition to the C implementation, there are a few other
interfaces that can be built.
@@ -125,11 +126,13 @@ Building:
This will require a copy of the ngaImage in the
current directory.
+Python: retro.py
This is an implementation of retro-repl in Python. As
with retro-repl it requires the ngaImage in the current
directory when starting.
+C#: retro.cs
This is an implementation of retro-repl in C#. As with
retro-repl it requires the ngaImage in the current
diff --git a/doc/html/chapters/building/obtaining.html b/doc/html/chapters/building/obtaining.html
index a036788..455b12a 100644
--- a/doc/html/chapters/building/obtaining.html
+++ b/doc/html/chapters/building/obtaining.html
@@ -1,7 +1,7 @@
+
+Stable Releases
I periodically make stable releases. This will typically happen
quarterly.
@@ -62,6 +64,7 @@ URLs:
• http://forthworks.com/retro/r/latest.tar.gz
• gopher://forthworks.com/9/retro/r/latest.tar.gz
+Fossil Repository
I use a Fossil repository to manage development. To obtain a
copy of the repository install Fossil and:
@@ -82,6 +85,7 @@ If you have problems, check the version of Fossil you are
using. I am currently using Fossil 2.10, you may experience
issues checking out or cloning if using older versions.
+git Repository
There is now a read-only mirror of the fossil repository
provided via git. This is hosted on sr.ht.
diff --git a/doc/html/chapters/building/unix.html b/doc/html/chapters/building/unix.html
index 3c8300a..906433c 100644
--- a/doc/html/chapters/building/unix.html
+++ b/doc/html/chapters/building/unix.html
@@ -1,7 +1,7 @@
+
Retro is well supported on BSD (tested on FreeBSD, NetBSD,
OpenBSD), Linux, and macOS systems. It should build on any
of these without issue.
@@ -74,6 +75,7 @@ In the bin/ directory, you should see the following:
retro-embedimage
retro-describe
+Test The Build
You can conduct a quick test of the build by running bin/retro:
@@ -92,6 +94,7 @@ or:
sudo make install
+Platform Specific Notes
Linux
diff --git a/doc/html/chapters/building/windows.html b/doc/html/chapters/building/windows.html
index f808056..59ce981 100644
--- a/doc/html/chapters/building/windows.html
+++ b/doc/html/chapters/building/windows.html
@@ -1,7 +1,7 @@
+
It is possible to build Retro on Windows, though a few of the
extensions are not supported:
@@ -54,6 +55,7 @@ This is currently more difficult than on a Unix host. If you have
Windows 10 and WSL, it may be better to build under that (using
the Unix instructions).
+Setup Build Environment
Retro on Windows is built with TCC.
@@ -63,6 +65,7 @@ Download the winapi-full and tcc-xxxx-bin pack
system. Decompress them, copy the headers from the winapi
package into the tcc directory.
+Prepare Source
Copy the vm/nga-c/retro.c and the vm/nga-c/image.c to
the directory you setup tcc into.
diff --git a/doc/html/chapters/general/basic-interactions.html b/doc/html/chapters/general/basic-interactions.html
index d401d4f..77d1821 100644
--- a/doc/html/chapters/general/basic-interactions.html
+++ b/doc/html/chapters/general/basic-interactions.html
@@ -1,7 +1,7 @@
+
Start Retro in interactive mode:
```
retro -i
diff --git a/doc/html/chapters/general/copyrights.html b/doc/html/chapters/general/copyrights.html
index efb1a53..76ef85a 100644
--- a/doc/html/chapters/general/copyrights.html
+++ b/doc/html/chapters/general/copyrights.html
@@ -1,7 +1,7 @@
-
+
As Retro evolves, some words will become obsolete and no longer be
needed. In each release, these will be marked as deprecated in the
glossary. Any deprecated words will be removed in the next quarterly
diff --git a/doc/html/chapters/general/introduction.html b/doc/html/chapters/general/introduction.html
index f152d18..3abb34a 100644
--- a/doc/html/chapters/general/introduction.html
+++ b/doc/html/chapters/general/introduction.html
@@ -1,7 +1,7 @@
+
Welcome to Retro, my personal take on the Forth language. This
is a modern system primarily targeting desktop, mobile, and
servers, though it can also be used on some larger (ARM, MIPS32)
diff --git a/doc/html/chapters/general/markdown.html b/doc/html/chapters/general/markdown.html
index 9951260..9ce013e 100644
--- a/doc/html/chapters/general/markdown.html
+++ b/doc/html/chapters/general/markdown.html
@@ -1,7 +1,7 @@
+
I use a variation of Markdown for writing documentation and
when commenting code written in Retro. The syntax is
described below.
+Basic Syntax
Headings
@@ -63,6 +65,7 @@ level.
My Markdown does not support the alternate underline
format for headings.
+Paragraphs & Line Breaks
To create paragraphs, use a blank line to separate one or
more lines of text.
@@ -93,6 +96,7 @@ To underline text, surround it with underscores.
Underline _some text_.
+Horizontal Rules
Horizontal rules can be inserted by starting a line with a
sequence of four or more dashes (-) or four or more alternating
@@ -116,6 +120,7 @@ the list marker can be used.
Code
+Code Blocks
Code blocks start and end with ~~~ on a line by themselves.
@@ -129,6 +134,7 @@ You can also denote code by starting the line with four spaces.
This line will be treated as code.
+Test Blocks
Unit testing blocks start and end with on a line by
themselves.
@@ -137,6 +143,7 @@ themselves.
{ #10 #20 #13 #4 #22 } #0 [ + ] a:reduce
```
+Inline Code
To mark a sequence as inline code, surround it with backticks.
diff --git a/doc/html/chapters/general/quick-tutorial.html b/doc/html/chapters/general/quick-tutorial.html
index 86bac8d..c9ec8ba 100644
--- a/doc/html/chapters/general/quick-tutorial.html
+++ b/doc/html/chapters/general/quick-tutorial.html
@@ -1,7 +1,7 @@
-
+
Programming in Retro is all about creating words to solve
the problem at hand. Words operate on data, which can be
kept in memory or on the stack.
diff --git a/doc/html/chapters/general/retro-unu.html b/doc/html/chapters/general/retro-unu.html
index cd0591c..f31f02a 100644
--- a/doc/html/chapters/general/retro-unu.html
+++ b/doc/html/chapters/general/retro-unu.html
@@ -1,7 +1,7 @@
+
Retro is written in a literate style. Most of the sources
are in a format called Unu. This allows easy mixing of
commentary and code blocks, making it simple to document
@@ -86,6 +87,7 @@ This illustrates the format. Only code in the fenced blocks
(Note: this only applies to source files; fences are not used
when entering code interactively).
+On The Name
The name Unu comes from the Maori language, where it means:
diff --git a/doc/html/chapters/general/starting.html b/doc/html/chapters/general/starting.html
index e05b7b8..c5cab77 100644
--- a/doc/html/chapters/general/starting.html
+++ b/doc/html/chapters/general/starting.html
@@ -1,7 +1,7 @@
+
Retro can be run for scripting or interactive use.
Interactive
@@ -61,6 +62,7 @@ Or:
```
This should be sufficient for most uses.
+Using In a Pipe
Retro will work with piped input.
@@ -68,6 +70,7 @@ E.g.,
```
echo "'lol s:put nl" | retro
```
+Running A Program In A File
You can run code in a file very easily. This is simply:
@@ -89,6 +92,7 @@ And make the file executable.
Source files must be written in Unu format.
+Command Line Arguments
For a summary of the full command line arguments available:
diff --git a/doc/html/chapters/general/syntax.html b/doc/html/chapters/general/syntax.html
index 3e04ec6..d319a53 100644
--- a/doc/html/chapters/general/syntax.html
+++ b/doc/html/chapters/general/syntax.html
@@ -1,7 +1,7 @@
+
The C implementation of Retro provides several functions for
interacting with code written in Retro.
diff --git a/doc/html/chapters/internals/image.html b/doc/html/chapters/internals/image.html
index 921d8d8..1d2666f 100644
--- a/doc/html/chapters/internals/image.html
+++ b/doc/html/chapters/internals/image.html
@@ -1,7 +1,7 @@
+
The actual Retro language is stored as a memory image for Nga.
Format
diff --git a/doc/html/chapters/internals/interface-layers.html b/doc/html/chapters/internals/interface-layers.html
index e1dc7e4..60bb39b 100644
--- a/doc/html/chapters/internals/interface-layers.html
+++ b/doc/html/chapters/internals/interface-layers.html
@@ -1,7 +1,7 @@
+
Nga provides a virtual processor and an extensible way of adding
I/O devices, but does not provide any I/O itself. Adding I/O is
the responsability of the interface layer.
diff --git a/doc/html/chapters/internals/io-devices.html b/doc/html/chapters/internals/io-devices.html
index a7df869..a2d17a4 100644
--- a/doc/html/chapters/internals/io-devices.html
+++ b/doc/html/chapters/internals/io-devices.html
@@ -1,7 +1,7 @@
+
I/O devices on Nga are exposed via three instructions:
ie enumerate i/o devices
@@ -53,6 +54,7 @@ I/O devices on Nga are exposed via three instructions:
All devices are registered with the VM. How this occurs is
implementation dependent.
+Counting Devices
Use the ie instruction to return the number of attached devices.
@@ -61,12 +63,14 @@ Use the ie instruction to return the number of attached
Upon running, the stack will contain the number of devices. You
can then query these by passing the device number to iq.
+Query Devices
Use iq to query an attached device. This will return two values,
a device class and a revision number.
The device class will be the top value on the stack.
+Invoking a Device
You can trigger an I/O operation by passing the device handle to
the ii instruction.
@@ -79,6 +83,7 @@ E.g., to display a character (ASCII code 98 in this case):
Be sure to pass the device handle, not the device class.
+Device Class
Ultimately devices are implementation-specific, but the
standard system provides or reserves the following:
@@ -102,19 +107,23 @@ It must be noted here that nothing forces devices to use these
class identifiers, and one must take care to use an Nga
implementation that provides the devices they need.
+Device Revisions
Over time, the functionality a device provides may change. To allow
detection of this, the query functionality provides a revision number.
Your code can use this to ensure that the device provided supports
the level of functionality you need.
+Device Class Details
+0000: Generic Output
Supported by all Nga implementations. This is required to be the
first device, and is the only one guaranteed to be provided. It
consumes a value from the stack, writing to to the host-specific
output. (This does not need to be a screen).
+0001: Keyboard
Read and return a keypress.
@@ -123,6 +132,7 @@ character that was read.
No subcommands are defined.
+0002: Floating Point
The current revision is 1.
@@ -159,9 +169,11 @@ It currently provides:
f:pop (f:-f)
f:adepth (-n)
+0003: Block Storage
Reserved for future use.
+0004: Filesystem
Currently at revision 0.
@@ -182,11 +194,13 @@ additional values.
| 7 | s- | Delete a file |
| 8 | h- | Flush pending writes |
+0010: Random Number Generator
This is currently at revision 0.
On invocation, this returns a random number.
+Implementation Details (C)
On the C implementation, each I/O device has the needed support
functions defined, then a query function and invocation function
diff --git a/doc/html/chapters/internals/io.html b/doc/html/chapters/internals/io.html
index cf45806..93d86e6 100644
--- a/doc/html/chapters/internals/io.html
+++ b/doc/html/chapters/internals/io.html
@@ -1,7 +1,7 @@
+
Retro provides three words for interacting with I/O. These are:
io:enumerate returns the number of attached devices
diff --git a/doc/html/chapters/internals/nga.html b/doc/html/chapters/internals/nga.html
index 2281488..d1a2647 100644
--- a/doc/html/chapters/internals/nga.html
+++ b/doc/html/chapters/internals/nga.html
@@ -1,7 +1,7 @@
+
Overview
At the heart of Retro is a simple MISC (minimal instruction
@@ -54,6 +55,7 @@ This is a very simple and straightforward system. There are
bit values. And there are two stacks: one for data and one
for return addresses.
+Instruction Table
| Stacks |
| Opcode | Muri | Full Name | Data | Address |
@@ -126,6 +128,7 @@ And returns a single one:
If y is positive, this shifts x right by y bits. If negative,
it shifts left.
+Queries: Memory, Stacks
The fe instruction allows queries of some data related to
the Nga VM state. These are returned by reading from negative
@@ -139,6 +142,7 @@ addresses:
| -4 | Minimum Integer Value |
| -5 | Maximum Integer Value |
+I/O Devices
Nga provides three instructions for interacting with I/O devices.
These are:
diff --git a/doc/html/chapters/tech-notes/code-it-yourself.html b/doc/html/chapters/tech-notes/code-it-yourself.html
index 77c6f32..1fc06ba 100644
--- a/doc/html/chapters/tech-notes/code-it-yourself.html
+++ b/doc/html/chapters/tech-notes/code-it-yourself.html
@@ -1,7 +1,7 @@
+
We use software for our everyday needs because we want to get
something done. We have goals to achieve and things to do.
diff --git a/doc/html/chapters/tech-notes/historical-papers.html b/doc/html/chapters/tech-notes/historical-papers.html
index 05152e5..c9cbbf2 100644
--- a/doc/html/chapters/tech-notes/historical-papers.html
+++ b/doc/html/chapters/tech-notes/historical-papers.html
@@ -1,7 +1,7 @@
+
+On the Naming of Retro
Taken from http://lists.tunes.org/archives/tunes-lll/1999-July/000121.html
@@ -87,6 +89,7 @@ software on 90's and 00's hardware :)
• Tom Novelli <tcn@tunes.org>
+The Design Philosophy of Retro Native Forth
Computer software is a technology in its infancy, a mere fifty years
old. The last 25 years in particular have seen an explosion in the
diff --git a/doc/html/chapters/tech-notes/kernel-words.html b/doc/html/chapters/tech-notes/kernel-words.html
index 8a6cc2a..43224df 100644
--- a/doc/html/chapters/tech-notes/kernel-words.html
+++ b/doc/html/chapters/tech-notes/kernel-words.html
@@ -1,7 +1,7 @@
+
In implementing the Retro 12 kernel (called Retro Core, and
defined in image/retro.muri) I had to decide on what functionality
would be needed. It was important to me that this be kept clean
diff --git a/doc/html/chapters/tech-notes/metacompilation.html b/doc/html/chapters/tech-notes/metacompilation.html
index 4200ac5..3f34b1c 100644
--- a/doc/html/chapters/tech-notes/metacompilation.html
+++ b/doc/html/chapters/tech-notes/metacompilation.html
@@ -1,7 +1,7 @@
+
Retro 10 and 11 were written in themselves using a metacompiler.
I had been fascinated by this idea for a long time and was able
to explore it heavily. While I still find it to be a good idea,
diff --git a/doc/html/chapters/tech-notes/ngaro-to-nga.html b/doc/html/chapters/tech-notes/ngaro-to-nga.html
index a0f9e9e..066d6b9 100644
--- a/doc/html/chapters/tech-notes/ngaro-to-nga.html
+++ b/doc/html/chapters/tech-notes/ngaro-to-nga.html
@@ -1,7 +1,7 @@
+
When I decided to begin work on what became Retro 12, I knew
the process would involve updating Ngaro, the virtual machine
that Retro 10 and 11 ran on.
diff --git a/doc/html/chapters/tech-notes/prefixes.html b/doc/html/chapters/tech-notes/prefixes.html
index bf13b89..7a6d91f 100644
--- a/doc/html/chapters/tech-notes/prefixes.html
+++ b/doc/html/chapters/tech-notes/prefixes.html
@@ -1,7 +1,7 @@
+
A big change in Retro 12 was the elimination of the traditional
parser from the language. This was a sacrifice due to the lack
of an I/O model. Retro has no way to know how input is given
diff --git a/doc/html/chapters/tech-notes/retro11-retrospective.html b/doc/html/chapters/tech-notes/retro11-retrospective.html
index 7eb8ba6..b10c848 100644
--- a/doc/html/chapters/tech-notes/retro11-retrospective.html
+++ b/doc/html/chapters/tech-notes/retro11-retrospective.html
@@ -1,7 +1,7 @@
+
So it's now been about five years since the last release of Retro
11. While I still see some people obtaining and using it, I've
moved on to the twelth generation of Retro. It's time for me to
diff --git a/doc/html/chapters/tech-notes/security.html b/doc/html/chapters/tech-notes/security.html
index ed676e9..57e4216 100644
--- a/doc/html/chapters/tech-notes/security.html
+++ b/doc/html/chapters/tech-notes/security.html
@@ -1,7 +1,7 @@
+
The standard Retro is not a good choice for applications
needing to be highly secure.
+Runtime Checks
The Retro system performs only minimal checks. It will not
load an image larger than the max set at build time. And
@@ -66,6 +68,7 @@ into the C portions.
I/O presents a bigger issue. Anything involving I/O, especially
with the unix: words, may be a vector for attacks.
+Future Direction
I'm not planning to add anything to the image side as, for me,
the performance hit due to added checks is bigger than the
diff --git a/doc/html/chapters/tech-notes/self-hosting.html b/doc/html/chapters/tech-notes/self-hosting.html
index 32d9082..0e58745 100644
--- a/doc/html/chapters/tech-notes/self-hosting.html
+++ b/doc/html/chapters/tech-notes/self-hosting.html
@@ -1,7 +1,7 @@
+
Retro is an image based Forth system running on a lightweight
virtual machine. This is the story of how that image is made.
diff --git a/doc/html/chapters/tech-notes/underscores-in-names.html b/doc/html/chapters/tech-notes/underscores-in-names.html
index 60d04b9..e003d17 100644
--- a/doc/html/chapters/tech-notes/underscores-in-names.html
+++ b/doc/html/chapters/tech-notes/underscores-in-names.html
@@ -1,7 +1,7 @@
+
In brief: don't use underscores in word names.
There is a good reason for this, and it has to do with how Retro
diff --git a/doc/html/chapters/techniques/arrays.html b/doc/html/chapters/techniques/arrays.html
index 398c480..e57eb57 100644
--- a/doc/html/chapters/techniques/arrays.html
+++ b/doc/html/chapters/techniques/arrays.html
@@ -1,7 +1,7 @@
+
RETRO offers a number of words for operating on statically sized
arrays.
@@ -51,6 +52,7 @@ arrays.
The words operating on arrays are kept in an a: namespace.
+Creating Arrays
The easiest way to create an array is to wrap the values in a
{ and } pair:
@@ -65,12 +67,14 @@ values and the number of values to store in the a:
```
[ #1 #2 #3 #3 ] a:counted-results
[ #1 #2 #3 #3 ] a:make
```
+Accessing Elements
You can access a specific value with a:th and fetch or
store:
```
{ #1 #2 #3 #4 } #3 a:th fetch
```
+Find The Length
Use a:length to find the size of the array.
diff --git a/doc/html/chapters/techniques/assembly.html b/doc/html/chapters/techniques/assembly.html
index f4603e2..dd4bade 100644
--- a/doc/html/chapters/techniques/assembly.html
+++ b/doc/html/chapters/techniques/assembly.html
@@ -1,7 +1,7 @@
+
RETRO runs on a virtual machine called Nga. It provides a
standard assembler for this called Muri.
Muri is a simple, multipass model that's not fancy, but
suffices for RETRO's needs.
+Assembling A Standalone File
A small example (test.muri)
@@ -111,6 +113,7 @@ each I/O instruction name. So a bundle may look like:
(This would correspond to dup multiply return nop).
+Runtime Assembler
RETRO also has a runtime variation of Muri that can be used
when you need to generate more optimal code. So one can write:
diff --git a/doc/html/chapters/techniques/buffer.html b/doc/html/chapters/techniques/buffer.html
index 24583be..220be15 100644
--- a/doc/html/chapters/techniques/buffer.html
+++ b/doc/html/chapters/techniques/buffer.html
@@ -1,7 +1,7 @@
+
RETRO provides words for operating on a linear memory area.
This can be useful in building strings or custom data
structures.
@@ -70,6 +71,7 @@ Only one buffer can be active at a time. RETRO provides a
buffer:preserve combinator to allow using a second one
before returning to the prior one.
+Set The Active Buffer
To set a buffer as the active one use buffer:set. This takes
an address.
@@ -77,16 +79,19 @@ an address.
The buffer will be assumed to be empty. The initial value will
be set to ASCII:NULL.
+Add Value
Use buffer:add to append a value to the buffer. This takes
a single value and will also add an ASCII:NULL after the end
of the buffer.
+Fetch Last Value
To return the last value in the buffer you can use buffer:get.
This removes the value and sets an ASCII:NULL in the memory
location the returned value occupied.
+Get Data About The Buffer
RETRO provides buffer:start to get the initial address in
the buffer, buffer:end to get the last address (ignoring the
diff --git a/doc/html/chapters/techniques/characters.html b/doc/html/chapters/techniques/characters.html
index f62e770..c274664 100644
--- a/doc/html/chapters/techniques/characters.html
+++ b/doc/html/chapters/techniques/characters.html
@@ -1,7 +1,7 @@
+
RETRO provides words for working with ASCII characters.
Sigil
diff --git a/doc/html/chapters/techniques/checking-the-version.html b/doc/html/chapters/techniques/checking-the-version.html
index 48367cd..0340431 100644
--- a/doc/html/chapters/techniques/checking-the-version.html
+++ b/doc/html/chapters/techniques/checking-the-version.html
@@ -1,7 +1,7 @@
+
RETRO releases add and change things. You can use the Version
variable to determine the version in use and react accordingly.
@@ -54,6 +55,7 @@ This can be also be used to conditionally load compatibility files:
```
(If_newer_than_2016.6,_load_aliases_for_renamed_words)
@Version #201906 gt? [ 'Renamed_2019.6.forth include ] if
```
+Version Number Format
The version is a six digit number encoding the year and month of
the release. So:
diff --git a/doc/html/chapters/techniques/definitions.html b/doc/html/chapters/techniques/definitions.html
index 005e024..8d35c1c 100644
--- a/doc/html/chapters/techniques/definitions.html
+++ b/doc/html/chapters/techniques/definitions.html
@@ -1,7 +1,7 @@
+
Words are named functions. To start a word, preceed it's name
with a colon. Follow this by the definition, and end with a
semicolon.
diff --git a/doc/html/chapters/techniques/dictionary.html b/doc/html/chapters/techniques/dictionary.html
index 9b8e34b..27e73c5 100644
--- a/doc/html/chapters/techniques/dictionary.html
+++ b/doc/html/chapters/techniques/dictionary.html
@@ -1,7 +1,7 @@
+
The Dictionary is a linked list containing the dictionary
headers.
@@ -56,6 +57,7 @@ Words operating on the dictionary are in the d: namespac
Dictionary is a variable holding a pointer to the most recent
header.
+Header Structure
Each entry follows the following structure:
@@ -71,12 +73,14 @@ RETRO provides words for accessing the fields in a portable
manner. It's recommended to use these to allow for future
revision of the header structure.
+Accessing Fields
Given a pointer to a header, you can use d:xt, d:class,
and d:name to access the address of each specific field.
There is no d:link, as the link will always be the first
field.
+Shortcuts For The Latest Header
RETRO provides several words for operating on the most recent
header.
@@ -85,6 +89,7 @@ header.
will give the contents of the d:xt field for the latest
header. There are also d:last.class and d:last.name.
+Adding Headers
Two words exist for making new headers. The easy one is
d:create. This takes a string for the name and makes a
@@ -126,6 +131,7 @@ of all words:
For each entry, this combinator will push a pointer to the
entry to the stack and call the quotation.
+Listing Words
Most Forth systems provide WORDS for listing the names of all
words in the dictionary. RETRO does as well, but this is named
diff --git a/doc/html/chapters/techniques/errors.html b/doc/html/chapters/techniques/errors.html
index 6b82ad2..ec464cc 100644
--- a/doc/html/chapters/techniques/errors.html
+++ b/doc/html/chapters/techniques/errors.html
@@ -1,7 +1,7 @@
+
On Unix and Windows systems RETRO provides a set of words for
working with files. As a pragmatic choice these are mostly
modeled after the file functions in libc.
The file words are in the file: namespace.
+File Access Modes
You can open a file for various operations. The functionality
allowed depends on the file access mode. Valid modes in RETRO
@@ -60,6 +62,7 @@ are:
file:R+ Open for reading and writing
file:W Open for writing
+Opening A File
To open a file, pass the file name and a file mode to file:open.
@@ -90,11 +93,13 @@ To open a file for append operations:
As with file:open-for-reading, this returns both the size of
the file and the file handle.
+Closing A File
To close a file, pass the file handle to file:close.
'/etc/motd file:A file:open file:close
+Reading From A File
To read a byte from an open file, pass the file handle to the
file:read word.
@@ -111,6 +116,7 @@ text to a safe place if you aren't using it quickly or if
the length of the line is bigger than the size of a temporary
string.
+Writing To A File
To write a byte to a file, pass it and the file handle to
file:write.
@@ -124,11 +130,13 @@ To write a byte to a file, pass it and the file handle to
Though cells are 32 or 64 bits in size, only the byte value will
be written to the file.
+Deleting Files
You can delete a file by passing the file name to file:delete.
/tmp/test file:delete
+Check For File Existance
Use file:exists? to detect the existance of a file. Pass it a
file name and it will return TRUE if existing or FALSE if
@@ -138,12 +146,14 @@ it does not.
This will also return TRUE if the filename is a directory.
+Flush Caches
Use file:flush to flush the system caches for a file. Pass a
file handle to this.
@FID file:flush
+Seek A Position Within A File
You can use file:seek to move the internal file pointer
for a given file. Pass this the new location and a file.
@@ -153,6 +163,7 @@ for a given file. Pass this the new location and a file.
The location for the file pointer is a fixed offset from the
start of the file, not a relative offset.
+Get The Current Position Within A File
To find the current value of the file pointer within a file
just pass the file handle to file:tell.
@@ -162,6 +173,7 @@ just pass the file handle to file:tell.
This returns a number that is the number of bytes into the file
that the file pointer is currently at.
+Determine The Size Of A File
Use file:size to return the size of a file. Pass this a file
handle and it will return the size of a file, or 0 if empty. If
@@ -169,6 +181,7 @@ the file is a directory, it returns -1.
@FID file:size
+Reading An Entire File
If you want to read an entire file into memory you can use
file:slurp. This takes the starting address of a memory
@@ -179,6 +192,7 @@ region and the name of the file.
Take care that the memory buffer is large enough for the file
being read or you will run into problems.
+Writing A String To A File
If you have a string that you want to write to a file, replacing
any existing contents, you can use file:spew. This takes the
@@ -186,6 +200,7 @@ string to write and a file name.
'hello_world '/tmp/test.txt file:spew
+Iterating Over A File, Line By Line
You can easily iterate over each line in a file using the word
file:for-each-line. This will take a file name and a quote,
diff --git a/doc/html/chapters/techniques/floating-point.html b/doc/html/chapters/techniques/floating-point.html
index 3b6c0ec..2963f86 100644
--- a/doc/html/chapters/techniques/floating-point.html
+++ b/doc/html/chapters/techniques/floating-point.html
@@ -1,7 +1,7 @@
+
Some RETRO systems include support for floating point numbers.
When present, this is built over the system libm using the
C double type.
@@ -135,6 +136,7 @@ like infinity and NaN.
• f:inf?
• f:nan?
+Basic Math
• f:*
• f:+
@@ -172,6 +174,7 @@ related calculations.
| f:sin | sine |
| f:tan | tangent |
+Storage and Retrieval
By leveraging the encoded value functions, RETRO is able to
allow storage of floating point values in memory. This does
@@ -193,6 +196,7 @@ store and retrieve values using multiple cells.
The floating point vocabulary has a single I/O word, f:put,
for the display of floating point numbers.
+Encoded Values
RETRO provides a means of encoding and decoding floating point
values into standard integer cells. This is based on the paper
diff --git a/doc/html/chapters/techniques/lexical-scope.html b/doc/html/chapters/techniques/lexical-scope.html
index 7445a60..9971cf2 100644
--- a/doc/html/chapters/techniques/lexical-scope.html
+++ b/doc/html/chapters/techniques/lexical-scope.html
@@ -1,7 +1,7 @@
+
RETRO has a single dictionary, but does provide a means of using
lexical scope to keep this dictionary clean.
@@ -89,6 +90,7 @@ example:
In this, after }} closes the area, the :a #2 ; is hidden and
the s:evaluate will find the :a #1 ; when b is run.
+A Word of Warning
Use of these words can result in a corrupt dictionary and system
crashes. Specifically, use of ---reveal--- with an empty private
diff --git a/doc/html/chapters/techniques/loops.html b/doc/html/chapters/techniques/loops.html
index 9d359f2..b8699d5 100644
--- a/doc/html/chapters/techniques/loops.html
+++ b/doc/html/chapters/techniques/loops.html
@@ -1,7 +1,7 @@
+
Nga has optional support for multiple virtual cores. These
are not directly comparable to actual CPU cores, but do
allow for a degree of multitasking.
@@ -83,6 +84,7 @@ Example:
#4 core:init
+Starting a Core
Initialization does not activate a core. To do this, you need
to use core:start. Pass this the address of the word to
@@ -93,6 +95,7 @@ Example:
:a [ $a c:put ] forever ;
&a #4 core:start
+Pausing a Core
Two words are provided for suspending a core. The first is
core:pause. Pass this the core number to pause.
@@ -108,6 +111,7 @@ Example:
core:pause-current
+Resuming a Core
To reactive a core, use core:resume. This takes the core
number to activate.
@@ -135,6 +139,7 @@ usable on Retro/Napia with minimal changes.
The main differences are that under Nga, this is an optional
extension, but in Napia, it is part of the standard system.
+Other Notes
On startup, execution occurs on core 0, with only core 0 being
initialized.
diff --git a/doc/html/chapters/techniques/naming-conventions.html b/doc/html/chapters/techniques/naming-conventions.html
index cd24d60..5aca74a 100644
--- a/doc/html/chapters/techniques/naming-conventions.html
+++ b/doc/html/chapters/techniques/naming-conventions.html
@@ -1,7 +1,7 @@
+
Word names in RETRO generally follow the following conventions.
+General Guidelines
• Readability is important
• Be consistent
@@ -55,6 +57,7 @@ Word names in RETRO generally follow the following conventions.
• Word names start with a - for "not"
• Words returning a flag end in ?
+Typical Format
The word names will generally follow a form like:
@@ -112,6 +115,7 @@ The common namespaces are:
Tips
+Don't Start Names With Sigil Characters
Avoid using a sigil as the first character of a word name. RETRO
will look for sigils first, this will prevent direct use of
@@ -121,6 +125,7 @@ To find a list of sigil characters, do:
'sigil: d:words-with
+Don't Use Underscores
Underscores in strings are replaced by spaces. This is problematic,
especially with variables. Consider:
diff --git a/doc/html/chapters/techniques/numbers.html b/doc/html/chapters/techniques/numbers.html
index 473eca9..6621c41 100644
--- a/doc/html/chapters/techniques/numbers.html
+++ b/doc/html/chapters/techniques/numbers.html
@@ -1,7 +1,7 @@
+
Numbers in RETRO are signed integers.
Sigil
@@ -54,6 +55,7 @@ All numbers start with a # sigil.
Most words operating on numbers are in the n: namespace.
+Range of Values
A default RETRO system with 32 bit cells provides a range of
-2,147,483,648 to 2,147,483,647. For 64 bit systems, the range
@@ -90,6 +92,7 @@ Additionally RETRO also provides:
n:strictly-positive?
n:zero?
+Basic Operations
+
-
diff --git a/doc/html/chapters/techniques/pointers.html b/doc/html/chapters/techniques/pointers.html
index 2552791..961e4e3 100644
--- a/doc/html/chapters/techniques/pointers.html
+++ b/doc/html/chapters/techniques/pointers.html
@@ -1,7 +1,7 @@
+
Sigil
Pointers are returned by the & sigil.
diff --git a/doc/html/chapters/techniques/quotes.html b/doc/html/chapters/techniques/quotes.html
index a4b2eec..bb608c9 100644
--- a/doc/html/chapters/techniques/quotes.html
+++ b/doc/html/chapters/techniques/quotes.html
@@ -1,7 +1,7 @@
+
RETRO has two stacks. The primary one is used to pass data
between words. The second one primarily holds return addresses.
diff --git a/doc/html/chapters/techniques/scripting.html b/doc/html/chapters/techniques/scripting.html
index 5951d16..f500915 100644
--- a/doc/html/chapters/techniques/scripting.html
+++ b/doc/html/chapters/techniques/scripting.html
@@ -1,7 +1,7 @@
+
RETRO on Unix hosts is designed to play well with scripting.
Shebang
diff --git a/doc/html/chapters/techniques/sockets.html b/doc/html/chapters/techniques/sockets.html
index 92e602b..f3e1ed1 100644
--- a/doc/html/chapters/techniques/sockets.html
+++ b/doc/html/chapters/techniques/sockets.html
@@ -1,7 +1,7 @@
+
Most words in RETRO have a stack comment. These look like:
(-)
diff --git a/doc/html/chapters/techniques/strings.html b/doc/html/chapters/techniques/strings.html
index 190e296..fb2df8f 100644
--- a/doc/html/chapters/techniques/strings.html
+++ b/doc/html/chapters/techniques/strings.html
@@ -1,7 +1,7 @@
+
Strings in RETRO are NULL terminated sequences of values
representing characters. Being NULL terminated, they can't
contain a NULL (ASCII 0).
@@ -177,6 +178,7 @@ which let you trim just the leading or trailing end as desired.
• s:format
• s:empty
+Controlling The Temporary Buffers
As dicussed in the Lifetime subsection, temporary strings are
allocated in a rotating buffer. The details of this can be
diff --git a/doc/html/chapters/techniques/the-stacks.html b/doc/html/chapters/techniques/the-stacks.html
index e654a9c..c8d9791 100644
--- a/doc/html/chapters/techniques/the-stacks.html
+++ b/doc/html/chapters/techniques/the-stacks.html
@@ -1,7 +1,7 @@
+
The stacks are a defining feature of Forth. They are are used
to pass data between words and to track return addresses for
function calls.
@@ -51,12 +52,14 @@ function calls.
RETRO always has two stacks, and optionally (if built with
floating point support) a third.
+Data Stack
This is the primary stack. Values are placed here, passed to
words which consume them and then return results. When I
refer to "the stack", this is the one I mean. Learning to use
the stack is a crucial part to making effective use of RETRO.
+Placing Values On The Stack
Values can be placed on the stack directly.
@@ -67,6 +70,7 @@ Values can be placed on the stack directly.
| `'hello_world` | Push a pointer to a string to the stack |
| `&fetch` | Push the address of `fetch` to the stack |
+Reordering The Stack
RETRO provides a number of shufflers for reordering items
on the stack.
@@ -109,15 +113,19 @@ states:
'abcd 'dcba reorder
+Resetting The Stack
If you need to quickly empty the stack, use reset.
+Get The Stack Depth
To find out how many items are on the stack, use depth.
+Displaying The Stack
You can display the stack by running dump-stack.
+Data Flow Combinators
RETRO provides combinators for working with data order on
the stack. These are covered in a later chapter and are worth
@@ -129,12 +137,14 @@ structured means of working.
The stack is not an array in addressable memory. Don't try
to treat it like one.
+Address Stack
This stack primarily holds return addresses for function calls.
You normally won't need to directly interact with this stack,
but you can use push and pop to move values between the
data stack and this.
+Floating Point Stack
If you are using a build with floating point support a third
stack will be present. Floating point values are kept and
diff --git a/doc/html/chapters/techniques/using-combinators.html b/doc/html/chapters/techniques/using-combinators.html
index 1d39f64..29ac753 100644
--- a/doc/html/chapters/techniques/using-combinators.html
+++ b/doc/html/chapters/techniques/using-combinators.html
@@ -1,7 +1,7 @@
+
A combinator is a function that consumes functions as input.
They are used heavily by the RETRO system.
+Types of Combinators
Combinators are divided into three primary types: compositional,
execution flow, and data flow.
@@ -72,6 +74,7 @@ the latest value. So:
dup call n:put
dup call n:put
```
+Execution Flow
Combinators of this type execute other functions.
@@ -151,6 +154,7 @@ access to the loop index (via I) and parent loop indexes
```
#10 [ I n:put sp ] indexed-times
```
+Data Flow
These combinators exist to simplify stack usage in various
circumstances.
diff --git a/doc/html/chapters/techniques/word-classes.html b/doc/html/chapters/techniques/word-classes.html
index 369a5f0..e3b6eff 100644
--- a/doc/html/chapters/techniques/word-classes.html
+++ b/doc/html/chapters/techniques/word-classes.html
@@ -1,7 +1,7 @@
+
Word classes are one of the two elements at the heart of
RETRO's interpreter.
@@ -55,6 +56,7 @@ In RETRO I define special words which receive a pointer and
decide how to deal with it. These are grouped into a class:
namespace.
+How It Works
When a word is found in the dictionary, RETRO will push a
pointer to the definition (the d:xt field) to the stack
@@ -77,6 +79,7 @@ like:
```
:class:word (a-) compiling? [ compile:call ] [ call ] choose ;
```
+Using Classes
The ability to add new classes is useful. If I wanted to add
a category of word that preserves an input value, I could do
diff --git a/doc/html/chapters/toolchain/info/additional-tools.html b/doc/html/chapters/toolchain/info/additional-tools.html
index e514b32..1d9e0af 100644
--- a/doc/html/chapters/toolchain/info/additional-tools.html
+++ b/doc/html/chapters/toolchain/info/additional-tools.html
@@ -1,7 +1,7 @@
+
In addition to the core retro binary, the bin directory
will contain a few other tools.
@@ -95,6 +96,7 @@ RETRO kernel and can be used by other tools as well.
retro-muri retro.muri
+retro-tags and retro-locate
These tools are intended to be used together. The first tool,
retro-tags, will recursively scan the current directory for
diff --git a/doc/html/chapters/toolchain/info/retro-compiler.html b/doc/html/chapters/toolchain/info/retro-compiler.html
index 4c4b970..e5e196d 100644
--- a/doc/html/chapters/toolchain/info/retro-compiler.html
+++ b/doc/html/chapters/toolchain/info/retro-compiler.html
@@ -1,7 +1,7 @@
+
In addition to the base system, users of RETRO on Unix hosts
with ELF executables can build and use the retro-compiler
to generate turnkey executables.
@@ -83,6 +84,7 @@ Use:
The compiler will generate an a.out file which you can
then rename.
+Known Limitations
This does not provide the scripting support for command line
arguments that the standard retro interface offers.
diff --git a/doc/html/chapters/toolchain/man/retro-describe.html b/doc/html/chapters/toolchain/man/retro-describe.html
index c631a90..674b542 100644
--- a/doc/html/chapters/toolchain/man/retro-describe.html
+++ b/doc/html/chapters/toolchain/man/retro-describe.html
@@ -1,7 +1,7 @@