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.
@@ -52,7 +51,6 @@ 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
@@ -88,13 +86,11 @@ 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
@@ -103,7 +99,6 @@ 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
@@ -111,7 +106,6 @@ 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:
@@ -119,7 +113,6 @@ 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.
@@ -129,7 +122,6 @@ 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 3199a45..5e1382e 100644
--- a/doc/html/chapters/building/alternatives.html
+++ b/doc/html/chapters/building/alternatives.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
-
+
In addition to the C implementation, there are a few other
interfaces that can be built.
@@ -126,13 +125,11 @@ 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 f2058ac..a036788 100644
--- a/doc/html/chapters/building/obtaining.html
+++ b/doc/html/chapters/building/obtaining.html
@@ -43,9 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
-Stable Releases
+
I periodically make stable releases. This will typically happen
quarterly.
@@ -64,7 +62,6 @@ 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:
@@ -85,7 +82,6 @@ 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 d40b556..3c8300a 100644
--- a/doc/html/chapters/building/unix.html
+++ b/doc/html/chapters/building/unix.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Retro is well supported on BSD (tested on FreeBSD, NetBSD,
OpenBSD), Linux, and macOS systems. It should build on any
of these without issue.
@@ -75,7 +74,6 @@ 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:
@@ -94,7 +92,6 @@ 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 7278bc9..f808056 100644
--- a/doc/html/chapters/building/windows.html
+++ b/doc/html/chapters/building/windows.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
It is possible to build Retro on Windows, though a few of the
extensions are not supported:
@@ -55,7 +54,6 @@ 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.
@@ -65,7 +63,6 @@ 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 fc8e2b1..d401d4f 100644
--- a/doc/html/chapters/general/basic-interactions.html
+++ b/doc/html/chapters/general/basic-interactions.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Start Retro in interactive mode:
```
retro -i
diff --git a/doc/html/chapters/general/copyrights.html b/doc/html/chapters/general/copyrights.html
index cd9069f..efb1a53 100644
--- a/doc/html/chapters/general/copyrights.html
+++ b/doc/html/chapters/general/copyrights.html
@@ -54,7 +54,6 @@ United States.
The historical papers are Copyright (c) 1999-2000 by
Tom Novelli.
-Legal Text
See https://creativecommons.org/publicdomain/zero/1.0/legalcode
diff --git a/doc/html/chapters/general/deprecation.html b/doc/html/chapters/general/deprecation.html
index c6121f4..96a5696 100644
--- a/doc/html/chapters/general/deprecation.html
+++ b/doc/html/chapters/general/deprecation.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
-
+
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 2abd61c..f152d18 100644
--- a/doc/html/chapters/general/introduction.html
+++ b/doc/html/chapters/general/introduction.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 cd96955..9951260 100644
--- a/doc/html/chapters/general/markdown.html
+++ b/doc/html/chapters/general/markdown.html
@@ -43,13 +43,11 @@
.hr { display: block; height: 2px; background: #000000; }
+
I use a variation of Markdown for writing documentation and
when commenting code written in Retro. The syntax is
described below.
-Basic Syntax
Headings
@@ -65,7 +63,6 @@ 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.
@@ -96,7 +93,6 @@ 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
@@ -120,7 +116,6 @@ the list marker can be used.
Code
-Code Blocks
Code blocks start and end with ~~~ on a line by themselves.
@@ -134,7 +129,6 @@ 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.
@@ -143,7 +137,6 @@ 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 7d66815..86bac8d 100644
--- a/doc/html/chapters/general/quick-tutorial.html
+++ b/doc/html/chapters/general/quick-tutorial.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
-
+
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 2ca129d..cd0591c 100644
--- a/doc/html/chapters/general/retro-unu.html
+++ b/doc/html/chapters/general/retro-unu.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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
@@ -87,7 +86,6 @@ 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 8e2c98c..e05b7b8 100644
--- a/doc/html/chapters/general/starting.html
+++ b/doc/html/chapters/general/starting.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Retro can be run for scripting or interactive use.
Interactive
@@ -62,7 +61,6 @@ Or:
```
This should be sufficient for most uses.
-Using In a Pipe
Retro will work with piped input.
@@ -70,7 +68,6 @@ 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:
@@ -92,7 +89,6 @@ 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 cdd40f0..3e04ec6 100644
--- a/doc/html/chapters/general/syntax.html
+++ b/doc/html/chapters/general/syntax.html
@@ -122,7 +122,6 @@ The major sigils are:
The individual sigils will be covered in more detail in the
later chapters on working with different data types.
-Word Classes
Word classes are words which take a pointer and do something
with it. These are covered in detail in their own chapter,
diff --git a/doc/html/chapters/internals/calling-retro-from-c.html b/doc/html/chapters/internals/calling-retro-from-c.html
index dbade3c..899a959 100644
--- a/doc/html/chapters/internals/calling-retro-from-c.html
+++ b/doc/html/chapters/internals/calling-retro-from-c.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 4e74890..921d8d8 100644
--- a/doc/html/chapters/internals/image.html
+++ b/doc/html/chapters/internals/image.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 12822ac..e1dc7e4 100644
--- a/doc/html/chapters/internals/interface-layers.html
+++ b/doc/html/chapters/internals/interface-layers.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 36dc385..a7df869 100644
--- a/doc/html/chapters/internals/io-devices.html
+++ b/doc/html/chapters/internals/io-devices.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
I/O devices on Nga are exposed via three instructions:
ie enumerate i/o devices
@@ -54,7 +53,6 @@ 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.
@@ -63,14 +61,12 @@ 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.
@@ -83,7 +79,6 @@ 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:
@@ -107,23 +102,19 @@ 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.
@@ -132,7 +123,6 @@ character that was read.
No subcommands are defined.
-0002: Floating Point
The current revision is 1.
@@ -169,11 +159,9 @@ It currently provides:
f:pop (f:-f)
f:adepth (-n)
-0003: Block Storage
Reserved for future use.
-0004: Filesystem
Currently at revision 0.
@@ -194,13 +182,11 @@ 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 217a5ac..cf45806 100644
--- a/doc/html/chapters/internals/io.html
+++ b/doc/html/chapters/internals/io.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 52e9ca0..2281488 100644
--- a/doc/html/chapters/internals/nga.html
+++ b/doc/html/chapters/internals/nga.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Overview
At the heart of Retro is a simple MISC (minimal instruction
@@ -55,7 +54,6 @@ 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 |
@@ -128,7 +126,6 @@ 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
@@ -142,7 +139,6 @@ 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 75f4440..77c6f32 100644
--- a/doc/html/chapters/tech-notes/code-it-yourself.html
+++ b/doc/html/chapters/tech-notes/code-it-yourself.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 de611d5..05152e5 100644
--- a/doc/html/chapters/tech-notes/historical-papers.html
+++ b/doc/html/chapters/tech-notes/historical-papers.html
@@ -43,9 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
-On the Naming of Retro
+
Taken from http://lists.tunes.org/archives/tunes-lll/1999-July/000121.html
@@ -89,7 +87,6 @@ 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 f5f7030..8a6cc2a 100644
--- a/doc/html/chapters/tech-notes/kernel-words.html
+++ b/doc/html/chapters/tech-notes/kernel-words.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 4f9ea03..4200ac5 100644
--- a/doc/html/chapters/tech-notes/metacompilation.html
+++ b/doc/html/chapters/tech-notes/metacompilation.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 9ff885d..a0f9e9e 100644
--- a/doc/html/chapters/tech-notes/ngaro-to-nga.html
+++ b/doc/html/chapters/tech-notes/ngaro-to-nga.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 c9e6824..bf13b89 100644
--- a/doc/html/chapters/tech-notes/prefixes.html
+++ b/doc/html/chapters/tech-notes/prefixes.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 38ebd80..7eb8ba6 100644
--- a/doc/html/chapters/tech-notes/retro11-retrospective.html
+++ b/doc/html/chapters/tech-notes/retro11-retrospective.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 96c49a4..ed676e9 100644
--- a/doc/html/chapters/tech-notes/security.html
+++ b/doc/html/chapters/tech-notes/security.html
@@ -43,12 +43,10 @@
.hr { display: block; height: 2px; background: #000000; }
+
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
@@ -68,7 +66,6 @@ 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 f3f328d..32d9082 100644
--- a/doc/html/chapters/tech-notes/self-hosting.html
+++ b/doc/html/chapters/tech-notes/self-hosting.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Retro is an image based Forth system running on a lightweight
virtual machine. This is the story of how that image is made.
@@ -83,10 +82,10 @@ This caused a large number of issues over R11's life.
So on to Retro 12. I decided that this would be different.
First, the kernel would be assembly, with an external tool
-to generate the core image. The kernel is in Rx.md and the
-assembler is Muri. To load the standard library, I wrote a
-second tool, Retro-extend. This separation has allowed me
-many fewer headaches as I can make changes more easily and
+to generate the core image. The kernel is in image/retro.muri
+and the assembler is Muri. To load the standard library, I
+wrote a second tool, Retro-extend. This separation has allowed
+me many fewer headaches as I can make changes more easily and
rebuild from scratch when necessary.
But I miss self-hosting. So last fall I decided to resolve
diff --git a/doc/html/chapters/tech-notes/underscores-in-names.html b/doc/html/chapters/tech-notes/underscores-in-names.html
index 72ddd12..60d04b9 100644
--- a/doc/html/chapters/tech-notes/underscores-in-names.html
+++ b/doc/html/chapters/tech-notes/underscores-in-names.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 c4bd62c..398c480 100644
--- a/doc/html/chapters/techniques/arrays.html
+++ b/doc/html/chapters/techniques/arrays.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
RETRO offers a number of words for operating on statically sized
arrays.
@@ -52,7 +51,6 @@ 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:
@@ -67,14 +65,12 @@ 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 cbbf9fb..f4603e2 100644
--- a/doc/html/chapters/techniques/assembly.html
+++ b/doc/html/chapters/techniques/assembly.html
@@ -43,15 +43,13 @@
.hr { display: block; height: 2px; background: #000000; }
+
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)
@@ -113,7 +111,6 @@ 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 1157d71..24583be 100644
--- a/doc/html/chapters/techniques/buffer.html
+++ b/doc/html/chapters/techniques/buffer.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
RETRO provides words for operating on a linear memory area.
This can be useful in building strings or custom data
structures.
@@ -71,7 +70,6 @@ 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.
@@ -79,19 +77,16 @@ 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 d4b31ea..f62e770 100644
--- a/doc/html/chapters/techniques/characters.html
+++ b/doc/html/chapters/techniques/characters.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 24e720f..48367cd 100644
--- a/doc/html/chapters/techniques/checking-the-version.html
+++ b/doc/html/chapters/techniques/checking-the-version.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
RETRO releases add and change things. You can use the Version
variable to determine the version in use and react accordingly.
@@ -55,7 +54,6 @@ 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 d4eaf8c..005e024 100644
--- a/doc/html/chapters/techniques/definitions.html
+++ b/doc/html/chapters/techniques/definitions.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 5acc0bb..9b8e34b 100644
--- a/doc/html/chapters/techniques/dictionary.html
+++ b/doc/html/chapters/techniques/dictionary.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
The Dictionary is a linked list containing the dictionary
headers.
@@ -57,7 +56,6 @@ 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:
@@ -73,14 +71,12 @@ 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.
@@ -89,7 +85,6 @@ 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
@@ -131,7 +126,6 @@ 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/files.html b/doc/html/chapters/techniques/files.html
index 7ad06e1..f1f627c 100644
--- a/doc/html/chapters/techniques/files.html
+++ b/doc/html/chapters/techniques/files.html
@@ -43,15 +43,13 @@
.hr { display: block; height: 2px; background: #000000; }
+
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
@@ -62,7 +60,6 @@ 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.
@@ -93,13 +90,11 @@ 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.
@@ -116,7 +111,6 @@ 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.
@@ -130,13 +124,11 @@ 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
@@ -146,14 +138,12 @@ 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.
@@ -163,7 +153,6 @@ 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.
@@ -173,7 +162,6 @@ 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
@@ -181,7 +169,6 @@ 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
@@ -192,7 +179,6 @@ 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
@@ -200,7 +186,6 @@ 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 d0b6658..3b6c0ec 100644
--- a/doc/html/chapters/techniques/floating-point.html
+++ b/doc/html/chapters/techniques/floating-point.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Some RETRO systems include support for floating point numbers.
When present, this is built over the system libm using the
C double type.
@@ -136,7 +135,6 @@ like infinity and NaN.
• f:inf?
• f:nan?
-Basic Math
• f:*
• f:+
@@ -174,7 +172,6 @@ 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
@@ -196,7 +193,6 @@ 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 716ec56..7445a60 100644
--- a/doc/html/chapters/techniques/lexical-scope.html
+++ b/doc/html/chapters/techniques/lexical-scope.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
RETRO has a single dictionary, but does provide a means of using
lexical scope to keep this dictionary clean.
@@ -90,7 +89,6 @@ 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 1e84526..9d359f2 100644
--- a/doc/html/chapters/techniques/loops.html
+++ b/doc/html/chapters/techniques/loops.html
@@ -47,7 +47,6 @@
RETRO provides several words for creating loops.
-Unconditional Loops
An unconditional loop begins with repeat and ends with again.
@@ -72,7 +71,6 @@ Be careful with recursion as the virtual machine will have a limited
amount of space for the address stack and recursing too many times
can cause a stack overflow.
-Conditional Loops
There are two conditional looping combinators: while and until.
Both take a quote and execute it, checking a returned flag to decide
@@ -81,7 +79,6 @@ when to stop running.
#0 [ dup n:put sp n:inc dup #10 eq? ] until
#10 [ dup n:put sp n:dec dup n:-zero? ] while
-Counted Loops
There are two combinators for counted loops. These are times and
indexed-times.
diff --git a/doc/html/chapters/techniques/multicore.html b/doc/html/chapters/techniques/multicore.html
index 7704837..fd158f7 100644
--- a/doc/html/chapters/techniques/multicore.html
+++ b/doc/html/chapters/techniques/multicore.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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.
@@ -84,7 +83,6 @@ 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
@@ -95,7 +93,6 @@ 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.
@@ -111,7 +108,6 @@ Example:
core:pause-current
-Resuming a Core
To reactive a core, use core:resume. This takes the core
number to activate.
@@ -139,7 +135,6 @@ 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 f0443cc..cd24d60 100644
--- a/doc/html/chapters/techniques/naming-conventions.html
+++ b/doc/html/chapters/techniques/naming-conventions.html
@@ -43,11 +43,9 @@
.hr { display: block; height: 2px; background: #000000; }
+
Word names in RETRO generally follow the following conventions.
-General Guidelines
• Readability is important
• Be consistent
@@ -57,7 +55,6 @@ 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:
@@ -115,7 +112,6 @@ 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
@@ -125,7 +121,6 @@ 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 13e5a94..473eca9 100644
--- a/doc/html/chapters/techniques/numbers.html
+++ b/doc/html/chapters/techniques/numbers.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Numbers in RETRO are signed integers.
Sigil
@@ -55,7 +54,6 @@ 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
@@ -92,7 +90,6 @@ 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 a12846a..2552791 100644
--- a/doc/html/chapters/techniques/pointers.html
+++ b/doc/html/chapters/techniques/pointers.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Sigil
Pointers are returned by the & sigil.
diff --git a/doc/html/chapters/techniques/quotes.html b/doc/html/chapters/techniques/quotes.html
index 54bc5f1..a4b2eec 100644
--- a/doc/html/chapters/techniques/quotes.html
+++ b/doc/html/chapters/techniques/quotes.html
@@ -48,7 +48,6 @@
Quotes are anonymous functions. RETRO uses these as the basis for
executable flow control and combinatorial logic.
-Using Quotations
To make a quotation, surround the code with square brackets. E.g.,
@@ -79,7 +78,6 @@ A quotation is compiled as:
d address of code for quotation
... code after quotation ....
-Other Notes
Quotations are used heavily in RETRO. They give the source a
feel that's different from traditional Forth, and allow for
diff --git a/doc/html/chapters/techniques/return-stack.html b/doc/html/chapters/techniques/return-stack.html
index 0e58c48..8701d5d 100644
--- a/doc/html/chapters/techniques/return-stack.html
+++ b/doc/html/chapters/techniques/return-stack.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 8e6c867..5951d16 100644
--- a/doc/html/chapters/techniques/scripting.html
+++ b/doc/html/chapters/techniques/scripting.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 a43b12e..92e602b 100644
--- a/doc/html/chapters/techniques/sockets.html
+++ b/doc/html/chapters/techniques/sockets.html
@@ -48,7 +48,6 @@
On Unix hosts, RETRO provides an optional set of words for using
network sockets.
-Create a Socket
To create a new socket, just run:
@@ -56,7 +55,6 @@ To create a new socket, just run:
This will return a socket handle.
-Bind To A Port
To bind to a port, pass the port number and socket handle
to socket:bind. The port should be a string. This will return
@@ -64,7 +62,6 @@ to socket:bind. The port should be a string. This will r
'9998 @Sock socket:bind
-Configure To Allow Incoming Connections
To prepare a socket for incoming connections use socket:listen. This
will take a backlog count and a socket handle. It returns a flag
@@ -72,14 +69,12 @@ will take a backlog count and a socket handle. It returns a flag
#3 @Sock socket:listen
-Accept Connections
To accept connections pass the socket handle to socket:accept.
This returns a new socket for the connection and an error code.
@Sock socket:accept
-Make A Connection
To connect to a server using the socket:
@@ -88,7 +83,6 @@ To connect to a server using the socket:
socket:connect will return a status code and an error code.
-Writing To A Socket
To write a string to a socket, use socket:send. This will
take a string and a socket handle and will return the number
@@ -96,7 +90,6 @@ of bytes sent and an error code.
'test @Sock socket:send
-Reading From A Socket
To read data from a socket pass an address, a maximum number of
bytes, and the socket handle to socket:recv. This will return
@@ -105,7 +98,6 @@ be stored in memory starting at the specified address.
here #1024 @Sock socket:recv
-Close a Socket
To close a socket, pass the socket handle to socket:close.
diff --git a/doc/html/chapters/techniques/stack-diagrams.html b/doc/html/chapters/techniques/stack-diagrams.html
index fb0ee51..7955ef0 100644
--- a/doc/html/chapters/techniques/stack-diagrams.html
+++ b/doc/html/chapters/techniques/stack-diagrams.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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 db2d31b..190e296 100644
--- a/doc/html/chapters/techniques/strings.html
+++ b/doc/html/chapters/techniques/strings.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Strings in RETRO are NULL terminated sequences of values
representing characters. Being NULL terminated, they can't
contain a NULL (ASCII 0).
@@ -178,7 +177,6 @@ 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 d1ac617..e654a9c 100644
--- a/doc/html/chapters/techniques/the-stacks.html
+++ b/doc/html/chapters/techniques/the-stacks.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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.
@@ -52,14 +51,12 @@ 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.
@@ -70,7 +67,6 @@ 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.
@@ -113,19 +109,15 @@ 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
@@ -137,14 +129,12 @@ 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 7fcd43a..1d39f64 100644
--- a/doc/html/chapters/techniques/using-combinators.html
+++ b/doc/html/chapters/techniques/using-combinators.html
@@ -43,12 +43,10 @@
.hr { display: block; height: 2px; background: #000000; }
+
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.
@@ -74,7 +72,6 @@ the latest value. So:
dup call n:put
dup call n:put
```
-Execution Flow
Combinators of this type execute other functions.
@@ -154,7 +151,6 @@ 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 16d7d1b..369a5f0 100644
--- a/doc/html/chapters/techniques/word-classes.html
+++ b/doc/html/chapters/techniques/word-classes.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
Word classes are one of the two elements at the heart of
RETRO's interpreter.
@@ -56,7 +55,6 @@ 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
@@ -79,7 +77,6 @@ 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 c3d250b..e514b32 100644
--- a/doc/html/chapters/toolchain/info/additional-tools.html
+++ b/doc/html/chapters/toolchain/info/additional-tools.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
In addition to the core retro binary, the bin directory
will contain a few other tools.
@@ -96,7 +95,6 @@ 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 bd8077a..4c4b970 100644
--- a/doc/html/chapters/toolchain/info/retro-compiler.html
+++ b/doc/html/chapters/toolchain/info/retro-compiler.html
@@ -43,8 +43,7 @@
.hr { display: block; height: 2px; background: #000000; }
+
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.
@@ -84,7 +83,6 @@ 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.