Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| Comment: | fix #101: epub: chapter names are not rendered |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
7dd2b1bd7506c2c488b70620ba9d889f |
| User & Date: | crc 2024-09-06 10:39:30 |
Context
|
2024-09-09
| ||
| 11:50 | add a d:stack field to hold a pointer to a stack comment for a word (currently unused) check-in: 638db3d5ba user: crc tags: trunk | |
|
2024-09-06
| ||
| 10:39 | fix #101: epub: chapter names are not rendered check-in: 7dd2b1bd75 user: crc tags: trunk | |
| 10:13 | fix #102: glossary: a:last description is same as a:left check-in: 23dffad274 user: crc tags: trunk | |
Changes
Changes to doc/html/chapters/building/advanced.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/building/advanced</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 |
.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">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/>
In this chapter, replace <span class="tt">Makefile</span> with <span class="tt">GNUmakefile</span> if you
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 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>
<tt class='indentedcode'>ENABLED += -DENABLE_FILES</tt>
<tt class='indentedcode'>ENABLED += -DENABLE_UNIX</tt>
<tt class='indentedcode'>ENABLED += -DENABLE_RNG</tt>
<tt class='indentedcode'>ENABLED += -DENABLE_CLOCK</tt>
|
| ︙ | ︙ | |||
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 | For the FFI, on Linux, you will need to link with <span class="tt">libdl</span>. Edit the <span class="tt">GNUmakefile</span> to uncomment the <span class="tt"># LIBDL += -ldl</span> line. <br/><br/> 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/> <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/> <br/><br/> <span class="h3">64-Bit</span> <br/><br/> A standard Retro system uses a 32-bit word size. You can increase this to 64-bit though. For a one-off build: <br/><br/> <tt class='indentedcode'>make OPTIONS=-DBIT64</tt> <br/><br/> <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 items and 500 addresses on the return stack: <br/><br/> <tt class='indentedcode'>make OPTIONS="-DSTACK_DEPTH=4000 -DADDRESSES=500</tt> <br/><br/> <br/><br/> You can also alter the image size. Again, for a one-off build: <br/><br/> <tt class='indentedcode'>make OPTIONS=-DIMAGE_SIZE=4000000</tt> <br/><br/> Would build a system with a maximum image size of 4,000,000 cells. <br/><br/> <br/><br/> If you do any of these routinely, edit the Makefile to include them. <br/><br/> <tt class='indentedcode'>OPTIONS ?=</tt> <tt class='indentedcode'>OPTIONS += -DBIT64</tt> <tt class='indentedcode'>OPTIONS += -DSTACK_DEPTH=4000</tt> <tt class='indentedcode'>OPTIONS += -DADDRESSES=500</tt> <tt class='indentedcode'>OPTIONS += -DIMAGE_SIZE=4000000</tt> <br/><br/> <br/><br/> You can customize the image further by having the build process include your code in the image. <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. | > > > > > > | 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | For the FFI, on Linux, you will need to link with <span class="tt">libdl</span>. Edit the <span class="tt">GNUmakefile</span> to uncomment the <span class="tt"># LIBDL += -ldl</span> line. <br/><br/> 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/> A standard Retro system uses a 32-bit word size. You can increase 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 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/> <tt class='indentedcode'>make OPTIONS=-DIMAGE_SIZE=4000000</tt> <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/> <tt class='indentedcode'>OPTIONS ?=</tt> <tt class='indentedcode'>OPTIONS += -DBIT64</tt> <tt class='indentedcode'>OPTIONS += -DSTACK_DEPTH=4000</tt> <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. <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. |
| ︙ | ︙ |
Changes to doc/html/chapters/building/alternatives.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/building/alternatives</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ | |||
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | <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/> <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/> <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/> | > > | 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | <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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/building/obtaining.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/building/obtaining</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 |
.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>
|
| ︙ | ︙ |
Changes to doc/html/chapters/building/unix.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/building/unix</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ | |||
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 | <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/> <br/><br/> You can conduct a quick test of the build by running <span class="tt">bin/retro</span>: <br/><br/> <tt class='indentedcode'>./bin/retro</tt> <br/><br/> Exit by typing <span class="tt">bye</span> and pressing enter. <br/><br/> <span class="h2">Installation</span> <br/><br/> You can install Retro globally on BSD systems (and possibly Linux) by doing: <br/><br/> <tt class='indentedcode'>doas make install</tt> <br/><br/> or: <br/><br/> <tt class='indentedcode'>sudo make install</tt> <br/><br/> <br/><br/> <span class="h3">Linux</span> <br/><br/> To build on Linux, you need to link with <strong>libdl</strong> if using the optional FFI. To do this, edit the <span class="tt">GNUmakefile</span> and uncomment this before building: <br/><br/> <tt class='indentedcode'># LIBDL += -ldl</tt> | > > | 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 | <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">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/> <tt class='indentedcode'>./bin/retro</tt> <br/><br/> Exit by typing <span class="tt">bye</span> and pressing enter. <br/><br/> <span class="h2">Installation</span> <br/><br/> You can install Retro globally on BSD systems (and possibly Linux) by doing: <br/><br/> <tt class='indentedcode'>doas make install</tt> <br/><br/> 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/> To build on Linux, you need to link with <strong>libdl</strong> if using the optional FFI. To do this, edit the <span class="tt">GNUmakefile</span> and uncomment this before building: <br/><br/> <tt class='indentedcode'># LIBDL += -ldl</tt> |
| ︙ | ︙ |
Changes to doc/html/chapters/building/windows.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/building/windows</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 |
.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">vm/nga-c/retro.c</span> and the <span class="tt">vm/nga-c/image.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.c -o retro.exe</tt>
</p>
</body></html>
|
Changes to doc/html/chapters/general/basic-interactions.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/basic-interactions</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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 (2021.7)</tt>
|
| ︙ | ︙ |
Changes to doc/html/chapters/general/copyrights.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/copyrights</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 {
|
| ︙ | ︙ | |||
50 51 52 53 54 55 56 57 58 59 60 61 62 63 | 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/> <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"). | > | 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | 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"). |
| ︙ | ︙ |
Changes to doc/html/chapters/general/deprecation.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/deprecation</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 |
.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>
|
Changes to doc/html/chapters/general/introduction.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/introduction</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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
|
| ︙ | ︙ |
Changes to doc/html/chapters/general/markdown.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/markdown</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
.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.
|
| ︙ | ︙ | |||
89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <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/> <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/> | > | 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | <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/> |
| ︙ | ︙ | |||
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 |
<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/>
<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/>
<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/>
<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>
| > > > | 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 |
<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>
|
Changes to doc/html/chapters/general/quick-tutorial.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/quick-tutorial</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ |
Changes to doc/html/chapters/general/retro-unu.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/retro-unu</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ | |||
82 83 84 85 86 87 88 89 90 91 92 93 94 95 | <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/> <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> | > | 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | <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> |
Changes to doc/html/chapters/general/starting.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/starting</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 |
.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>.
<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/>
<span class="h2">Using In a Pipe</span>
<br/><br/>
Retro will work with piped input.
<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 </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>
|
| ︙ | ︙ | |||
85 86 87 88 89 90 91 92 93 94 95 96 97 98 | <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/> <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/> | > | 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/general/syntax.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/general/syntax</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 {
|
| ︙ | ︙ | |||
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | <tt class='indentedcode'>| ' | Strings |</tt> <tt class='indentedcode'>| ( | Comments |</tt> <tt class='indentedcode'>| : | Define a word |</tt> <br/><br/> The individual sigils will be covered in more detail in the later chapters on working with different data types. <br/><br/> <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> | > | 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | <tt class='indentedcode'>| ' | Strings |</tt> <tt class='indentedcode'>| ( | Comments |</tt> <tt class='indentedcode'>| : | Define a word |</tt> <br/><br/> 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, but essentially they decide <strong>how</strong> to execute or compile specific types of words. <br/><br/> </p> </body></html> |
Changes to doc/html/chapters/internals/calling-retro-from-c.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/internals/calling-retro-from-c</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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">Calling Retro from C</span>
<br/><br/>
The C implementation of Retro provides several functions for
interacting with code written in Retro.
<br/><br/>
<span class="h2">Dictionary</span>
<br/><br/>
The dictionary is a linked list, with a pointer to the most
recent entry stored in address 2.
|
| ︙ | ︙ |
Changes to doc/html/chapters/internals/image.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/internals/image</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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
|
| ︙ | ︙ |
Changes to doc/html/chapters/internals/interface-layers.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/internals/interface-layers</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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>.
|
| ︙ | ︙ |
Changes to doc/html/chapters/internals/io-devices.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/internals/io-devices</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 |
.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">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>
<tt class='indentedcode'>iq query i/o device for class and version</tt>
<tt class='indentedcode'>ii invoke i/o interaction</tt>
<br/><br/>
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/>
<tt class='indentedcode'>i ie......</tt>
<br/><br/>
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.
<br/><br/>
E.g., to display a character (ASCII code 98 in this case):
<br/><br/>
<tt class='indentedcode'>i liliii..</tt>
<tt class='indentedcode'>d 98</tt>
<tt class='indentedcode'>d 0</tt>
<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:
<br/><br/>
<tt class='indentedcode'> ID | Device Class | Notes |</tt>
<tt class='indentedcode'>-----+------------------+----------------------------+</tt>
<tt class='indentedcode'>0000 | Generic Output | Always present as handle 0 |</tt>
|
| ︙ | ︙ | |||
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | <tt class='indentedcode'>0010 | Random Number | |</tt> <tt class='indentedcode'>1000 | Image Saving | |</tt> <br/><br/> 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/> <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/> <br/><br/> <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/> <br/><br/> Read and return a keypress. <br/><br/> Consumes no data, returns a single value representing the character that was read. <br/><br/> No subcommands are defined. <br/><br/> <br/><br/> The current revision is 1. <br/><br/> It currently provides: <br/><br/> <tt class='indentedcode'>n:to-float (n-_f:-n)</tt> <tt class='indentedcode'>s:to-float (s-_f:-n)</tt> | > > > > > | 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | <tt class='indentedcode'>0010 | Random Number | |</tt> <tt class='indentedcode'>1000 | Image Saving | |</tt> <br/><br/> 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/> Consumes no data, returns a single value representing the 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/> It currently provides: <br/><br/> <tt class='indentedcode'>n:to-float (n-_f:-n)</tt> <tt class='indentedcode'>s:to-float (s-_f:-n)</tt> |
| ︙ | ︙ | |||
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 | <tt class='indentedcode'>f:asin (f:f-f)</tt> <tt class='indentedcode'>f:acos (f:f-f)</tt> <tt class='indentedcode'>f:atan (f:f-f)</tt> <tt class='indentedcode'>f:push (f:f-)</tt> <tt class='indentedcode'>f:pop (f:-f)</tt> <tt class='indentedcode'>f:adepth (-n)</tt> <br/><br/> <br/><br/> Reserved for future use. <br/><br/> <br/><br/> Currently at revision 0. <br/><br/> This implements a device providing traditional Unix-like files. <br/><br/> Takes a value indicating an operation, and each operation takes additional values. <br/><br/> <tt class='indentedcode'>| Operation | Stack | Action |</tt> <tt class='indentedcode'>| --------- | ----- | -------------------------------- |</tt> <tt class='indentedcode'>| 0 | sm-h | Open a file |</tt> <tt class='indentedcode'>| 1 | h- | Close a file |</tt> <tt class='indentedcode'>| 2 | h-c | Read a byte from a file |</tt> <tt class='indentedcode'>| 3 | ch- | Write a byte to a file |</tt> <tt class='indentedcode'>| 4 | h-n | Return current pointer into file |</tt> <tt class='indentedcode'>| 5 | nh- | Move pointer in a file |</tt> <tt class='indentedcode'>| 6 | h-n | Return the size of a file |</tt> <tt class='indentedcode'>| 7 | s- | Delete a file |</tt> <tt class='indentedcode'>| 8 | h- | Flush pending writes |</tt> <br/><br/> <br/><br/> This is currently at revision 0. <br/><br/> On invocation, this returns a random number. <br/><br/> <br/><br/> On the C implementation, each I/O device has the needed support functions defined, then a query function and invocation function defined. <br/><br/> As an example, to add a device that has two functions, I might do: <br/><br/> | > > > > | 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | <tt class='indentedcode'>f:asin (f:f-f)</tt> <tt class='indentedcode'>f:acos (f:f-f)</tt> <tt class='indentedcode'>f:atan (f:f-f)</tt> <tt class='indentedcode'>f:push (f:f-)</tt> <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/> This implements a device providing traditional Unix-like files. <br/><br/> Takes a value indicating an operation, and each operation takes additional values. <br/><br/> <tt class='indentedcode'>| Operation | Stack | Action |</tt> <tt class='indentedcode'>| --------- | ----- | -------------------------------- |</tt> <tt class='indentedcode'>| 0 | sm-h | Open a file |</tt> <tt class='indentedcode'>| 1 | h- | Close a file |</tt> <tt class='indentedcode'>| 2 | h-c | Read a byte from a file |</tt> <tt class='indentedcode'>| 3 | ch- | Write a byte to a file |</tt> <tt class='indentedcode'>| 4 | h-n | Return current pointer into file |</tt> <tt class='indentedcode'>| 5 | nh- | Move pointer in a file |</tt> <tt class='indentedcode'>| 6 | h-n | Return the size of a file |</tt> <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 defined. <br/><br/> As an example, to add a device that has two functions, I might do: <br/><br/> |
| ︙ | ︙ |
Changes to doc/html/chapters/internals/io.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/internals/io</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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,
|
| ︙ | ︙ |
Changes to doc/html/chapters/internals/nga.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/internals/nga</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
.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>
|
| ︙ | ︙ | |||
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | 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/> <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/> <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> | > > | 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | 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> |
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/code-it-yourself.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/code-it-yourself</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/historical-papers.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/historical-papers</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
.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
|
| ︙ | ︙ | |||
83 84 85 86 87 88 89 90 91 92 93 94 95 96 | <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/> <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 | > | 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | <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 |
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/kernel-words.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/kernel-words</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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.
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/metacompilation.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/metacompilation</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/ngaro-to-nga.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/ngaro-to-nga</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/prefixes.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/prefixes</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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">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
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
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/retro11-retrospective.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/retro11-retrospective</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/security.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/security</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
.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
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/self-hosting.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/self-hosting</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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,
|
| ︙ | ︙ |
Changes to doc/html/chapters/tech-notes/underscores-in-names.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/tech-notes/underscores-in-names</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/arrays.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/arrays</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 |
.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/>
|
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/assembly.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/assembly</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
.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>
|
| ︙ | ︙ | |||
107 108 109 110 111 112 113 114 115 116 117 118 119 120 | 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/> <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: | > | 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | 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: |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/buffer.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/buffer</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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>
|
| ︙ | ︙ | |||
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | <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/> <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/> <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/> <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/> <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> | > > > > | 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 | <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> |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/characters.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/characters</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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">Sigil</span>
<br/><br/>
Character constants are returned using the <span class="tt">$</span> sigil.
<br/><br/>
<span class="h2">Namespace</span>
|
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/checking-the-version.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/checking-the-version</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
.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>
|
Changes to doc/html/chapters/techniques/definitions.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/definitions</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 |
.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>
|
Changes to doc/html/chapters/techniques/dictionary.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/dictionary</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 |
.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 Source Identifier</tt>
<tt class='indentedcode'>0004+ 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:
|
| ︙ | ︙ | |||
122 123 124 125 126 127 128 129 130 131 132 133 134 135 | 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/> <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 | > | 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 | 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 |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/errors.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/errors</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/files.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/files</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 |
.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.
|
| ︙ | ︙ | |||
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | 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/> <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/> <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/> <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/> <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/> <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/> <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/> <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/> <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/> <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/> <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/> <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/> <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> | > > > > > > > > > > > > | 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 | 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> |
Changes to doc/html/chapters/techniques/floating-point.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/floating-point</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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
|
| ︙ | ︙ | |||
131 132 133 134 135 136 137 138 139 140 141 142 143 144 | 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/> <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/> | > | 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 | 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/> |
| ︙ | ︙ | |||
168 169 170 171 172 173 174 175 176 177 178 179 180 181 | | <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/> <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 | > | 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | | <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 |
| ︙ | ︙ | |||
189 190 191 192 193 194 195 196 197 198 199 200 201 202 | • <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/> <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/> | > | 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | • <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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/lexical-scope.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/lexical-scope</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ | |||
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | <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. <br/><br/> <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 or public section will result in dictionary corruption. <br/><br/> If you don't need private words, don't put them in a scope. And if you don't need public words, don't include the <span class="tt">---reveal---</span>. </p> </body></html> | > | 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <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. <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 or public section will result in dictionary corruption. <br/><br/> If you don't need private words, don't put them in a scope. And if you don't need public words, don't include the <span class="tt">---reveal---</span>. </p> </body></html> |
Changes to doc/html/chapters/techniques/loops.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/loops</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 {
|
| ︙ | ︙ | |||
43 44 45 46 47 48 49 50 51 52 53 54 55 56 |
.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/>
<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
| > | 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 |
.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
|
| ︙ | ︙ | |||
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | <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/> <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/> <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/> | > > | 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | <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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/multicore.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/multicore</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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">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.
<br/><br/>
Cores share a single address space for RAM, but each gets
its own data and address stacks, as well as 24 internal
registers for private data storage. The floating point stack
|
| ︙ | ︙ | |||
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | to <span class="tt">core:init</span>. This will zero out its internal registers and set it to. <br/><br/> Example: <br/><br/> <tt class='indentedcode'>#4 core:init</tt> <br/><br/> <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 run and the core number. <br/><br/> Example: <br/><br/> <tt class='indentedcode'>:a [ $a c:put ] forever ;</tt> <tt class='indentedcode'>&a #4 core:start</tt> <br/><br/> <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. <br/><br/> Example: <br/><br/> <tt class='indentedcode'>#4 core:pause</tt> <br/><br/> The second option is intended if you need the currently active core to pause. This word is <span class="tt">core:pause-current</span>. <br/><br/> Example: <br/><br/> <tt class='indentedcode'>core:pause-current</tt> <br/><br/> <br/><br/> To reactive a core, use <span class="tt">core:resume</span>. This takes the core number to activate. <br/><br/> Example: <br/><br/> <tt class='indentedcode'>#4 core:resume</tt> | > > > | 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | to <span class="tt">core:init</span>. This will zero out its internal registers and set it to. <br/><br/> 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 run and the core number. <br/><br/> Example: <br/><br/> <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. <br/><br/> Example: <br/><br/> <tt class='indentedcode'>#4 core:pause</tt> <br/><br/> The second option is intended if you need the currently active core to pause. This word is <span class="tt">core:pause-current</span>. <br/><br/> 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. <br/><br/> Example: <br/><br/> <tt class='indentedcode'>#4 core:resume</tt> |
| ︙ | ︙ | |||
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | in Napia, the virtual machine being written for the Retro on smaller targets. Code written to work with this will be usable on Retro/Napia with minimal changes. <br/><br/> The main differences are that under Nga, this is an optional extension, but in Napia, it is part of the standard system. <br/><br/> <br/><br/> On startup, execution occurs on core 0, with only core 0 being initialized. <br/><br/> I/O is run on the currently active core. Since I/O is blocking, waiting for an interaction to occur will prevent other cores from running until the operation is complete. <br/><br/> </p> </body></html> | > | 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 | in Napia, the virtual machine being written for the Retro on smaller targets. Code written to work with this will be usable on Retro/Napia with minimal changes. <br/><br/> 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. <br/><br/> I/O is run on the currently active core. Since I/O is blocking, waiting for an interaction to occur will prevent other cores from running until the operation is complete. <br/><br/> </p> </body></html> |
Changes to doc/html/chapters/techniques/naming-conventions.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/naming-conventions</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 |
.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 sigil 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
|
| ︙ | ︙ | |||
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | <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/> <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 the work in question. <br/><br/> To find a list of sigil characters, do: <br/><br/> <tt class='indentedcode'>'sigil: d:words-with</tt> <br/><br/> <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/> | > > | 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 | <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 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 the work in question. <br/><br/> 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: <br/><br/> <tt class='indentedcode'>'test_name var</tt> <tt class='indentedcode'>#188 !test_name</tt> <br/><br/> |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/numbers.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/numbers</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
.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">Sigil</span>
<br/><br/>
All numbers start with a <span class="tt">#</span> sigil.
<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/>
|
| ︙ | ︙ | |||
86 87 88 89 90 91 92 93 94 95 96 97 98 99 | <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/> <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> | > | 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <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> |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/pointers.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/pointers</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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">Sigil</span>
<br/><br/>
Pointers are returned by the <span class="tt">&</span> sigil.
<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/>
|
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/quotes.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/quotes</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 {
|
| ︙ | ︙ | |||
44 45 46 47 48 49 50 51 52 53 54 55 56 57 | </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/> <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/> | > | 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | </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/> |
| ︙ | ︙ | |||
74 75 76 77 78 79 80 81 82 83 84 85 86 87 | <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/> <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: | > | 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | <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: |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/return-stack.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/return-stack</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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>
|
Changes to doc/html/chapters/techniques/scripting.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/scripting</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
Shebang
<br/><br/>
To run an entire program directly, start the file with the standard
shebang and make the file executable:
<br/><br/>
|
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/sockets.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/sockets</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 {
|
| ︙ | ︙ | |||
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | </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/> <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/> <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/> <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/> <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/> <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/> <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/> <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/> <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> | > > > > > > > > | 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 | </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> |
Changes to doc/html/chapters/techniques/stack-diagrams.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/stack-diagrams</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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.
|
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/strings.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/strings</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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,
|
| ︙ | ︙ | |||
173 174 175 176 177 178 179 180 181 182 183 184 185 186 | • <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/> <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> | > | 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 | • <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> |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/the-stacks.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/the-stacks</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > > > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 |
.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>
|
| ︙ | ︙ | |||
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | <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/> <br/><br/> If you need to quickly empty the stack, use <span class="tt">reset</span>. <br/><br/> <br/><br/> To find out how many items are on the stack, use <span class="tt">depth</span>. <br/><br/> <br/><br/> You can display the stack by running <span class="tt">dump-stack</span>. <br/><br/> <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/> <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/> <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/> | > > > > > > | 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | <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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/using-combinators.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/using-combinators</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
.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
|
| ︙ | ︙ | |||
68 69 70 71 72 73 74 75 76 77 78 79 80 81 | 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/> <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/> | > | 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | 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/> |
| ︙ | ︙ | |||
147 148 149 150 151 152 153 154 155 156 157 158 159 160 | <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/> <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 | > | 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 | <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 |
| ︙ | ︙ |
Changes to doc/html/chapters/techniques/word-classes.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/techniques/word-classes</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | > | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 |
.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.
|
| ︙ | ︙ | |||
73 74 75 76 77 78 79 80 81 82 83 84 85 86 | <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/> <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/> | > | 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | <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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/info/additional-tools.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/info/additional-tools</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ | |||
91 92 93 94 95 96 97 98 99 100 101 102 103 104 | <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/> <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/> | > | 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | <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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/info/retro-compiler.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/info/retro-compiler</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 {
|
| ︙ | ︙ | |||
39 40 41 42 43 44 45 |
.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>
| > | | 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
.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/>
|
| ︙ | ︙ | |||
79 80 81 82 83 84 85 86 87 88 89 90 91 92 | 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/> <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/> | > | 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | 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/> |
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro-describe.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro-describe</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro-document.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro-document</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro-embedimage.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro-embedimage</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro-extend.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro-extend</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro-locate.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro-locate</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro-muri.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro-muri</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro-tags.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro-tags</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 {
|
| ︙ | ︙ |
Changes to doc/html/chapters/toolchain/man/retro.html.
1 2 3 | <?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> | | | 1 2 3 4 5 6 7 8 9 10 11 |
<?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>doc/book/toolchain/man/retro</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 {
|
| ︙ | ︙ |
Changes to example/markdown-to-xhtml.retro.
| ︙ | ︙ | |||
91 92 93 94 95 96 97 | work nicely, so I start with some header stuff. ~~~ '<?xml_version="1.0"_encoding="utf-8"?> s:put nl '<!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 | | | 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | work nicely, so I start with some header stuff. ~~~ '<?xml_version="1.0"_encoding="utf-8"?> s:put nl '<!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 #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 will be at the end of the file, starting with the line reading "\#\# CSS". ~~~ |
| ︙ | ︙ |