diff --git a/doc/html/chapters/building/advanced.html b/doc/html/chapters/building/advanced.html index f0fe771..7c6fbf8 100644 --- a/doc/html/chapters/building/advanced.html +++ b/doc/html/chapters/building/advanced.html @@ -1,7 +1,7 @@ -. +doc/book/building/advanced -



+

Customizing the Build +

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 @@ -. +doc/book/building/alternatives -



+

Building Alternative Systems +

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 @@ -. +doc/book/building/obtaining -



+

Obtaining Retro +

+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 @@ -. +doc/book/building/unix -



+

Building on BSD, Linux, macOS, and other Unix Targets +

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 @@ -. +doc/book/building/windows -



+

Building Retro on Windows +

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 @@ -. +doc/book/general/basic-interactions -



+

Basic Interactions +

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 @@ -. +doc/book/general/copyrights -



+

Deprecation Policy +

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 @@ -. +doc/book/general/introduction -



+

Retro: a Modern, Pragmatic Forth +

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 @@ -. +doc/book/general/markdown -



+

Retro's Markdown Syntax +

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 @@ -. +doc/book/general/quick-tutorial -



+

A Quick Tutorial +

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 @@ -. +doc/book/general/retro-unu -



+

Unu: Simple, Literate Source Files +

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 @@ -. +doc/book/general/starting -



+

Starting Retro +

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 @@ -. +doc/book/general/syntax -



+

Calling Retro from C +

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 @@ -. +doc/book/internals/image -



+

Internals: The Retro Image +

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 @@ -. +doc/book/internals/interface-layers -



+

Internals: Interface Layers +

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 @@ -. +doc/book/internals/io-devices -



+

I/O Devices +

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 @@ -. +doc/book/internals/io -



+

Internals: I/O +

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 @@ -. +doc/book/internals/nga -



+

Internals: Nga Virtual Machine +

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 @@ -. +doc/book/tech-notes/code-it-yourself -



+

The Code It Yourself Manifesto +

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 @@ -. +doc/book/tech-notes/historical-papers -



+

Historical Papers and Notes +

+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 @@ -. +doc/book/tech-notes/kernel-words -



+

On The Kernel Wordset +

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 @@ -. +doc/book/tech-notes/metacompilation -



+

Metacompilation and Assembly +

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 @@ -. +doc/book/tech-notes/ngaro-to-nga -



+

On The Evolution Of Ngaro Into Nga +

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 @@ -. +doc/book/tech-notes/prefixes -



+

Sigils as a Language Element +

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 @@ -. +doc/book/tech-notes/retro11-retrospective -



+

Retro 11 (2011 - 2019): A Look Back +

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 @@ -. +doc/book/tech-notes/security -



+

Security Concerns +

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 @@ -. +doc/book/tech-notes/self-hosting -



+

The Path to Self Hosting +

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 @@ -. +doc/book/tech-notes/underscores-in-names -



+

On The Use Of Underscores In Word Names +

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 @@ -. +doc/book/techniques/arrays -



+

Working With Arrays +

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 @@ -. +doc/book/techniques/assembly -



+

Working With Assembly Language +

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 @@ -. +doc/book/techniques/buffer -



+

Working With a Buffer +

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 @@ -. +doc/book/techniques/characters -



+

Working With Characters +

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 @@ -. +doc/book/techniques/checking-the-version -



+

Checking The Version +

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 @@ -. +doc/book/techniques/definitions -



+

Defining Words +

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 @@ -. +doc/book/techniques/dictionary -



+

Working With The Dictionary +

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 @@ -. +doc/book/techniques/errors -



+

Working With Files +

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 @@ -. +doc/book/techniques/floating-point -



+

Working With Floating Point +

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 @@ -. +doc/book/techniques/lexical-scope -



+

Lexical Scope +

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 @@ -. +doc/book/techniques/loops -



+

Multiple Cores +

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 @@ -. +doc/book/techniques/naming-conventions -



+

Naming Conventions +

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 @@ -. +doc/book/techniques/numbers -



+

Working With Numbers +

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 @@ -. +doc/book/techniques/pointers -



+

Working With Pointers +

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 @@ -. +doc/book/techniques/quotes -



+

The Return Stack +

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 @@ -. +doc/book/techniques/scripting -



+

Unix Scripting +

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 @@ -. +doc/book/techniques/sockets -



+

Stack Diagrams +

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 @@ -. +doc/book/techniques/strings -



+

Working With Strings +

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 @@ -. +doc/book/techniques/the-stacks -



+

The Stacks +

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 @@ -. +doc/book/techniques/using-combinators -



+

Using Combinators +

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 @@ -. +doc/book/techniques/word-classes -



+

Word Classes +

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 @@ -. +doc/book/toolchain/info/additional-tools -



+

Additional Tools +

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 @@ -. +doc/book/toolchain/info/retro-compiler -



+

The Optional Retro Compiler +

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 @@ -. +doc/book/toolchain/man/retro-describe