fix #101: epub: chapter names are not rendered
FossilOrigin-Name: 7dd2b1bd7506c2c488b70620ba9d889f3a9a3d58f99b4dba1d6923e0ac0edb8d
This commit is contained in:
crc
parent
2f6d35485a
commit
5c52887aa8
66 changed files with 291 additions and 119 deletions
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/building/advanced</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Customizing the Build</span>
|
||||
<br/><br/>
|
||||
While a simple <span class="tt">make</span> will suffice for building Retro, there
|
||||
are a number of ways to customize the build to your needs.
|
||||
<br/><br/>
|
||||
|
|
@ -51,10 +52,11 @@ In this chapter, replace <span class="tt">Makefile</span> with <span class="tt">
|
|||
are using GNU Make (most Linux and macOS users will probably
|
||||
be using this).
|
||||
<br/><br/>
|
||||
<span class="h2">I/O Devices</span>
|
||||
<br/><br/>
|
||||
Many of the I/O devices are optional. The most common ones are
|
||||
enabled by default in the Makefile. Look near the end of the top
|
||||
section for lines starting with <span class="tt">ENABLED</span>:
|
||||
enabled by default in the Configuration.mk. Look for the lines
|
||||
starting with <span class="tt">ENABLED</span>:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>ENABLED ?=</tt>
|
||||
<tt class='indentedcode'>ENABLED += -DENABLE_FLOATS</tt>
|
||||
|
|
@ -86,11 +88,13 @@ If you want to build with sockets support, uncomment the
|
|||
<span class="tt"># ENABLED += -DENABLE_SOCKETS</span> and <span class="tt">DEVICES += interface/sockets.retro</span>
|
||||
lines before building.
|
||||
<br/><br/>
|
||||
<span class="h2">Compiler Flags</span>
|
||||
<br/><br/>
|
||||
You may need or want to adjust the compiler flags. In the first
|
||||
section of the <span class="tt">Makefile</span>, look for <span class="tt">CFLAGS</span> and add/change as
|
||||
desired to override the defaults.
|
||||
<br/><br/>
|
||||
<span class="h2">VM Tweaks</span>
|
||||
<br/><br/>
|
||||
<span class="h3">64-Bit</span>
|
||||
<br/><br/>
|
||||
|
|
@ -99,6 +103,7 @@ this to 64-bit though. For a one-off build:
|
|||
<br/><br/>
|
||||
<tt class='indentedcode'>make OPTIONS=-DBIT64</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Stack Size</span>
|
||||
<br/><br/>
|
||||
You can alter the stack sizes by defining <span class="tt">STACK_DEPTH</span> and
|
||||
<span class="tt">ADDRESSES</span>. For a one-off build with a max stack depth of 4000
|
||||
|
|
@ -106,6 +111,7 @@ items and 500 addresses on the return stack:
|
|||
<br/><br/>
|
||||
<tt class='indentedcode'>make OPTIONS="-DSTACK_DEPTH=4000 -DADDRESSES=500</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">Image Size</span>
|
||||
<br/><br/>
|
||||
You can also alter the image size. Again, for a one-off build:
|
||||
<br/><br/>
|
||||
|
|
@ -113,6 +119,7 @@ You can also alter the image size. Again, for a one-off build:
|
|||
<br/><br/>
|
||||
Would build a system with a maximum image size of 4,000,000 cells.
|
||||
<br/><br/>
|
||||
<span class="h3">Update the Makefile</span>
|
||||
<br/><br/>
|
||||
If you do any of these routinely, edit the Makefile to include them.
|
||||
<br/><br/>
|
||||
|
|
@ -122,6 +129,7 @@ If you do any of these routinely, edit the Makefile to include them.
|
|||
<tt class='indentedcode'>OPTIONS += -DADDRESSES=500</tt>
|
||||
<tt class='indentedcode'>OPTIONS += -DIMAGE_SIZE=4000000</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Further Image Customization</span>
|
||||
<br/><br/>
|
||||
You can customize the image further by having the build process
|
||||
include your code in the image.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/building/alternatives</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -125,11 +126,13 @@ Building:
|
|||
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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/building/obtaining</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,9 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
@ -62,6 +64,7 @@ URLs:
|
|||
• 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:
|
||||
|
|
@ -82,6 +85,7 @@ If you have problems, check the version of Fossil you are
|
|||
using. I am currently using Fossil 2.10, you may experience
|
||||
issues checking out or cloning if using older versions.
|
||||
<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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/building/unix</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
@ -74,6 +75,7 @@ In the <span class="tt">bin/</span> directory, you should see the following:
|
|||
<tt class='indentedcode'>retro-embedimage</tt>
|
||||
<tt class='indentedcode'>retro-describe</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Test The Build</span>
|
||||
<br/><br/>
|
||||
You can conduct a quick test of the build by running <span class="tt">bin/retro</span>:
|
||||
<br/><br/>
|
||||
|
|
@ -92,6 +94,7 @@ or:
|
|||
<br/><br/>
|
||||
<tt class='indentedcode'>sudo make install</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Platform Specific Notes</span>
|
||||
<br/><br/>
|
||||
<span class="h3">Linux</span>
|
||||
<br/><br/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/building/windows</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -54,6 +55,7 @@ This is currently more difficult than on a Unix host. If you have
|
|||
Windows 10 and WSL, it may be better to build under that (using
|
||||
the Unix instructions).
|
||||
<br/><br/>
|
||||
<span class="h2">Setup Build Environment</span>
|
||||
<br/><br/>
|
||||
Retro on Windows is built with TCC.
|
||||
<br/><br/>
|
||||
|
|
@ -63,6 +65,7 @@ Download the <strong>winapi-full</strong> and <strong>tcc-xxxx-bin</strong> pack
|
|||
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">vm/nga-c/retro.c</span> and the <span class="tt">vm/nga-c/image.c</span> to
|
||||
the directory you setup tcc into.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/basic-interactions</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/copyrights</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -54,6 +54,7 @@ United States.
|
|||
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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/deprecation</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/introduction</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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)
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/markdown</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,11 +43,13 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -63,6 +65,7 @@ level.
|
|||
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.
|
||||
|
|
@ -93,6 +96,7 @@ 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
|
||||
|
|
@ -116,6 +120,7 @@ the list marker can be used.
|
|||
<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/>
|
||||
|
|
@ -129,6 +134,7 @@ 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.
|
||||
|
|
@ -137,6 +143,7 @@ themselves.
|
|||
<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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/quick-tutorial</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/retro-unu</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
@ -86,6 +87,7 @@ This illustrates the format. Only code in the fenced blocks
|
|||
(Note: this only applies to source files; fences are not used
|
||||
when entering code interactively).
|
||||
<br/><br/>
|
||||
<span class="h2">On The Name</span>
|
||||
<br/><br/>
|
||||
The name Unu comes from the Maori language, where it means:
|
||||
<br/><br/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/starting</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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>
|
||||
|
|
@ -61,6 +62,7 @@ Or:
|
|||
<span class="tt">```</span></span><br/><br/>
|
||||
This should be sufficient for most uses.
|
||||
<br/><br/>
|
||||
<span class="h2">Using In a Pipe</span>
|
||||
<br/><br/>
|
||||
Retro will work with piped input.
|
||||
<br/><br/>
|
||||
|
|
@ -68,6 +70,7 @@ 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 </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/>
|
||||
|
|
@ -89,6 +92,7 @@ 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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/general/syntax</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -122,6 +122,7 @@ The major sigils are:
|
|||
The individual sigils 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,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/internals/calling-retro-from-c</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Calling Retro from C</span>
|
||||
<br/><br/>
|
||||
The C implementation of Retro provides several functions for
|
||||
interacting with code written in Retro.
|
||||
<br/><br/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/internals/image</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/internals/interface-layers</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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>.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/internals/io-devices</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">I/O Devices</span>
|
||||
<br/><br/>
|
||||
I/O devices on Nga are exposed via three instructions:
|
||||
<br/><br/>
|
||||
<tt class='indentedcode'>ie enumerate i/o devices</tt>
|
||||
|
|
@ -53,6 +54,7 @@ I/O devices on Nga are exposed via three instructions:
|
|||
All devices are registered with the VM. How this occurs is
|
||||
implementation dependent.
|
||||
<br/><br/>
|
||||
<span class="h2">Counting Devices</span>
|
||||
<br/><br/>
|
||||
Use the <span class="tt">ie</span> instruction to return the number of attached devices.
|
||||
<br/><br/>
|
||||
|
|
@ -61,12 +63,14 @@ Use the <span class="tt">ie</span> instruction to return the number of attached
|
|||
Upon running, the stack will contain the number of devices. You
|
||||
can then query these by passing the device number to <span class="tt">iq</span>.
|
||||
<br/><br/>
|
||||
<span class="h2">Query Devices</span>
|
||||
<br/><br/>
|
||||
Use <span class="tt">iq</span> to query an attached device. This will return two values,
|
||||
a device class and a revision number.
|
||||
<br/><br/>
|
||||
The device class will be the top value on the stack.
|
||||
<br/><br/>
|
||||
<span class="h2">Invoking a Device</span>
|
||||
<br/><br/>
|
||||
You can trigger an I/O operation by passing the device handle to
|
||||
the <span class="tt">ii</span> instruction.
|
||||
|
|
@ -79,6 +83,7 @@ E.g., to display a character (ASCII code 98 in this case):
|
|||
<br/><br/>
|
||||
Be sure to pass the device handle, not the device class.
|
||||
<br/><br/>
|
||||
<span class="h2">Device Class</span>
|
||||
<br/><br/>
|
||||
Ultimately devices are implementation-specific, but the
|
||||
standard system provides or reserves the following:
|
||||
|
|
@ -102,19 +107,23 @@ It must be noted here that nothing forces devices to use these
|
|||
class identifiers, and one must take care to use an Nga
|
||||
implementation that provides the devices they need.
|
||||
<br/><br/>
|
||||
<span class="h2">Device Revisions</span>
|
||||
<br/><br/>
|
||||
Over time, the functionality a device provides may change. To allow
|
||||
detection of this, the query functionality provides a revision number.
|
||||
Your code can use this to ensure that the device provided supports
|
||||
the level of functionality you need.
|
||||
<br/><br/>
|
||||
<span class="h2">Device Class Details</span>
|
||||
<br/><br/>
|
||||
<span class="h3">0000: Generic Output</span>
|
||||
<br/><br/>
|
||||
Supported by all Nga implementations. This is required to be the
|
||||
first device, and is the only one guaranteed to be provided. It
|
||||
consumes a value from the stack, writing to to the host-specific
|
||||
output. (This does not need to be a screen).
|
||||
<br/><br/>
|
||||
<span class="h3">0001: Keyboard</span>
|
||||
<br/><br/>
|
||||
Read and return a keypress.
|
||||
<br/><br/>
|
||||
|
|
@ -123,6 +132,7 @@ character that was read.
|
|||
<br/><br/>
|
||||
No subcommands are defined.
|
||||
<br/><br/>
|
||||
<span class="h3">0002: Floating Point</span>
|
||||
<br/><br/>
|
||||
The current revision is 1.
|
||||
<br/><br/>
|
||||
|
|
@ -159,9 +169,11 @@ It currently provides:
|
|||
<tt class='indentedcode'>f:pop (f:-f)</tt>
|
||||
<tt class='indentedcode'>f:adepth (-n)</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">0003: Block Storage</span>
|
||||
<br/><br/>
|
||||
Reserved for future use.
|
||||
<br/><br/>
|
||||
<span class="h3">0004: Filesystem</span>
|
||||
<br/><br/>
|
||||
Currently at revision 0.
|
||||
<br/><br/>
|
||||
|
|
@ -182,11 +194,13 @@ additional values.
|
|||
<tt class='indentedcode'>| 7 | s- | Delete a file |</tt>
|
||||
<tt class='indentedcode'>| 8 | h- | Flush pending writes |</tt>
|
||||
<br/><br/>
|
||||
<span class="h3">0010: Random Number Generator</span>
|
||||
<br/><br/>
|
||||
This is currently at revision 0.
|
||||
<br/><br/>
|
||||
On invocation, this returns a random number.
|
||||
<br/><br/>
|
||||
<span class="h2">Implementation Details (C)</span>
|
||||
<br/><br/>
|
||||
On the C implementation, each I/O device has the needed support
|
||||
functions defined, then a query function and invocation function
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/internals/io</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/internals/nga</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
@ -54,6 +55,7 @@ This is a very simple and straightforward system. There are
|
|||
bit values. And there are two stacks: one for data and one
|
||||
for return addresses.
|
||||
<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>
|
||||
|
|
@ -126,6 +128,7 @@ And returns a single one:
|
|||
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
|
||||
|
|
@ -139,6 +142,7 @@ addresses:
|
|||
<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:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/code-it-yourself</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/historical-papers</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,9 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -87,6 +89,7 @@ software on 90's and 00's hardware :)
|
|||
• 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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/kernel-words</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/metacompilation</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/ngaro-to-nga</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/prefixes</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h2">Sigils 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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/retro11-retrospective</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/security</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,10 +43,12 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
@ -66,6 +68,7 @@ into the C portions.
|
|||
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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/self-hosting</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/tech-notes/underscores-in-names</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/arrays</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Working With Arrays</span>
|
||||
<br/><br/>
|
||||
RETRO offers a number of words for operating on statically sized
|
||||
arrays.
|
||||
<br/><br/>
|
||||
|
|
@ -51,6 +52,7 @@ arrays.
|
|||
<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:
|
||||
|
|
@ -65,12 +67,14 @@ values and the number of values to store in the a:
|
|||
<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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/assembly</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,13 +43,15 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -111,6 +113,7 @@ each I/O instruction name. So a bundle may look like:
|
|||
<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:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/buffer</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
@ -70,6 +71,7 @@ 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.
|
||||
|
|
@ -77,16 +79,19 @@ an address.
|
|||
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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/characters</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Working With Characters</span>
|
||||
<br/><br/>
|
||||
RETRO provides words for working with ASCII characters.
|
||||
<br/><br/>
|
||||
<span class="h2">Sigil</span>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/checking-the-version</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -54,6 +55,7 @@ This can be also be used to conditionally load compatibility files:
|
|||
<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:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/definitions</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/dictionary</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Working With The Dictionary</span>
|
||||
<br/><br/>
|
||||
The Dictionary is a linked list containing the dictionary
|
||||
headers.
|
||||
<br/><br/>
|
||||
|
|
@ -56,6 +57,7 @@ Words operating on the dictionary are in the <span class="tt">d:</span> namespac
|
|||
<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/>
|
||||
|
|
@ -71,12 +73,14 @@ RETRO provides words for accessing the fields in a portable
|
|||
manner. It's recommended to use these to allow for future
|
||||
revision of the header structure.
|
||||
<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.
|
||||
|
|
@ -85,6 +89,7 @@ header.
|
|||
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
|
||||
|
|
@ -126,6 +131,7 @@ of all words:
|
|||
For each entry, this combinator will push a pointer to the
|
||||
entry to the stack and call the quotation.
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/errors</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/files</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,13 +43,15 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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
|
||||
|
|
@ -60,6 +62,7 @@ are:
|
|||
<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/>
|
||||
|
|
@ -90,11 +93,13 @@ To open a file for append operations:
|
|||
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.
|
||||
|
|
@ -111,6 +116,7 @@ text to a safe place if you aren't using it quickly or if
|
|||
the length of the line is bigger than the size of a temporary
|
||||
string.
|
||||
<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>.
|
||||
|
|
@ -124,11 +130,13 @@ To write a byte to a file, pass it and the file handle to
|
|||
Though cells are 32 or 64 bits in size, only the byte value will
|
||||
be written to the file.
|
||||
<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
|
||||
|
|
@ -138,12 +146,14 @@ it does not.
|
|||
<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.
|
||||
|
|
@ -153,6 +163,7 @@ for a given file. Pass this the new location and a file.
|
|||
The location for the file pointer is a fixed offset from the
|
||||
start of the file, not a relative offset.
|
||||
<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>.
|
||||
|
|
@ -162,6 +173,7 @@ just pass the file handle to <span class="tt">file:tell</span>.
|
|||
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
|
||||
|
|
@ -169,6 +181,7 @@ 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
|
||||
|
|
@ -179,6 +192,7 @@ region and the name of the file.
|
|||
Take care that the memory buffer is large enough for the file
|
||||
being read or you will run into problems.
|
||||
<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
|
||||
|
|
@ -186,6 +200,7 @@ 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,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/floating-point</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
@ -135,6 +136,7 @@ like infinity and NaN.
|
|||
• <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/>
|
||||
|
|
@ -172,6 +174,7 @@ related calculations.
|
|||
| <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
|
||||
|
|
@ -193,6 +196,7 @@ store and retrieve values using multiple cells.
|
|||
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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/lexical-scope</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -89,6 +90,7 @@ example:
|
|||
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.
|
||||
<br/><br/>
|
||||
<span class="h2">A Word of Warning</span>
|
||||
<br/><br/>
|
||||
Use of these words can result in a corrupt dictionary and system
|
||||
crashes. Specifically, use of <span class="tt">---reveal---</span> with an empty private
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/loops</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -47,6 +47,7 @@
|
|||
<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/>
|
||||
|
|
@ -71,6 +72,7 @@ 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
|
||||
|
|
@ -79,6 +81,7 @@ when to stop running.
|
|||
<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>.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/multicore</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Multiple Cores</span>
|
||||
<br/><br/>
|
||||
Nga has optional support for multiple virtual cores. These
|
||||
are not directly comparable to actual CPU cores, but do
|
||||
allow for a degree of multitasking.
|
||||
|
|
@ -83,6 +84,7 @@ Example:
|
|||
<br/><br/>
|
||||
<tt class='indentedcode'>#4 core:init</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Starting a Core</span>
|
||||
<br/><br/>
|
||||
Initialization does not activate a core. To do this, you need
|
||||
to use <span class="tt">core:start</span>. Pass this the address of the word to
|
||||
|
|
@ -93,6 +95,7 @@ Example:
|
|||
<tt class='indentedcode'>:a [ $a c:put ] forever ;</tt>
|
||||
<tt class='indentedcode'>&a #4 core:start</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Pausing a Core</span>
|
||||
<br/><br/>
|
||||
Two words are provided for suspending a core. The first is
|
||||
<span class="tt">core:pause</span>. Pass this the core number to pause.
|
||||
|
|
@ -108,6 +111,7 @@ Example:
|
|||
<br/><br/>
|
||||
<tt class='indentedcode'>core:pause-current</tt>
|
||||
<br/><br/>
|
||||
<span class="h2">Resuming a Core</span>
|
||||
<br/><br/>
|
||||
To reactive a core, use <span class="tt">core:resume</span>. This takes the core
|
||||
number to activate.
|
||||
|
|
@ -135,6 +139,7 @@ usable on Retro/Napia with minimal changes.
|
|||
The main differences are that under Nga, this is an optional
|
||||
extension, but in Napia, it is part of the standard system.
|
||||
<br/><br/>
|
||||
<span class="h2">Other Notes</span>
|
||||
<br/><br/>
|
||||
On startup, execution occurs on core 0, with only core 0 being
|
||||
initialized.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/naming-conventions</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,9 +43,11 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -55,6 +57,7 @@ Word names in RETRO generally follow the following conventions.
|
|||
• 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/>
|
||||
|
|
@ -112,6 +115,7 @@ The common namespaces are:
|
|||
<br/><br/>
|
||||
<span class="h2">Tips</span>
|
||||
<br/><br/>
|
||||
<span class="h3">Don't Start Names With Sigil Characters</span>
|
||||
<br/><br/>
|
||||
Avoid using a sigil as the first character of a word name. RETRO
|
||||
will look for sigils first, this will prevent direct use of
|
||||
|
|
@ -121,6 +125,7 @@ To find a list of sigil characters, do:
|
|||
<br/><br/>
|
||||
<tt class='indentedcode'>'sigil: 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:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/numbers</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Working With Numbers</span>
|
||||
<br/><br/>
|
||||
Numbers in RETRO are signed integers.
|
||||
<br/><br/>
|
||||
<span class="h2">Sigil</span>
|
||||
|
|
@ -54,6 +55,7 @@ All numbers start with a <span class="tt">#</span> sigil.
|
|||
<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
|
||||
|
|
@ -90,6 +92,7 @@ Additionally RETRO also provides:
|
|||
<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>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/pointers</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Working With Pointers</span>
|
||||
<br/><br/>
|
||||
<span class="h2">Sigil</span>
|
||||
<br/><br/>
|
||||
Pointers are returned by the <span class="tt">&</span> sigil.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/quotes</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -48,6 +48,7 @@
|
|||
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/>
|
||||
|
|
@ -78,6 +79,7 @@ A quotation is compiled as:
|
|||
<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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/return-stack</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/scripting</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<p><span class="h1">Unix Scripting</span>
|
||||
<br/><br/>
|
||||
RETRO on Unix hosts is designed to play well with scripting.
|
||||
<br/><br/>
|
||||
Shebang
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/sockets</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -48,6 +48,7 @@
|
|||
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/>
|
||||
|
|
@ -55,6 +56,7 @@ To create a new socket, just run:
|
|||
<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
|
||||
|
|
@ -62,6 +64,7 @@ to <span class="tt">socket:bind</span>. The port should be a string. This will r
|
|||
<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
|
||||
|
|
@ -69,12 +72,14 @@ will take a backlog count and a socket handle. It returns a flag
|
|||
<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/>
|
||||
|
|
@ -83,6 +88,7 @@ To connect to a server using the socket:
|
|||
<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
|
||||
|
|
@ -90,6 +96,7 @@ 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
|
||||
|
|
@ -98,6 +105,7 @@ 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/>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/stack-diagrams</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/strings</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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).
|
||||
|
|
@ -177,6 +178,7 @@ which let you trim just the leading or trailing end as desired.
|
|||
• <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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/the-stacks</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
@ -51,12 +52,14 @@ function calls.
|
|||
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/>
|
||||
|
|
@ -67,6 +70,7 @@ Values can be placed on the stack directly.
|
|||
<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.
|
||||
|
|
@ -109,15 +113,19 @@ 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
|
||||
|
|
@ -129,12 +137,14 @@ structured means of working.
|
|||
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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/using-combinators</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,10 +43,12 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
@ -72,6 +74,7 @@ the latest value. So:
|
|||
<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/>
|
||||
|
|
@ -151,6 +154,7 @@ access to the loop index (via <span class="tt">I</span>) and parent loop indexes
|
|||
<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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/techniques/word-classes</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -55,6 +56,7 @@ In RETRO I define special words which receive a pointer and
|
|||
decide how to deal with it. These are grouped into a <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
|
||||
|
|
@ -77,6 +79,7 @@ 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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/info/additional-tools</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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/>
|
||||
|
|
@ -95,6 +96,7 @@ 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
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/info/retro-compiler</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
@ -43,7 +43,8 @@
|
|||
.hr { display: block; height: 2px; background: #000000; }
|
||||
</style>
|
||||
</head><body>
|
||||
<p><br/><br/>
|
||||
<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.
|
||||
|
|
@ -83,6 +84,7 @@ Use:
|
|||
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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro-describe</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro-document</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro-embedimage</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro-extend</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro-locate</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro-muri</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro-tags</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<?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>
|
||||
<title>doc/book/toolchain/man/retro</title>
|
||||
<style type="text/css">
|
||||
|
||||
* { color: #000; background: #fff; max-width: 700px; }
|
||||
|
|
|
|||
|
|
@ -95,7 +95,7 @@ work nicely, so I start with some header stuff.
|
|||
'<!DOCTYPE_html_PUBLIC_"-//W3C//DTD_XHTML_1.1//EN" s:put sp
|
||||
'"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> s:put nl
|
||||
'<html_xmlns="http://www.w3.org/1999/xhtml"><head> s:put nl
|
||||
'<title>.</title> s:put nl
|
||||
#0 script:get-argument '<title>%s</title> s:format s:put nl
|
||||
~~~
|
||||
|
||||
Locate and embed the CSS from the end of this file. The CSS
|
||||
|
|
|
|||
Loading…
Reference in a new issue