generate & include html documentation files
FossilOrigin-Name: 03f8a1f5293ceeb245b4e6315578c114c69eb4341027fad8eba5ec8c8dbca5fa
This commit is contained in:
crc
parent
1052e8a83c
commit
e4a838d588
64 changed files with 7535 additions and 0 deletions
69
doc/html/chapters/building/advanced.html
Normal file
69
doc/html/chapters/building/advanced.html
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Advanced Builds</span>
|
||||
<br/><br/>
|
||||
<span class="h2">Custom Image</span>
|
||||
<br/><br/>
|
||||
For users of BSD, Linux, macOS, you can customize the image at
|
||||
build time.
|
||||
<br/><br/>
|
||||
In the top level directory is a <span class="tt">package</span> directory containing
|
||||
a file named <span class="tt">list.forth</span>. You can add files to compile into
|
||||
your system by adding them to the <span class="tt">list.forth</span> and rebuilding.
|
||||
<br/><br/>
|
||||
Example:
|
||||
<br/><br/>
|
||||
If you have wanted to include the NumbersWithoutPrefixes.forth
|
||||
example, add:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>'example/NumbersWithoutPrefixes.forth include</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
To the start of the <span class="tt">list.forth</span> file and then run <span class="tt">make</span> again.
|
||||
The newly built <span class="tt">bin/retro</span> will now include your additions.
|
||||
</p>
|
||||
</body></html>
|
||||
155
doc/html/chapters/building/alternatives.html
Normal file
155
doc/html/chapters/building/alternatives.html
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Building Alternative Systems</span>
|
||||
<br/><br/>
|
||||
In addition to the C implementation, there are a few other
|
||||
interfaces that can be built.
|
||||
<br/><br/>
|
||||
<span class="h2">Requirements</span>
|
||||
<br/><br/>
|
||||
• c compiler (tested: clang, tcc, gcc)<br/>
|
||||
• make<br/>
|
||||
• standard unix shell<br/>
|
||||
<br/><br/>
|
||||
<span class="h2">retro-repl</span>
|
||||
<br/><br/>
|
||||
A basic interactive system can be built by using:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>make bin/retro-repl</tt>
|
||||
<br/><br/>
|
||||
This requires a copy of <span class="tt">ngaImage</span> to be in the current
|
||||
directory.
|
||||
<br/><br/>
|
||||
<span class="h2">Barebones</span>
|
||||
<br/><br/>
|
||||
This is a minimal version of the <span class="tt">retro-repl</span>. It keeps the C
|
||||
portion as short as possible, making it a useful starting point
|
||||
for new interfaces.
|
||||
<br/><br/>
|
||||
To build:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>make bin/retro-barebones</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">retro-compiler</span>
|
||||
<br/><br/>
|
||||
This is a turnkey compiler. It can compile a new executable
|
||||
bundling a Retro VM and image.
|
||||
<br/><br/>
|
||||
Requirements:
|
||||
<br/><br/>
|
||||
• BSD or Linux<br/>
|
||||
• objcopy in $PATH<br/>
|
||||
<br/><br/>
|
||||
To build:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>make bin/retro-compiler</tt>
|
||||
<br/><br/>
|
||||
Example use:
|
||||
<br/><br/>
|
||||
1. Given a source file like "Hello.forth":
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>:hello 'hello_world! s:put nl ;</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
2. Use:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>./bin/retro-compiler Hello.forth hello</tt>
|
||||
<br/><br/>
|
||||
The first argument is the source file, the second is the
|
||||
word to run on startup.
|
||||
<br/><br/>
|
||||
3. Run the generated <span class="tt">a.out</span>
|
||||
<br/><br/>
|
||||
Limits:
|
||||
<br/><br/>
|
||||
This only supports the core words ('all' interface) and the
|
||||
file i/o words. Support for other I/O extensions will be
|
||||
added in the future.
|
||||
<br/><br/>
|
||||
<span class="h2">Pascal</span>
|
||||
<br/><br/>
|
||||
There is a Pascal version of <span class="tt">retro-repl</span>.
|
||||
<br/><br/>
|
||||
Dependencies:
|
||||
<br/><br/>
|
||||
• freepascal<br/>
|
||||
<br/><br/>
|
||||
Building:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>cd vm/nga-pascal</tt>
|
||||
<tt class='indentedcode'>fpc listener.lpr</tt>
|
||||
<br/><br/>
|
||||
This will require a copy of the <span class="tt">ngaImage</span> in the
|
||||
current directory.
|
||||
<br/><br/>
|
||||
<span class="h2">Python: retro.py</span>
|
||||
<br/><br/>
|
||||
This is an implementation of <span class="tt">retro-repl</span> in Python. As
|
||||
with <span class="tt">retro-repl</span> it requires the <span class="tt">ngaImage</span> in the current
|
||||
directory when starting.
|
||||
<br/><br/>
|
||||
<span class="h2">C#: retro.cs</span>
|
||||
<br/><br/>
|
||||
This is an implementation of <span class="tt">retro-repl</span> in C#. As with
|
||||
<span class="tt">retro-repl</span> it requires the <span class="tt">ngaImage</span> in the current
|
||||
directory when starting.
|
||||
<br/><br/>
|
||||
Building:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>cd vm\nga-csharp</tt>
|
||||
<tt class='indentedcode'>csc retro.cs</tt>
|
||||
<br/><br/>
|
||||
You'll need to make sure your path has the CSC.EXE in it,
|
||||
or provide a full path to it. Something like this should
|
||||
reveal the path to use:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>dir /s %WINDIR%\CSC.EXE</tt>
|
||||
<br/><br/>
|
||||
I've only tested building this using Microsoft's .NET tools.
|
||||
It should also build and run under Mono.
|
||||
</p>
|
||||
</body></html>
|
||||
102
doc/html/chapters/building/obtaining.html
Normal file
102
doc/html/chapters/building/obtaining.html
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Obtaining RETRO</span>
|
||||
<br/><br/>
|
||||
<span class="h2">Stable Releases</span>
|
||||
<br/><br/>
|
||||
I periodically make stable releases. This will typically happen
|
||||
quarterly.
|
||||
<br/><br/>
|
||||
• http://forthworks.com/retro<br/>
|
||||
• http://forth.works<br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Snapshots</span>
|
||||
<br/><br/>
|
||||
A lot of development happens between releases. I make snapshots
|
||||
of my working source tree nightly (and often more often).
|
||||
<br/><br/>
|
||||
The latest snapshot can be downloaded from the following stable
|
||||
URLs:
|
||||
<br/><br/>
|
||||
• http://forthworks.com/retro/r/latest.tar.gz<br/>
|
||||
• gopher://forthworks.com/9/retro/r/latest.tar.gz<br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Fossil Repository</span>
|
||||
<br/><br/>
|
||||
I use a Fossil repository to manage development. To obtain a
|
||||
copy of the repository install Fossil and:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>fossil clone http://forthworks.com:8000 retro.fossil</tt>
|
||||
<tt class='indentedcode'>mkdir retro</tt>
|
||||
<tt class='indentedcode'>cd retro</tt>
|
||||
<tt class='indentedcode'>fossil open /path/to/retro.fossil</tt>
|
||||
<br/><br/>
|
||||
See the Fossil documentation for details on using Fossil to
|
||||
keep your local copy of the repository current.
|
||||
<br/><br/>
|
||||
This will let you stay current with my latest changes faster
|
||||
than the snapshots, but you may occasionally encounter bigger
|
||||
problems as some commits may be in a partially broken state.
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
<span class="h2">git Repository</span>
|
||||
<br/><br/>
|
||||
There is now a read-only mirror of the fossil repository
|
||||
provided via git. This is hosted on sr.ht.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>git clone https://git.sr.ht/~crc_/retroforth</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Notes</span>
|
||||
<br/><br/>
|
||||
I personally recommend using either a recent snapshot or a
|
||||
build from one of the repositories. This will reflect the
|
||||
latest system as I use it, and are normally reliable as I
|
||||
run them daily for my production systems.
|
||||
</p>
|
||||
</body></html>
|
||||
110
doc/html/chapters/building/unix.html
Normal file
110
doc/html/chapters/building/unix.html
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Building on BSD, Linux, macOS, and other Unix Targets</span>
|
||||
<br/><br/>
|
||||
RETRO is well supported on BSD (tested on FreeBSD, NetBSD,
|
||||
OpenBSD), Linux, and macOS systems. It should build on any
|
||||
of these without issue.
|
||||
<br/><br/>
|
||||
<span class="h2">Requirements</span>
|
||||
<br/><br/>
|
||||
• c compiler & linker<br/>
|
||||
• standard headers<br/>
|
||||
• make<br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Process</span>
|
||||
<br/><br/>
|
||||
For a standard 32-bit system:
|
||||
<br/><br/>
|
||||
Run <span class="tt">make</span>
|
||||
<br/><br/>
|
||||
For a 64-bit system:
|
||||
<br/><br/>
|
||||
Run <span class="tt">make OPTIONS=-DBIT64</span>
|
||||
<br/><br/>
|
||||
This will build the toolchain and then the main <span class="tt">retro</span>
|
||||
executable.
|
||||
<br/><br/>
|
||||
<span class="h2">Executables</span>
|
||||
<br/><br/>
|
||||
In the <span class="tt">bin/</span> directory:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro</tt>
|
||||
<tt class='indentedcode'>retro-unu</tt>
|
||||
<tt class='indentedcode'>retro-muri</tt>
|
||||
<tt class='indentedcode'>retro-extend</tt>
|
||||
<tt class='indentedcode'>retro-embedimage</tt>
|
||||
<tt class='indentedcode'>retro-describe</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Platform Specific Notes</span>
|
||||
<br/><br/>
|
||||
In addition to the 64-bit build, it is possible to override the
|
||||
image size, address stack depth, and data stack depth by defining
|
||||
the appropriate elements.
|
||||
<br/><br/>
|
||||
E.g., for a 64-bit build with:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>4,000,000 cells of memory</tt>
|
||||
<tt class='indentedcode'>4,000 item limit on data stack</tt>
|
||||
<tt class='indentedcode'>500 item limit on address stack</tt>
|
||||
<br/><br/>
|
||||
Run <span class="tt">make OPTIONS="-DBIT64 -DIMAGE_SIZE=4000000 -DSTACK_DEPTH=4000 -DADDRESSES=500"</span>
|
||||
<br/><br/>
|
||||
<br/><br/>
|
||||
<span class="h3">Haiku</span>
|
||||
<br/><br/>
|
||||
To build on Haiku, you need to link with the <strong>network</strong> library.
|
||||
E.g.:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>make LDFLAGS=-lnetwork</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Issues</span>
|
||||
<br/><br/>
|
||||
If you run into any build issues, please send details to
|
||||
crc@forth.works so I can work on addressing them as quickly
|
||||
as possible.
|
||||
</p>
|
||||
</body></html>
|
||||
81
doc/html/chapters/building/windows.html
Normal file
81
doc/html/chapters/building/windows.html
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Building RETRO on Windows</span>
|
||||
<br/><br/>
|
||||
It is possible to build RETRO on Windows, though a few of the
|
||||
extensions are not supported:
|
||||
<br/><br/>
|
||||
• no <span class="tt">unix:</span> words<br/>
|
||||
• no <span class="tt">gopher:</span> words<br/>
|
||||
<br/><br/>
|
||||
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).
|
||||
<br/><br/>
|
||||
<span class="h2">Setup Build Environment</span>
|
||||
<br/><br/>
|
||||
RETRO on Windows is built with TCC.
|
||||
<br/><br/>
|
||||
Go to http://download.savannah.gnu.org/releases/tinycc/
|
||||
<br/><br/>
|
||||
Download the <strong>winapi-full</strong> and <strong>tcc-xxxx-bin</strong> packages for your
|
||||
system. Decompress them, copy the headers from the winapi
|
||||
package into the tcc directory.
|
||||
<br/><br/>
|
||||
<span class="h2">Prepare Source</span>
|
||||
<br/><br/>
|
||||
Copy the <span class="tt">source/interfaces/retro-windows.c</span> and the
|
||||
<span class="tt">source/interfaces/retro-windows.c</span> to the directory you setup
|
||||
tcc into.
|
||||
<br/><br/>
|
||||
<span class="h2">Build</span>
|
||||
<br/><br/>
|
||||
Building will require use of the command line. Assuming that
|
||||
tcc.exe is in the current directory along with the RETRO sources:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>tcc retro-windows.c -o retro.exe</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
65
doc/html/chapters/general/basic-interactions.html
Normal file
65
doc/html/chapters/general/basic-interactions.html
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Basic Interactions</span>
|
||||
<br/><br/>
|
||||
Start RETRO in interactive mode:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">retro -i </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
You should see something similar to this:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>RETRO 12 (2019.6)</tt>
|
||||
<tt class='indentedcode'>8388608 MAX, TIB @ 1025, Heap @ 9374</tt>
|
||||
<br/><br/>
|
||||
At this point you are at the <strong>listener</strong>, which reads and
|
||||
processes your input. You are now set to begin exploring
|
||||
RETRO.
|
||||
<br/><br/>
|
||||
To exit, run <span class="tt">bye</span>:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">bye </span><br/>
|
||||
<span class="tt">```</span></span></p>
|
||||
</body></html>
|
||||
522
doc/html/chapters/general/copyrights.html
Normal file
522
doc/html/chapters/general/copyrights.html
Normal file
|
|
@ -0,0 +1,522 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>The text in these files is Copyright (c) 2018-2020 by
|
||||
Charles Childers.
|
||||
<br/><br/>
|
||||
To the extent possible under law, Charles Childers has
|
||||
waived all copyright and related or neighboring rights
|
||||
to the RETRO Documentation. This work is published from:
|
||||
United States.
|
||||
<br/><br/>
|
||||
The historical papers are Copyright (c) 1999-2000 by
|
||||
Tom Novelli.
|
||||
<br/><br/>
|
||||
<span class="h2">Legal Text</span>
|
||||
<br/><br/>
|
||||
See https://creativecommons.org/publicdomain/zero/1.0/legalcode
|
||||
<br/><br/>
|
||||
The laws of most jurisdictions throughout the world automatically confer
|
||||
exclusive Copyright and Related Rights (defined below) upon the creator
|
||||
and subsequent owner(s) (each and all, an "owner") of an original work
|
||||
of authorship and/or a database (each, a "Work").
|
||||
<br/><br/>
|
||||
Certain owners wish to permanently relinquish those rights to a Work for
|
||||
the purpose of contributing to a commons of creative, cultural and
|
||||
scientific works ("Commons") that the public can reliably and without
|
||||
fear of later claims of infringement build upon, modify, incorporate in
|
||||
other works, reuse and redistribute as freely as possible in any form
|
||||
whatsoever and for any purposes, including without limitation commercial
|
||||
purposes. These owners may contribute to the Commons to promote the
|
||||
ideal of a free culture and the further production of creative, cultural
|
||||
and scientific works, or to gain reputation or greater distribution for
|
||||
their Work in part through the use and efforts of others.
|
||||
<br/><br/>
|
||||
For these and/or other purposes and motivations, and without any
|
||||
expectation of additional consideration or compensation, the person
|
||||
associating CC0 with a Work (the "Affirmer"), to the extent that he or
|
||||
she is an owner of Copyright and Related Rights in the Work, voluntarily
|
||||
elects to apply CC0 to the Work and publicly distribute the Work under
|
||||
its terms, with knowledge of his or her Copyright and Related Rights in
|
||||
the Work and the meaning and intended legal effect of CC0 on those
|
||||
rights.
|
||||
<br/><br/>
|
||||
1. Copyright and Related Rights. A Work made available under CC0 may be
|
||||
protected by copyright and related or neighboring rights ("Copyright and
|
||||
Related Rights"). Copyright and Related Rights include, but are not
|
||||
limited to, the following:
|
||||
<br/><br/>
|
||||
• the right to reproduce, adapt, distribute, perform, display, <br/>
|
||||
communicate, and translate a Work;
|
||||
<br/><br/>
|
||||
• moral rights retained by the original author(s) and/or performer(s);<br/>
|
||||
<br/><br/>
|
||||
• publicity and privacy rights pertaining to a person's image or <br/>
|
||||
likeness depicted in a Work;
|
||||
<br/><br/>
|
||||
• rights protecting against unfair competition in regards to a Work, <br/>
|
||||
subject to the limitations in paragraph 4(a), below;
|
||||
<br/><br/>
|
||||
• rights protecting the extraction, dissemination, use and reuse of data <br/>
|
||||
in a Work;
|
||||
<br/><br/>
|
||||
• database rights (such as those arising under Directive 96/9/EC of the <br/>
|
||||
European Parliament and of the Council of 11 March 1996 on the legal
|
||||
protection of databases, and under any national implementation thereof,
|
||||
including any amended or successor version of such directive); and
|
||||
<br/><br/>
|
||||
• other similar, equivalent or corresponding rights throughout the world<br/>
|
||||
based on applicable law or treaty, and any national implementations
|
||||
thereof.
|
||||
<br/><br/>
|
||||
2. Waiver. To the greatest extent permitted by, but not in contravention
|
||||
of, applicable law, Affirmer hereby overtly, fully, permanently,
|
||||
irrevocably and unconditionally waives, abandons, and surrenders all of
|
||||
Affirmer's Copyright and Related Rights and associated claims and causes
|
||||
of action, whether now known or unknown (including existing as well as
|
||||
future claims and causes of action), in the Work (i) in all territories
|
||||
worldwide, (ii) for the maximum duration provided by applicable law or
|
||||
treaty (including future time extensions), (iii) in any current or
|
||||
future medium and for any number of copies, and (iv) for any purpose
|
||||
whatsoever, including without limitation commercial, advertising or
|
||||
promotional purposes (the "Waiver"). Affirmer makes the Waiver for the
|
||||
benefit of each member of the public at large and to the detriment of
|
||||
Affirmer's heirs and successors, fully intending that such Waiver shall
|
||||
not be subject to revocation, rescission, cancellation, termination, or
|
||||
any other legal or equitable action to disrupt the quiet enjoyment of
|
||||
the Work by the public as contemplated by Affirmer's express Statement
|
||||
of Purpose.
|
||||
<br/><br/>
|
||||
3. Public License Fallback. Should any part of the Waiver for any reason
|
||||
be judged legally invalid or ineffective under applicable law, then the
|
||||
Waiver shall be preserved to the maximum extent permitted taking into
|
||||
account Affirmer's express Statement of Purpose. In addition, to the
|
||||
extent the Waiver is so judged Affirmer hereby grants to each affected
|
||||
person a royalty-free, non transferable, non sublicensable, non
|
||||
exclusive, irrevocable and unconditional license to exercise Affirmer's
|
||||
Copyright and Related Rights in the Work (i) in all territories
|
||||
worldwide, (ii) for the maximum duration provided by applicable law or
|
||||
treaty (including future time extensions), (iii) in any current or
|
||||
future medium and for any number of copies, and (iv) for any purpose
|
||||
whatsoever, including without limitation commercial, advertising or
|
||||
promotional purposes (the "License"). The License shall be deemed
|
||||
effective as of the date CC0 was applied by Affirmer to the Work. Should
|
||||
any part of the License for any reason be judged legally invalid or
|
||||
ineffective under applicable law, such partial invalidity or
|
||||
ineffectiveness shall not invalidate the remainder of the License, and
|
||||
in such case Affirmer hereby affirms that he or she will not (i)
|
||||
exercise any of his or her remaining Copyright and Related Rights in the
|
||||
Work or (ii) assert any associated claims and causes of action with
|
||||
respect to the Work, in either case contrary to Affirmer's express
|
||||
Statement of Purpose.
|
||||
<br/><br/>
|
||||
4. Limitations and Disclaimers.
|
||||
<br/><br/>
|
||||
No trademark or patent rights held by Affirmer are waived, abandoned,
|
||||
surrendered, licensed or otherwise affected by this document.
|
||||
<br/><br/>
|
||||
Affirmer offers the Work as-is and makes no representations or
|
||||
warranties of any kind concerning the Work, express, implied, statutory
|
||||
or otherwise, including without limitation warranties of title,
|
||||
merchantability, fitness for a particular purpose, non infringement, or
|
||||
the absence of latent or other defects, accuracy, or the present or
|
||||
absence of errors, whether or not discoverable, all to the greatest
|
||||
extent permissible under applicable law.
|
||||
<br/><br/>
|
||||
Affirmer disclaims responsibility for clearing rights of other persons
|
||||
that may apply to the Work or any use thereof, including without
|
||||
limitation any person's Copyright and Related Rights in the Work.
|
||||
Further, Affirmer disclaims responsibility for obtaining any necessary
|
||||
consents, permissions or other rights required for any use of the Work.
|
||||
<br/><br/>
|
||||
Affirmer understands and acknowledges that Creative Commons is not a
|
||||
party to this document and has no duty or obligation with respect to
|
||||
this CC0 or use of the Work.
|
||||
<br/><br/>
|
||||
<span class="hr"></span>
|
||||
<br/><br/>
|
||||
The Code It Yourself Manifesto is Copyright (c) 2016 by
|
||||
Christian Kellermann and is used under the
|
||||
Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) license.
|
||||
<br/><br/>
|
||||
This license reads:
|
||||
<br/><br/>
|
||||
THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE
|
||||
COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY
|
||||
COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS
|
||||
AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
|
||||
<br/><br/>
|
||||
BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE
|
||||
TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY
|
||||
BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS
|
||||
CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND
|
||||
CONDITIONS.
|
||||
<br/><br/>
|
||||
1. Definitions
|
||||
<br/><br/>
|
||||
"Adaptation" means a work based upon the Work, or upon the Work and
|
||||
other pre-existing works, such as a translation, adaptation, derivative
|
||||
work, arrangement of music or other alterations of a literary or
|
||||
artistic work, or phonogram or performance and includes cinematographic
|
||||
adaptations or any other form in which the Work may be recast,
|
||||
transformed, or adapted including in any form recognizably derived from
|
||||
the original, except that a work that constitutes a Collection will not
|
||||
be considered an Adaptation for the purpose of this License. For the
|
||||
avoidance of doubt, where the Work is a musical work, performance or
|
||||
phonogram, the synchronization of the Work in timed-relation with a
|
||||
moving image ("synching") will be considered an Adaptation for the
|
||||
purpose of this License.
|
||||
<br/><br/>
|
||||
"Collection" means a collection of literary or artistic works, such as
|
||||
encyclopedias and anthologies, or performances, phonograms or
|
||||
broadcasts, or other works or subject matter other than works listed in
|
||||
Section 1(f) below, which, by reason of the selection and arrangement of
|
||||
their contents, constitute intellectual creations, in which the Work is
|
||||
included in its entirety in unmodified form along with one or more other
|
||||
contributions, each constituting separate and independent works in
|
||||
themselves, which together are assembled into a collective whole. A work
|
||||
that constitutes a Collection will not be considered an Adaptation (as
|
||||
defined below) for the purposes of this License.
|
||||
<br/><br/>
|
||||
"Creative Commons Compatible License" means a license that is listed at
|
||||
https://creativecommons.org/compatiblelicenses that has been approved by
|
||||
Creative Commons as being essentially equivalent to this License,
|
||||
including, at a minimum, because that license: (i) contains terms that
|
||||
have the same purpose, meaning and effect as the License Elements of
|
||||
this License; and, (ii) explicitly permits the relicensing of
|
||||
adaptations of works made available under that license under this
|
||||
License or a Creative Commons jurisdiction license with the same License
|
||||
Elements as this License.
|
||||
<br/><br/>
|
||||
"Distribute" means to make available to the public the original and
|
||||
copies of the Work or Adaptation, as appropriate, through sale or other
|
||||
transfer of ownership.
|
||||
<br/><br/>
|
||||
"License Elements" means the following high-level license attributes as
|
||||
selected by Licensor and indicated in the title of this License:
|
||||
Attribution, ShareAlike.
|
||||
<br/><br/>
|
||||
"Licensor" means the individual, individuals, entity or entities that
|
||||
offer(s) the Work under the terms of this License.
|
||||
<br/><br/>
|
||||
"Original Author" means, in the case of a literary or artistic work, the
|
||||
individual, individuals, entity or entities who created the Work or if
|
||||
no individual or entity can be identified, the publisher; and in
|
||||
addition (i) in the case of a performance the actors, singers,
|
||||
musicians, dancers, and other persons who act, sing, deliver, declaim,
|
||||
play in, interpret or otherwise perform literary or artistic works or
|
||||
expressions of folklore; (ii) in the case of a phonogram the producer
|
||||
being the person or legal entity who first fixes the sounds of a
|
||||
performance or other sounds; and, (iii) in the case of broadcasts, the
|
||||
organization that transmits the broadcast.
|
||||
<br/><br/>
|
||||
"Work" means the literary and/or artistic work offered under the terms
|
||||
of this License including without limitation any production in the
|
||||
literary, scientific and artistic domain, whatever may be the mode or
|
||||
form of its expression including digital form, such as a book, pamphlet
|
||||
and other writing; a lecture, address, sermon or other work of the same
|
||||
nature; a dramatic or dramatico-musical work; a choreographic work or
|
||||
entertainment in dumb show; a musical composition with or without words;
|
||||
a cinematographic work to which are assimilated works expressed by a
|
||||
process analogous to cinematography; a work of drawing, painting,
|
||||
architecture, sculpture, engraving or lithography; a photographic work
|
||||
to which are assimilated works expressed by a process analogous to
|
||||
photography; a work of applied art; an illustration, map, plan, sketch
|
||||
or three-dimensional work relative to geography, topography,
|
||||
architecture or science; a performance; a broadcast; a phonogram; a
|
||||
compilation of data to the extent it is protected as a copyrightable
|
||||
work; or a work performed by a variety or circus performer to the extent
|
||||
it is not otherwise considered a literary or artistic work.
|
||||
<br/><br/>
|
||||
"You" means an individual or entity exercising rights under this License
|
||||
who has not previously violated the terms of this License with respect
|
||||
to the Work, or who has received express permission from the Licensor to
|
||||
exercise rights under this License despite a previous violation.
|
||||
<br/><br/>
|
||||
"Publicly Perform" means to perform public recitations of the Work and
|
||||
to communicate to the public those public recitations, by any means or
|
||||
process, including by wire or wireless means or public digital
|
||||
performances; to make available to the public Works in such a way that
|
||||
members of the public may access these Works from a place and at a place
|
||||
individually chosen by them; to perform the Work to the public by any
|
||||
means or process and the communication to the public of the performances
|
||||
of the Work, including by public digital performance; to broadcast and
|
||||
rebroadcast the Work by any means including signs, sounds or images.
|
||||
<br/><br/>
|
||||
"Reproduce" means to make copies of the Work by any means including
|
||||
without limitation by sound or visual recordings and the right of
|
||||
fixation and reproducing fixations of the Work, including storage of a
|
||||
protected performance or phonogram in digital form or other electronic
|
||||
medium.
|
||||
<br/><br/>
|
||||
2. Fair Dealing Rights. Nothing in this License is intended to reduce,
|
||||
limit, or restrict any uses free from copyright or rights arising from
|
||||
limitations or exceptions that are provided for in connection with the
|
||||
copyright protection under copyright law or other applicable laws.
|
||||
<br/><br/>
|
||||
3. License Grant. Subject to the terms and conditions of this License,
|
||||
Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
|
||||
perpetual (for the duration of the applicable copyright) license to
|
||||
exercise the rights in the Work as stated below:
|
||||
<br/><br/>
|
||||
• to Reproduce the Work, to incorporate the Work into one or more <br/>
|
||||
Collections, and to Reproduce the Work as incorporated in the
|
||||
Collections;
|
||||
<br/><br/>
|
||||
• to create and Reproduce Adaptations provided that any such Adaptation, <br/>
|
||||
including any translation in any medium, takes reasonable steps to
|
||||
clearly label, demarcate or otherwise identify that changes were made to
|
||||
the original Work. For example, a translation could be marked "The
|
||||
original work was translated from English to Spanish," or a modification
|
||||
could indicate "The original work has been modified.";
|
||||
<br/><br/>
|
||||
• to Distribute and Publicly Perform the Work including as incorporated in <br/>
|
||||
Collections; and,
|
||||
<br/><br/>
|
||||
• to Distribute and Publicly Perform Adaptations.<br/>
|
||||
<br/><br/>
|
||||
For the avoidance of doubt:
|
||||
<br/><br/>
|
||||
Non-waivable Compulsory License Schemes. In those jurisdictions in which
|
||||
the right to collect royalties through any statutory or compulsory
|
||||
licensing scheme cannot be waived, the Licensor reserves the exclusive
|
||||
right to collect such royalties for any exercise by You of the rights
|
||||
granted under this License;
|
||||
<br/><br/>
|
||||
Waivable Compulsory License Schemes. In those jurisdictions in which the
|
||||
right to collect royalties through any statutory or compulsory licensing
|
||||
scheme can be waived, the Licensor waives the exclusive right to collect
|
||||
such royalties for any exercise by You of the rights granted under this
|
||||
License; and,
|
||||
<br/><br/>
|
||||
Voluntary License Schemes. The Licensor waives the right to collect
|
||||
royalties, whether individually or, in the event that the Licensor is a
|
||||
member of a collecting society that administers voluntary licensing
|
||||
schemes, via that society, from any exercise by You of the rights
|
||||
granted under this License.
|
||||
<br/><br/>
|
||||
The above rights may be exercised in all media and formats whether now
|
||||
known or hereafter devised. The above rights include the right to make
|
||||
such modifications as are technically necessary to exercise the rights
|
||||
in other media and formats. Subject to Section 8(f), all rights not
|
||||
expressly granted by Licensor are hereby reserved.
|
||||
<br/><br/>
|
||||
4. Restrictions. The license granted in Section 3 above is expressly
|
||||
made subject to and limited by the following restrictions:
|
||||
<br/><br/>
|
||||
You may Distribute or Publicly Perform the Work only under the terms of
|
||||
this License. You must include a copy of, or the Uniform Resource
|
||||
Identifier (URI) for, this License with every copy of the Work You
|
||||
Distribute or Publicly Perform. You may not offer or impose any terms on
|
||||
the Work that restrict the terms of this License or the ability of the
|
||||
recipient of the Work to exercise the rights granted to that recipient
|
||||
under the terms of the License. You may not sublicense the Work. You
|
||||
must keep intact all notices that refer to this License and to the
|
||||
disclaimer of warranties with every copy of the Work You Distribute or
|
||||
Publicly Perform. When You Distribute or Publicly Perform the Work, You
|
||||
may not impose any effective technological measures on the Work that
|
||||
restrict the ability of a recipient of the Work from You to exercise the
|
||||
rights granted to that recipient under the terms of the License. This
|
||||
Section 4(a) applies to the Work as incorporated in a Collection, but
|
||||
this does not require the Collection apart from the Work itself to be
|
||||
made subject to the terms of this License. If You create a Collection,
|
||||
upon notice from any Licensor You must, to the extent practicable,
|
||||
remove from the Collection any credit as required by Section 4(c), as
|
||||
requested. If You create an Adaptation, upon notice from any Licensor
|
||||
You must, to the extent practicable, remove from the Adaptation any
|
||||
credit as required by Section 4(c), as requested.
|
||||
<br/><br/>
|
||||
You may Distribute or Publicly Perform an Adaptation only under the
|
||||
terms of: (i) this License; (ii) a later version of this License with
|
||||
the same License Elements as this License; (iii) a Creative Commons
|
||||
jurisdiction license (either this or a later license version) that
|
||||
contains the same License Elements as this License (e.g.,
|
||||
Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible
|
||||
License. If you license the Adaptation under one of the licenses
|
||||
mentioned in (iv), you must comply with the terms of that license. If
|
||||
you license the Adaptation under the terms of any of the licenses
|
||||
mentioned in (i), (ii) or (iii) (the "Applicable License"), you must
|
||||
comply with the terms of the Applicable License generally and the
|
||||
following provisions: (I) You must include a copy of, or the URI for,
|
||||
the Applicable License with every copy of each Adaptation You Distribute
|
||||
or Publicly Perform; (II) You may not offer or impose any terms on the
|
||||
Adaptation that restrict the terms of the Applicable License or the
|
||||
ability of the recipient of the Adaptation to exercise the rights
|
||||
granted to that recipient under the terms of the Applicable License;
|
||||
(III) You must keep intact all notices that refer to the Applicable
|
||||
License and to the disclaimer of warranties with every copy of the Work
|
||||
as included in the Adaptation You Distribute or Publicly Perform; (IV)
|
||||
when You Distribute or Publicly Perform the Adaptation, You may not
|
||||
impose any effective technological measures on the Adaptation that
|
||||
restrict the ability of a recipient of the Adaptation from You to
|
||||
exercise the rights granted to that recipient under the terms of the
|
||||
Applicable License. This Section 4(b) applies to the Adaptation as
|
||||
incorporated in a Collection, but this does not require the Collection
|
||||
apart from the Adaptation itself to be made subject to the terms of the
|
||||
Applicable License.
|
||||
<br/><br/>
|
||||
If You Distribute, or Publicly Perform the Work or any Adaptations or
|
||||
Collections, You must, unless a request has been made pursuant to
|
||||
Section 4(a), keep intact all copyright notices for the Work and
|
||||
provide, reasonable to the medium or means You are utilizing: (i) the
|
||||
name of the Original Author (or pseudonym, if applicable) if supplied,
|
||||
and/or if the Original Author and/or Licensor designate another party or
|
||||
parties (e.g., a sponsor institute, publishing entity, journal) for
|
||||
attribution ("Attribution Parties") in Licensor's copyright notice,
|
||||
terms of service or by other reasonable means, the name of such party or
|
||||
parties; (ii) the title of the Work if supplied; (iii) to the extent
|
||||
reasonably practicable, the URI, if any, that Licensor specifies to be
|
||||
associated with the Work, unless such URI does not refer to the
|
||||
copyright notice or licensing information for the Work; and (iv) ,
|
||||
consistent with Ssection 3(b), in the case of an Adaptation, a credit
|
||||
identifying the use of the Work in the Adaptation (e.g., "French
|
||||
translation of the Work by Original Author," or "Screenplay based on
|
||||
original Work by Original Author"). The credit required by this Section
|
||||
4(c) may be implemented in any reasonable manner; provided, however,
|
||||
that in the case of a Adaptation or Collection, at a minimum such credit
|
||||
will appear, if a credit for all contributing authors of the Adaptation
|
||||
or Collection appears, then as part of these credits and in a manner at
|
||||
least as prominent as the credits for the other contributing authors.
|
||||
For the avoidance of doubt, You may only use the credit required by this
|
||||
Section for the purpose of attribution in the manner set out above and,
|
||||
by exercising Your rights under this License, You may not implicitly or
|
||||
explicitly assert or imply any connection with, sponsorship or
|
||||
endorsement by the Original Author, Licensor and/or Attribution Parties,
|
||||
as appropriate, of You or Your use of the Work, without the separate,
|
||||
express prior written permission of the Original Author, Licensor and/or
|
||||
Attribution Parties.
|
||||
<br/><br/>
|
||||
Except as otherwise agreed in writing by the Licensor or as may be
|
||||
otherwise permitted by applicable law, if You Reproduce, Distribute or
|
||||
Publicly Perform the Work either by itself or as part of any Adaptations
|
||||
or Collections, You must not distort, mutilate, modify or take other
|
||||
derogatory action in relation to the Work which would be prejudicial to
|
||||
the Original Author's honor or reputation. Licensor agrees that in those
|
||||
jurisdictions (e.g. Japan), in which any exercise of the right granted
|
||||
in Section 3(b) of this License (the right to make Adaptations) would be
|
||||
deemed to be a distortion, mutilation, modification or other derogatory
|
||||
action prejudicial to the Original Author's honor and reputation, the
|
||||
Licensor will waive or not assert, as appropriate, this Section, to the
|
||||
fullest extent permitted by the applicable national law, to enable You
|
||||
to reasonably exercise Your right under Section 3(b) of this License
|
||||
(right to make Adaptations) but not otherwise.
|
||||
<br/><br/>
|
||||
5. Representations, Warranties and Disclaimer
|
||||
<br/><br/>
|
||||
UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR
|
||||
OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY
|
||||
KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE,
|
||||
INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF
|
||||
LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS,
|
||||
WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE
|
||||
EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.
|
||||
<br/><br/>
|
||||
6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE
|
||||
LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR
|
||||
ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES
|
||||
ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS
|
||||
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
|
||||
<br/><br/>
|
||||
7. Termination
|
||||
<br/><br/>
|
||||
This License and the rights granted hereunder will terminate
|
||||
automatically upon any breach by You of the terms of this License.
|
||||
Individuals or entities who have received Adaptations or Collections
|
||||
from You under this License, however, will not have their licenses
|
||||
terminated provided such individuals or entities remain in full
|
||||
compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will
|
||||
survive any termination of this License. Subject to the above terms and
|
||||
conditions, the license granted here is perpetual (for the duration of
|
||||
the applicable copyright in the Work). Notwithstanding the above,
|
||||
Licensor reserves the right to release the Work under different license
|
||||
terms or to stop distributing the Work at any time; provided, however
|
||||
that any such election will not serve to withdraw this License (or any
|
||||
other license that has been, or is required to be, granted under the
|
||||
terms of this License), and this License will continue in full force and
|
||||
effect unless terminated as stated above. 8. Miscellaneous
|
||||
<br/><br/>
|
||||
Each time You Distribute or Publicly Perform the Work or a Collection,
|
||||
the Licensor offers to the recipient a license to the Work on the same
|
||||
terms and conditions as the license granted to You under this License.
|
||||
<br/><br/>
|
||||
Each time You Distribute or Publicly Perform an Adaptation, Licensor
|
||||
offers to the recipient a license to the original Work on the same terms
|
||||
and conditions as the license granted to You under this License.
|
||||
<br/><br/>
|
||||
If any provision of this License is invalid or unenforceable under
|
||||
applicable law, it shall not affect the validity or enforceability of
|
||||
the remainder of the terms of this License, and without further action
|
||||
by the parties to this agreement, such provision shall be reformed to
|
||||
the minimum extent necessary to make such provision valid and
|
||||
enforceable.
|
||||
<br/><br/>
|
||||
No term or provision of this License shall be deemed waived and no
|
||||
breach consented to unless such waiver or consent shall be in writing
|
||||
and signed by the party to be charged with such waiver or consent.
|
||||
<br/><br/>
|
||||
This License constitutes the entire agreement between the parties with
|
||||
respect to the Work licensed here. There are no understandings,
|
||||
agreements or representations with respect to the Work not specified
|
||||
here. Licensor shall not be bound by any additional provisions that may
|
||||
appear in any communication from You. This License may not be modified
|
||||
without the mutual written agreement of the Licensor and You.
|
||||
<br/><br/>
|
||||
The rights granted under, and the subject matter referenced, in this
|
||||
License were drafted utilizing the terminology of the Berne Convention
|
||||
for the Protection of Literary and Artistic Works (as amended on
|
||||
September 28, 1979), the Rome Convention of 1961, the WIPO Copyright
|
||||
Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 and
|
||||
the Universal Copyright Convention (as revised on July 24, 1971). These
|
||||
rights and subject matter take effect in the relevant jurisdiction in
|
||||
which the License terms are sought to be enforced according to the
|
||||
corresponding provisions of the implementation of those treaty
|
||||
provisions in the applicable national law. If the standard suite of
|
||||
rights granted under applicable copyright law includes additional rights
|
||||
not granted under this License, such additional rights are deemed to be
|
||||
included in the License; this License is not intended to restrict the
|
||||
license of any rights under applicable law.
|
||||
</p>
|
||||
</body></html>
|
||||
57
doc/html/chapters/general/deprecation.html
Normal file
57
doc/html/chapters/general/deprecation.html
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Deprecation Policy</span>
|
||||
<br/><br/>
|
||||
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 release.
|
||||
<br/><br/>
|
||||
E.g., if 2020.1 had deprecated words, these would be removed in
|
||||
the 2020.4 release. Any words made deprecated in between 2020.1
|
||||
and 2020.4 would be removed in the 2020.7 release.
|
||||
</p>
|
||||
</body></html>
|
||||
66
doc/html/chapters/general/introduction.html
Normal file
66
doc/html/chapters/general/introduction.html
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">RETRO: a Modern, Pragmatic Forth</span>
|
||||
<br/><br/>
|
||||
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)
|
||||
embedded systems.
|
||||
<br/><br/>
|
||||
The language is Forth. It is untyped, uses a stack to pass data
|
||||
between functions called words, and a dictionary which tracks
|
||||
the word names and data structures.
|
||||
<br/><br/>
|
||||
But it's not a traditional Forth. RETRO draws influences from
|
||||
many sources and takes a unique approach to the language.
|
||||
<br/><br/>
|
||||
RETRO has a large vocabulary of words. Keeping a copy of the
|
||||
Glossary on hand is highly recommended as you learn to use RETRO.
|
||||
<br/><br/>
|
||||
This book will hopefully help you develop a better understanding
|
||||
of RETRO and how it works.
|
||||
</p>
|
||||
</body></html>
|
||||
158
doc/html/chapters/general/markdown.html
Normal file
158
doc/html/chapters/general/markdown.html
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">RETRO's Markdown Syntax</span>
|
||||
<br/><br/>
|
||||
I use a variation of Markdown for writing documentation and
|
||||
when commenting code written in RETRO. The syntax is
|
||||
described below.
|
||||
<br/><br/>
|
||||
<span class="h2">Basic Syntax</span>
|
||||
<br/><br/>
|
||||
<span class="h3">Headings</span>
|
||||
<br/><br/>
|
||||
Headings start with one or more number (<span class="tt">#</span>) signs. The
|
||||
number of number signs should correspond to the heading
|
||||
level.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'># Heading 1</tt>
|
||||
<tt class='indentedcode'>## Heading 2</tt>
|
||||
<tt class='indentedcode'>### Heading 3</tt>
|
||||
<tt class='indentedcode'>#### Heading 4</tt>
|
||||
<br/><br/>
|
||||
My Markdown does not support the alternate underline
|
||||
format for headings.
|
||||
<br/><br/>
|
||||
<span class="h3">Paragraphs & Line Breaks</span>
|
||||
<br/><br/>
|
||||
To create paragraphs, use a blank line to separate one or
|
||||
more lines of text.
|
||||
<br/><br/>
|
||||
Do not add spaces or tabs at the start of a paragraph as
|
||||
this may cause the Markdown tools to interpret the line
|
||||
improperly.
|
||||
<br/><br/>
|
||||
Line breaks are entered at the end of each line.
|
||||
<br/><br/>
|
||||
<span class="h3">Emphasis</span>
|
||||
<br/><br/>
|
||||
<span class="h4">Bold</span>
|
||||
<br/><br/>
|
||||
To make text bold, surround it with asterisks.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>The *bold* word.</tt>
|
||||
<br/><br/>
|
||||
<span class="h4">Italic</span>
|
||||
<br/><br/>
|
||||
To make text italic, surround it with front slashes.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>The /italic words/.</tt>
|
||||
<br/><br/>
|
||||
<span class="h4">Underline</span>
|
||||
<br/><br/>
|
||||
To underline text, surround it with underscores.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Underline _some text_.</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Horizontal Rules</span>
|
||||
<br/><br/>
|
||||
Horizontal rules can be inserted by starting a line with a
|
||||
sequence of four or more dashes (<span class="tt">-</span>) or four or more alternating
|
||||
dash and plus (<span class="tt">-+-+</span>) characters.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>----</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Lists</span>
|
||||
<br/><br/>
|
||||
Lists start with a <span class="tt">-</span> or <span class="tt">*</span>, followed by a space, then the item
|
||||
text. Additionally, nested lists starting with two spaces before
|
||||
the list marker can be used.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>- this is a list item</tt>
|
||||
<tt class='indentedcode'>- so is this</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> - this will be indented</tt>
|
||||
<tt class='indentedcode'> - likewise</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>- back to the standard level</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Code</span>
|
||||
<br/><br/>
|
||||
<span class="h3">Code Blocks</span>
|
||||
<br/><br/>
|
||||
Code blocks start and end with ~~~ on a line by themselves.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Sum the values.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>{ #10 #20 #13 #4 #22 } #0 [ + ] a:reduce</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
You can also denote code by starting the line with four spaces.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> This line will be treated as code.</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Test Blocks</span>
|
||||
<br/><br/>
|
||||
Unit testing blocks start and end with <span class="tt"></span><span class="tt"> on a line by
|
||||
themselves.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>```</tt>
|
||||
<tt class='indentedcode'>{ #10 #20 #13 #4 #22 } #0 [ + ] a:reduce</tt>
|
||||
<tt class='indentedcode'>```</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Inline Code</span>
|
||||
<br/><br/>
|
||||
To mark a sequence as inline code, surround it with backticks.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>For instance, look at the value in `Compiler` to see if</tt>
|
||||
<tt class='indentedcode'>the colon compiler is active.</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Escaping</span>
|
||||
<br/><br/>
|
||||
You can preceed a character with a backslash () to have it
|
||||
not be processed as a Markdown element.
|
||||
</p>
|
||||
</body></html>
|
||||
83
doc/html/chapters/general/quick-tutorial.html
Normal file
83
doc/html/chapters/general/quick-tutorial.html
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">A Quick Tutorial</span>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
Let's look at this by solving a small problem: writing a
|
||||
word to determine if a string is a palindrome.
|
||||
<br/><br/>
|
||||
A palindrome is a phrase which reads the same backward
|
||||
and forward.
|
||||
<br/><br/>
|
||||
We first need a string to look at. Starting with something
|
||||
easy:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'anna</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Looking in the Glossary, there is a <span class="tt">s:reverse</span> word for
|
||||
reversing a string. We can find <span class="tt">dup</span> to copy a value, and
|
||||
<span class="tt">s:eq?</span> to compare two strings. So testing:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'anna</span> <span class='prim'>dup</span> s:reverse s:eq? </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
This yields -1 (<span class="tt">TRUE</span>) as expected. So we can easily
|
||||
name it:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:palindrome?</span> <span class='prim'>dup</span> s:reverse s:eq? <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Naming uses the <span class="tt">:</span> prefix to add a new word to the dictionary.
|
||||
The words that make up the definition are then placed, with a
|
||||
final word (<span class="tt">;</span>) ending the definition. We can then use this:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'anna</span> palindrome? </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Once defined there is no difference between our new word and
|
||||
any of the words already provided by the RETRO system.
|
||||
</p>
|
||||
</body></html>
|
||||
97
doc/html/chapters/general/retro-unu.html
Normal file
97
doc/html/chapters/general/retro-unu.html
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Unu: Simple, Literate Source Files</span>
|
||||
<br/><br/>
|
||||
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
|
||||
the code.
|
||||
<br/><br/>
|
||||
As an example,
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'># Determine The Average Word Name Length</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>To determine the average length of a word name two values</tt>
|
||||
<tt class='indentedcode'>are needed. First, the total length of all names in the</tt>
|
||||
<tt class='indentedcode'>Dictionary:</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>#0 [ d:name s:length + ] d:for-each</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>And then the number of words in the Dictionary:</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>#0 [ drop n:inc ] d:for-each</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>With these, a simple division is all that's left.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>/</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Finally, display the results:</tt>
|
||||
<br/><br/>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>'Average_name_length:_%n\n s:format s:put</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
This illustrates the format. Only code in the fenced blocks
|
||||
(between ~~~ pairs) get extracted and run.
|
||||
<br/><br/>
|
||||
(Note: this only applies to source files; fences are not used
|
||||
when entering code interactively).
|
||||
<br/><br/>
|
||||
<span class="h2">On The Name</span>
|
||||
<br/><br/>
|
||||
The name Unu comes from the Maori language, where it means:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>(verb) (-hia) pull out, withdraw, draw out, extract.</tt>
|
||||
<tt class='indentedcode'>Taken from https://maoridictionary.co.nz/</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
120
doc/html/chapters/general/starting.html
Normal file
120
doc/html/chapters/general/starting.html
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Starting RETRO</span>
|
||||
<br/><br/>
|
||||
RETRO can be run for scripting or interactive use.
|
||||
<br/><br/>
|
||||
<span class="h2">Interactive</span>
|
||||
<br/><br/>
|
||||
To start it interactively, run: <span class="tt">retro</span> without any command line
|
||||
arguments, or with <span class="tt">-i</span>, <span class="tt">-s</span>, or <span class="tt">-i,c</span>.
|
||||
<br/><br/>
|
||||
Starting the interactive system:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">retro </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Or:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">retro -i </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
This should be sufficient for most uses.
|
||||
<br/><br/>
|
||||
Starting the interactive system (without displaying the
|
||||
startup banner):
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">retro -s </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Using In a Pipe</span>
|
||||
<br/><br/>
|
||||
If using a Unix shell and piping input between processes, you
|
||||
will probably want to use <span class="tt">-s</span> to suppress the startup messages
|
||||
and <span class="tt">Ok</span> prompt that normally appear.
|
||||
<br/><br/>
|
||||
E.g.,
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">echo "'lol s:put nl" <span class='defer'>|</span> retro -s </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Running A Program In A File</span>
|
||||
<br/><br/>
|
||||
You can run code in a file very easily. This is simply:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">retro filename </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
You can follow the filename with any arguments that it may need.
|
||||
These will be accessible to the program via the <span class="tt">script:arguments</span>
|
||||
and <span class="tt">script:get-argument</span> words.
|
||||
<br/><br/>
|
||||
Source files must be written in Unu format.
|
||||
<br/><br/>
|
||||
<span class="h2">Scripting</span>
|
||||
<br/><br/>
|
||||
You can use RETRO to write scripts. Add a shebang:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#!/usr/bin/env</span> retro </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
And make the file executable.
|
||||
<br/><br/>
|
||||
Source files must be written in Unu format.
|
||||
<br/><br/>
|
||||
<span class="h2">Command Line Arguments</span>
|
||||
<br/><br/>
|
||||
For a summary of the full command line arguments available:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Scripting Usage:</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro filename [script arguments...]</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Interactive Usage:</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro [-h] [-i] [-c] [-s] [-f filename] [-t]</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> -h Display this help text</tt>
|
||||
<tt class='indentedcode'> -i Interactive mode (line buffered)</tt>
|
||||
<tt class='indentedcode'> -s Suppress the startup text</tt>
|
||||
<tt class='indentedcode'> -f filename Run the contents of the specified file</tt>
|
||||
<tt class='indentedcode'> -t Run tests (in ``` blocks) in any loaded files</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
133
doc/html/chapters/general/syntax.html
Normal file
133
doc/html/chapters/general/syntax.html
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Syntax</span>
|
||||
<br/><br/>
|
||||
RETRO has more syntax than a traditional Forth due to ideas
|
||||
borrowed from ColorForth and some design decisions. This has
|
||||
some useful traits, and helps to make the language more
|
||||
consistent.
|
||||
<br/><br/>
|
||||
<span class="h2">Tokens</span>
|
||||
<br/><br/>
|
||||
Input is divided into a series of whitespace delimited tokens.
|
||||
Each of these is then processed individually. There are no
|
||||
parsing words in RETRO.
|
||||
<br/><br/>
|
||||
Tokens may have a single character <strong>prefix</strong>, which RETRO will
|
||||
use to decide how to process the token.
|
||||
<br/><br/>
|
||||
<span class="h2">Prefixes</span>
|
||||
<br/><br/>
|
||||
Prefixes are single characters added to the start of a token
|
||||
to guide the compiler. The use of these is a major way in
|
||||
which RETRO differs from traditional Forth.
|
||||
<br/><br/>
|
||||
When a token is passed to <span class="tt">interpret</span>, RETRO first takes the
|
||||
initial character and looks to see if there is a word that
|
||||
matches this. If so, it will pass the rest of the token to
|
||||
that word to handle.
|
||||
<br/><br/>
|
||||
In a traditional Forth, the interpret process is something
|
||||
like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>get token</tt>
|
||||
<tt class='indentedcode'>is token in the dictionary?</tt>
|
||||
<tt class='indentedcode'> yes:</tt>
|
||||
<tt class='indentedcode'> is it immediate?</tt>
|
||||
<tt class='indentedcode'> yes: call the word.</tt>
|
||||
<tt class='indentedcode'> no: are we interpreting?</tt>
|
||||
<tt class='indentedcode'> yes: call the word</tt>
|
||||
<tt class='indentedcode'> no: compile a call to the word</tt>
|
||||
<tt class='indentedcode'> no:</tt>
|
||||
<tt class='indentedcode'> is it a number?</tt>
|
||||
<tt class='indentedcode'> yes: are we interpreting?</tt>
|
||||
<tt class='indentedcode'> yes: push the number to the stack</tt>
|
||||
<tt class='indentedcode'> no: compile the number as a literal</tt>
|
||||
<tt class='indentedcode'> no: report an error ("not found")</tt>
|
||||
<br/><br/>
|
||||
In RETRO, the interpret process is basically:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>get token</tt>
|
||||
<tt class='indentedcode'>does the first character match a `prefix:` word?</tt>
|
||||
<tt class='indentedcode'> yes: pass the token to the prefix handler</tt>
|
||||
<tt class='indentedcode'> no: is token a word in the dictionary?</tt>
|
||||
<tt class='indentedcode'> yes: push the XT to the stack and call the</tt>
|
||||
<tt class='indentedcode'> class handler</tt>
|
||||
<tt class='indentedcode'> no: report an error ("not found")</tt>
|
||||
<br/><br/>
|
||||
All of the actual logic for how to deal with tokens is moved
|
||||
to the individual prefix handlers, and the logic for handling
|
||||
words is moved to word class handlers.
|
||||
<br/><br/>
|
||||
This means that prefixes are used for a lot of things. Numbers?
|
||||
Handled by a <span class="tt">#</span> prefix. Strings? Use the <span class="tt">'</span> prefix. Comments?
|
||||
Use <span class="tt">(</span>. Making a new word? Use the <span class="tt">:</span> prefix.
|
||||
<br/><br/>
|
||||
The major prefixes are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Prefix | Used For |</tt>
|
||||
<tt class='indentedcode'>| ------ | ----------------------------- |</tt>
|
||||
<tt class='indentedcode'>| @ | Fetch from variable |</tt>
|
||||
<tt class='indentedcode'>| ! | Store into variable |</tt>
|
||||
<tt class='indentedcode'>| & | Pointer to named item |</tt>
|
||||
<tt class='indentedcode'>| # | Numbers |</tt>
|
||||
<tt class='indentedcode'>| $ | ASCII characters |</tt>
|
||||
<tt class='indentedcode'>| ' | Strings |</tt>
|
||||
<tt class='indentedcode'>| ( | Comments |</tt>
|
||||
<tt class='indentedcode'>| : | Define a word |</tt>
|
||||
<br/><br/>
|
||||
The individual prefixes will be covered in more detail in the
|
||||
later chapters on working with different data types.
|
||||
<br/><br/>
|
||||
<span class="h2">Word Classes</span>
|
||||
<br/><br/>
|
||||
Word classes are words which take a pointer and do something
|
||||
with it. These are covered in detail in their own chapter,
|
||||
but essentially they decide <strong>how</strong> to execute or compile specific
|
||||
types of words.
|
||||
<br/><br/>
|
||||
</p>
|
||||
</body></html>
|
||||
100
doc/html/chapters/internals/image.html
Normal file
100
doc/html/chapters/internals/image.html
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Internals: The Retro Image</span>
|
||||
<br/><br/>
|
||||
The actual RETRO language is stored as a memory image for Nga.
|
||||
<br/><br/>
|
||||
<span class="h2">Format</span>
|
||||
<br/><br/>
|
||||
The image file is a flat, linear sequence of signed 32-bit
|
||||
values. Each value is stored in little endian format. The
|
||||
size is not fixed. An interface should check when loading to
|
||||
ensure that the physical image is not larger than the emulated
|
||||
memory.
|
||||
<br/><br/>
|
||||
<span class="h2">Header</span>
|
||||
<br/><br/>
|
||||
The image will start with two cells. The first is a liju....
|
||||
instruction, the second is the target address for the jump.
|
||||
This serves to skip over the rest of the data and reach the
|
||||
actual entry point.
|
||||
<br/><br/>
|
||||
This is followed by a pointer to the most recent dictionary
|
||||
header, a pointer to the next free address in memory, and
|
||||
then the RETRO version number.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Offset | Contains |</tt>
|
||||
<tt class='indentedcode'>| ------ | --------------------------- |</tt>
|
||||
<tt class='indentedcode'>| 0 | lit call nop nop |</tt>
|
||||
<tt class='indentedcode'>| 1 | Pointer to main entry point |</tt>
|
||||
<tt class='indentedcode'>| 2 | Dictionary |</tt>
|
||||
<tt class='indentedcode'>| 3 | Heap |</tt>
|
||||
<tt class='indentedcode'>| 4 | RETRO version |</tt>
|
||||
<br/><br/>
|
||||
The actual code starts after this header.
|
||||
<br/><br/>
|
||||
The version number is the year and month. As an example,
|
||||
the 12.2019.6 release will have a version number of
|
||||
<span class="tt">201906</span>.
|
||||
<br/><br/>
|
||||
<span class="h2">Layout</span>
|
||||
<br/><br/>
|
||||
Assuming an Nga built with 524287 cells of memory:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| RANGE | CONTAINS |</tt>
|
||||
<tt class='indentedcode'>| --------------- | ---------------------------- |</tt>
|
||||
<tt class='indentedcode'>| 0 - 1024 | RETRO Core kernel |</tt>
|
||||
<tt class='indentedcode'>| 1025 - 1535 | token input buffer |</tt>
|
||||
<tt class='indentedcode'>| 1536 + | start of heap space |</tt>
|
||||
<tt class='indentedcode'>| ............... | free memory for your use |</tt>
|
||||
<tt class='indentedcode'>| 506879 | buffer for string evaluate |</tt>
|
||||
<tt class='indentedcode'>| 507904 | temporary strings (32 * 512) |</tt>
|
||||
<tt class='indentedcode'>| 524287 | end of memory |</tt>
|
||||
<br/><br/>
|
||||
The buffers at the end of memory will resize when specific
|
||||
variables related to them are altered.
|
||||
</p>
|
||||
</body></html>
|
||||
62
doc/html/chapters/internals/interface-layers.html
Normal file
62
doc/html/chapters/internals/interface-layers.html
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Internals: Interface Layers</span>
|
||||
<br/><br/>
|
||||
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 <strong>interface layer</strong>.
|
||||
<br/><br/>
|
||||
An interface layer will wrap Nga, providing at least one I/O
|
||||
device (a generic output target), and a means of interacting
|
||||
with the <strong>retro image</strong>.
|
||||
<br/><br/>
|
||||
It's expected that this layer will be host specific, adding any
|
||||
system interactions that are needed via the I/O instructions.
|
||||
The image will typically be extended with words to use these.
|
||||
<br/><br/>
|
||||
<br/><br/>
|
||||
</p>
|
||||
</body></html>
|
||||
82
doc/html/chapters/internals/io.html
Normal file
82
doc/html/chapters/internals/io.html
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Internals: I/O</span>
|
||||
<br/><br/>
|
||||
RETRO provides three words for interacting with I/O. These are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>io:enumerate returns the number of attached devices</tt>
|
||||
<tt class='indentedcode'>io:query returns information about a device</tt>
|
||||
<tt class='indentedcode'>io:invoke invokes an interaction with a device</tt>
|
||||
<br/><br/>
|
||||
As an example, with an implementation providing an output source,
|
||||
a block storage system, and keyboard:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>io:enumerate will return `3` since there are three</tt>
|
||||
<tt class='indentedcode'> i/o devices</tt>
|
||||
<tt class='indentedcode'>#0 io:query will return 0 0, since the first device</tt>
|
||||
<tt class='indentedcode'> is a screen (type 0) with a version of 0</tt>
|
||||
<tt class='indentedcode'>#1 io:query will return 1 3, since the second device is</tt>
|
||||
<tt class='indentedcode'> block storage (type 3), with a version of 1</tt>
|
||||
<tt class='indentedcode'>#2 io:query will return 0 1, since the last device is a</tt>
|
||||
<tt class='indentedcode'> keyboard (type 1), with a version of 0</tt>
|
||||
<br/><br/>
|
||||
In this case, some interactions can be defined:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:c:put #0 io:invoke ;</tt>
|
||||
<tt class='indentedcode'>:c:get #2 io:invoke ;</tt>
|
||||
<br/><br/>
|
||||
Setup the stack, push the device ID, and then use <span class="tt">io:invoke</span>
|
||||
to invoke the interaction.
|
||||
<br/><br/>
|
||||
A RETRO system requires one I/O device (a generic output for a
|
||||
single character). This must be the first device, and must have
|
||||
a device ID of 0.
|
||||
<br/><br/>
|
||||
All other devices are optional and can be specified in any
|
||||
order.
|
||||
<br/><br/>
|
||||
</p>
|
||||
</body></html>
|
||||
203
doc/html/chapters/internals/nga.html
Normal file
203
doc/html/chapters/internals/nga.html
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Internals: Nga Virtual Machine</span>
|
||||
<br/><br/>
|
||||
<span class="h2">Overview</span>
|
||||
<br/><br/>
|
||||
At the heart of RETRO is a simple MISC (minimal instruction
|
||||
set computer) processor for a dual stack architecture.
|
||||
<br/><br/>
|
||||
This is a very simple and straightforward system. There are
|
||||
30 instructions. The memory is a linear array of signed 32
|
||||
bit values. And there are two stacks: one for data and one
|
||||
for return addresses.
|
||||
<br/><br/>
|
||||
<span class="h2">Instruction Table</span>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> | Stacks |</tt>
|
||||
<tt class='indentedcode'>| Opcode | Muri | Full Name | Data | Address |</tt>
|
||||
<tt class='indentedcode'>| ------ | ---- | ------------------ | ----- | ------- |</tt>
|
||||
<tt class='indentedcode'>| 0 | .. | nop | - | - |</tt>
|
||||
<tt class='indentedcode'>| 1 | li | lit | -n | - |</tt>
|
||||
<tt class='indentedcode'>| 2 | du | dup | n-nn | - |</tt>
|
||||
<tt class='indentedcode'>| 3 | dr | drop | n- | - |</tt>
|
||||
<tt class='indentedcode'>| 4 | sw | swap | xy-yx | - |</tt>
|
||||
<tt class='indentedcode'>| 5 | pu | push | n- | -n |</tt>
|
||||
<tt class='indentedcode'>| 6 | po | pop | -n | n- |</tt>
|
||||
<tt class='indentedcode'>| 7 | ju | jump | a- | - |</tt>
|
||||
<tt class='indentedcode'>| 8 | ca | call | a- | -A |</tt>
|
||||
<tt class='indentedcode'>| 9 | cc | conditional call | af- | -A |</tt>
|
||||
<tt class='indentedcode'>| 10 | re | return | - | A- |</tt>
|
||||
<tt class='indentedcode'>| 11 | eq | equality | xy-f | - |</tt>
|
||||
<tt class='indentedcode'>| 12 | ne | inequality | xy-f | - |</tt>
|
||||
<tt class='indentedcode'>| 13 | lt | less than | xy-f | - |</tt>
|
||||
<tt class='indentedcode'>| 14 | gt | greater than | xy-f | - |</tt>
|
||||
<tt class='indentedcode'>| 15 | fe | fetch | a-n | - |</tt>
|
||||
<tt class='indentedcode'>| 16 | st | store | na- | - |</tt>
|
||||
<tt class='indentedcode'>| 17 | ad | addition | xy-n | - |</tt>
|
||||
<tt class='indentedcode'>| 18 | su | subtraction | xy-n | - |</tt>
|
||||
<tt class='indentedcode'>| 19 | mu | multiplication | xy-n | - |</tt>
|
||||
<tt class='indentedcode'>| 20 | di | divide & remainder | xy-rq | - |</tt>
|
||||
<tt class='indentedcode'>| 21 | an | bitwise and | xy-n | - |</tt>
|
||||
<tt class='indentedcode'>| 22 | or | bitwise or | xy-n | - |</tt>
|
||||
<tt class='indentedcode'>| 23 | xo | bitwise xor | xy-n | - |</tt>
|
||||
<tt class='indentedcode'>| 24 | sh | shift | xy-n | - |</tt>
|
||||
<tt class='indentedcode'>| 25 | zr | zero return | n-? | - |</tt>
|
||||
<tt class='indentedcode'>| 26 | ha | halt | - | - |</tt>
|
||||
<tt class='indentedcode'>| 27 | ie | i/o enumerate | -n | - |</tt>
|
||||
<tt class='indentedcode'>| 28 | iq | i/o query | n-xy | - |</tt>
|
||||
<tt class='indentedcode'>| 29 | ii | i/o invoke | ...n- | - |</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Encoding</span>
|
||||
<br/><br/>
|
||||
Up to four instructions can be packed into each memory cell.
|
||||
<br/><br/>
|
||||
As an example,
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Opcode 4 Opcode 3 Opcode 2 Opcode 1</tt>
|
||||
<tt class='indentedcode'>00000000:00000000:00000000:00000000</tt>
|
||||
<br/><br/>
|
||||
If we have a bundle of <span class="tt">duliswst</span>, it would look like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>st sw li du</tt>
|
||||
<tt class='indentedcode'>00010000:00000100:00000001:00000010</tt>
|
||||
<br/><br/>
|
||||
Each <span class="tt">li</span> should have a value in the following cell(s). These
|
||||
values will be pushed to the stack. E.g., <span class="tt">lili....</span> and
|
||||
1, 2:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>00000000:00000000:00000001:00000001</tt>
|
||||
<tt class='indentedcode'>00000000 00000000 00000000 00000001 (1)</tt>
|
||||
<tt class='indentedcode'>00000000 00000000 00000000 00000010 (2)</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Shifts</span>
|
||||
<br/><br/>
|
||||
<span class="tt">sh</span> performs a bitwise arithmetic shift operation.
|
||||
<br/><br/>
|
||||
This takes two values:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>xy</tt>
|
||||
<br/><br/>
|
||||
And returns a single one:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>z</tt>
|
||||
<br/><br/>
|
||||
If y is positive, this shifts <span class="tt">x</span> right by <span class="tt">y</span> bits. If negative,
|
||||
it shifts left.
|
||||
<br/><br/>
|
||||
<span class="h2">Queries: Memory, Stacks</span>
|
||||
<br/><br/>
|
||||
The <span class="tt">fe</span> instruction allows queries of some data related to
|
||||
the Nga VM state. These are returned by reading from negative
|
||||
addresses:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Address | Returns |</tt>
|
||||
<tt class='indentedcode'>| ------- | ---------------------- |</tt>
|
||||
<tt class='indentedcode'>| -1 | Data stack depth |</tt>
|
||||
<tt class='indentedcode'>| -2 | Address stack depth |</tt>
|
||||
<tt class='indentedcode'>| -3 | Maximum Image Size |</tt>
|
||||
<tt class='indentedcode'>| -4 | Minimum Integer Value |</tt>
|
||||
<tt class='indentedcode'>| -5 | Maximum Integer Value |</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">I/O Devices</span>
|
||||
<br/><br/>
|
||||
Nga provides three instructions for interacting with I/O devices.
|
||||
These are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>ie i/o enumerate returns the number of attached devices</tt>
|
||||
<tt class='indentedcode'>iq i/o query returns information about a device</tt>
|
||||
<tt class='indentedcode'>ii i/o interact invokes an interaction with a device</tt>
|
||||
<br/><br/>
|
||||
As an example, with an implementation providing an output source,
|
||||
a block storage system, and keyboard:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>ie will return `3` since there are three i/o devices</tt>
|
||||
<tt class='indentedcode'>0 iq will return 0 0, since the first device is a screen (0)</tt>
|
||||
<tt class='indentedcode'> with a version of 0</tt>
|
||||
<tt class='indentedcode'>1 iq will return 1 3, since the second device is a block</tt>
|
||||
<tt class='indentedcode'> storage (3), with a version of 1</tt>
|
||||
<tt class='indentedcode'>2 iq will return 0 1, since the third device is a keyboard</tt>
|
||||
<tt class='indentedcode'> (1), with a version of 0</tt>
|
||||
<br/><br/>
|
||||
In this case, some interactions can be defined:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>: c:put</tt>
|
||||
<tt class='indentedcode'>i liiire..</tt>
|
||||
<tt class='indentedcode'>d 0</tt>
|
||||
<tt class='indentedcode'></tt>
|
||||
<tt class='indentedcode'>: c:get</tt>
|
||||
<tt class='indentedcode'>i liiire..</tt>
|
||||
<tt class='indentedcode'>d 2</tt>
|
||||
<br/><br/>
|
||||
Setup the stack, push the device ID to the stack, and then use
|
||||
<span class="tt">ii</span> to invoke the interaction.
|
||||
<br/><br/>
|
||||
A RETRO system requires one I/O device (a generic output for a
|
||||
single character). This must be the first device, and must have
|
||||
a device ID of 0.
|
||||
<br/><br/>
|
||||
All other devices are optional and can be specified in any order.
|
||||
<br/><br/>
|
||||
The currently supported and reserved device identifiers are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| ID | Device Type | Notes |</tt>
|
||||
<tt class='indentedcode'>| ---- | ---------------- | -------------------------- |</tt>
|
||||
<tt class='indentedcode'>| 0000 | Generic Output | Always present as device 0 |</tt>
|
||||
<tt class='indentedcode'>| 0001 | Keyboard | |</tt>
|
||||
<tt class='indentedcode'>| 0002 | Floating Point | |</tt>
|
||||
<tt class='indentedcode'>| 0003 | Block Storage | Raw, 1024 cell blocks |</tt>
|
||||
<tt class='indentedcode'>| 0004 | Filesystem | Unix-style Files |</tt>
|
||||
<tt class='indentedcode'>| 0005 | Network: Gopher | Make gopher requests |</tt>
|
||||
<tt class='indentedcode'>| 0006 | Network: HTTP | Make HTTP requests |</tt>
|
||||
<tt class='indentedcode'>| 0007 | Network: Sockets | |</tt>
|
||||
<tt class='indentedcode'>| 0008 | Syscalls: Unix | |</tt>
|
||||
<tt class='indentedcode'>| 0009 | Scripting Hooks | |</tt>
|
||||
<tt class='indentedcode'>| 0010 | Random Number | |</tt>
|
||||
<br/><br/>
|
||||
This list may be revised in the future. The only guaranteed
|
||||
stable indentifier is 0000 for generic output.
|
||||
</p>
|
||||
</body></html>
|
||||
102
doc/html/chapters/tech-notes/code-it-yourself.html
Normal file
102
doc/html/chapters/tech-notes/code-it-yourself.html
Normal file
|
|
@ -0,0 +1,102 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">The Code It Yourself Manifesto</span>
|
||||
<br/><br/>
|
||||
We use software for our everyday needs because we want to get
|
||||
something done. We have goals to achieve and things to do.
|
||||
<br/><br/>
|
||||
The software we use is coded by brave programmers that have
|
||||
their own goals. Most of the time there is an overlap between
|
||||
their goals and ours.
|
||||
<br/><br/>
|
||||
Over time these will diverge.
|
||||
<br/><br/>
|
||||
This means that the tools we depend on grow features we don't
|
||||
use or understand. There will be bugs in these code parts which
|
||||
will prevent us from reaching our goals.
|
||||
<br/><br/>
|
||||
So we are at a fork in the road:
|
||||
<br/><br/>
|
||||
• We have the choice of trying to understand the code and<br/>
|
||||
fix it.
|
||||
• We have the choice of trying another program, whose<br/>
|
||||
creator's goals are closer to ours.
|
||||
• We also have the choice of coding the software ourself.<br/>
|
||||
<br/><br/>
|
||||
All but the last path mean endless seeking, evaluating and
|
||||
further deviation from our goals. Therefore we replace programs
|
||||
we do not understand fully with our own implementation.
|
||||
<br/><br/>
|
||||
The followers of the Code It Yourself Manifesto believe in
|
||||
these things:
|
||||
<br/><br/>
|
||||
• We implement it according to our own goals.<br/>
|
||||
• We make mistakes and learn from them.<br/>
|
||||
• We learn how our tools we depend on need to work.<br/>
|
||||
• We gain a deep understanding of our problem domain.<br/>
|
||||
• We still embrace sharing of ideas and code.<br/>
|
||||
<br/><br/>
|
||||
Sharing is only possible if we are excellent developers to
|
||||
each other. The next developer reading our code will be us
|
||||
in a not so distant future. Coding It Ourselves means we will
|
||||
document our code, clearly stating the goal of the software
|
||||
we write.
|
||||
<br/><br/>
|
||||
Together we enjoy the diversity of implementations and ideas.
|
||||
<br/><br/>
|
||||
We encourage our colleagues to
|
||||
<br/><br/>
|
||||
<strong></strong>Code It Yourself.<strong></strong>
|
||||
<br/><br/>
|
||||
<span class="hr"></span>
|
||||
<br/><br/>
|
||||
Written by Christian Kellermann on 2016-01-12, licensed under
|
||||
a CreativeCommonsAttribution-ShareAlike3.0UnportedLicense.
|
||||
<br/><br/>
|
||||
Original text taken from
|
||||
http://pestilenz.org/~ckeen/blog/posts/ciy-manifesto.html
|
||||
</p>
|
||||
</body></html>
|
||||
200
doc/html/chapters/tech-notes/historical-papers.html
Normal file
200
doc/html/chapters/tech-notes/historical-papers.html
Normal file
|
|
@ -0,0 +1,200 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Historical Papers and Notes</span>
|
||||
<br/><br/>
|
||||
<span class="h2">On the Naming of RETRO</span>
|
||||
<br/><br/>
|
||||
Taken from http://lists.tunes.org/archives/tunes-lll/1999-July/000121.html
|
||||
<br/><br/>
|
||||
On Fri, Jul 30, 1999 at 07:43:54PM -0400, Paul Dufresne wrote:
|
||||
<br/><br/>
|
||||
> My brother did found it funny that Retro is called like that.
|
||||
> For him retro means going back (generally in time) so this
|
||||
> does not looks like a name of a OS to come. So he'd like to
|
||||
> know from where the name came.
|
||||
<br/><br/>
|
||||
Heheh, here's the story: When I started playing with OS stuff
|
||||
last year (not seriously), I was reading about some old things
|
||||
like FORTH and ITS, dating back to the 1960's and 70's. The
|
||||
past few years in America, there's been a revival of disco
|
||||
music (along with bell bottoms, platform shoes, and all that
|
||||
crap) and they call it "retro". Now, my OS was named by
|
||||
musicians.. I was telling a fellow musician about my ideas,
|
||||
how it would be cool to have a small OS that isn't bloated and
|
||||
unmanageable like Windows... go back to the 70's and resurrect
|
||||
a line of software that died out. He goes "hmm.. sounds kinda
|
||||
retro.."
|
||||
<br/><br/>
|
||||
I think it sounds kinda rebellious, which is a Good Thing now
|
||||
that everybody hates the M$ empire. :) It seems like other
|
||||
people are as sick of the future as I am. Look at TUNES, the
|
||||
idea there isn't to make some great new invention, just take
|
||||
some decades-old ideas and combine them in one OS. The first
|
||||
time I saw Knuth's "Art of Computer Programming" in the library
|
||||
I thought "god that looks old.. 1973!!! nevermind.." Now it's
|
||||
my programming bible. Find me something better published in
|
||||
the 90's.. if such a thing exists, it'll be like a needle in a
|
||||
haystack. "Newer" doesn't necessarily mean "better".
|
||||
<br/><br/>
|
||||
New cars = flimsier
|
||||
New farming methods = more devastating
|
||||
New version of Netscape = more bloat, more bullshit
|
||||
<br/><br/>
|
||||
One thing is better now: computer hardware. Give me 70's
|
||||
software on 90's and 00's hardware :)
|
||||
<br/><br/>
|
||||
• Tom Novelli <tcn@tunes.org><br/>
|
||||
<br/><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">The Design Philosophy of RETRO Native Forth</span>
|
||||
<br/><br/>
|
||||
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
|
||||
software business. However, software has seen little innovation while
|
||||
hardware technology has improved phenomenally (notwithstanding the advent
|
||||
of lousy slave-made parts). Proven software techniques of forty years ago
|
||||
have yet to reach widespread use, in deference to the "latest and
|
||||
greatest" proprietary solutions of dubious value. Thanks to agressive
|
||||
marketing, we make huge investments in these dead-end technologies
|
||||
(through our businesses and governments, if not personally) and we end up
|
||||
with a reliance on a heap of complicated, error-prone, poorly understood
|
||||
junk software.
|
||||
<br/><br/>
|
||||
Complexity will dominate the software industry for the foreseeable
|
||||
future. The Retro philosophy is a simple alternative for those willing to
|
||||
make a clean break with legacy software. A Retro system can communicate
|
||||
with other systems, but it won't run much legacy software, especially
|
||||
proprietary software without source code. An emulation layer could be
|
||||
added, but doing so would defeat the purpose of a simple operating system.
|
||||
I think TCP/IP support is all the compatibility that's needed.
|
||||
<br/><br/>
|
||||
At first Retro will appeal to computer hobbyists and electronic
|
||||
engineers. Once the rough edges are smoothed out, it could catch on with
|
||||
ordinary folks who don't like waiting five minutes just to check their
|
||||
email (not to mention the long hours of setup and maintenance). Game
|
||||
programmers who take their craft seriously may also be interested.
|
||||
Businesses might even see a use for it, if the managers decide it's more
|
||||
cost-effective to carefully design software for specific needs, rather
|
||||
than buying off-the-shelf crap and spending countless manhours working
|
||||
around the bugs. Since it's not practical for businesses to make a clean
|
||||
break, my advice is to run Retro (and its ilk) on separate machines
|
||||
connected by a network. Retro is efficient enough to run on older
|
||||
machines that would otherwise sit idle, being too slow for the latest
|
||||
Microsoft bloatware (or Linux, for that matter).
|
||||
<br/><br/>
|
||||
I strive to avoid the extraneous. That applies even to proven
|
||||
technologies, if I don't need them. If my computer isn't set up for
|
||||
people to log in over the network, I don't want security features; they
|
||||
just get in the way. If I'm only running programs I wrote, I should be
|
||||
able to run them with full access to the hardware; I don't need protection
|
||||
from viruses. If I download something I don't trust, then I can run it in
|
||||
an isolated process, which is customary with Unix and kin. But that's not
|
||||
core functionality. All that's needed is the flexibility to add things
|
||||
like security, graphical interfaces, and distributed processing - if the
|
||||
need ever arises.
|
||||
<br/><br/>
|
||||
In programming languagues, I was misled. It's the Tower of Babel all
|
||||
over again. The thousands of languages in existence all fall into a
|
||||
handful of archetypes: Assembler, LISP, FORTRAN and FORTH represent the
|
||||
earliest descendants of nearly all languages. I hesitate to name a
|
||||
definitive "object-oriented" language, and here's why: Object-Oriented
|
||||
programming is just a technique, and any language will suffice, even
|
||||
Assembler. The complexites of fancy languages like Ada and C++ are a
|
||||
departure from reality -- the reality of the actual physical machine.
|
||||
When it all boils down, even LISP, FORTRAN and FORTH are only extensions
|
||||
of the machine.
|
||||
<br/><br/>
|
||||
I chose FORTH as the "native tongue" of Retro. LISP, FORTRAN, and
|
||||
other languages can be efficiently implemented as extensions of FORTH, but
|
||||
the reverse isn't so efficient. Theoretically all languages are
|
||||
equivalent, but when design time, compilation time, and complexity are
|
||||
accounted for, FORTH is most efficient. FORTH also translates most
|
||||
directly to the hardware. (In fact, FORTH has been implemented in
|
||||
hardware; these "stack machines" are extremely efficient.) FORTH is also
|
||||
the easiest language to implement from scratch - a major concern when
|
||||
you're trying to make a clean break. So with simplicity in mind, FORTH
|
||||
was the obvious choice.
|
||||
<br/><br/>
|
||||
I'm perfectly happy working with text only, and I go to great lengths
|
||||
to avoid using the standard graphical environments, which have major
|
||||
problems: windows, pulldown menus, and mice. Windows can't share the
|
||||
screen nicely; that idea is hopeless. Pulldowns are tedious. Mice get in
|
||||
the way of typing without reducing the need for it; all they give me is
|
||||
tendonitis. Their main use is for drawing.
|
||||
<br/><br/>
|
||||
Some of my favorite interfaces: Telix, Telegard BBS, Pine, Pico, Lynx,
|
||||
and ScreamTracker. All "hotkey" interfaces where you press a key or two
|
||||
to perform an action. Usually the important commands are listed at the
|
||||
bottom of the screen, or at least on a help screen. The same principles
|
||||
apply to graphical interfaces: use the full screen, except for a status
|
||||
and menu area on one edge. Resist the temptation to clutter up the
|
||||
screen.
|
||||
<br/><br/>
|
||||
As for switching between programs, the Windows methods suck; the only
|
||||
thing worse is Unix job control (jobs, fg, and such). The Linux method is
|
||||
tolerable: Alt-Arrows, Alt-F1, Alt-F2, etc. Still, things could be
|
||||
better: F11 and F12 cycle back and forth through all open programs; Alt-F1
|
||||
assigns the currently selected program to F1, and likewise for the other
|
||||
function keys. Programs just won't use function keys - Control and Alt
|
||||
combinations are less awkward and easier to remember, besides. I'll also
|
||||
want a "last channel" key and a "task list" key; maybe I'll borrow those
|
||||
stupid Win95 keys. The Pause key will do like it says - pause the current
|
||||
program - and Ctrl-Pause (Break) will kill it.
|
||||
<br/><br/>
|
||||
One more thing: consistency. I like programs to look different so I
|
||||
can tell them apart, but the keys should be the same as much as possible.
|
||||
Keys should be configured in one place, for all programs. Finally,
|
||||
remember the most consistent interface, one of the few constants
|
||||
throughout the history of computing - the text screen and keyboard, and
|
||||
the teletypewriter before that. Don't overlook it.
|
||||
<br/><br/>
|
||||
More to come, maybe... :)
|
||||
<br/><br/>
|
||||
"If it's on line, it's a work in progress."
|
||||
<br/><br/>
|
||||
Tom Novelli, 3/4/2000
|
||||
</p>
|
||||
</body></html>
|
||||
122
doc/html/chapters/tech-notes/kernel-words.html
Normal file
122
doc/html/chapters/tech-notes/kernel-words.html
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h2">On The Kernel Wordset</span>
|
||||
<br/><br/>
|
||||
In implementing the RETRO 12 kernel (called RETRO Core, and
|
||||
defined in <span class="tt">image/retro.muri</span>) I had to decide on what functionality
|
||||
would be needed. It was important to me that this be kept clean
|
||||
and minimalistic, as I didn't want to spend a lot of time
|
||||
changing it as time progressed. It's far nicer to code at the
|
||||
higher level, where the RETRO language is fully functional, as
|
||||
opposed to writing more assembly code.
|
||||
<br/><br/>
|
||||
So what made it in?
|
||||
<br/><br/>
|
||||
Primitives
|
||||
<br/><br/>
|
||||
These are words that map directly to Nga instructions.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>dup drop swap call eq? -eq? lt? gt?</tt>
|
||||
<tt class='indentedcode'>fetch store + - * /mod and or</tt>
|
||||
<tt class='indentedcode'>xor shift push pop 0;</tt>
|
||||
<br/><br/>
|
||||
Memory
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>fetch-next store-next , s,</tt>
|
||||
<br/><br/>
|
||||
Strings
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>s:to-number s:eq? s:length</tt>
|
||||
<br/><br/>
|
||||
Flow Control
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>choose if -if repeat again</tt>
|
||||
<br/><br/>
|
||||
Compiler & Interpreter
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Compiler Heap ; [ ] Dictionary</tt>
|
||||
<tt class='indentedcode'>d:link d:class d:xt d:name d:add-header</tt>
|
||||
<tt class='indentedcode'>class:word class:primitive class:data class:macro</tt>
|
||||
<tt class='indentedcode'>prefix:: prefix:# prefix:& prefix:$</tt>
|
||||
<tt class='indentedcode'>interpret d:lookup err:notfound</tt>
|
||||
<br/><br/>
|
||||
Assembler
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>i d r</tt>
|
||||
<br/><br/>
|
||||
I <strong>could</strong> slightly reduce this. The $ prefix could be defined in
|
||||
higher level code, and I don't strictly <strong>need</strong> to expose the
|
||||
<span class="tt">fetch-next</span> and <span class="tt">store-next</span> here. But since the are already
|
||||
implemented as dependencies of the words in the kernel, it would
|
||||
be a bit wasteful to redefine them later in higher level code.
|
||||
<br/><br/>
|
||||
A recent change was the addition of the assembler into the
|
||||
kernel. This allows the higher levels to use assembly as needed,
|
||||
which gives more flexibility and allows for more optimal code
|
||||
in the standard library.
|
||||
<br/><br/>
|
||||
With these words the rest of the language can be built up. Note
|
||||
that the RETRO kernel does not provide any I/O words. It's assumed
|
||||
that the RETRO interfaces will add these as best suited for the
|
||||
systems they run on.
|
||||
<br/><br/>
|
||||
There is another small bit. All images start with a few key
|
||||
pointers in fixed offsets of memory. These are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Offset | Contains |</tt>
|
||||
<tt class='indentedcode'>| ------ | --------------------------- |</tt>
|
||||
<tt class='indentedcode'>| 0 | lit call nop nop |</tt>
|
||||
<tt class='indentedcode'>| 1 | Pointer to main entry point |</tt>
|
||||
<tt class='indentedcode'>| 2 | Dictionary |</tt>
|
||||
<tt class='indentedcode'>| 3 | Heap |</tt>
|
||||
<tt class='indentedcode'>| 4 | RETRO version identifier |</tt>
|
||||
<br/><br/>
|
||||
An interface can use the dictionary pointer and knowledge of the
|
||||
dictionary format for a specific RETRO version to identify the
|
||||
location of essential words like <span class="tt">interpret</span> and <span class="tt">err:notfound</span>
|
||||
when implementing the user facing interface.
|
||||
</p>
|
||||
</body></html>
|
||||
123
doc/html/chapters/tech-notes/metacompilation.html
Normal file
123
doc/html/chapters/tech-notes/metacompilation.html
Normal file
|
|
@ -0,0 +1,123 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h2">Metacompilation and Assembly</span>
|
||||
<br/><br/>
|
||||
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,
|
||||
the way I ended up doing it was problematic.
|
||||
<br/><br/>
|
||||
The biggest issue I faced was that I wanted to do this in one
|
||||
step, where loading the RETRO source would create a new image
|
||||
in place of the old one, switch to the new one, and then load
|
||||
the higher level parts of the language over this. In retrospect,
|
||||
this was a really bad idea.
|
||||
<br/><br/>
|
||||
My earlier design for RETRO was very flexible. I allowed almost
|
||||
everything to be swapped out or extended at any time. This made
|
||||
it extremely easy to customize the language and environment, but
|
||||
made it crucial to keep track of what was in memory and what had
|
||||
been patched so that the metacompiler wouldn't refer to anything
|
||||
in the old image during the relocation and control change. It
|
||||
was far too easy to make a mistake, discover that elements of
|
||||
the new image were broken, and then have to go and revert many
|
||||
changes to try to figure out what went wrong.
|
||||
<br/><br/>
|
||||
This was also complicated by the fact that I built new images
|
||||
as I worked, and, while a new image could be built from the last
|
||||
built one, it wasn't always possible to build a new image from
|
||||
the prior release version. (Actually, it was often worse - I
|
||||
failed to check in every change as I went, so often even the
|
||||
prior commits couldn't rebuild the latest images).
|
||||
<br/><br/>
|
||||
For RETRO 12 I wanted to avoid this problem, so I decided to go
|
||||
back to writing the kernel ("Rx") in assembly. I actually wrote
|
||||
a Machine Forth dialect to generate the initial assembly, before
|
||||
eventually hand tuning the final results to its current state.
|
||||
<br/><br/>
|
||||
I could (and likely will eventually) write the assembler in
|
||||
RETRO, but the current one is in C, and is built as part of the
|
||||
standard toolchain.
|
||||
<br/><br/>
|
||||
My VM actually has two assemblers. The older one is Naje. This
|
||||
was intended to be fairly friendly to work with, and handles
|
||||
many of the details of packing instructions for the user. Here
|
||||
is an example of a small program in it:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:square</tt>
|
||||
<tt class='indentedcode'> dup</tt>
|
||||
<tt class='indentedcode'> mul</tt>
|
||||
<tt class='indentedcode'> ret</tt>
|
||||
<tt class='indentedcode'>:main</tt>
|
||||
<tt class='indentedcode'> lit 35</tt>
|
||||
<tt class='indentedcode'> lit &square</tt>
|
||||
<tt class='indentedcode'> call</tt>
|
||||
<tt class='indentedcode'> end</tt>
|
||||
<br/><br/>
|
||||
The other assembler is Muri. This is a far more minimalistic
|
||||
assembler, but I've actually grown to prefer it. The above
|
||||
example in Muri would become:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>i liju....</tt>
|
||||
<tt class='indentedcode'>r main</tt>
|
||||
<tt class='indentedcode'>: square</tt>
|
||||
<tt class='indentedcode'>i dumure..</tt>
|
||||
<tt class='indentedcode'>: main</tt>
|
||||
<tt class='indentedcode'>i lilica..</tt>
|
||||
<tt class='indentedcode'>d 35</tt>
|
||||
<tt class='indentedcode'>r square</tt>
|
||||
<tt class='indentedcode'>i en......</tt>
|
||||
<br/><br/>
|
||||
In Muri, each instruction is reduced to two characters, and the
|
||||
bundlings are listed as part of an instruction bundle (lines
|
||||
starting with <span class="tt">i</span>). This is less readable if you aren't very
|
||||
familiar with Nga's assembly and packing rules, but allows a
|
||||
very quick, efficient way of writing assembly for those who are.
|
||||
<br/><br/>
|
||||
I eventually rewrote the kernel in the Muri style as it's what
|
||||
I prefer, and since there's not much need to make changes in it.
|
||||
</p>
|
||||
</body></html>
|
||||
120
doc/html/chapters/tech-notes/ngaro-to-nga.html
Normal file
120
doc/html/chapters/tech-notes/ngaro-to-nga.html
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h2">On The Evolution Of Ngaro Into Nga</span>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
Ngaro rose out of an earlier experimental virtual machine I had
|
||||
written back in 2005-2006. This earlier VM, called Maunga, was
|
||||
very close to what Ngaro ended up being, though it had a very
|
||||
different approach to I/O. (All I/O in Maunga was intended to be
|
||||
memory mapped; Ngaro adopted a port based I/O system).
|
||||
<br/><br/>
|
||||
Ngaro itself evolved along with RETRO, gaining features like
|
||||
automated skipping of NOPs and a LOOP opcode to help improve
|
||||
performance. But the I/O model proved to be a problem. When I
|
||||
created Ngaro, I had the idea that I would always be able to
|
||||
assume a console/terminal style environment. The assumption was
|
||||
that all code would be entered via the keyboard (or maybe a
|
||||
block editor), and that proved to be the fundamental flaw as
|
||||
time went on.
|
||||
<br/><br/>
|
||||
As RETRO grew it was evident that the model had some serious
|
||||
problems. Need to load code from a file? The VM and language had
|
||||
functionality to pretend it was being typed in. Want to run on
|
||||
something like a browser, Android, or iOS? The VM would need to
|
||||
be implemented in a way that simulates input being typed into
|
||||
the VM via a simulated keyboard. And RETRO was built around this.
|
||||
I couldn't change it because of a promise to maintain, as much
|
||||
as possible, source compatibility for a period of at least five
|
||||
years.
|
||||
<br/><br/>
|
||||
When the time came to fix this, I decided at the start to keep
|
||||
the I/O model separate from the core VM. I also decided that the
|
||||
core RETRO language would provide some means of interpreting
|
||||
code without requiring an assumption that a traditional terminal
|
||||
was being used.
|
||||
<br/><br/>
|
||||
So Nga began. I took the opportunity to simplify the instruction
|
||||
set to just 26 essential instructions, add support for packing
|
||||
multiple instructions per memory location (allowing a long due
|
||||
reduction in memory footprint), and to generally just make a far
|
||||
simpler design.
|
||||
<br/><br/>
|
||||
I've been pleased with Nga. On its own it really isn't useful
|
||||
though. So with RETRO I embed it into a larger framework that
|
||||
adds some basic I/O functionality. The <strong>interfaces</strong> handle the
|
||||
details of passing tokens into the language and capturing any
|
||||
output. They are free to do this in whatever model makes most
|
||||
sense on a given platform.
|
||||
<br/><br/>
|
||||
So far I've implemented:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>- a scripting interface, reading input from a file and</tt>
|
||||
<tt class='indentedcode'> offering file i/o, gopher, and reading from stdin, and</tt>
|
||||
<tt class='indentedcode'> sending output to stdout.</tt>
|
||||
<tt class='indentedcode'>- an interactive interface, built around ncurses, reading</tt>
|
||||
<tt class='indentedcode'> input from stdin, and displaying output to a scrolling</tt>
|
||||
<tt class='indentedcode'> buffer.</tt>
|
||||
<tt class='indentedcode'>- an iOS interface, built around a text editor, directing</tt>
|
||||
<tt class='indentedcode'> output to a separate interface pane.</tt>
|
||||
<tt class='indentedcode'>- an interactive block editor, using a gopher-based block</tt>
|
||||
<tt class='indentedcode'> data store. Output is displayed to stdout, and input is</tt>
|
||||
<tt class='indentedcode'> done via the blocks being evaluated or by reading from</tt>
|
||||
<tt class='indentedcode'> stdin.</tt>
|
||||
<br/><br/>
|
||||
In all cases, the only common I/O word that has to map to an
|
||||
exposed instruction is <span class="tt">putc</span>, to display a single character to
|
||||
some output device. There is no requirement for a traditional
|
||||
keyboard input model.
|
||||
<br/><br/>
|
||||
By doing this I was able to solve the biggest portability issue
|
||||
with the RETRO 10/11 model, and make a much simpler, cleaner
|
||||
language in the end.
|
||||
</p>
|
||||
</body></html>
|
||||
93
doc/html/chapters/tech-notes/prefixes.html
Normal file
93
doc/html/chapters/tech-notes/prefixes.html
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h2">Prefixes as a Language Element</span>
|
||||
<br/><br/>
|
||||
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 <strong>how</strong> input is given
|
||||
to the <span class="tt">interpret</span> word, or whether anything else will ever be
|
||||
passed into it.
|
||||
<br/><br/>
|
||||
And so <span class="tt">interpret</span> operates only on the current token. The core
|
||||
language does not track what came before or attempt to guess at
|
||||
what might come in the future.
|
||||
<br/><br/>
|
||||
This leads into the prefixes. RETRO 11 had a complicated system
|
||||
for prefixes, with different types of prefixes for words that
|
||||
parsed ahead (e.g., strings) and words that operated on the
|
||||
current token (e.g., <span class="tt">@</span>). RETRO 12 eliminates all of these in
|
||||
favor of just having a single prefix model.
|
||||
<br/><br/>
|
||||
The first thing <span class="tt">interpret</span> does is look to see if the first
|
||||
character in a token matches a <span class="tt">prefix:</span> word. If it does, it
|
||||
passes the rest of the token as a string pointer to the prefix
|
||||
specific handler to deal with. If there is no valid prefix
|
||||
found, it tries to find it in the dictionary. Assuming that it
|
||||
finds the words, it passes the <span class="tt">d:xt</span> field to the handler that
|
||||
<span class="tt">d:class</span> points to. Otherwise it calls <span class="tt">err:notfound</span>.
|
||||
<br/><br/>
|
||||
This has an important implication: <strong>words can not reliably
|
||||
have names that start with a prefix character.</strong>
|
||||
<br/><br/>
|
||||
It also simplifies things. Anything that would normally parse
|
||||
becomes a prefix handler. So creating a new word? Use the <span class="tt">:</span>
|
||||
prefix. Strings? Use <span class="tt">'</span>. Pointers? Try <span class="tt">&</span>. And so on. E.g.,
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>In ANS | In RETRO</tt>
|
||||
<tt class='indentedcode'>: foo ... ; | :foo ... ;</tt>
|
||||
<tt class='indentedcode'>' foo | &foo</tt>
|
||||
<tt class='indentedcode'>: bar ... ['] foo ; | :bar ... &foo ;</tt>
|
||||
<tt class='indentedcode'>s" hello world!" | 'hello_world!</tt>
|
||||
<br/><br/>
|
||||
If you are familiar with ColorForth, prefixes are a similar
|
||||
idea to colors, but can be defined by the user as normal words.
|
||||
<br/><br/>
|
||||
After doing this for quite a while I rather like it. I can see
|
||||
why Chuck Moore eventually went towards ColorForth as using
|
||||
color (or prefixes in my case) does simplify the implementation
|
||||
in many ways.
|
||||
</p>
|
||||
</body></html>
|
||||
126
doc/html/chapters/tech-notes/retro11-retrospective.html
Normal file
126
doc/html/chapters/tech-notes/retro11-retrospective.html
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h2">RETRO 11 (2011 - 2019): A Look Back</span>
|
||||
<br/><br/>
|
||||
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
|
||||
finally retire RETRO 11.
|
||||
<br/><br/>
|
||||
As I prepare to do so, I thought I'd take a brief look back.
|
||||
<br/><br/>
|
||||
RETRO 11 began life in 2011. It grew out of RETRO 10, which was
|
||||
the first version of RETRO to not be written in x86 assembly
|
||||
language. For R10 and R11, I wrote a portable virtual machine
|
||||
(with numerous implementations) and the Forth dialect was kept
|
||||
in an image file which ran on the VM.
|
||||
<br/><br/>
|
||||
RETRO 10 worked, but was always a bit too sloppy and changed
|
||||
drastically between releases. The major goal of RETRO 11 was to
|
||||
provide a stable base for a five year period. In retrospect,
|
||||
this was mostly achieved. Code from earlier releases normally
|
||||
needed only minor adjustments to run on later releases, though
|
||||
newer releases added significantly to the language.
|
||||
<br/><br/>
|
||||
There were seven releases.
|
||||
<br/><br/>
|
||||
• Release 11.0: 2011, July<br/>
|
||||
• Release 11.1: 2011, November<br/>
|
||||
• Release 11.2: 2012, January<br/>
|
||||
• Release 11.3: 2012, March<br/>
|
||||
• Release 11.4: 2012, July<br/>
|
||||
• Release 11.5: 2013, March<br/>
|
||||
• Release 11.6: 2014, August<br/>
|
||||
<br/><br/>
|
||||
Development was fast until 11.4. This was the point at which I
|
||||
had to slow down due to RSI problems. It was also the point
|
||||
which I started experiencing some problems with the metacompiler
|
||||
(as discussed previously).
|
||||
<br/><br/>
|
||||
RETRO 11 was flexible. All colon definitions were setup as hooks,
|
||||
allowing new functionality to be layered in easily. This allowed
|
||||
the later releases to add things like vocabularies, search order,
|
||||
tab completion, and keyboard remapping. This all came at a cost
|
||||
though: later things could use the hooks to alter behavior of
|
||||
existing words, so it was necessary to use a lot of caution to
|
||||
ensure that the layers didn't break the earlier code.
|
||||
<br/><br/>
|
||||
The biggest issue was the I/O model. RETRO 11 and the Ngaro VM
|
||||
assumed the existence of a console environment. All input was
|
||||
required to be input at the keyboard, and all output was to be
|
||||
shown on screen. This caused some problems. Including code from
|
||||
a file required some tricks, temporarily rewriting the keyboard
|
||||
input function to read from the file. It also became a major
|
||||
issue when I wrote the iOS version. The need to simulate the
|
||||
keyboard and console complicated everything and I had to spend
|
||||
a considerable amount of effort to deal with battery performance
|
||||
resulting from the I/O polling and wait states.
|
||||
<br/><br/>
|
||||
But on the whole it worked well. I used RETRO 11.6 until I started
|
||||
work on RETRO 12 in late 2016, and continued running some tools
|
||||
written in R11 until the first quarter of last year.
|
||||
<br/><br/>
|
||||
The final image file was 23,137 cells (92,548 bytes). This was
|
||||
bloated by keeping some documentation (stack comments and short
|
||||
descriptions) in the image, which started in 11.4. This contained
|
||||
269 words.
|
||||
<br/><br/>
|
||||
I used RETRO 11 for a wide variety of tasks. A small selection of
|
||||
things that were written includes:
|
||||
<br/><br/>
|
||||
• a pastebin<br/>
|
||||
• front end to ii (irc client)<br/>
|
||||
• small explorations of interactive fiction<br/>
|
||||
• irc log viewer<br/>
|
||||
• tool to create html from templates<br/>
|
||||
• tool to automate creation of an SVCD from a set of photos<br/>
|
||||
• tools to generate reports from data sets for my employer<br/>
|
||||
<br/><br/>
|
||||
In the end, I'm happy with how RETRO 11 turned out. I made some
|
||||
mistakes in embracing too much complexity, but despite this it
|
||||
was a successful system for many years.
|
||||
</p>
|
||||
</body></html>
|
||||
91
doc/html/chapters/tech-notes/security.html
Normal file
91
doc/html/chapters/tech-notes/security.html
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Security Concerns</span>
|
||||
<br/><br/>
|
||||
The standard RETRO is not a good choice for applications
|
||||
needing to be highly secure.
|
||||
<br/><br/>
|
||||
<span class="h2">Runtime Checks</span>
|
||||
<br/><br/>
|
||||
The RETRO system performs only minimal checks. It will not
|
||||
load an image larger than the max set at build time. And
|
||||
stack over/underflow are checked for as code executes.
|
||||
<br/><br/>
|
||||
The system does not attempt to validate anything else, it's
|
||||
quite easy to crash.
|
||||
<br/><br/>
|
||||
<span class="h2">Isolation</span>
|
||||
<br/><br/>
|
||||
The VM itself and the core code is self contained. Nga does
|
||||
not make use of malloc/free, and uses only standard system
|
||||
libraries. It's possible for buffer overruns within the image
|
||||
(overwriting Nga code), but the RETRO image shouldn't leak
|
||||
into the C portions.
|
||||
<br/><br/>
|
||||
I/O presents a bigger issue. Anything involving I/O, especially
|
||||
with the <span class="tt">unix:</span> words, may be a vector for attacks.
|
||||
<br/><br/>
|
||||
<span class="h2">Future Direction</span>
|
||||
<br/><br/>
|
||||
I'm not planning to add anything to the <strong>image</strong> side as, for me,
|
||||
the performance hit due to added checks is bigger than the
|
||||
benefits.
|
||||
<br/><br/>
|
||||
The story is different on the VM side. I've already begun taking
|
||||
steps to address some of the issues, using functions that check
|
||||
for overruns with strings and doing some minor testing for these
|
||||
conditions. I will be gradually addressing the various I/O
|
||||
related extensions, though it's unlikely to ever be fully guarded
|
||||
against attacks.
|
||||
<br/><br/>
|
||||
<span class="h2">Rationale</span>
|
||||
<br/><br/>
|
||||
RETRO is, primarily, a personal system. I'm running code I wrote
|
||||
to solve problems I face. On the occasions where I run code sent
|
||||
to me by others, I read it carefully first and then run inside a
|
||||
sandboxed environment if I'm worried about anything in it.
|
||||
</p>
|
||||
</body></html>
|
||||
169
doc/html/chapters/tech-notes/self-hosting.html
Normal file
169
doc/html/chapters/tech-notes/self-hosting.html
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h2">The Path to Self Hosting</span>
|
||||
<br/><br/>
|
||||
RETRO is an image based Forth system running on a lightweight
|
||||
virtual machine. This is the story of how that image is made.
|
||||
<br/><br/>
|
||||
The first RETRO to use an image based approach was RETRO 10.
|
||||
The earliest images were built using a compiler written in
|
||||
Toka, an earlier experimental stack language I had written.
|
||||
It didn't take long to want to drop the dependency on Toka,
|
||||
so I rewrote the image compiler in RETRO and then began
|
||||
development at a faster pace.
|
||||
<br/><br/>
|
||||
RETRO 11 was built using the last RETRO 10 image and an
|
||||
evolved version of the metacompiler. This worked well, but
|
||||
I eventually found it to be problematic.
|
||||
<br/><br/>
|
||||
One of the issues I faced was the inability to make a new
|
||||
image from the prior stable release. Since I develop and
|
||||
test changes incrementally, I reached a point where the
|
||||
current metacompiler and image required each other. This
|
||||
wasn't a fatal flaw, but it was annoying.
|
||||
<br/><br/>
|
||||
Perhaps more critical was the fragility of the system. In
|
||||
R11 small mistakes could result in a corrupt image. The test
|
||||
suite helped identify some of these, but there were a few
|
||||
times I was forced to dig back through the version control
|
||||
history to recover a working image.
|
||||
<br/><br/>
|
||||
The fragile nature was amplified by some design decisions.
|
||||
In R11, after the initial kernel was built, it would be
|
||||
moved to memory address 0, then control would jump into the
|
||||
new kernel to finish building the higher level parts.
|
||||
<br/><br/>
|
||||
Handling this was a tricky task. In R11 almost everything
|
||||
could be revectored, so the metacompiler had to ensure that
|
||||
it didn't rely on anything in the old image during the move.
|
||||
This caused a large number of issues over R11's life.
|
||||
<br/><br/>
|
||||
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 <span class="tt">Rx.md</span> and the
|
||||
assembler is <span class="tt">Muri</span>. To load the standard library, I wrote a
|
||||
second tool, <span class="tt">retro-extend</span>. This separation has allowed me
|
||||
many fewer headaches as I can make changes more easily and
|
||||
rebuild from scratch when necessary.
|
||||
<br/><br/>
|
||||
But I miss self-hosting. So last fall I decided to resolve
|
||||
this. And today I'm pleased to say that it is now done.
|
||||
<br/><br/>
|
||||
There are a few parts to this.
|
||||
<br/><br/>
|
||||
<strong></strong>Unu<strong></strong>. I use a Markdown variation with fenced code blocks.
|
||||
The tool I wrote in C to extract these is called <span class="tt">unu</span>. For
|
||||
a self hosting RETRO, I rewrote this as a combinator that
|
||||
reads in a file and runs another word against each line in the
|
||||
file. So I could display the code block contents by doing:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'filename [ s:put nl ] unu</tt>
|
||||
<br/><br/>
|
||||
This made it easier to implement the other tools.
|
||||
<br/><br/>
|
||||
<strong></strong>Muri<strong></strong>. This is my assembler. It's minimalistic, fast, and
|
||||
works really well for my purposes. RETRO includes a runtime
|
||||
version of this (using <span class="tt">as{</span>, <span class="tt">}as</span>, <span class="tt">i</span>, <span class="tt">d</span>, and <span class="tt">r</span>), so
|
||||
all I needed for this was to write a few words to parse the
|
||||
lines and run the corresponding runtime words. As with the C
|
||||
version, this is a two pass assembler.
|
||||
<br/><br/>
|
||||
Muri generates a new <span class="tt">ngaImage</span> with the kernel. To create a
|
||||
full image I needed a way to load in the standard library and
|
||||
I/O extensions.
|
||||
<br/><br/>
|
||||
This is handled by <strong></strong>retro-extend<strong></strong>. This is where it gets
|
||||
more complex. I implemented the Nga virtual machine in RETRO
|
||||
to allow this to run the new image in isolation from the
|
||||
host image. The new ngaImage is loaded, the interpreter is
|
||||
located, and each token is passed to the interpreter. Once
|
||||
done, the new image is written to disk.
|
||||
<br/><br/>
|
||||
So at this point I'm pleased to say that I can now develop
|
||||
RETRO using only an existing copy of RETRO (VM+image) and
|
||||
tools (unu, muri, retro-extend, and a line oriented text
|
||||
editor) written in RETRO.
|
||||
<br/><br/>
|
||||
This project has delivered some additional side benefits.
|
||||
During the testing I was able to use it to identify a few
|
||||
bugs in the I/O extensions, and the Nga-in-RETRO will replace
|
||||
the older attempt at this in the debugger, allowing a safer
|
||||
testing environment.
|
||||
<br/><br/>
|
||||
What issues remain?
|
||||
<br/><br/>
|
||||
The extend process is <strong>slow</strong>. On my main development server
|
||||
(Linode 1024, OpenBSD 6.4, 64-bit) it takes a bit over five
|
||||
minutes to complete loading the standard library, and a few
|
||||
additional depending on the I/O drivers selected.
|
||||
<br/><br/>
|
||||
Most of the performance issues come from running Nga-in-RETRO
|
||||
to isolate the new image from the host one. It'd be possible
|
||||
to do something a bit more clever (e.g., running a RETRO
|
||||
instance using the new image via a subprocess and piping in
|
||||
the source, or doing relocations of the data), but this is
|
||||
less error prone and will work on all systems that I plan to
|
||||
support (including, with a few minor adjustments, the native
|
||||
hardware versions [assuming the existance of mass storage]).
|
||||
<br/><br/>
|
||||
Sources:
|
||||
<br/><br/>
|
||||
<strong></strong>Unu<strong></strong>
|
||||
<br/><br/>
|
||||
• http://forth.works/c8820f85e0c52d32c7f9f64c28f435c0<br/>
|
||||
• gopher://forth.works/0/c8820f85e0c52d32c7f9f64c28f435c0<br/>
|
||||
<br/><br/>
|
||||
<strong></strong>Muri<strong></strong>
|
||||
<br/><br/>
|
||||
• http://forth.works/09d6c4f3f8ab484a31107dca780058e3<br/>
|
||||
• gopher://forth.works/0/09d6c4f3f8ab484a31107dca780058e3<br/>
|
||||
<br/><br/>
|
||||
<strong></strong>retro-extend<strong></strong>
|
||||
<br/><br/>
|
||||
• http://forth.works/c812416f397af11db58e97388a3238f2<br/>
|
||||
• gopher://forth.works/0/c812416f397af11db58e97388a3238f2<br/>
|
||||
</p>
|
||||
</body></html>
|
||||
96
doc/html/chapters/tech-notes/underscores-in-names.html
Normal file
96
doc/html/chapters/tech-notes/underscores-in-names.html
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h3">On The Use Of Underscores In Word Names</span>
|
||||
<br/><br/>
|
||||
In brief: don't use underscores in word names.
|
||||
<br/><br/>
|
||||
There is a good reason for this, and it has to do with how RETRO
|
||||
processes strings. By default, underscores in strings are replaced
|
||||
by spaces. This is problematic when dealing with words like <span class="tt">var</span>,
|
||||
<span class="tt">const</span>, and <span class="tt">d:create</span> which take word names as strings.
|
||||
<br/><br/>
|
||||
Consider:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:hello_msg 'hello_user ;</tt>
|
||||
<tt class='indentedcode'>'test_name var</tt>
|
||||
<tt class='indentedcode'>#188 !test_name</tt>
|
||||
<br/><br/>
|
||||
In the first case, the <span class="tt">:</span> prefix handles the token, so the
|
||||
underscore is not remapped to a space, creating a word name as
|
||||
<span class="tt">hello_msg</span>. But in the second, the <span class="tt">'</span> prefix remaps the
|
||||
underscore to a space, giving a variable name of <span class="tt">test name</span>.
|
||||
In the third line, the name lookup will fail as <span class="tt">test_name</span> is
|
||||
not defined, so the store will be done to an incorrect address.
|
||||
<br/><br/>
|
||||
Because of this, it's best to avoid underscores in names.
|
||||
<br/><br/>
|
||||
Having covered this, if you do need to use them for some reason,
|
||||
you can replace <span class="tt">d:add-header</span> with a version that remaps spaces
|
||||
back to underscores before creating the header. The following
|
||||
will allow for this.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>{{</tt>
|
||||
<tt class='indentedcode'> :fields @Dictionary , (link) , (xt) , (class) ;</tt>
|
||||
<tt class='indentedcode'> :invalid-name? dup ASCII:SPACE s:contains-char? ;</tt>
|
||||
<tt class='indentedcode'> :rewrite [ ASCII:SPACE [ $_ ] case ] s:map ;</tt>
|
||||
<tt class='indentedcode'> :entry here &call dip !Dictionary ;</tt>
|
||||
<tt class='indentedcode'> [ [ fields invalid-name? &rewrite if s, (name) ] entry ]</tt>
|
||||
<tt class='indentedcode'>}}</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#1793 &d:add-header store</tt>
|
||||
<tt class='indentedcode'>&d:add-header n:inc store</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
Additional Note:
|
||||
<br/><br/>
|
||||
Some version of RETRO have included the above patch. The last
|
||||
release that will include this by default is 2020.4 as it is
|
||||
not needed by the majority of users. If you want to keep it in
|
||||
your system, you will need to load it yourself or add it to
|
||||
your <span class="tt">package/list.forth</span> (for Unix users) before building.
|
||||
</p>
|
||||
</body></html>
|
||||
154
doc/html/chapters/techniques/arrays.html
Normal file
154
doc/html/chapters/techniques/arrays.html
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Arrays</span>
|
||||
<br/><br/>
|
||||
RETRO offers a number of words for operating on statically sized
|
||||
arrays.
|
||||
<br/><br/>
|
||||
<span class="h2">Namespace</span>
|
||||
<br/><br/>
|
||||
The words operating on arrays are kept in an <span class="tt">a:</span> namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">Creating Arrays</span>
|
||||
<br/><br/>
|
||||
The easiest way to create an array is to wrap the values in a
|
||||
<span class="tt">{</span> and <span class="tt">}</span> pair:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='num'>#4</span> <span class='imm'>}</span> </span><br/>
|
||||
<span class="tt"><span class='imm'>{</span> <span class='str'>'this</span> <span class='str'>'is</span> <span class='str'>'an</span> <span class='str'>'array</span> <span class='str'>'of</span> <span class='str'>'strings</span> <span class='imm'>}</span> </span><br/>
|
||||
<span class="tt"><span class='imm'>{</span> <span class='str'>'this</span> <span class='str'>'is</span> <span class='str'>'a</span> <span class='str'>'mixed</span> <span class='str'>'array</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='imm'>}</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
You can also make an array from a quotation which returns
|
||||
values and the number of values to store in the a:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>[</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='num'>#3</span> <span class='imm'>]</span> a:counted-results </span><br/>
|
||||
<span class="tt"><span class='imm'>[</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='num'>#3</span> <span class='imm'>]</span> a:make </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Accessing Elements</span>
|
||||
<br/><br/>
|
||||
You can access a specific value with <span class="tt">a:th</span> and <span class="tt">fetch</span> or
|
||||
<span class="tt">store</span>:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='num'>#4</span> <span class='imm'>}</span> <span class='num'>#3</span> a:th <span class='prim'>fetch</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Find The Length</span>
|
||||
<br/><br/>
|
||||
Use <span class="tt">a:length</span> to find the size of the array.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='num'>#4</span> <span class='imm'>}</span> a:length </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Duplicate</span>
|
||||
<br/><br/>
|
||||
Use <span class="tt">a:dup</span> to make a copy of an a:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='num'>#4</span> <span class='imm'>}</span> a:dup </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Filtering</span>
|
||||
<br/><br/>
|
||||
RETRO provides <span class="tt">a:filter</span> which extracts matching values
|
||||
from an array. This is used like:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='num'>#4</span> <span class='num'>#5</span> <span class='num'>#6</span> <span class='num'>#7</span> <span class='num'>#8</span> <span class='imm'>}</span> <span class='imm'>[</span> n:even? <span class='imm'>]</span> a:filter </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
The quote will be passed each value in the array and should
|
||||
return TRUE or FALSE. Values that lead to TRUE will be collected
|
||||
into a new array.
|
||||
<br/><br/>
|
||||
<span class="h2">Mapping</span>
|
||||
<br/><br/>
|
||||
<span class="tt">a:map</span> applies a quotation to each item in an array and
|
||||
constructs a new array from the returned values.
|
||||
<br/><br/>
|
||||
Example:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='imm'>}</span> <span class='imm'>[</span> <span class='num'>#10</span> <span class='prim'>*</span> <span class='imm'>]</span> a:map </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Reduce</span>
|
||||
<br/><br/>
|
||||
<span class="tt">a:reduce</span> takes an array, a starting value, and a quote. It
|
||||
executes the quote once for each item in the array, passing the
|
||||
item and the value to the quote. The quote should consume both
|
||||
and return a new value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='imm'>}</span> <span class='num'>#0</span> <span class='imm'>[</span> <span class='prim'>+</span> <span class='imm'>]</span> a:reduce </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Search</span>
|
||||
<br/><br/>
|
||||
RETRO provides <span class="tt">a:contains?</span> and <span class="tt">a:contains-string?</span>
|
||||
to search an array for a value (either a number or string) and
|
||||
return either TRUE or FALSE.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#100</span> <span class='imm'>{</span> <span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='imm'>}</span> a:contains? </span><br/>
|
||||
<span class="tt"><span class='str'>'test</span> <span class='imm'>{</span> <span class='str'>'abc</span> <span class='str'>'def</span> <span class='str'>'test</span> <span class='str'>'ghi</span> <span class='imm'>}</span> a:contains-string? </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Implementation</span>
|
||||
<br/><br/>
|
||||
In memory, an array is a count followed by the values. As an
|
||||
example, if you have an array:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>{ #10 #20 #30 }</tt>
|
||||
<br/><br/>
|
||||
In memory this would be setup as:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Offset | Value |</tt>
|
||||
<tt class='indentedcode'>| ------ | ----- |</tt>
|
||||
<tt class='indentedcode'>| 000 | 3 |</tt>
|
||||
<tt class='indentedcode'>| 001 | 10 |</tt>
|
||||
<tt class='indentedcode'>| 002 | 20 |</tt>
|
||||
<tt class='indentedcode'>| 003 | 30 |</tt>
|
||||
<br/><br/>
|
||||
You can construct one on the fly by keeping a pointer to
|
||||
<span class="tt">here</span> and using <span class="tt">,</span> to place the values. E.g.,
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>here [ #3 , #10 , #20 , #30 , ] dip</tt>
|
||||
<br/><br/>
|
||||
An example of this can be seen in this excerpt from an example
|
||||
(<strong>example/Primes.forth</strong>):
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:create-set (-a) </tt>
|
||||
<tt class='indentedcode'> here #3000 , #2 #3002 [ dup , n:inc ] times drop ;</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
165
doc/html/chapters/techniques/assembly.html
Normal file
165
doc/html/chapters/techniques/assembly.html
Normal file
|
|
@ -0,0 +1,165 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Assembly Language</span>
|
||||
<br/><br/>
|
||||
RETRO runs on a virtual machine called Nga. It provides a
|
||||
standard assembler for this called <strong>Muri</strong>.
|
||||
<br/><br/>
|
||||
Muri is a simple, multipass model that's not fancy, but
|
||||
suffices for RETRO's needs.
|
||||
<br/><br/>
|
||||
<span class="h2">Assembling A Standalone File</span>
|
||||
<br/><br/>
|
||||
A small example (<strong>test.muri</strong>)
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>i liju....</tt>
|
||||
<tt class='indentedcode'>r main</tt>
|
||||
<tt class='indentedcode'>: c:put</tt>
|
||||
<tt class='indentedcode'>i liiire..</tt>
|
||||
<tt class='indentedcode'>i 0</tt>
|
||||
<tt class='indentedcode'>: main</tt>
|
||||
<tt class='indentedcode'>i lilica..</tt>
|
||||
<tt class='indentedcode'>d 97</tt>
|
||||
<tt class='indentedcode'>i liju....</tt>
|
||||
<tt class='indentedcode'>r main</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
Assembling it:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-muri test.muri</tt>
|
||||
<br/><br/>
|
||||
So breaking down: Muri extracts the assembly code blocks to
|
||||
assemble, then proceeds to do the assembly. Each source line
|
||||
starts with a directive, followed by a space, and then ending
|
||||
with a value.
|
||||
<br/><br/>
|
||||
The directives are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>: value is a label</tt>
|
||||
<tt class='indentedcode'>i value is an instruction bundle</tt>
|
||||
<tt class='indentedcode'>d value is a numeric value</tt>
|
||||
<tt class='indentedcode'>r value is a reference</tt>
|
||||
<tt class='indentedcode'>s value is a string to inline</tt>
|
||||
<br/><br/>
|
||||
Instructions for Nga are provided as bundles. Each memory
|
||||
location can store up to four instructions. And each instruction
|
||||
gets a two character identifier.
|
||||
<br/><br/>
|
||||
From the list of instructions:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>0 nop 5 push 10 ret 15 fetch 20 div 25 zret</tt>
|
||||
<tt class='indentedcode'>1 lit 6 pop 11 eq 16 store 21 and 26 halt</tt>
|
||||
<tt class='indentedcode'>2 dup 7 jump 12 neq 17 add 22 or 27 ienum</tt>
|
||||
<tt class='indentedcode'>3 drop 8 call 13 lt 18 sub 23 xor 28 iquery</tt>
|
||||
<tt class='indentedcode'>4 swap 9 ccall 14 gt 19 mul 24 shift 29 iinvoke</tt>
|
||||
<br/><br/>
|
||||
This reduces to:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>0 .. 5 pu 10 re 15 fe 20 di 25 zr</tt>
|
||||
<tt class='indentedcode'>1 li 6 po 11 eq 16 st 21 an 26 ha</tt>
|
||||
<tt class='indentedcode'>2 du 7 ju 12 ne 17 ad 22 or 27 ie</tt>
|
||||
<tt class='indentedcode'>3 dr 8 ca 13 lt 18 su 23 xo 28 iq</tt>
|
||||
<tt class='indentedcode'>4 sw 9 cc 14 gt 19 mu 24 sh 29 ii</tt>
|
||||
<br/><br/>
|
||||
Most are just the first two letters of the instruction name. I
|
||||
use <span class="tt">..</span> instead of <span class="tt">no</span> for <span class="tt">NOP</span>, and the first letter of
|
||||
each I/O instruction name. So a bundle may look like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>dumure..</tt>
|
||||
<br/><br/>
|
||||
(This would correspond to <span class="tt">dup multiply return nop</span>).
|
||||
<br/><br/>
|
||||
<span class="h2">Runtime Assembler</span>
|
||||
<br/><br/>
|
||||
RETRO also has a runtime variation of Muri that can be used
|
||||
when you need to generate more optimal code. So one can write:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:n:square dup * ;</tt>
|
||||
<br/><br/>
|
||||
Or:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:n:square \dumure.. ;</tt>
|
||||
<br/><br/>
|
||||
The second one will be faster, as the entire definition is one
|
||||
bundle, which reduces memory reads and decoding by 2/3.
|
||||
<br/><br/>
|
||||
Doing this is less readable, so I only recommend doing so after
|
||||
you have finalized working RETRO level code and determined the
|
||||
best places to optimize.
|
||||
<br/><br/>
|
||||
The runtime assembler has the following directives:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>i value is an instruction bundle</tt>
|
||||
<tt class='indentedcode'>d value is a numeric value</tt>
|
||||
<tt class='indentedcode'>r value is a reference</tt>
|
||||
<br/><br/>
|
||||
Additionally, in the runtime assembler, these are reversed:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'dudumu.. i</tt>
|
||||
<br/><br/>
|
||||
Instead of:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>i dudumu..</tt>
|
||||
<br/><br/>
|
||||
The runtime assembler also provides three prefixes for use in
|
||||
inlining machine code into a definition. These are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> \ Treat token as an assembly sequence</tt>
|
||||
<tt class='indentedcode'> ` Treat token as a numeric value</tt>
|
||||
<tt class='indentedcode'> ^ Treat token as a reference</tt>
|
||||
<br/><br/>
|
||||
E.g., instead of doing something like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:n:square as{ 'dumu.... i }as ;</tt>
|
||||
<tt class='indentedcode'>:test as{ 'lilica.... i #22 d 'n:square r }as ;</tt>
|
||||
<br/><br/>
|
||||
Just write:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:n:square \dumu.... ;</tt>
|
||||
<tt class='indentedcode'>:test \lilica.. `22 ^n:square ; </tt>
|
||||
</p>
|
||||
</body></html>
|
||||
186
doc/html/chapters/techniques/buffer.html
Normal file
186
doc/html/chapters/techniques/buffer.html
Normal file
|
|
@ -0,0 +1,186 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With a Buffer</span>
|
||||
<br/><br/>
|
||||
RETRO provides words for operating on a linear memory area.
|
||||
This can be useful in building strings or custom data
|
||||
structures.
|
||||
<br/><br/>
|
||||
<span class="h2">Namespace</span>
|
||||
<br/><br/>
|
||||
Words operating on the buffer are kept in the <span class="tt">buffer:</span>
|
||||
namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">Implementation</span>
|
||||
<br/><br/>
|
||||
A buffer is a linear sequence of memory. The buffer words
|
||||
provide a means of incrementally storing and retrieving
|
||||
values from it.
|
||||
<br/><br/>
|
||||
The buffer words keep track of the start and end of the
|
||||
buffer. They also ensure that an <span class="tt">ASCII:NULL</span> is written
|
||||
after the last value, which make using them for string
|
||||
data easy.
|
||||
<br/><br/>
|
||||
<span class="h2">Limitations</span>
|
||||
<br/><br/>
|
||||
Only one buffer can be active at a time. RETRO provides a
|
||||
<span class="tt">buffer:preserve</span> combinator to allow using a second one
|
||||
before returning to the prior one.
|
||||
<br/><br/>
|
||||
<span class="h2">Set The Active Buffer</span>
|
||||
<br/><br/>
|
||||
To set a buffer as the active one use <span class="tt">buffer:set</span>. This takes
|
||||
an address.
|
||||
<br/><br/>
|
||||
The buffer will be assumed to be empty. The initial value will
|
||||
be set to ASCII:NULL.
|
||||
<br/><br/>
|
||||
<span class="h2">Add Value</span>
|
||||
<br/><br/>
|
||||
Use <span class="tt">buffer:add</span> 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.
|
||||
<br/><br/>
|
||||
<span class="h2">Fetch Last Value</span>
|
||||
<br/><br/>
|
||||
To return the last value in the buffer you can use <span class="tt">buffer:get</span>.
|
||||
This removes the value and sets an ASCII:NULL in the memory
|
||||
location the returned value occupied.
|
||||
<br/><br/>
|
||||
<span class="h2">Get Data About The Buffer</span>
|
||||
<br/><br/>
|
||||
RETRO provides <span class="tt">buffer:start</span> to get the initial address in
|
||||
the buffer, <span class="tt">buffer:end</span> to get the last address (ignoring the
|
||||
ASCII:NULL), and <span class="tt">buffer:size</span> to return the number of values
|
||||
in the buffer.
|
||||
<br/><br/>
|
||||
<span class="h2">Reset</span>
|
||||
<br/><br/>
|
||||
You can reset a buffer to the empty state using <span class="tt">buffer:empty</span>.
|
||||
<br/><br/>
|
||||
<span class="h2">Example</span>
|
||||
<br/><br/>
|
||||
To begin, create a memory region to use as a buffer.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'Test</span> d:create <span class='num'>#1025</span> allot </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Then you can set this as the current buffer:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='ptr'>&Test</span> buffer:set </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
When a buffer is set, the vocabulary sets an internal
|
||||
index to the first address in it. This will be
|
||||
incremented when you add data and decremented when you
|
||||
remove data.
|
||||
<br/><br/>
|
||||
Let's add some stuff using <span class="tt">buffer:add</span>:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#100</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='num'>#200</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='num'>#300</span> buffer:add </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
And then retrieve the values:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">buffer:get n:put nl </span><br/>
|
||||
<span class="tt">buffer:get n:put nl </span><br/>
|
||||
<span class="tt">buffer:get n:put nl </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
You can remove all values using <span class="tt">buffer:empty</span>:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#100</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='num'>#200</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='num'>#300</span> buffer:add </span><br/>
|
||||
<span class="tt">buffer:empty </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
And ask the buffer how many items it contains:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">buffer:size n:put nl </span><br/>
|
||||
<span class="tt"><span class='num'>#100</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='num'>#200</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='num'>#300</span> buffer:add </span><br/>
|
||||
<span class="tt">buffer:size n:put nl </span><br/>
|
||||
<span class="tt">buffer:empty </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
The other functions are <span class="tt">buffer:start</span>, which returns
|
||||
the address of the buffer, <span class="tt">buffer:end</span>, which returns
|
||||
the address of the last value, and <span class="tt">buffer:preserve</span>.
|
||||
The first is easy to demo:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">buffer:start Test <span class='prim'>eq?</span> n:put nl </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
The last one is useful. Only one buffer is ever active
|
||||
at a given time. The <span class="tt">buffer:preserve</span> combinator lets
|
||||
you execute a word, saving and restoring the current
|
||||
buffer indexes. So the word could assign and use a new
|
||||
buffer and this will reset the previous one after
|
||||
control returns.
|
||||
<br/><br/>
|
||||
There are a few notes that need to be considered. The
|
||||
preserve combinator saves the start and current index
|
||||
but <strong>not</strong> the contents. If the word you call uses the
|
||||
same buffer, the contents will remain altered.
|
||||
<br/><br/>
|
||||
Finally, the buffer words have one interesting trait:
|
||||
they store an ASCII NULL after adding each item to the
|
||||
buffer. This lets one use them to build strings easily.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">Test buffer:set </span><br/>
|
||||
<span class="tt"><span class='char'>$h</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$e</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$l</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$l</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$o</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$,</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='num'>#32</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$w</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$o</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$r</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$l</span> buffer:add </span><br/>
|
||||
<span class="tt"><span class='char'>$d</span> buffer:add </span><br/>
|
||||
<span class="tt">buffer:start s:put nl </span><br/>
|
||||
<span class="tt">```</span></span></p>
|
||||
</body></html>
|
||||
110
doc/html/chapters/techniques/characters.html
Normal file
110
doc/html/chapters/techniques/characters.html
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Characters</span>
|
||||
<br/><br/>
|
||||
RETRO provides words for working with ASCII characters.
|
||||
<br/><br/>
|
||||
<span class="h2">Prefix</span>
|
||||
<br/><br/>
|
||||
Character constants are returned using the <span class="tt">$</span> prefix.
|
||||
<br/><br/>
|
||||
<span class="h2">Namespace</span>
|
||||
<br/><br/>
|
||||
Words operating on characters are in the <span class="tt">c:</span> namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">Classification</span>
|
||||
<br/><br/>
|
||||
RETRO provides a number of words to determine if a character
|
||||
fits into predefined groups.
|
||||
<br/><br/>
|
||||
The primary words for this are:
|
||||
<br/><br/>
|
||||
• <span class="tt">c:consonant?</span><br/>
|
||||
• <span class="tt">c:digit?</span><br/>
|
||||
• <span class="tt">c:letter?</span><br/>
|
||||
• <span class="tt">c:lowercase?</span><br/>
|
||||
• <span class="tt">c:uppercase?</span><br/>
|
||||
• <span class="tt">c:visible?</span><br/>
|
||||
• <span class="tt">c:vowel?</span><br/>
|
||||
• <span class="tt">c:whitespace?</span><br/>
|
||||
<br/><br/>
|
||||
There are also corresponding "not" forms:
|
||||
<br/><br/>
|
||||
• <span class="tt">c:-consonant?</span><br/>
|
||||
• <span class="tt">c:-digit?</span><br/>
|
||||
• <span class="tt">c:-lowercase?</span><br/>
|
||||
• <span class="tt">c:-uppercase?</span><br/>
|
||||
• <span class="tt">c:-visible?</span><br/>
|
||||
• <span class="tt">c:-vowel?</span><br/>
|
||||
• <span class="tt">c:-whitespace?</span><br/>
|
||||
<br/><br/>
|
||||
All of these take a character and return either a <span class="tt">TRUE</span> or
|
||||
<span class="tt">FALSE</span> flag.
|
||||
<br/><br/>
|
||||
<span class="h2">Conversions</span>
|
||||
<br/><br/>
|
||||
A few words are provided to convert case. Each takes a character
|
||||
and returns the modified character.
|
||||
<br/><br/>
|
||||
• <span class="tt">c:to-lower</span><br/>
|
||||
• <span class="tt">c:to-number</span><br/>
|
||||
• <span class="tt">c:to-upper</span><br/>
|
||||
• <span class="tt">c:toggle-case</span><br/>
|
||||
<br/><br/>
|
||||
RETRO also has <span class="tt">c:to-string</span>, which takes a character and
|
||||
creates a new temporary string with the character.
|
||||
<br/><br/>
|
||||
<span class="h2">I/O</span>
|
||||
<br/><br/>
|
||||
Characters can be displayed using <span class="tt">c:put</span>.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='char'>$a</span> c:put </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
With the default system on BSD, Linux, and macOS (and other
|
||||
Unix style hosts), <span class="tt">c:get</span> is provided to read input. This
|
||||
may be buffered, depending on the host.
|
||||
</p>
|
||||
</body></html>
|
||||
69
doc/html/chapters/techniques/checking-the-version.html
Normal file
69
doc/html/chapters/techniques/checking-the-version.html
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Checking The Version</span>
|
||||
<br/><br/>
|
||||
RETRO releases add and change things. You can use the <span class="tt">Version</span>
|
||||
variable to determine the version in use and react accordingly.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='fetch'>@Version</span> <span class='num'>#201906</span> <span class='prim'>eq?</span> <span class='imm'>[</span> <span class='str'>'Needs_2019.6!</span> s:put nl bye <span class='imm'>]</span> <span class='prim'>if</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
This can be also be used to conditionally load compatibility files:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='note'>(If_newer_than_2016.6,_load_aliases_for_renamed_words)</span> </span><br/>
|
||||
<span class="tt"><span class='fetch'>@Version</span> <span class='num'>#201906</span> <span class='prim'>gt?</span> <span class='imm'>[</span> <span class='str'>'Renamed_2019.6.forth</span> include <span class='imm'>]</span> <span class='prim'>if</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Version Number Format</span>
|
||||
<br/><br/>
|
||||
The version is a six digit number encoding the year and month of
|
||||
the release. So:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>201901 is 2019.1</tt>
|
||||
<tt class='indentedcode'>201906 is 2019.6</tt>
|
||||
<tt class='indentedcode'>201911 is 2019.11</tt>
|
||||
<br/><br/>
|
||||
A <span class="tt">#100 /mod</span> will suffice to split these if needed.
|
||||
</p>
|
||||
</body></html>
|
||||
57
doc/html/chapters/techniques/definitions.html
Normal file
57
doc/html/chapters/techniques/definitions.html
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Defining Words</span>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
E.g.,
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:do-nothing ;</tt>
|
||||
<tt class='indentedcode'>:square dup * ;</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
148
doc/html/chapters/techniques/dictionary.html
Normal file
148
doc/html/chapters/techniques/dictionary.html
Normal file
|
|
@ -0,0 +1,148 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With The Dictionary</span>
|
||||
<br/><br/>
|
||||
The Dictionary is a linked list containing the dictionary
|
||||
headers.
|
||||
<br/><br/>
|
||||
<span class="h2">Namespace</span>
|
||||
<br/><br/>
|
||||
Words operating on the dictionary are in the <span class="tt">d:</span> namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">Variables</span>
|
||||
<br/><br/>
|
||||
<span class="tt">Dictionary</span> is a variable holding a pointer to the most recent
|
||||
header.
|
||||
<br/><br/>
|
||||
<span class="h2">Header Structure</span>
|
||||
<br/><br/>
|
||||
Each entry follows the following structure:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Offset Contains</tt>
|
||||
<tt class='indentedcode'>------ ---------------------------</tt>
|
||||
<tt class='indentedcode'>0000 Link to Prior Header</tt>
|
||||
<tt class='indentedcode'>0001 Link to XT</tt>
|
||||
<tt class='indentedcode'>0002 Link to Class Handler</tt>
|
||||
<tt class='indentedcode'>0003+ Word name (null terminated)</tt>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
<span class="h2">Accessing Fields</span>
|
||||
<br/><br/>
|
||||
Given a pointer to a header, you can use <span class="tt">d:xt</span>, <span class="tt">d:class</span>,
|
||||
and <span class="tt">d:name</span> to access the address of each specific field.
|
||||
There is no <span class="tt">d:link</span>, as the link will always be the first
|
||||
field.
|
||||
<br/><br/>
|
||||
<span class="h2">Shortcuts For The Latest Header</span>
|
||||
<br/><br/>
|
||||
RETRO provides several words for operating on the most recent
|
||||
header.
|
||||
<br/><br/>
|
||||
<span class="tt">d:last</span> returns a pointer to the latest header. <span class="tt">d:last.xt</span>
|
||||
will give the contents of the <span class="tt">d:xt</span> field for the latest
|
||||
header. There are also <span class="tt">d:last.class</span> and <span class="tt">d:last.name</span>.
|
||||
<br/><br/>
|
||||
<span class="h2">Adding Headers</span>
|
||||
<br/><br/>
|
||||
Two words exist for making new headers. The easy one is
|
||||
<span class="tt">d:create</span>. This takes a string for the name and makes a
|
||||
new header with the class set to <span class="tt">class:data</span> and the XT
|
||||
field pointing to <span class="tt">here</span>.
|
||||
<br/><br/>
|
||||
Example:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'Base</span> d:create </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
The other is <span class="tt">d:add-header</span>. This takes a string, a pointer
|
||||
to the class handler, and a pointer for the XT field and
|
||||
builds a new header using these.
|
||||
<br/><br/>
|
||||
Example:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'Base</span> <span class='ptr'>&class:data</span> <span class='num'>#10000</span> d:add-header </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Searching</span>
|
||||
<br/><br/>
|
||||
RETRO provides two words for searching the dictionary.
|
||||
<br/><br/>
|
||||
<span class="tt">d:lookup</span> takes a string and tries to find it in the
|
||||
dictionary. It will return a pointer to the dictionary header
|
||||
or a value of zero if the word was not found.
|
||||
<br/><br/>
|
||||
<span class="tt">d:lookup-xt</span> takes a pointer and will return the dictionary
|
||||
header that has this as the <span class="tt">d:xt</span> field, or zero if no match
|
||||
is found.
|
||||
<br/><br/>
|
||||
<span class="h2">Iteration</span>
|
||||
<br/><br/>
|
||||
You can use the <span class="tt">d:for-each</span> combinator to iterate over all
|
||||
entries in the dictionary. For instance, to display the names
|
||||
of all words:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>[</span> d:name s:put sp <span class='imm'>]</span> d:for-each </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
For each entry, this combinator will push a pointer to the
|
||||
entry to the stack and call the quotation.
|
||||
<br/><br/>
|
||||
<span class="h2">Listing Words</span>
|
||||
<br/><br/>
|
||||
Most Forth systems provide WORDS for listing the names of all
|
||||
words in the dictionary. RETRO does as well, but this is named
|
||||
<span class="tt">d:words</span>.
|
||||
<br/><br/>
|
||||
This isn't super useful as looking through several hundred
|
||||
names is annoying. RETRO also provides <span class="tt">d:words-with</span> to help
|
||||
in filtering the results.
|
||||
<br/><br/>
|
||||
Example:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'class:</span> d:words-with </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
</p>
|
||||
</body></html>
|
||||
81
doc/html/chapters/techniques/errors.html
Normal file
81
doc/html/chapters/techniques/errors.html
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Errors</span>
|
||||
<br/><br/>
|
||||
RETRO does only minimal error checking.
|
||||
<br/><br/>
|
||||
<span class="h2">Non-Fatal</span>
|
||||
<br/><br/>
|
||||
A non-fatal error will be reported on <strong>word not found</strong> during
|
||||
interactive or compile time. Note that this only applies to
|
||||
calls: if you try to get a pointer to an undefined word, the
|
||||
returned pointer will be zero.
|
||||
<br/><br/>
|
||||
<span class="h2">Fatal</span>
|
||||
<br/><br/>
|
||||
A number of conditions are known to cause fatal errors. The
|
||||
main ones are stack overflow, stack underflow, and division
|
||||
by zero.
|
||||
<br/><br/>
|
||||
On these, RETRO will generally exit. For stack depth issues,
|
||||
the VM will attempt to display an error prior to exiting.
|
||||
<br/><br/>
|
||||
In some cases, the VM may get stuck in an endless loop. If this
|
||||
occurs, try using CTRL+C to kill the process, or kill it using
|
||||
whatever means your host system provides.
|
||||
<br/><br/>
|
||||
<span class="h2">Rationale</span>
|
||||
<br/><br/>
|
||||
Error checks are useful, but slow - especially on a minimal
|
||||
system like RETRO. The overhead of doing depth or other checks
|
||||
adds up quickly.
|
||||
<br/><br/>
|
||||
As an example, adding a depth check to <span class="tt">drop</span> increases the
|
||||
time to use it 250,000 times in a loop from 0.16 seconds to
|
||||
1.69 seconds.
|
||||
<br/><br/>
|
||||
</p>
|
||||
</body></html>
|
||||
212
doc/html/chapters/techniques/files.html
Normal file
212
doc/html/chapters/techniques/files.html
Normal file
|
|
@ -0,0 +1,212 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Files</span>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
The file words are in the <span class="tt">file:</span> namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">File Access Modes</span>
|
||||
<br/><br/>
|
||||
You can open a file for various operations. The functionality
|
||||
allowed depends on the file access mode. Valid modes in RETRO
|
||||
are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>file:A Open for appending; file pointer set to end of file</tt>
|
||||
<tt class='indentedcode'>file:R Open for reading; file pointer set to start of file</tt>
|
||||
<tt class='indentedcode'>file:R+ Open for reading and writing</tt>
|
||||
<tt class='indentedcode'>file:W Open for writing</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Opening A File</span>
|
||||
<br/><br/>
|
||||
To open a file, pass the file name and a file mode to <span class="tt">file:open</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'/etc/motd file:R file:open</tt>
|
||||
<br/><br/>
|
||||
On a successful open this will return a file handle greater than
|
||||
zero.
|
||||
<br/><br/>
|
||||
Additionally, RETRO provides a few other forms for opening files.
|
||||
<br/><br/>
|
||||
To open a file for reading:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'/etc/motd file:open-for-reading</tt>
|
||||
<br/><br/>
|
||||
This will return the size of the file (as NOS) and the file handle
|
||||
(as TOS).
|
||||
<br/><br/>
|
||||
To open a file for writing:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'/tmp/test file:open-for-writing</tt>
|
||||
<br/><br/>
|
||||
This returns the file handle.
|
||||
<br/><br/>
|
||||
To open a file for append operations:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'/tmp/test file:open-for-append</tt>
|
||||
<br/><br/>
|
||||
As with <span class="tt">file:open-for-reading</span>, this returns both the size of
|
||||
the file and the file handle.
|
||||
<br/><br/>
|
||||
<span class="h2">Closing A File</span>
|
||||
<br/><br/>
|
||||
To close a file, pass the file handle to <span class="tt">file:close</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'/etc/motd file:A file:open file:close</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Reading From A File</span>
|
||||
<br/><br/>
|
||||
To read a byte from an open file, pass the file handle to the
|
||||
<span class="tt">file:read</span> word.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>@FID file:read n:put</tt>
|
||||
<br/><br/>
|
||||
To read a line from a file, pass the file handle to the word
|
||||
<span class="tt">file:read-line</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>@FID file:read-line s:put</tt>
|
||||
<br/><br/>
|
||||
The line is read into a temporary string buffer. Move the
|
||||
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.
|
||||
<br/><br/>
|
||||
<span class="h2">Writing To A File</span>
|
||||
<br/><br/>
|
||||
To write a byte to a file, pass it and the file handle to
|
||||
<span class="tt">file:write</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>$h @FID file:write</tt>
|
||||
<tt class='indentedcode'>$e @FID file:write</tt>
|
||||
<tt class='indentedcode'>$l @FID file:write</tt>
|
||||
<tt class='indentedcode'>$l @FID file:write</tt>
|
||||
<tt class='indentedcode'>$o @FID file:write</tt>
|
||||
<br/><br/>
|
||||
Though cells are 32 or 64 bits in size, only the byte value will
|
||||
be written to the file.
|
||||
<br/><br/>
|
||||
<span class="h2">Deleting Files</span>
|
||||
<br/><br/>
|
||||
You can delete a file by passing the file name to <span class="tt">file:delete</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>/tmp/test file:delete</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Check For File Existance</span>
|
||||
<br/><br/>
|
||||
Use <span class="tt">file:exists?</span> to detect the existance of a file. Pass it a
|
||||
file name and it will return <span class="tt">TRUE</span> if existing or <span class="tt">FALSE</span> if
|
||||
it does not.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'/etc/motd file:exists?</tt>
|
||||
<br/><br/>
|
||||
This will also return <span class="tt">TRUE</span> if the filename is a directory.
|
||||
<br/><br/>
|
||||
<span class="h2">Flush Caches</span>
|
||||
<br/><br/>
|
||||
Use <span class="tt">file:flush</span> to flush the system caches for a file. Pass a
|
||||
file handle to this.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>@FID file:flush</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Seek A Position Within A File</span>
|
||||
<br/><br/>
|
||||
You can use <span class="tt">file:seek</span> to move the internal file pointer
|
||||
for a given file. Pass this the new location and a file.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#100 @FID file:seek</tt>
|
||||
<br/><br/>
|
||||
The location for the file pointer is a fixed offset from the
|
||||
start of the file, not a relative offset.
|
||||
<br/><br/>
|
||||
<span class="h2">Get The Current Position Within A File</span>
|
||||
<br/><br/>
|
||||
To find the current value of the file pointer within a file
|
||||
just pass the file handle to <span class="tt">file:tell</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>@FID file:tell</tt>
|
||||
<br/><br/>
|
||||
This returns a number that is the number of bytes into the file
|
||||
that the file pointer is currently at.
|
||||
<br/><br/>
|
||||
<span class="h2">Determine The Size Of A File</span>
|
||||
<br/><br/>
|
||||
Use <span class="tt">file:size</span> 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
|
||||
the file is a directory, it returns -1.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>@FID file:size</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Reading An Entire File</span>
|
||||
<br/><br/>
|
||||
If you want to read an entire file into memory you can use
|
||||
<span class="tt">file:slurp</span>. This takes the starting address of a memory
|
||||
region and the name of the file.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>here '/etc/motd file:slurp</tt>
|
||||
<br/><br/>
|
||||
Take care that the memory buffer is large enough for the file
|
||||
being read or you will run into problems.
|
||||
<br/><br/>
|
||||
<span class="h2">Writing A String To A File</span>
|
||||
<br/><br/>
|
||||
If you have a string that you want to write to a file, replacing
|
||||
any existing contents, you can use <span class="tt">file:spew</span>. This takes the
|
||||
string to write and a file name.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'hello_world '/tmp/test.txt file:spew</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Iterating Over A File, Line By Line</span>
|
||||
<br/><br/>
|
||||
You can easily iterate over each line in a file using the word
|
||||
<span class="tt">file:for-each-line</span>. This will take a file name and a quote,
|
||||
read each line into a temporary string, then pass this string to
|
||||
the quote.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'/etc/motd [ s:put nl ] file:for-each-line</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
224
doc/html/chapters/techniques/floating-point.html
Normal file
224
doc/html/chapters/techniques/floating-point.html
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Floating Point</span>
|
||||
<br/><br/>
|
||||
Some RETRO systems include support for floating point numbers.
|
||||
When present, this is built over the system <span class="tt">libm</span> using the
|
||||
C <span class="tt">double</span> type.
|
||||
<br/><br/>
|
||||
Floating point values are typically 64 bit IEEE 754 double
|
||||
precision (1 bit for the sign, 11 bits for the exponent, and
|
||||
the remaining 52 bits for the value), i.e. 15 decimal digits
|
||||
of precision.
|
||||
<br/><br/>
|
||||
<span class="h2">Prefix</span>
|
||||
<br/><br/>
|
||||
Floating point numbers start with a <span class="tt">.</span>
|
||||
<br/><br/>
|
||||
Examples:
|
||||
<br/><br/>
|
||||
Token Value
|
||||
<tt class='indentedcode'>.1 1.0</tt>
|
||||
<tt class='indentedcode'>.0.5 0.5</tt>
|
||||
<tt class='indentedcode'>.-.4 -0.4</tt>
|
||||
<tt class='indentedcode'>.1.3 1.3</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Namespace</span>
|
||||
<br/><br/>
|
||||
Floating point words are in the <span class="tt">f:</span> namespace. There is also
|
||||
a related <span class="tt">e:</span> namespace for <strong>encoded values</strong>, which allows
|
||||
storing of floats in standard memory.
|
||||
<br/><br/>
|
||||
<span class="h2">Operation</span>
|
||||
<br/><br/>
|
||||
Floating point values exist on a separate stack, and are bigger
|
||||
than the standard memory cells, so can not be directly stored
|
||||
and fetched from memory.
|
||||
<br/><br/>
|
||||
The floating point system also provides an alternate stack that
|
||||
can be used to temporarily store values.
|
||||
<br/><br/>
|
||||
The following words exist for arranging values on the floating
|
||||
point stack. These are direct analogs to the non-prefiexd words
|
||||
for dealing with the data stack.
|
||||
<br/><br/>
|
||||
• <span class="tt">f:nip</span><br/>
|
||||
• <span class="tt">f:over</span><br/>
|
||||
• <span class="tt">f:depth</span><br/>
|
||||
• <span class="tt">f:drop</span><br/>
|
||||
• <span class="tt">f:drop-pair</span><br/>
|
||||
• <span class="tt">f:dup</span><br/>
|
||||
• <span class="tt">f:dup-pair</span><br/>
|
||||
• <span class="tt">f:dump-stack</span><br/>
|
||||
• <span class="tt">f:tuck</span><br/>
|
||||
• <span class="tt">f:swap</span><br/>
|
||||
• <span class="tt">f:rot</span><br/>
|
||||
<br/><br/>
|
||||
For the secondary floating point stack, the following words are
|
||||
provided:
|
||||
<br/><br/>
|
||||
• <span class="tt">f:push</span><br/>
|
||||
• <span class="tt">f:pop</span><br/>
|
||||
• <span class="tt">f:adepth</span><br/>
|
||||
• <span class="tt">f:dump-astack</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Constants</span>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Name | Returns |</tt>
|
||||
<tt class='indentedcode'>| -------- | ----------------- |</tt>
|
||||
<tt class='indentedcode'>| `f:E` | Euler's number |</tt>
|
||||
<tt class='indentedcode'>| `f:-INF` | Negative infinity |</tt>
|
||||
<tt class='indentedcode'>| `f:INF` | Positive infinity |</tt>
|
||||
<tt class='indentedcode'>| `f:NAN` | Not a Number |</tt>
|
||||
<tt class='indentedcode'>| `f:PI` | PI |</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Comparisons</span>
|
||||
<br/><br/>
|
||||
The basic set of comparators are the same as those for
|
||||
operating on integers. These are:
|
||||
<br/><br/>
|
||||
• <span class="tt">f:-eq?</span><br/>
|
||||
• <span class="tt">f:between?</span><br/>
|
||||
• <span class="tt">f:eq?</span><br/>
|
||||
• <span class="tt">f:gt?</span><br/>
|
||||
• <span class="tt">f:lt?</span><br/>
|
||||
• <span class="tt">f:negative?</span><br/>
|
||||
• <span class="tt">f:positive?</span><br/>
|
||||
• <span class="tt">f:case</span><br/>
|
||||
<br/><br/>
|
||||
There are also a few additions for comparing to special values
|
||||
like infinity and NaN.
|
||||
<br/><br/>
|
||||
• <span class="tt">f:-inf?</span><br/>
|
||||
• <span class="tt">f:inf?</span><br/>
|
||||
• <span class="tt">f:nan?</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Basic Math</span>
|
||||
<br/><br/>
|
||||
• <span class="tt">f:*</span><br/>
|
||||
• <span class="tt">f:+</span><br/>
|
||||
• <span class="tt">f:-</span><br/>
|
||||
• <span class="tt">f:/</span><br/>
|
||||
• <span class="tt">f:abs</span><br/>
|
||||
• <span class="tt">f:floor</span><br/>
|
||||
• <span class="tt">f:inc</span><br/>
|
||||
• <span class="tt">f:limit</span><br/>
|
||||
• <span class="tt">f:max</span><br/>
|
||||
• <span class="tt">f:min</span><br/>
|
||||
• <span class="tt">f:negate</span><br/>
|
||||
• <span class="tt">f:power</span><br/>
|
||||
• <span class="tt">f:ceiling</span><br/>
|
||||
• <span class="tt">f:dec</span><br/>
|
||||
• <span class="tt">f:log</span><br/>
|
||||
• <span class="tt">f:sqrt</span><br/>
|
||||
• <span class="tt">f:square</span><br/>
|
||||
• <span class="tt">f:round</span><br/>
|
||||
• <span class="tt">f:sign</span><br/>
|
||||
• <span class="tt">f:signed-sqrt</span><br/>
|
||||
• <span class="tt">f:signed-square</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Geometry</span>
|
||||
<br/><br/>
|
||||
RETRO provides a small number of words for doing geometric
|
||||
related calculations.
|
||||
<br/><br/>
|
||||
| Word | Returns |
|
||||
| -------- | ------------ |
|
||||
| <span class="tt">f:acos</span> | arc cosine |
|
||||
| <span class="tt">f:asin</span> | arc sine |
|
||||
| <span class="tt">f:atan</span> | arc tangent |
|
||||
| <span class="tt">f:cos</span> | cosine |
|
||||
| <span class="tt">f:sin</span> | sine |
|
||||
| <span class="tt">f:tan</span> | tangent |
|
||||
<br/><br/>
|
||||
<span class="h2">Storage and Retrieval</span>
|
||||
<br/><br/>
|
||||
By leveraging the encoded value functions, RETRO is able to
|
||||
allow storage of floating point values in memory. This does
|
||||
have a tradeoff in accuracy as the memory cells are considerably
|
||||
smaller than a full floating point size.
|
||||
<br/><br/>
|
||||
You can use <span class="tt">f:fetch</span> to fetch a floating point value and
|
||||
<span class="tt">f:store</span> to store one.
|
||||
<br/><br/>
|
||||
If you need more precision, try Kiyoshi Yoneda's FloatVar
|
||||
example (<span class="tt">example/FloatVar.forth</span>), which includes words to
|
||||
store and retrieve values using multiple cells.
|
||||
<br/><br/>
|
||||
• <span class="tt">f:to-number</span><br/>
|
||||
• <span class="tt">f:to-string</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">I/O</span>
|
||||
<br/><br/>
|
||||
The floating point vocabulary has a single I/O word, <span class="tt">f:put</span>,
|
||||
for the display of floating point numbers.
|
||||
<br/><br/>
|
||||
<span class="h2">Encoded Values</span>
|
||||
<br/><br/>
|
||||
RETRO provides a means of encoding and decoding floating point
|
||||
values into standard integer cells. This is based on the paper
|
||||
"Encoding floating point values to shorter integers" by Kiyoshi
|
||||
Yoneda and Charles Childers.
|
||||
<br/><br/>
|
||||
• <span class="tt">f:E1</span><br/>
|
||||
• <span class="tt">f:to-e</span><br/>
|
||||
• <span class="tt">e:-INF</span><br/>
|
||||
• <span class="tt">e:-inf?</span><br/>
|
||||
• <span class="tt">e:INF</span><br/>
|
||||
• <span class="tt">e:MAX</span><br/>
|
||||
• <span class="tt">e:MIN</span><br/>
|
||||
• <span class="tt">e:NAN</span><br/>
|
||||
• <span class="tt">e:clip</span><br/>
|
||||
• <span class="tt">e:inf?</span><br/>
|
||||
• <span class="tt">e:max?</span><br/>
|
||||
• <span class="tt">e:min?</span><br/>
|
||||
• <span class="tt">e:n?</span><br/>
|
||||
• <span class="tt">e:nan?</span><br/>
|
||||
• <span class="tt">e:put</span><br/>
|
||||
• <span class="tt">e:to-f</span><br/>
|
||||
• <span class="tt">e:zero?</span><br/>
|
||||
</p>
|
||||
</body></html>
|
||||
85
doc/html/chapters/techniques/lexical-scope.html
Normal file
85
doc/html/chapters/techniques/lexical-scope.html
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Lexical Scope</span>
|
||||
<br/><br/>
|
||||
RETRO has a single dictionary, but does provide a means of using
|
||||
lexical scope to keep this dictionary clean.
|
||||
<br/><br/>
|
||||
<span class="h2">Example</span>
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">{{ </span><br/>
|
||||
<span class="tt"> <span class='str'>'A</span> var </span><br/>
|
||||
<span class="tt"> <span class='colon'>:++A</span> <span class='ptr'>&A</span> v:inc <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">---reveal--- </span><br/>
|
||||
<span class="tt"> <span class='colon'>:B</span> ++A ++A <span class='fetch'>@A</span> n:put nl <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">}} </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
In this example, the lexical namespace is created with <span class="tt">{{</span>. A
|
||||
variable (<span class="tt">A</span>) and word (<span class="tt">++A</span>) are defined. Then a marker is
|
||||
set with <span class="tt">---reveal---</span>. Another word (<span class="tt">B</span>) is defined, and the
|
||||
lexical area is closed with <span class="tt">}}</span>.
|
||||
<br/><br/>
|
||||
The headers between <span class="tt">{{</span> and <span class="tt">---reveal---</span> are then hidden from
|
||||
the dictionary, leaving only the headers between <span class="tt">---reveal---</span>
|
||||
and <span class="tt">}}</span> exposed.
|
||||
<br/><br/>
|
||||
<span class="h2">Notes</span>
|
||||
<br/><br/>
|
||||
This only affects word visibility within the scoped area. As an
|
||||
example:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:a</span> <span class='num'>#1</span> <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt"> </span><br/>
|
||||
<span class="tt">{{ </span><br/>
|
||||
<span class="tt"> <span class='colon'>:a</span> <span class='num'>#2</span> <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">---reveal--- </span><br/>
|
||||
<span class="tt"> <span class='colon'>:b</span> <span class='str'>'a</span> s:evaluate n:put <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">}} </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
In this, after <span class="tt">}}</span> closes the area, the <span class="tt">:a #2 ;</span> is hidden and
|
||||
the <span class="tt">s:evaluate</span> will find the <span class="tt">:a #1 ;</span> when <span class="tt">b</span> is run.
|
||||
</p>
|
||||
</body></html>
|
||||
110
doc/html/chapters/techniques/loops.html
Normal file
110
doc/html/chapters/techniques/loops.html
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Loops</span>
|
||||
<br/><br/>
|
||||
RETRO provides several words for creating loops.
|
||||
<br/><br/>
|
||||
<span class="h2">Unconditional Loops</span>
|
||||
<br/><br/>
|
||||
An unconditional loop begins with <span class="tt">repeat</span> and ends with <span class="tt">again</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:test repeat #1 n:put sp again ;</tt>
|
||||
<tt class='indentedcode'>test</tt>
|
||||
<br/><br/>
|
||||
Unconditional loops must be inside a definition or quote. To exit
|
||||
one of these, use <span class="tt">0;</span>, <span class="tt">-if;</span> or <span class="tt">if;</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:test #100 repeat 0; dup n:put sp n:dec again ;</tt>
|
||||
<tt class='indentedcode'>test</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:test #100 repeat dup #50 eq? [ 'done! s:put nl ] if; n:dec again ;</tt>
|
||||
<tt class='indentedcode'>test</tt>
|
||||
<br/><br/>
|
||||
You can also achieve this via recursion:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:test 0; dup n:put sp n:dec test ;</tt>
|
||||
<tt class='indentedcode'>#100 test</tt>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
<span class="h2">Conditional Loops</span>
|
||||
<br/><br/>
|
||||
There are two conditional looping combinators: <span class="tt">while</span> and <span class="tt">until</span>.
|
||||
Both take a quote and execute it, checking a returned flag to decide
|
||||
when to stop running.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#0 [ dup n:put sp n:inc dup #10 eq? ] until</tt>
|
||||
<tt class='indentedcode'>#10 [ dup n:put sp n:dec dup n:-zero? ] while</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Counted Loops</span>
|
||||
<br/><br/>
|
||||
There are two combinators for counted loops. These are <span class="tt">times</span> and
|
||||
<span class="tt">indexed-times</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#0 #10 [ dup n:put sp n:inc ] times nl</tt>
|
||||
<tt class='indentedcode'>#10 [ I n:put sp ] indexed-times</tt>
|
||||
<br/><br/>
|
||||
The <span class="tt">indexed-times</span> provides an index via the <span class="tt">I</span>, <span class="tt">J</span>, and
|
||||
<span class="tt">K</span> words. <span class="tt">I</span> will be the index of the current loop, with <span class="tt">J</span> and
|
||||
<span class="tt">K</span> being the indexes of the next two older loops.
|
||||
<br/><br/>
|
||||
The loop indexes can be accessed outside the loop body:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>:display I n:square n:put sp ;</tt>
|
||||
<tt class='indentedcode'>:squares [ display ] indexed-times nl ;</tt>
|
||||
<tt class='indentedcode'>#100 squares</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Tradeoffs</span>
|
||||
<br/><br/>
|
||||
The unconditional loop form is more efficient as it's just a
|
||||
simple jump operation. The <span class="tt">times</span> counted loops are a little
|
||||
slower, but can be cleaner and more readable in many cases. The
|
||||
<span class="tt">indexed-times</span> form is significantly slower than the other
|
||||
two forms.
|
||||
</p>
|
||||
</body></html>
|
||||
143
doc/html/chapters/techniques/naming-conventions.html
Normal file
143
doc/html/chapters/techniques/naming-conventions.html
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Naming Conventions</span>
|
||||
<br/><br/>
|
||||
Word names in RETRO generally follow the following conventions.
|
||||
<br/><br/>
|
||||
<span class="h2">General Guidelines</span>
|
||||
<br/><br/>
|
||||
• Readability is important<br/>
|
||||
• Be consistent<br/>
|
||||
• Don't use a prefix as the first character of a name<br/>
|
||||
• Don't use underscores in word names<br/>
|
||||
• Use short names for indices<br/>
|
||||
• Word names start with a <span class="tt">-</span> for "not"<br/>
|
||||
• Words returning a flag end in ?<br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Typical Format</span>
|
||||
<br/><br/>
|
||||
The word names will generally follow a form like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>[namespace:]name</tt>
|
||||
<br/><br/>
|
||||
The <span class="tt">namespace:</span> is optional, but recommended for consistency
|
||||
with the rest of the system and to make it easier to identify
|
||||
related words.
|
||||
<br/><br/>
|
||||
<span class="h2">Case</span>
|
||||
<br/><br/>
|
||||
Word names are lowercase, with a dash (-) for compound names.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>hello</tt>
|
||||
<tt class='indentedcode'>drop-pair</tt>
|
||||
<tt class='indentedcode'>s:for-each</tt>
|
||||
<br/><br/>
|
||||
Variables use TitleCase, with no dash between compound names.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>Base</tt>
|
||||
<tt class='indentedcode'>Heap</tt>
|
||||
<tt class='indentedcode'>StringBuffers</tt>
|
||||
<br/><br/>
|
||||
Constants are UPPERCASE, with a dash (-) for compound names.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>TRUE</tt>
|
||||
<tt class='indentedcode'>FALSE</tt>
|
||||
<tt class='indentedcode'>f:PI</tt>
|
||||
<tt class='indentedcode'>MAX-STRING-LENGTH</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Namespaces</span>
|
||||
<br/><br/>
|
||||
Words are grouped into broad namespaces by attaching a short
|
||||
prefix string to the start of a name.
|
||||
<br/><br/>
|
||||
The common namespaces are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Prefix | Contains |</tt>
|
||||
<tt class='indentedcode'>| ------- | ------------------------------------------------------ |</tt>
|
||||
<tt class='indentedcode'>| a: | Words operating on simple arrays |</tt>
|
||||
<tt class='indentedcode'>| ASCII: | ASCII character constants for control characters |</tt>
|
||||
<tt class='indentedcode'>| buffer: | Words for operating on a simple linear LIFO buffer |</tt>
|
||||
<tt class='indentedcode'>| c: | Words for operating on ASCII character data |</tt>
|
||||
<tt class='indentedcode'>| class: | Contains class handlers for words |</tt>
|
||||
<tt class='indentedcode'>| d: | Words operating on the Dictionary |</tt>
|
||||
<tt class='indentedcode'>| err: | Words for handling errors |</tt>
|
||||
<tt class='indentedcode'>| io: | General I/O words |</tt>
|
||||
<tt class='indentedcode'>| n: | Words operating on numeric data |</tt>
|
||||
<tt class='indentedcode'>| prefix: | Contains prefix handlers |</tt>
|
||||
<tt class='indentedcode'>| s: | Words operating on string data |</tt>
|
||||
<tt class='indentedcode'>| v: | Words operating on variables |</tt>
|
||||
<tt class='indentedcode'>| file: | File I/O words |</tt>
|
||||
<tt class='indentedcode'>| f: | Floating Point words |</tt>
|
||||
<tt class='indentedcode'>| unix: | Unix system call words |</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Tips</span>
|
||||
<br/><br/>
|
||||
<span class="h3">Don't Start Names With Prefix Characters</span>
|
||||
<br/><br/>
|
||||
Avoid using a prefix as the first character of a word name. RETRO
|
||||
will look for prefixes first, this will prevent direct use of
|
||||
the work in question.
|
||||
<br/><br/>
|
||||
To find a list of prefix characters, do:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'prefix: d:words-with</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Don't Use Underscores</span>
|
||||
<br/><br/>
|
||||
Underscores in strings are replaced by spaces. This is problematic,
|
||||
especially with variables. Consider:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'test_name var</tt>
|
||||
<tt class='indentedcode'>#188 !test_name</tt>
|
||||
<br/><br/>
|
||||
In this, the string for the name is converted to "test name". The
|
||||
store in the second line will not add the space, so resolves to an
|
||||
incorrect address.
|
||||
<br/><br/>
|
||||
I personally recommend avoiding the use of underscores in any word
|
||||
names.
|
||||
</p>
|
||||
</body></html>
|
||||
129
doc/html/chapters/techniques/numbers.html
Normal file
129
doc/html/chapters/techniques/numbers.html
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Numbers</span>
|
||||
<br/><br/>
|
||||
Numbers in RETRO are signed integers.
|
||||
<br/><br/>
|
||||
<span class="h2">Token Prefix</span>
|
||||
<br/><br/>
|
||||
All numbers start with a <span class="tt">#</span> prefix.
|
||||
<br/><br/>
|
||||
<span class="h2">Namespace</span>
|
||||
<br/><br/>
|
||||
Most words operating on numbers are in the <span class="tt">n:</span> namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">Range of Values</span>
|
||||
<br/><br/>
|
||||
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
|
||||
will be -9,223,372,036,854,775,807 to 9,223,372,036,854,775,806.
|
||||
<br/><br/>
|
||||
You can check the range your VM and image support using:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>n:MIN</tt>
|
||||
<tt class='indentedcode'>n:MAX</tt>
|
||||
<br/><br/>
|
||||
These will return the limits for your system.
|
||||
<br/><br/>
|
||||
<span class="h2">Comparisons</span>
|
||||
<br/><br/>
|
||||
RETRO provides a number of comparison words for numeric values.
|
||||
<br/><br/>
|
||||
The basic comparators are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>-eq?</tt>
|
||||
<tt class='indentedcode'>eq?</tt>
|
||||
<tt class='indentedcode'>lt?</tt>
|
||||
<tt class='indentedcode'>lteq?</tt>
|
||||
<tt class='indentedcode'>gt?</tt>
|
||||
<tt class='indentedcode'>gteq?</tt>
|
||||
<br/><br/>
|
||||
Additionally RETRO also provides:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>n:-zero?</tt>
|
||||
<tt class='indentedcode'>n:between?</tt>
|
||||
<tt class='indentedcode'>n:even?</tt>
|
||||
<tt class='indentedcode'>n:negative?</tt>
|
||||
<tt class='indentedcode'>n:odd?</tt>
|
||||
<tt class='indentedcode'>n:positive?</tt>
|
||||
<tt class='indentedcode'>n:strictly-positive?</tt>
|
||||
<tt class='indentedcode'>n:zero?</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Basic Operations</span>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>+</tt>
|
||||
<tt class='indentedcode'>-</tt>
|
||||
<tt class='indentedcode'>*</tt>
|
||||
<tt class='indentedcode'>/</tt>
|
||||
<tt class='indentedcode'>mod</tt>
|
||||
<tt class='indentedcode'>/mod</tt>
|
||||
<tt class='indentedcode'>n:abs</tt>
|
||||
<tt class='indentedcode'>n:dec</tt>
|
||||
<tt class='indentedcode'>n:inc</tt>
|
||||
<tt class='indentedcode'>n:limit</tt>
|
||||
<tt class='indentedcode'>n:max</tt>
|
||||
<tt class='indentedcode'>n:min</tt>
|
||||
<tt class='indentedcode'>n:negate</tt>
|
||||
<tt class='indentedcode'>n:pow</tt>
|
||||
<tt class='indentedcode'>n:sqrt</tt>
|
||||
<tt class='indentedcode'>n:square</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Conversions</span>
|
||||
<br/><br/>
|
||||
You can convert a number to a string with <span class="tt">n:to-string</span> or
|
||||
to a floating point value with <span class="tt">n:to-float</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#123 n:to-float f:put</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#123 n:to-string s:put</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Display</span>
|
||||
<br/><br/>
|
||||
To display a number, use <span class="tt">n:put</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#123 n:put</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
80
doc/html/chapters/techniques/pointers.html
Normal file
80
doc/html/chapters/techniques/pointers.html
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Pointers</span>
|
||||
<br/><br/>
|
||||
<span class="h2">Prefix</span>
|
||||
<br/><br/>
|
||||
Pointers are returned by the <span class="tt">&</span> prefix.
|
||||
<br/><br/>
|
||||
<span class="h2">Examples</span>
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='str'>'Base</span> var </span><br/>
|
||||
<span class="tt"><span class='ptr'>&Base</span> <span class='prim'>fetch</span> </span><br/>
|
||||
<span class="tt"><span class='num'>#10</span> <span class='ptr'>&Base</span> <span class='prim'>store</span> </span><br/>
|
||||
<span class="tt"> </span><br/>
|
||||
<span class="tt"><span class='num'>#10</span> <span class='ptr'>&n:inc</span> <span class='prim'>call</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Notes</span>
|
||||
<br/><br/>
|
||||
The use of <span class="tt">&</span> to get a pointer to a data structure (with a
|
||||
word class of <span class="tt">class:data</span>) is not required. I like to use it
|
||||
anyway as it makes my intent a little clearer.
|
||||
<br/><br/>
|
||||
Pointers are useful with combinators. Consider:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:abs</span> <span class='prim'>dup</span> n:negative? <span class='imm'>[</span> n:negate <span class='imm'>]</span> <span class='prim'>if</span> <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Since the target quote body is a single word, it is more
|
||||
efficient to use a pointer instead:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:abs</span> <span class='prim'>dup</span> n:negative? <span class='ptr'>&n:negate</span> <span class='prim'>if</span> <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
The advantages are speed (saves a level of call/return by
|
||||
avoiding the quotation) and size (for the same reason).
|
||||
This may be less readable though, so consider the balance
|
||||
of performance to readability when using this approach.
|
||||
</p>
|
||||
</body></html>
|
||||
133
doc/html/chapters/techniques/quotes.html
Normal file
133
doc/html/chapters/techniques/quotes.html
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Quotations</span>
|
||||
<br/><br/>
|
||||
Quotes are anonymous functions. RETRO uses these as the basis for
|
||||
executable flow control and combinatorial logic.
|
||||
<br/><br/>
|
||||
<span class="h2">Using Quotations</span>
|
||||
<br/><br/>
|
||||
To make a quotation, surround the code with square brackets. E.g.,
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#1 #2 eq? [ 'No_match s:put nl ] -if</tt>
|
||||
<br/><br/>
|
||||
Quotes can be nested:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>[ #3 [ #4 ] dip ] call</tt>
|
||||
<br/><br/>
|
||||
After creation, a pointer to the quotation is left on the stack
|
||||
(or is compiled into the current definition).
|
||||
<br/><br/>
|
||||
<span class="h2">Combinators</span>
|
||||
<br/><br/>
|
||||
Words operating on quotations are called combinators; these are
|
||||
discussed in <strong>Using Combinators</strong>.
|
||||
<br/><br/>
|
||||
<span class="h2">Implementation</span>
|
||||
<br/><br/>
|
||||
A quotation is compiled as:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>... code before quotation ...</tt>
|
||||
<tt class='indentedcode'>i liju.... (if_compiling_only)</tt>
|
||||
<tt class='indentedcode'>d address after quotation (if_compiling_only)</tt>
|
||||
<tt class='indentedcode'>... code for quotation</tt>
|
||||
<tt class='indentedcode'>i re...... (this_is_where_the_quote_ends)</tt>
|
||||
<tt class='indentedcode'>i li......</tt>
|
||||
<tt class='indentedcode'>d address of code for quotation</tt>
|
||||
<tt class='indentedcode'>... code after quotation ....</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Other Notes</span>
|
||||
<br/><br/>
|
||||
Quotations are used heavily in RETRO. They give the source a
|
||||
feel that's different from traditional Forth, and allow for
|
||||
a more consistent syntax.
|
||||
<br/><br/>
|
||||
For instance, in a traditional Forth, you might have some
|
||||
conditionals:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>IF ... THEN</tt>
|
||||
<tt class='indentedcode'>IF ... ELSE ... THEN</tt>
|
||||
<tt class='indentedcode'>IF ... EXIT THEN</tt>
|
||||
<br/><br/>
|
||||
RETRO uses conditional combinators for these:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>[ ... ] if</tt>
|
||||
<tt class='indentedcode'>[ ... ] [ ... ] choose</tt>
|
||||
<tt class='indentedcode'>[ ... ] if;</tt>
|
||||
<br/><br/>
|
||||
Or loops:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>FOR ... NEXT</tt>
|
||||
<br/><br/>
|
||||
Is replaced by:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>[ ... ] times</tt>
|
||||
<br/><br/>
|
||||
This can also extend to stack flow. Sequences like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>>R ... >R</tt>
|
||||
<tt class='indentedcode'>DUP >R ... >R</tt>
|
||||
<br/><br/>
|
||||
Become:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>[ ... ] dip</tt>
|
||||
<tt class='indentedcode'>[ ... ] sip</tt>
|
||||
<br/><br/>
|
||||
And forms like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>1 2 3 * swap 3 * swap</tt>
|
||||
<br/><br/>
|
||||
Can be replaced with a combinator like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#1 #2 [ #3 * ] bi@</tt>
|
||||
<br/><br/>
|
||||
While there is a different set of words to learn, I find that
|
||||
overall there's less noise from low level stack shuffling words
|
||||
and the added consistency with regards to overall syntax has
|
||||
been nice as I was never fond of the multiple forms that existed
|
||||
in traditional Forth.
|
||||
</p>
|
||||
</body></html>
|
||||
54
doc/html/chapters/techniques/return-stack.html
Normal file
54
doc/html/chapters/techniques/return-stack.html
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">The Return Stack</span>
|
||||
<br/><br/>
|
||||
RETRO has two stacks. The primary one is used to pass data
|
||||
between words. The second one primarily holds return addresses.
|
||||
<br/><br/>
|
||||
Each time a word is called, the next address is pushed to
|
||||
the return stack.
|
||||
</p>
|
||||
</body></html>
|
||||
99
doc/html/chapters/techniques/scripting.html
Normal file
99
doc/html/chapters/techniques/scripting.html
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Unix Scripting</span>
|
||||
<br/><br/>
|
||||
RETRO on Unix hosts is designed to play well with scripting.
|
||||
<br/><br/>
|
||||
<span class="h2">Shebang</span>
|
||||
<br/><br/>
|
||||
To run an entire program directly, start the file with the
|
||||
standard shebang and make the file executable:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#!/usr/bin/env retro</tt>
|
||||
<br/><br/>
|
||||
This requires the <span class="tt">retro</span> binary to be in your path.
|
||||
<br/><br/>
|
||||
<span class="h2">Arguments</span>
|
||||
<br/><br/>
|
||||
RETRO provides several words in the <span class="tt">script:</span> namespace for accessing
|
||||
command line arguments.
|
||||
<br/><br/>
|
||||
The number of arguments can be accessed via <span class="tt">script:arguments</span>. This
|
||||
will return a number with the arguments, other than the script
|
||||
name.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>script:arguments '%n_arguments_passed\n s:format s:put</tt>
|
||||
<br/><br/>
|
||||
To retreive an argument, pass the argument number to <span class="tt">script:get-argument</span>:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>script:arguments [ I script:get-argument s:put nl ] indexed-times </tt>
|
||||
<br/><br/>
|
||||
And to get the name of the script, use <span class="tt">script:name</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>script:name s:put</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Mixing</span>
|
||||
<br/><br/>
|
||||
With use of the Unu literate format, it's possible to mix both
|
||||
shell and RETRO code into a single script. As an example, this
|
||||
is a bit of shell that runs itself via retro for each .retro
|
||||
file in the current directory tree:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#!/bin/sh</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'># shell part</tt>
|
||||
<tt class='indentedcode'>find . -name '*.retro' -print0 | xargs -0 -n 1 retro $0</tt>
|
||||
<tt class='indentedcode'>exit</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'># retro part</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>This will scan a source file and do something with it:</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>... do stuff ...</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
114
doc/html/chapters/techniques/sockets.html
Normal file
114
doc/html/chapters/techniques/sockets.html
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Sockets</span>
|
||||
<br/><br/>
|
||||
On Unix hosts, RETRO provides an optional set of words for using
|
||||
network sockets.
|
||||
<br/><br/>
|
||||
<span class="h2">Create a Socket</span>
|
||||
<br/><br/>
|
||||
To create a new socket, just run:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>socket:create</tt>
|
||||
<br/><br/>
|
||||
This will return a socket handle.
|
||||
<br/><br/>
|
||||
<span class="h2">Bind To A Port</span>
|
||||
<br/><br/>
|
||||
To bind to a port, pass the port number and socket handle
|
||||
to <span class="tt">socket:bind</span>. The port should be a string. This will return
|
||||
0 if successful, -1 if not successful, and an error code.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'9998 @Sock socket:bind</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Configure To Allow Incoming Connections</span>
|
||||
<br/><br/>
|
||||
To prepare a socket for incoming connections use socket:listen. This
|
||||
will take a backlog count and a socket handle. It returns a flag
|
||||
(0 success, -1 failed) and an error code.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#3 @Sock socket:listen</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Accept Connections</span>
|
||||
<br/><br/>
|
||||
To accept connections pass the socket handle to <span class="tt">socket:accept</span>.
|
||||
This returns a new socket for the connection and an error code.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>@Sock socket:accept</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Make A Connection</span>
|
||||
<br/><br/>
|
||||
To connect to a server using the socket:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'forth.works '70 socket:configure</tt>
|
||||
<tt class='indentedcode'>@Sock socket:connect</tt>
|
||||
<br/><br/>
|
||||
<span class="tt">socket:connect</span> will return a status code and an error code.
|
||||
<br/><br/>
|
||||
<span class="h2">Writing To A Socket</span>
|
||||
<br/><br/>
|
||||
To write a string to a socket, use <span class="tt">socket:send</span>. This will
|
||||
take a string and a socket handle and will return the number
|
||||
of bytes sent and an error code.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'test @Sock socket:send</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Reading From A Socket</span>
|
||||
<br/><br/>
|
||||
To read data from a socket pass an address, a maximum number of
|
||||
bytes, and the socket handle to <span class="tt">socket:recv</span>. This will return
|
||||
the number of bytes received and an error code. The bytes will
|
||||
be stored in memory starting at the specified address.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>here #1024 @Sock socket:recv</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Close a Socket</span>
|
||||
<br/><br/>
|
||||
To close a socket, pass the socket handle to <span class="tt">socket:close</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>@Socket socket:close</tt>
|
||||
</p>
|
||||
</body></html>
|
||||
79
doc/html/chapters/techniques/stack-diagrams.html
Normal file
79
doc/html/chapters/techniques/stack-diagrams.html
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Stack Diagrams</span>
|
||||
<br/><br/>
|
||||
Most words in RETRO have a stack comment. These look like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>(-)</tt>
|
||||
<tt class='indentedcode'>(nn-n)</tt>
|
||||
<br/><br/>
|
||||
As with all comments, a stack comment begins with <span class="tt">(</span> and
|
||||
should end with a <span class="tt">)</span>. There are two parts to the comment.
|
||||
On the left side of the <span class="tt">-</span> is what the word <strong>consumes</strong>. On
|
||||
the right is what it <strong>leaves</strong>.
|
||||
<br/><br/>
|
||||
RETRO uses a short notation, with one character per value
|
||||
taken or left. In general, the following symbols represent
|
||||
certain types of values.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Notation | Represents |</tt>
|
||||
<tt class='indentedcode'>| ------------------- | ----------------------- |</tt>
|
||||
<tt class='indentedcode'>| b, n, m, o, x, y, z | generic numeric values |</tt>
|
||||
<tt class='indentedcode'>| s | string |</tt>
|
||||
<tt class='indentedcode'>| v | variable |</tt>
|
||||
<tt class='indentedcode'>| p, a | pointers |</tt>
|
||||
<tt class='indentedcode'>| q | quotation |</tt>
|
||||
<tt class='indentedcode'>| d | dictionary header |</tt>
|
||||
<tt class='indentedcode'>| f | `TRUE` or `FALSE` flag. |</tt>
|
||||
<br/><br/>
|
||||
In the case of something like <span class="tt">(xyz-m)</span>, RETRO expects z to be
|
||||
on the top of the stack, with y below it and x below the y
|
||||
value. And after execution, a single value (m) will be left on
|
||||
the stack.
|
||||
<br/><br/>
|
||||
Words with no stack effect have a comment of (-)
|
||||
</p>
|
||||
</body></html>
|
||||
209
doc/html/chapters/techniques/strings.html
Normal file
209
doc/html/chapters/techniques/strings.html
Normal file
|
|
@ -0,0 +1,209 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Working With Strings</span>
|
||||
<br/><br/>
|
||||
Strings in RETRO are NULL terminated sequences of values
|
||||
representing characters. Being NULL terminated, they can't
|
||||
contain a NULL (ASCII 0).
|
||||
<br/><br/>
|
||||
The character words in RETRO are built around ASCII, but
|
||||
strings can contain UTF8 encoded data if the host platform
|
||||
allows. Words like <span class="tt">s:length</span> will return the number of bytes,
|
||||
not the number of logical characters in this case.
|
||||
<br/><br/>
|
||||
<span class="h2">Prefix</span>
|
||||
<br/><br/>
|
||||
Strings begin with a single <span class="tt">'</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'Hello</tt>
|
||||
<tt class='indentedcode'>'This_is_a_string</tt>
|
||||
<tt class='indentedcode'>'This_is_a_much_longer_string_12345_67890_!!!</tt>
|
||||
<br/><br/>
|
||||
RETRO will replace spaces with underscores. If you need both
|
||||
spaces and underscores in a string, escape the underscores and
|
||||
use <span class="tt">s:format</span>:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'This_has_spaces_and_under\_scored_words. s:format</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Namespace</span>
|
||||
<br/><br/>
|
||||
Words operating on strings are in the <span class="tt">s:</span> namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">Lifetime</span>
|
||||
<br/><br/>
|
||||
At the interpreter, strings get allocated in a rotating buffer.
|
||||
This is used by the words operating on strings, so if you need
|
||||
to keep them around, use <span class="tt">s:keep</span> or <span class="tt">s:copy</span> to move them to
|
||||
more permanent storage.
|
||||
<br/><br/>
|
||||
In a definition, the string is compiled inline and so is in
|
||||
permanent memory.
|
||||
<br/><br/>
|
||||
You can manually manage the string lifetime by using <span class="tt">s:keep</span>
|
||||
to place it into permanent memory or <span class="tt">s:temp</span> to copy it to
|
||||
the rotating buffer.
|
||||
<br/><br/>
|
||||
<span class="h2">Mutability</span>
|
||||
<br/><br/>
|
||||
Strings are mutable. If you need to ensure that a string is
|
||||
not altered, make a copy before operating on it or see the
|
||||
individual glossary entries for notes on words that may do
|
||||
this automatically.
|
||||
<br/><br/>
|
||||
<span class="h2">Searching</span>
|
||||
<br/><br/>
|
||||
RETRO provides four words for searching within a string.
|
||||
<br/><br/>
|
||||
• <span class="tt">s:contains-char?</span> <br/>
|
||||
• <span class="tt">s:contains-string?</span><br/>
|
||||
• <span class="tt">s:index-of</span><br/>
|
||||
• <span class="tt">s:index-of-string</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Comparisons</span>
|
||||
<br/><br/>
|
||||
• <span class="tt">s:eq?</span><br/>
|
||||
• <span class="tt">s:case</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Extraction</span>
|
||||
<br/><br/>
|
||||
To obtain a new string containing the first <span class="tt">n</span> characters from
|
||||
a source string, use <span class="tt">s:left</span>:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'Hello_World #5 s:left</tt>
|
||||
<br/><br/>
|
||||
To obtain a new string containing the last <span class="tt">n</span> characters from
|
||||
a source string, use <span class="tt">s:right</span>:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'Hello_World #5 s:right</tt>
|
||||
<br/><br/>
|
||||
If you need to extract data from the middle of the string, use
|
||||
<span class="tt">s:substr</span>. This takes a string, the offset of the first
|
||||
character, and the number of characters to extract.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'Hello_World #3 #5 s:substr</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Joining</span>
|
||||
<br/><br/>
|
||||
You can use <span class="tt">s:append</span> or <span class="tt">s:prepend</span> to merge two strings.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'First 'Second s:append</tt>
|
||||
<tt class='indentedcode'>'Second 'First s:prepend</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Tokenization</span>
|
||||
<br/><br/>
|
||||
• <span class="tt">s:tokenize</span><br/>
|
||||
• <span class="tt">s:tokenize-on-string</span><br/>
|
||||
• <span class="tt">s:split</span><br/>
|
||||
• <span class="tt">s:split-on-string</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Conversions</span>
|
||||
<br/><br/>
|
||||
To convert the case of a string, RETRO provides <span class="tt">s:to-lower</span>
|
||||
and <span class="tt">s:to-upper</span>.
|
||||
<br/><br/>
|
||||
<span class="tt">s:to-number</span> is provided to convert a string to an integer
|
||||
value. This has a few limitations:
|
||||
<br/><br/>
|
||||
• only supports decimal<br/>
|
||||
• non-numeric characters will result in incorrect values<br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Cleanup</span>
|
||||
<br/><br/>
|
||||
RETRO provides a handful of words for cleaning up strings.
|
||||
<br/><br/>
|
||||
<span class="tt">s:chop</span> will remove the last character from a string. This
|
||||
is done by replacing it with an ASCII:NULL.
|
||||
<br/><br/>
|
||||
<span class="tt">s:trim</span> removes leading and trailing whitespace from a string.
|
||||
For more control, there is also <span class="tt">s:trim-left</span> and <span class="tt">s:trim-right</span>
|
||||
which let you trim just the leading or trailing end as desired.
|
||||
<br/><br/>
|
||||
<span class="h2">Combinators</span>
|
||||
<br/><br/>
|
||||
• <span class="tt">s:for-each</span><br/>
|
||||
• <span class="tt">s:filter</span><br/>
|
||||
• <span class="tt">s:map</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Other</span>
|
||||
<br/><br/>
|
||||
• <span class="tt">s:evaluate</span><br/>
|
||||
• <span class="tt">s:copy</span><br/>
|
||||
• <span class="tt">s:reverse</span><br/>
|
||||
• <span class="tt">s:hash</span><br/>
|
||||
• <span class="tt">s:length</span><br/>
|
||||
• <span class="tt">s:replace</span><br/>
|
||||
• <span class="tt">s:format</span><br/>
|
||||
• <span class="tt">s:empty</span><br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Controlling The Temporary Buffers</span>
|
||||
<br/><br/>
|
||||
As dicussed in the Lifetime subsection, temporary strings are
|
||||
allocated in a rotating buffer. The details of this can be
|
||||
altered by updating two variables.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Variable | Holds |</tt>
|
||||
<tt class='indentedcode'>| ------------- | ---------------------------------------- |</tt>
|
||||
<tt class='indentedcode'>| TempStrings | The number of temporary strings |</tt>
|
||||
<tt class='indentedcode'>| TempStringMax | The maximum length of a temporary string |</tt>
|
||||
<br/><br/>
|
||||
For example, to increase the number of temporary strings to
|
||||
48:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#48 !TempStrings</tt>
|
||||
<br/><br/>
|
||||
The defaults are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Variable | Default |</tt>
|
||||
<tt class='indentedcode'>| ------------- | ------- |</tt>
|
||||
<tt class='indentedcode'>| TempStrings | 32 |</tt>
|
||||
<tt class='indentedcode'>| TempStringMax | 512 |</tt>
|
||||
<br/><br/>
|
||||
It's also important to note that altering these will affect
|
||||
the memory map for all temporary buffers. Do not use anything
|
||||
already in the buffers after updating these or you will risk
|
||||
data corruption and possible crashes.
|
||||
</p>
|
||||
</body></html>
|
||||
169
doc/html/chapters/techniques/the-stacks.html
Normal file
169
doc/html/chapters/techniques/the-stacks.html
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">The Stacks</span>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
RETRO always has two stacks, and optionally (if built with
|
||||
floating point support) a third.
|
||||
<br/><br/>
|
||||
<span class="h2">Data Stack</span>
|
||||
<br/><br/>
|
||||
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.
|
||||
<br/><br/>
|
||||
<span class="h3">Placing Values On The Stack</span>
|
||||
<br/><br/>
|
||||
Values can be placed on the stack directly.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Example | Action |</tt>
|
||||
<tt class='indentedcode'>| -------------- | ---------------------------------------- |</tt>
|
||||
<tt class='indentedcode'>| `#300123` | Push the number `300123` to the stack |</tt>
|
||||
<tt class='indentedcode'>| `$h` | Push the ASCII code for `h` to the stack |</tt>
|
||||
<tt class='indentedcode'>| `'hello_world` | Push a pointer to a string to the stack |</tt>
|
||||
<tt class='indentedcode'>| `&fetch` | Push the address of `fetch` to the stack |</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Reordering The Stack</span>
|
||||
<br/><br/>
|
||||
RETRO provides a number of <strong>shufflers</strong> for reordering items
|
||||
on the stack.
|
||||
<br/><br/>
|
||||
Some of the most common ones are:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>| Word | Before | After |</tt>
|
||||
<tt class='indentedcode'>| ------- |--------- | -------- |</tt>
|
||||
<tt class='indentedcode'>| dup | #1 | #1 #1 |</tt>
|
||||
<tt class='indentedcode'>| drop | #1 #2 | #1 |</tt>
|
||||
<tt class='indentedcode'>| swap | #1 #2 | #2 #1 |</tt>
|
||||
<tt class='indentedcode'>| over | #1 #2 | #1 #2 #1 |</tt>
|
||||
<tt class='indentedcode'>| tuck | #1 #2 | #2 #1 #2 |</tt>
|
||||
<tt class='indentedcode'>| nip | #1 #2 | #2 |</tt>
|
||||
<tt class='indentedcode'>| rot | #1 #2 #3 | #3 #1 #2 |</tt>
|
||||
<br/><br/>
|
||||
You can use <span class="tt">push</span> and <span class="tt">pop</span> to move values to and from the
|
||||
address stack. Make sure you <span class="tt">pop</span> them back before the word
|
||||
ends or RETRO will crash. These two words can not be used
|
||||
at the interpreter.
|
||||
<br/><br/>
|
||||
There is also a special one, <span class="tt">reorder</span>, which allows for big
|
||||
stack restructuring. This is slow but can be very useful.
|
||||
<br/><br/>
|
||||
As an example, let's say we have four values:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#1 #2 #3 #4</tt>
|
||||
<br/><br/>
|
||||
And we want them to become:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>#4 #3 #2 #1</tt>
|
||||
<br/><br/>
|
||||
Doing this with the basic shufflers is difficult. You could end
|
||||
up with something similar to:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>swap rot push rot pop swap </tt>
|
||||
<br/><br/>
|
||||
But with <span class="tt">reorder</span>, you can just express the before and after
|
||||
states:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>'abcd 'dcba reorder</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Resetting The Stack</span>
|
||||
<br/><br/>
|
||||
If you need to quickly empty the stack, use <span class="tt">reset</span>.
|
||||
<br/><br/>
|
||||
<span class="h3">Get The Stack Depth</span>
|
||||
<br/><br/>
|
||||
To find out how many items are on the stack, use <span class="tt">depth</span>.
|
||||
<br/><br/>
|
||||
<span class="h3">Displaying The Stack</span>
|
||||
<br/><br/>
|
||||
You can display the stack by running <span class="tt">dump-stack</span>.
|
||||
<br/><br/>
|
||||
<span class="h3">Data Flow Combinators</span>
|
||||
<br/><br/>
|
||||
RETRO provides <strong>combinators</strong> for working with data order on
|
||||
the stack. These are covered in a later chapter and are worth
|
||||
learning to use as they can help provide a cleaner, more
|
||||
structured means of working.
|
||||
<br/><br/>
|
||||
<span class="h3">Tips</span>
|
||||
<br/><br/>
|
||||
The stack is <strong>not</strong> an array in addressable memory. Don't try
|
||||
to treat it like one.
|
||||
<br/><br/>
|
||||
<span class="h2">Address Stack</span>
|
||||
<br/><br/>
|
||||
This stack primarily holds return addresses for function calls.
|
||||
You normally won't need to directly interact with this stack,
|
||||
but you can use <span class="tt">push</span> and <span class="tt">pop</span> to move values between the
|
||||
data stack and this.
|
||||
<br/><br/>
|
||||
<span class="h2">Floating Point Stack</span>
|
||||
<br/><br/>
|
||||
If you are using a build with floating point support a third
|
||||
stack will be present. Floating point values are kept and
|
||||
passed between words using this.
|
||||
<br/><br/>
|
||||
See the Floating Point chapter for more details on this.
|
||||
<br/><br/>
|
||||
<span class="h2">Tips</span>
|
||||
<br/><br/>
|
||||
I recommend keeping the data stack shallow. Don't try to juggle
|
||||
too much; it's better to factor definitions into shorter ones
|
||||
that deal with simpler parts of the stack values than to have
|
||||
a big definition with a lot of complex shuffling.
|
||||
<br/><br/>
|
||||
<span class="h2">Notes</span>
|
||||
<br/><br/>
|
||||
The standard system is configured with a very deep data stack
|
||||
(around 2,000 items) and an address stack that is 3x deeper.
|
||||
In actual use, your programs are unlikely to ever need this,
|
||||
but if you do, keep the limits in mind.
|
||||
</p>
|
||||
</body></html>
|
||||
239
doc/html/chapters/techniques/using-combinators.html
Normal file
239
doc/html/chapters/techniques/using-combinators.html
Normal file
|
|
@ -0,0 +1,239 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Using Combinators</span>
|
||||
<br/><br/>
|
||||
A combinator is a function that consumes functions as input.
|
||||
They are used heavily by the RETRO system.
|
||||
<br/><br/>
|
||||
<span class="h2">Types of Combinators</span>
|
||||
<br/><br/>
|
||||
Combinators are divided into three primary types: compositional,
|
||||
execution flow, and data flow.
|
||||
<br/><br/>
|
||||
<span class="h2">Compositional</span>
|
||||
<br/><br/>
|
||||
A compositional combinator takes elements from the stack and
|
||||
returns a new quote.
|
||||
<br/><br/>
|
||||
<span class="tt">curry</span> takes a value and a quote and returns a new quote
|
||||
applying the specified quote to the specified value. As an
|
||||
example,
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:acc</span> <span class='note'>(n-)</span> here <span class='prim'>swap</span> , <span class='imm'>[</span> <span class='prim'>dup</span> v:inc <span class='prim'>fetch</span> <span class='imm'>]</span> curry <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
This would create an accumulator function, which takes an
|
||||
initial value and returns a quote that will increase the
|
||||
accumulator by 1 each time it is invoked. It will also return
|
||||
the latest value. So:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#10</span> acc </span><br/>
|
||||
<span class="tt"><span class='prim'>dup</span> <span class='prim'>call</span> n:put </span><br/>
|
||||
<span class="tt"><span class='prim'>dup</span> <span class='prim'>call</span> n:put </span><br/>
|
||||
<span class="tt"><span class='prim'>dup</span> <span class='prim'>call</span> n:put </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Execution Flow</span>
|
||||
<br/><br/>
|
||||
Combinators of this type execute other functions.
|
||||
<br/><br/>
|
||||
<span class="h3">Fundamental</span>
|
||||
<br/><br/>
|
||||
<span class="tt">call</span> takes a quote and executes it immediately.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='imm'>[</span> <span class='num'>#1</span> n:put <span class='imm'>]</span> <span class='prim'>call</span> </span><br/>
|
||||
<span class="tt"><span class='ptr'>&words</span> <span class='prim'>call</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h3">Conditionals</span>
|
||||
<br/><br/>
|
||||
RETRO provides three primary combinators for use with
|
||||
conditional execution of quotes. These are <span class="tt">choose</span>, <span class="tt">if</span>,
|
||||
and <span class="tt">-if</span>.
|
||||
<br/><br/>
|
||||
<span class="tt">choose</span> takes a flag and two quotes from the stack. If the
|
||||
flag is true, the first quote is executed. If false, the
|
||||
second quote is executed.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#-1</span> <span class='imm'>[</span> <span class='str'>'true</span> s:put <span class='imm'>]</span> <span class='imm'>[</span> <span class='str'>'false</span> s:put <span class='imm'>]</span> choose </span><br/>
|
||||
<span class="tt"> <span class='num'>#0</span> <span class='imm'>[</span> <span class='str'>'true</span> s:put <span class='imm'>]</span> <span class='imm'>[</span> <span class='str'>'false</span> s:put <span class='imm'>]</span> choose </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="tt">if</span> takes a flag and one quote from the stack. If the flag is
|
||||
true, the quote is executed. If false, the quote is discarded.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#-1</span> <span class='imm'>[</span> <span class='str'>'true</span> s:put <span class='imm'>]</span> <span class='prim'>if</span> </span><br/>
|
||||
<span class="tt"> <span class='num'>#0</span> <span class='imm'>[</span> <span class='str'>'true</span> s:put <span class='imm'>]</span> <span class='prim'>if</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="tt">-if</span> takes a flag and one quote from the stack. If the flag is
|
||||
false, the quote is executed. If true, the quote is discarded.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#-1</span> <span class='imm'>[</span> <span class='str'>'false</span> s:put <span class='imm'>]</span> -if </span><br/>
|
||||
<span class="tt"> <span class='num'>#0</span> <span class='imm'>[</span> <span class='str'>'false</span> s:put <span class='imm'>]</span> -if </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
RETRO also provides <span class="tt">case</span> and <span class="tt">s:case</span> for use when you have
|
||||
multiple values to check against. This is similar to a <span class="tt">switch</span>
|
||||
in C.
|
||||
<br/><br/>
|
||||
<span class="tt">case</span> takes two numbers and a quote. The initial value is
|
||||
compared to the second one. If they match, the quote is
|
||||
executed. If false, the quote is discarded and the initial
|
||||
value is left on the stack.
|
||||
<br/><br/>
|
||||
Additionally, if the first value was matched, <span class="tt">case</span> will exit
|
||||
the calling function, but if false, it returns to the calling
|
||||
function.
|
||||
<br/><br/>
|
||||
<span class="tt">s:case</span> works the same way, but for strings instead of simple
|
||||
values.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:test</span> <span class='note'>(n-)</span> </span><br/>
|
||||
<span class="tt"> <span class='num'>#1</span> <span class='imm'>[</span> <span class='str'>'Yes</span> s:put <span class='imm'>]</span> case </span><br/>
|
||||
<span class="tt"> <span class='num'>#2</span> <span class='imm'>[</span> <span class='str'>'No</span> s:put <span class='imm'>]</span> case </span><br/>
|
||||
<span class="tt"> <span class='prim'>drop</span> <span class='str'>'No</span> idea s:put <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h3">Looping</span>
|
||||
<br/><br/>
|
||||
Several combinators are available for handling various looping
|
||||
constructs.
|
||||
<br/><br/>
|
||||
<span class="tt">while</span> takes a quote from the stack and executes it repeatedly
|
||||
as long as the quote returns a true flag on the stack. This flag
|
||||
must be well formed and equal -1 or 0.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#10</span> <span class='imm'>[</span> <span class='prim'>dup</span> n:put sp n:dec <span class='prim'>dup</span> 0 <span class='prim'>-eq?</span> <span class='imm'>]</span> while </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="tt">times</span> takes a count and quote from the stack. The quote will
|
||||
be executed the number of times specified. No indexes are pushed
|
||||
to the stack.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#1</span> <span class='num'>#10</span> <span class='imm'>[</span> <span class='prim'>dup</span> n:put sp n:inc <span class='imm'>]</span> times <span class='prim'>drop</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
There is also a <span class="tt">indexed-times</span> variation that provides
|
||||
access to the loop index (via <span class="tt">I</span>) and parent loop indexes
|
||||
(via <span class="tt">J</span> and <span class="tt">K</span>).
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#10</span> <span class='imm'>[</span> I n:put sp <span class='imm'>]</span> indexed-times </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Data Flow</span>
|
||||
<br/><br/>
|
||||
These combinators exist to simplify stack usage in various
|
||||
circumstances.
|
||||
<br/><br/>
|
||||
<span class="h3">Preserving</span>
|
||||
<br/><br/>
|
||||
Preserving combinators execute code while preserving portions
|
||||
of the data stack.
|
||||
<br/><br/>
|
||||
<span class="tt">dip</span> takes a value and a quote, moves the value off the main
|
||||
stack temporarily, executes the quote, and then restores the
|
||||
value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#10</span> <span class='num'>#20</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> dip </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Would yield the following on the stack:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">11 20 </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="tt">sip</span> is similar to <span class="tt">dip</span>, but leaves a copy of the original
|
||||
value on the stack during execution of the quote. So:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#10</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> sip </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Leaves us with:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt">11 10 </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h3">Cleave</span>
|
||||
<br/><br/>
|
||||
Cleave combinators apply multiple quotations to a single value
|
||||
or set of values.
|
||||
<br/><br/>
|
||||
<span class="tt">bi</span> takes a value and two quotes, it then applies each quote to
|
||||
a copy of the value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#100</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> <span class='imm'>[</span> n:dec <span class='imm'>]</span> bi </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="tt">tri</span> takes a value and three quotes. It then applies each quote
|
||||
to a copy of the value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#100</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> <span class='imm'>[</span> n:dec <span class='imm'>]</span> <span class='imm'>[</span> <span class='prim'>dup</span> <span class='prim'>*</span> <span class='imm'>]</span> tri </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h3">Spread</span>
|
||||
<br/><br/>
|
||||
Spread combinators apply multiple quotations to multiple values.
|
||||
The asterisk suffixed to these function names signifies that
|
||||
they are spread combinators.
|
||||
<br/><br/>
|
||||
<span class="tt">bi*</span> takes two values and two quotes. It applies the first
|
||||
quote to the first value and the second quote to the second
|
||||
value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#1</span> <span class='num'>#2</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> <span class='imm'>[</span> <span class='num'>#2</span> <span class='prim'>*</span> <span class='imm'>]</span> bi* </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="tt">tri*</span> takes three values and three quotes, applying the
|
||||
first quote to the first value, the second quote to the
|
||||
second value, and the third quote to the third value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> <span class='imm'>[</span> <span class='num'>#2</span> <span class='prim'>*</span> <span class='imm'>]</span> <span class='imm'>[</span> n:dec <span class='imm'>]</span> tri* </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h3">Apply</span>
|
||||
<br/><br/>
|
||||
Apply combinators apply a single quotation to multiple values.
|
||||
The @ sign suffixed to these function names signifies that they
|
||||
are apply combinators.
|
||||
<br/><br/>
|
||||
<span class="tt">bi@</span> takes two values and a quote. It then applies the quote to
|
||||
each value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#1</span> <span class='num'>#2</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> bi@ </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="tt">tri@</span> takes three values and a quote. It then applies the quote
|
||||
to each value.
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='num'>#1</span> <span class='num'>#2</span> <span class='num'>#3</span> <span class='imm'>[</span> n:inc <span class='imm'>]</span> tri@ </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
RETRO also provides <span class="tt">for-each</span> combinators for various data
|
||||
structures. The exact usage of these varies; consult the
|
||||
Glossary and relevant chapters for more details on these.
|
||||
</p>
|
||||
</body></html>
|
||||
97
doc/html/chapters/techniques/word-classes.html
Normal file
97
doc/html/chapters/techniques/word-classes.html
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Word Classes</span>
|
||||
<br/><br/>
|
||||
Word classes are one of the two elements at the heart of
|
||||
RETRO's interpreter.
|
||||
<br/><br/>
|
||||
There are different types of words in a Forth system. At a
|
||||
minimum there are data words, regular words, and immediate
|
||||
words. There are numerous approaches to dealing with this.
|
||||
<br/><br/>
|
||||
In RETRO I define special words which receive a pointer and
|
||||
decide how to deal with it. These are grouped into a <span class="tt">class:</span>
|
||||
namespace.
|
||||
<br/><br/>
|
||||
<span class="h2">How It Works</span>
|
||||
<br/><br/>
|
||||
When a word is found in the dictionary, RETRO will push a
|
||||
pointer to the definition (the <span class="tt">d:xt</span> field) to the stack
|
||||
and then call the word specified by the <span class="tt">d:class</span> field.
|
||||
<br/><br/>
|
||||
The word called is responsible for processing the pointer
|
||||
passed to it.
|
||||
<br/><br/>
|
||||
As a simple case, let's look at <span class="tt">immediate</span> words. These are
|
||||
words which will always be called when encountered. A common
|
||||
strategy is to have an immediacy bit which the interpreter
|
||||
will look at, but RETRO uses a class for this. The class is
|
||||
defined:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:class:immediate</span> <span class='note'>(a-)</span> <span class='prim'>call</span> <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
Or a normal word. These should be called at interpret time
|
||||
or compiled into definitions. The handler for this can look
|
||||
like:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:class:word</span> <span class='note'>(a-)</span> compiling? <span class='imm'>[</span> compile:call <span class='imm'>]</span> <span class='imm'>[</span> <span class='prim'>call</span> <span class='imm'>]</span> choose <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt">```</span></span><br/><br/>
|
||||
<span class="h2">Using Classes</span>
|
||||
<br/><br/>
|
||||
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
|
||||
it with a class:
|
||||
<br/><br/>
|
||||
<span class='codeblock'><span class="tt">```</span><br/><span class="tt"><span class='colon'>:class:duplicating</span> <span class='note'>(a-)</span> </span><br/>
|
||||
<span class="tt"> compiling? <span class='imm'>[</span> <span class='ptr'>&dup</span> compile:call <span class='imm'>]</span> <span class='imm'>[</span> <span class='ptr'>&dup</span> dip <span class='imm'>]</span> choose </span><br/>
|
||||
<span class="tt"> class:word <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt"> </span><br/>
|
||||
<span class="tt"><span class='colon'>:duplicating</span> <span class='ptr'>&class:duplicating</span> reclass <span class='imm'>;</span> </span><br/>
|
||||
<span class="tt"> </span><br/>
|
||||
<span class="tt"><span class='colon'>:.</span> n:put nl <span class='imm'>;</span> duplicating </span><br/>
|
||||
<span class="tt"><span class='num'>#100</span> <span class='fnum'>.</span> <span class='fnum'>.</span> <span class='fnum'>.</span> </span><br/>
|
||||
<span class="tt">```</span></span></p>
|
||||
</body></html>
|
||||
129
doc/html/chapters/toolchain/info/additional-tools.html
Normal file
129
doc/html/chapters/toolchain/info/additional-tools.html
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">Additional Tools</span>
|
||||
<br/><br/>
|
||||
In addition to the core <span class="tt">retro</span> binary, the <span class="tt">bin</span> directory
|
||||
will contain a few other tools.
|
||||
<br/><br/>
|
||||
<span class="h2">retro</span>
|
||||
<br/><br/>
|
||||
This is the main RETRO binary.
|
||||
<br/><br/>
|
||||
<span class="h2">retro-describe</span>
|
||||
<br/><br/>
|
||||
This is a program that looks up entries in the Glossary.
|
||||
<br/><br/>
|
||||
At the command line, you can use it like:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-describe s:for-each</tt>
|
||||
<br/><br/>
|
||||
You can pass multiple word names to it:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-describe s:for-each nl d:words</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">retro-embedimage</span>
|
||||
<br/><br/>
|
||||
This is a program which generates a C file with the ngaImage
|
||||
contents. It's used when building <span class="tt">retro</span>.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-embedimage ngaImage</tt>
|
||||
<br/><br/>
|
||||
The output is written to stdout; redirect it as needed.
|
||||
<br/><br/>
|
||||
<span class="h2">retro-extend</span>
|
||||
<br/><br/>
|
||||
This is a program which compiles code into the ngaImage.
|
||||
It's used when building <span class="tt">retro</span> and when you want to make a
|
||||
standalone image with custom additions.
|
||||
<br/><br/>
|
||||
Example command line:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-extend ngaImage example/rot13.forth</tt>
|
||||
<br/><br/>
|
||||
Pass the image name as the first argument, and then file names
|
||||
as subsequent ones. Do <strong>not</strong> use this for things relying on I/O
|
||||
apart from the basic console output as it doesn't emulate other
|
||||
devices. If you need to load in things that rely on using the
|
||||
optional I/O devices, see the <strong></strong>Advanced Builds<strong></strong> chapter.
|
||||
<br/><br/>
|
||||
<span class="h2">retro-muri</span>
|
||||
<br/><br/>
|
||||
This is the assembler for Nga. It's used to build the initial
|
||||
RETRO kernel and can be used by other tools as well.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-muri retro.muri</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">retro-tags and retro-locate</span>
|
||||
<br/><br/>
|
||||
These tools are intended to be used together. The first tool,
|
||||
<span class="tt">retro-tags</span>, will recursively scan the current directory for
|
||||
RETRO source files and extract the locations of words defined
|
||||
in them. These will be written to disk in a <span class="tt">tags</span> file, using
|
||||
the standard ctags format.
|
||||
<br/><br/>
|
||||
<span class="tt">retro-locate</span> takes a word name, and returns the location(s)
|
||||
where it is defined. This requires a <span class="tt">tags</span> file to be present.
|
||||
<br/><br/>
|
||||
Create the <span class="tt">tags</span> file:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-tags</tt>
|
||||
<br/><br/>
|
||||
Locate a word:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-locate n:square</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">retro-unu</span>
|
||||
<br/><br/>
|
||||
This is the literate source extraction tool for RETRO. It
|
||||
is used in building <span class="tt">retro</span>.
|
||||
<br/><br/>
|
||||
Example usage:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-unu literate/RetroForth.md</tt>
|
||||
<br/><br/>
|
||||
Output is written to stdout; redirect as neeeded.
|
||||
</p>
|
||||
</body></html>
|
||||
101
doc/html/chapters/toolchain/info/retro-compiler.html
Normal file
101
doc/html/chapters/toolchain/info/retro-compiler.html
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><span class="h1">The Optional Retro Compiler</span>
|
||||
<br/><br/>
|
||||
In addition to the base system, users of RETRO on Unix hosts
|
||||
with ELF executables can build and use the <span class="tt">retro-compiler</span>
|
||||
to generate turnkey executables.
|
||||
<br/><br/>
|
||||
<span class="h2">Requirements</span>
|
||||
<br/><br/>
|
||||
• Unix host<br/>
|
||||
• ELF executable support<br/>
|
||||
• <span class="tt">objcopy</span> in the $PATH<br/>
|
||||
<br/><br/>
|
||||
<span class="h2">Building</span>
|
||||
<br/><br/>
|
||||
make bin/retro-compiler
|
||||
<br/><br/>
|
||||
<span class="h2">Installing</span>
|
||||
<br/><br/>
|
||||
Copy <span class="tt">bin/retro-compiler</span> to somewhere in your $PATH.
|
||||
<br/><br/>
|
||||
<span class="h2">Using</span>
|
||||
<br/><br/>
|
||||
<span class="tt">retro-compiler</span> takes two arguments: the source file to
|
||||
compile and the name of the word to use as the main entry
|
||||
point.
|
||||
<br/><br/>
|
||||
Example:
|
||||
<br/><br/>
|
||||
Given a <span class="tt">hello.forth</span>:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<tt class='indentedcode'>:hello 'Hello_World! s:put nl ;</tt>
|
||||
<tt class='indentedcode'>~~~</tt>
|
||||
<br/><br/>
|
||||
Use:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>retro-compiler hello.forth hello</tt>
|
||||
<br/><br/>
|
||||
The compiler will generate an <span class="tt">a.out</span> file which you can
|
||||
then rename.
|
||||
<br/><br/>
|
||||
<span class="h2">Known Limitations</span>
|
||||
<br/><br/>
|
||||
This does not provide the scripting support for command line
|
||||
arguments that the standard <span class="tt">retro</span> interface offers.
|
||||
<br/><br/>
|
||||
A copy of <span class="tt">objcopy</span> needs to be in the path for compilation
|
||||
to work.
|
||||
<br/><br/>
|
||||
The current working directory must be writable.
|
||||
<br/><br/>
|
||||
This only supports hosts using ELF executables.
|
||||
<br/><br/>
|
||||
The output file name is fixed to <span class="tt">a.out</span>.
|
||||
</p>
|
||||
</body></html>
|
||||
67
doc/html/chapters/toolchain/man/retro-describe.html
Normal file
67
doc/html/chapters/toolchain/man/retro-describe.html
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO-DESCRIBE(1) General Commands Manual RETRO-DESCRIBE(1)
|
||||
<br/><br/>
|
||||
RETRO-DESCRIBE
|
||||
<tt class='indentedcode'> retro-describe - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro-describe wordname [additional wordnames]</tt>
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro-describe is a tool for looking up the description and stack</tt>
|
||||
<tt class='indentedcode'> comments for words in the core language and extensions. It will write</tt>
|
||||
<tt class='indentedcode'> output to stdout.</tt>
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.4 May 2019 OpenBSD 6.4
|
||||
</p>
|
||||
</body></html>
|
||||
67
doc/html/chapters/toolchain/man/retro-document.html
Normal file
67
doc/html/chapters/toolchain/man/retro-document.html
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO-DOCUMENT(1) General Commands Manual RETRO-DOCUMENT(1)
|
||||
<br/><br/>
|
||||
RETRO-DOCUMENT
|
||||
<tt class='indentedcode'> retro-document - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro-document filename</tt>
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro-document is a tool for generating a listing of the descriptions and</tt>
|
||||
<tt class='indentedcode'> stack comments for all standard word used in a source file. It will write</tt>
|
||||
<tt class='indentedcode'> output to stdout.</tt>
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.4 May 2019 OpenBSD 6.4
|
||||
</p>
|
||||
</body></html>
|
||||
68
doc/html/chapters/toolchain/man/retro-embedimage.html
Normal file
68
doc/html/chapters/toolchain/man/retro-embedimage.html
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO-EMBEDIMAGE(1) General Commands Manual RETRO-EMBEDIMAGE(1)
|
||||
<br/><br/>
|
||||
RETRO-EMBEDIMAGE
|
||||
<tt class='indentedcode'> retro-embedimage - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro-embedimage [filename]</tt>
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro-embedimage loads the specified image (or `ngaImage` from the</tt>
|
||||
<tt class='indentedcode'> current directory if none is specified). It converts this into C code</tt>
|
||||
<tt class='indentedcode'> that can be compiled for inclusion in a RETRO executable. It will write</tt>
|
||||
<tt class='indentedcode'> the output to stdout.</tt>
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.4 February 2019 OpenBSD 6.4
|
||||
</p>
|
||||
</body></html>
|
||||
75
doc/html/chapters/toolchain/man/retro-extend.html
Normal file
75
doc/html/chapters/toolchain/man/retro-extend.html
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO-EXTEND(1) General Commands Manual RETRO-EXTEND(1)
|
||||
<br/><br/>
|
||||
RETRO-EXTEND
|
||||
<tt class='indentedcode'> retro-extend - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro-extend image filename [filenames]</tt>
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro-extend is a tool to load additional code into an image file. It</tt>
|
||||
<tt class='indentedcode'> takes the name of an image file and one or more source files to load into</tt>
|
||||
<tt class='indentedcode'> the image. After completion the image file will be updated with the</tt>
|
||||
<tt class='indentedcode'> changes.</tt>
|
||||
<br/><br/>
|
||||
<br/><br/>
|
||||
CAVEATS
|
||||
<tt class='indentedcode'> retro-extend only emulates the minimal console output device. If the</tt>
|
||||
<tt class='indentedcode'> source files require additional I/O to be present, the extend process</tt>
|
||||
<tt class='indentedcode'> will likely fail to work correctly.</tt>
|
||||
<br/><br/>
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.4 January 2021 OpenBSD 6.4
|
||||
</p>
|
||||
</body></html>
|
||||
66
doc/html/chapters/toolchain/man/retro-locate.html
Normal file
66
doc/html/chapters/toolchain/man/retro-locate.html
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO-LOCATE(1) General Commands Manual RETRO-LOCATE(1)
|
||||
<br/><br/>
|
||||
RETRO-LOCATE
|
||||
<tt class='indentedcode'> retro-locate - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro-locate wordname</tt>
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro-locate searches the tags file generated by retro-tags for the</tt>
|
||||
<tt class='indentedcode'> desired word name. Any matches are displayed, along with the line number.</tt>
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.6 January 2020 OpenBSD 6.6
|
||||
</p>
|
||||
</body></html>
|
||||
70
doc/html/chapters/toolchain/man/retro-muri.html
Normal file
70
doc/html/chapters/toolchain/man/retro-muri.html
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO-MURI(1) General Commands Manual RETRO-MURI(1)
|
||||
<br/><br/>
|
||||
RETRO-MURI
|
||||
<tt class='indentedcode'> retro-muri - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro-muri filename</tt>
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro-muri is an assembler for Nga, the virtual machine at the heart of</tt>
|
||||
<tt class='indentedcode'> Retro. It is used to build the image file containing the actual Retro</tt>
|
||||
<tt class='indentedcode'> language.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> This will extract the code blocks in the specified file and generate an</tt>
|
||||
<tt class='indentedcode'> image file named `ngaImage`.</tt>
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.4 February 2019 OpenBSD 6.4
|
||||
</p>
|
||||
</body></html>
|
||||
66
doc/html/chapters/toolchain/man/retro-tags.html
Normal file
66
doc/html/chapters/toolchain/man/retro-tags.html
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO-TAGS(1) General Commands Manual RETRO-TAGS(1)
|
||||
<br/><br/>
|
||||
RETRO-TAGS
|
||||
<tt class='indentedcode'> retro-tags - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro-tags</tt>
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro-tags is a tool for extracting code from fenced blocks in literate</tt>
|
||||
<tt class='indentedcode'> sources and generating a tags file compatible with ctags.</tt>
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.4 August 2019 OpenBSD 6.4
|
||||
</p>
|
||||
</body></html>
|
||||
91
doc/html/chapters/toolchain/man/retro.html
Normal file
91
doc/html/chapters/toolchain/man/retro.html
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml"><head>
|
||||
<title>.</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
tt, pre { background: #dedede; color: #111; font-family: monospace;
|
||||
white-space: pre; display: block; width: 100%; }
|
||||
.indentedcode { margin-left: 2em; margin-right: 2em; }
|
||||
.codeblock {
|
||||
background: #dedede; color: #111; font-family: monospace;
|
||||
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
|
||||
padding: 7px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
.indentedlist { margin-left: 2em; color: #000; }
|
||||
|
||||
span { white-space: pre; }
|
||||
.text { color: #000; white-space: pre; background: #dedede; }
|
||||
.colon { color: #000; background: #dedede; }
|
||||
.note { color: #000; background: #dedede; }
|
||||
.str { color: #000; text-decoration: underline; background: #dedede; }
|
||||
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
|
||||
.fnum { color: #000; font-weight: bold; background: #dedede; }
|
||||
.ptr { color: #000; font-weight: bold; background: #dedede; }
|
||||
.fetch { color: #000; font-style: italic; background: #dedede; }
|
||||
.store { color: #000; font-style: italic; background: #dedede; }
|
||||
.char { color: #000; background: #dedede; }
|
||||
.inst { color: #000; background: #dedede; }
|
||||
.defer { color: #000; background: #dedede; }
|
||||
.imm { color: #000; font-weight: bold; background: #dedede; }
|
||||
.prim { color: #000; font-weight: bolder; background: #dedede; }
|
||||
|
||||
.tt { white-space: pre; font-family: monospace; background: #dedede; }
|
||||
|
||||
.h1, .h2, .h3, .h4 { white-space: normal; }
|
||||
.h1 { font-size: 125%; }
|
||||
.h2 { font-size: 120%; }
|
||||
.h3 { font-size: 115%; }
|
||||
.h4 { font-size: 110%; }
|
||||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p>RETRO(1) General Commands Manual RETRO(1)
|
||||
<br/><br/>
|
||||
RETRO
|
||||
<tt class='indentedcode'> retro - a modern, pragmatic forth development system</tt>
|
||||
<br/><br/>
|
||||
SYNOPSIS
|
||||
<tt class='indentedcode'> retro [-h] [-i] [-t] [-f filename] [-u filename] [-r filename]</tt>
|
||||
[filename script-args]
|
||||
<br/><br/>
|
||||
DESCRIPTION
|
||||
<tt class='indentedcode'> RETRO is a modern, pragmatic Forth drawing influences from many sources.</tt>
|
||||
<tt class='indentedcode'> It's clean, elegant, tiny, and easy to grasp and adapt to various uses.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> retro is the main interface for interacting with Retro. It provides both</tt>
|
||||
<tt class='indentedcode'> an interactive and a scripting model.</tt>
|
||||
<br/><br/>
|
||||
OPTIONS
|
||||
<tt class='indentedcode'> -h Display a help screen.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> -i Start Retro in interactive mode.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> -s Start Retro in interactive mode and supress the startup message.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> -t Run any test blocks in the loaded files.</tt>
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> -f filename</tt>
|
||||
Run any code blocks in the specified file.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> -u filename</tt>
|
||||
Load and use the specified image file rather than the integral
|
||||
one.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> -r filename</tt>
|
||||
Load and run the code in the specified image file rather than
|
||||
the integral one.
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'> filename script-args</tt>
|
||||
Run code blocks in a single file. Pass script-args to the code
|
||||
being run.
|
||||
<br/><br/>
|
||||
AUTHORS
|
||||
<tt class='indentedcode'> Charles Childers <crc@forthworks.com></tt>
|
||||
<br/><br/>
|
||||
OpenBSD 6.4 September 2019 OpenBSD 6.4
|
||||
</p>
|
||||
</body></html>
|
||||
1
doc/html/index.html
Normal file
1
doc/html/index.html
Normal file
File diff suppressed because one or more lines are too long
81
tools/generate-html-docs.retro
Executable file
81
tools/generate-html-docs.retro
Executable file
|
|
@ -0,0 +1,81 @@
|
|||
#!/usr/bin/env retro
|
||||
|
||||
This tool is intended to be used to create an HTML version of the
|
||||
standard documentation.
|
||||
|
||||
Our structure will look like:
|
||||
|
||||
Book Root Directory
|
||||
|-- index.html
|
||||
|-- chapters/...
|
||||
|
||||
Begin by defining some helper functions for writing to a
|
||||
file.
|
||||
|
||||
~~~
|
||||
'tools/book-chapters.retro include
|
||||
|
||||
'FID var
|
||||
:file:s:put [ @FID file:write ] s:for-each ;
|
||||
:file:nl ASCII:CR @FID file:write ;
|
||||
:unix:mkdir 'mkdir_-p_%s s:format unix:system ;
|
||||
~~~
|
||||
|
||||
Create the directories needed.
|
||||
|
||||
~~~
|
||||
'Create_directories s:put nl
|
||||
{ 'chapters
|
||||
'chapters/building
|
||||
'chapters/general
|
||||
'chapters/internals
|
||||
'chapters/tech-notes
|
||||
'chapters/techniques
|
||||
'chapters/toolchain
|
||||
'chapters/toolchain/info
|
||||
'chapters/toolchain/man
|
||||
'html
|
||||
} [ dup tab s:put nl unix:mkdir ] a:for-each
|
||||
~~~
|
||||
|
||||
# Create the Index file
|
||||
|
||||
~~~
|
||||
'Generate_`index.html` s:put nl
|
||||
'html/index.html file:open-for-writing !FID
|
||||
|
||||
{ '<html>
|
||||
'<head>
|
||||
'____<meta_name="dtb:uid"_content="works.forth.retro-manual"/>
|
||||
'____<title>Retro_Forth:_Manual</title>
|
||||
'</head>
|
||||
'<body>
|
||||
'<h1>Retro_Forth</h1>
|
||||
} [ file:s:put file:nl ] a:for-each
|
||||
|
||||
:a:unpack [ ] a:for-each ;
|
||||
|
||||
TOC [ a:unpack '____•_<a_href="chapters/%s.html">%s</a><br> s:format file:s:put file:nl ] a:for-each
|
||||
|
||||
{ '</body>
|
||||
'</html>
|
||||
} [ file:s:put file:nl ] a:for-each
|
||||
|
||||
@FID file:close
|
||||
~~~
|
||||
|
||||
# Generate the Chapters
|
||||
|
||||
~~~
|
||||
'Convert_chapters_to_XHTML s:put nl
|
||||
'retro_tools/epub/chapters-to-xhtml.retro unix:system
|
||||
~~~
|
||||
|
||||
# Relocate Files
|
||||
|
||||
~~~
|
||||
'Relocate_files s:put nl
|
||||
'rm_-rf_doc/html unix:system
|
||||
'mv_chapters_html unix:system
|
||||
'mv_html_doc unix:system
|
||||
~~~
|
||||
Loading…
Reference in a new issue