From e4a838d588c4beca1206fdf30033f1dd443b722f Mon Sep 17 00:00:00 2001 From: crc Date: Thu, 21 Jan 2021 12:40:28 +0000 Subject: [PATCH] generate & include html documentation files FossilOrigin-Name: 03f8a1f5293ceeb245b4e6315578c114c69eb4341027fad8eba5ec8c8dbca5fa --- doc/html/chapters/building/advanced.html | 69 +++ doc/html/chapters/building/alternatives.html | 155 ++++++ doc/html/chapters/building/obtaining.html | 102 ++++ doc/html/chapters/building/unix.html | 110 ++++ doc/html/chapters/building/windows.html | 81 +++ .../chapters/general/basic-interactions.html | 65 +++ doc/html/chapters/general/copyrights.html | 522 ++++++++++++++++++ doc/html/chapters/general/deprecation.html | 57 ++ doc/html/chapters/general/introduction.html | 66 +++ doc/html/chapters/general/markdown.html | 158 ++++++ doc/html/chapters/general/quick-tutorial.html | 83 +++ doc/html/chapters/general/retro-unu.html | 97 ++++ doc/html/chapters/general/starting.html | 120 ++++ doc/html/chapters/general/syntax.html | 133 +++++ doc/html/chapters/internals/image.html | 100 ++++ .../chapters/internals/interface-layers.html | 62 +++ doc/html/chapters/internals/io.html | 82 +++ doc/html/chapters/internals/nga.html | 203 +++++++ .../chapters/tech-notes/code-it-yourself.html | 102 ++++ .../tech-notes/historical-papers.html | 200 +++++++ .../chapters/tech-notes/kernel-words.html | 122 ++++ .../chapters/tech-notes/metacompilation.html | 123 +++++ .../chapters/tech-notes/ngaro-to-nga.html | 120 ++++ doc/html/chapters/tech-notes/prefixes.html | 93 ++++ .../tech-notes/retro11-retrospective.html | 126 +++++ doc/html/chapters/tech-notes/security.html | 91 +++ .../chapters/tech-notes/self-hosting.html | 169 ++++++ .../tech-notes/underscores-in-names.html | 96 ++++ doc/html/chapters/techniques/arrays.html | 154 ++++++ doc/html/chapters/techniques/assembly.html | 165 ++++++ doc/html/chapters/techniques/buffer.html | 186 +++++++ doc/html/chapters/techniques/characters.html | 110 ++++ .../techniques/checking-the-version.html | 69 +++ doc/html/chapters/techniques/definitions.html | 57 ++ doc/html/chapters/techniques/dictionary.html | 148 +++++ doc/html/chapters/techniques/errors.html | 81 +++ doc/html/chapters/techniques/files.html | 212 +++++++ .../chapters/techniques/floating-point.html | 224 ++++++++ .../chapters/techniques/lexical-scope.html | 85 +++ doc/html/chapters/techniques/loops.html | 110 ++++ .../techniques/naming-conventions.html | 143 +++++ doc/html/chapters/techniques/numbers.html | 129 +++++ doc/html/chapters/techniques/pointers.html | 80 +++ doc/html/chapters/techniques/quotes.html | 133 +++++ .../chapters/techniques/return-stack.html | 54 ++ doc/html/chapters/techniques/scripting.html | 99 ++++ doc/html/chapters/techniques/sockets.html | 114 ++++ .../chapters/techniques/stack-diagrams.html | 79 +++ doc/html/chapters/techniques/strings.html | 209 +++++++ doc/html/chapters/techniques/the-stacks.html | 169 ++++++ .../techniques/using-combinators.html | 239 ++++++++ .../chapters/techniques/word-classes.html | 97 ++++ .../toolchain/info/additional-tools.html | 129 +++++ .../toolchain/info/retro-compiler.html | 101 ++++ .../toolchain/man/retro-describe.html | 67 +++ .../toolchain/man/retro-document.html | 67 +++ .../toolchain/man/retro-embedimage.html | 68 +++ .../chapters/toolchain/man/retro-extend.html | 75 +++ .../chapters/toolchain/man/retro-locate.html | 66 +++ .../chapters/toolchain/man/retro-muri.html | 70 +++ .../chapters/toolchain/man/retro-tags.html | 66 +++ doc/html/chapters/toolchain/man/retro.html | 91 +++ doc/html/index.html | 1 + tools/generate-html-docs.retro | 81 +++ 64 files changed, 7535 insertions(+) create mode 100644 doc/html/chapters/building/advanced.html create mode 100644 doc/html/chapters/building/alternatives.html create mode 100644 doc/html/chapters/building/obtaining.html create mode 100644 doc/html/chapters/building/unix.html create mode 100644 doc/html/chapters/building/windows.html create mode 100644 doc/html/chapters/general/basic-interactions.html create mode 100644 doc/html/chapters/general/copyrights.html create mode 100644 doc/html/chapters/general/deprecation.html create mode 100644 doc/html/chapters/general/introduction.html create mode 100644 doc/html/chapters/general/markdown.html create mode 100644 doc/html/chapters/general/quick-tutorial.html create mode 100644 doc/html/chapters/general/retro-unu.html create mode 100644 doc/html/chapters/general/starting.html create mode 100644 doc/html/chapters/general/syntax.html create mode 100644 doc/html/chapters/internals/image.html create mode 100644 doc/html/chapters/internals/interface-layers.html create mode 100644 doc/html/chapters/internals/io.html create mode 100644 doc/html/chapters/internals/nga.html create mode 100644 doc/html/chapters/tech-notes/code-it-yourself.html create mode 100644 doc/html/chapters/tech-notes/historical-papers.html create mode 100644 doc/html/chapters/tech-notes/kernel-words.html create mode 100644 doc/html/chapters/tech-notes/metacompilation.html create mode 100644 doc/html/chapters/tech-notes/ngaro-to-nga.html create mode 100644 doc/html/chapters/tech-notes/prefixes.html create mode 100644 doc/html/chapters/tech-notes/retro11-retrospective.html create mode 100644 doc/html/chapters/tech-notes/security.html create mode 100644 doc/html/chapters/tech-notes/self-hosting.html create mode 100644 doc/html/chapters/tech-notes/underscores-in-names.html create mode 100644 doc/html/chapters/techniques/arrays.html create mode 100644 doc/html/chapters/techniques/assembly.html create mode 100644 doc/html/chapters/techniques/buffer.html create mode 100644 doc/html/chapters/techniques/characters.html create mode 100644 doc/html/chapters/techniques/checking-the-version.html create mode 100644 doc/html/chapters/techniques/definitions.html create mode 100644 doc/html/chapters/techniques/dictionary.html create mode 100644 doc/html/chapters/techniques/errors.html create mode 100644 doc/html/chapters/techniques/files.html create mode 100644 doc/html/chapters/techniques/floating-point.html create mode 100644 doc/html/chapters/techniques/lexical-scope.html create mode 100644 doc/html/chapters/techniques/loops.html create mode 100644 doc/html/chapters/techniques/naming-conventions.html create mode 100644 doc/html/chapters/techniques/numbers.html create mode 100644 doc/html/chapters/techniques/pointers.html create mode 100644 doc/html/chapters/techniques/quotes.html create mode 100644 doc/html/chapters/techniques/return-stack.html create mode 100644 doc/html/chapters/techniques/scripting.html create mode 100644 doc/html/chapters/techniques/sockets.html create mode 100644 doc/html/chapters/techniques/stack-diagrams.html create mode 100644 doc/html/chapters/techniques/strings.html create mode 100644 doc/html/chapters/techniques/the-stacks.html create mode 100644 doc/html/chapters/techniques/using-combinators.html create mode 100644 doc/html/chapters/techniques/word-classes.html create mode 100644 doc/html/chapters/toolchain/info/additional-tools.html create mode 100644 doc/html/chapters/toolchain/info/retro-compiler.html create mode 100644 doc/html/chapters/toolchain/man/retro-describe.html create mode 100644 doc/html/chapters/toolchain/man/retro-document.html create mode 100644 doc/html/chapters/toolchain/man/retro-embedimage.html create mode 100644 doc/html/chapters/toolchain/man/retro-extend.html create mode 100644 doc/html/chapters/toolchain/man/retro-locate.html create mode 100644 doc/html/chapters/toolchain/man/retro-muri.html create mode 100644 doc/html/chapters/toolchain/man/retro-tags.html create mode 100644 doc/html/chapters/toolchain/man/retro.html create mode 100644 doc/html/index.html create mode 100755 tools/generate-html-docs.retro diff --git a/doc/html/chapters/building/advanced.html b/doc/html/chapters/building/advanced.html new file mode 100644 index 0000000..df1b7e2 --- /dev/null +++ b/doc/html/chapters/building/advanced.html @@ -0,0 +1,69 @@ + + + +. + + +

Advanced Builds +

+Custom Image +

+For users of BSD, Linux, macOS, you can customize the image at +build time. +

+In the top level directory is a package directory containing +a file named list.forth. You can add files to compile into +your system by adding them to the list.forth and rebuilding. +

+Example: +

+If you have wanted to include the NumbersWithoutPrefixes.forth +example, add: +

+~~~ +'example/NumbersWithoutPrefixes.forth include +~~~ +

+To the start of the list.forth file and then run make again. +The newly built bin/retro will now include your additions. +

+ diff --git a/doc/html/chapters/building/alternatives.html b/doc/html/chapters/building/alternatives.html new file mode 100644 index 0000000..3199a45 --- /dev/null +++ b/doc/html/chapters/building/alternatives.html @@ -0,0 +1,155 @@ + + + +. + + +

Building Alternative Systems +

+In addition to the C implementation, there are a few other +interfaces that can be built. +

+Requirements +

+• c compiler (tested: clang, tcc, gcc)
+• make
+• standard unix shell
+

+retro-repl +

+A basic interactive system can be built by using: +

+make bin/retro-repl +

+This requires a copy of ngaImage to be in the current +directory. +

+Barebones +

+This is a minimal version of the retro-repl. It keeps the C +portion as short as possible, making it a useful starting point +for new interfaces. +

+To build: +

+make bin/retro-barebones +

+retro-compiler +

+This is a turnkey compiler. It can compile a new executable +bundling a Retro VM and image. +

+Requirements: +

+• BSD or Linux
+• objcopy in $PATH
+

+To build: +

+make bin/retro-compiler +

+Example use: +

+1. Given a source file like "Hello.forth": +

+~~~ +:hello 'hello_world! s:put nl ; +~~~ +

+2. Use: +

+./bin/retro-compiler Hello.forth hello +

+The first argument is the source file, the second is the +word to run on startup. +

+3. Run the generated a.out +

+Limits: +

+This only supports the core words ('all' interface) and the +file i/o words. Support for other I/O extensions will be +added in the future. +

+Pascal +

+There is a Pascal version of retro-repl. +

+Dependencies: +

+• freepascal
+

+Building: +

+cd vm/nga-pascal +fpc listener.lpr +

+This will require a copy of the ngaImage in the +current directory. +

+Python: retro.py +

+This is an implementation of retro-repl in Python. As +with retro-repl it requires the ngaImage in the current +directory when starting. +

+C#: retro.cs +

+This is an implementation of retro-repl in C#. As with +retro-repl it requires the ngaImage in the current +directory when starting. +

+Building: +

+cd vm\nga-csharp +csc retro.cs +

+You'll need to make sure your path has the CSC.EXE in it, +or provide a full path to it. Something like this should +reveal the path to use: +

+dir /s %WINDIR%\CSC.EXE +

+I've only tested building this using Microsoft's .NET tools. +It should also build and run under Mono. +

+ diff --git a/doc/html/chapters/building/obtaining.html b/doc/html/chapters/building/obtaining.html new file mode 100644 index 0000000..35cda6a --- /dev/null +++ b/doc/html/chapters/building/obtaining.html @@ -0,0 +1,102 @@ + + + +. + + +

Obtaining RETRO +

+Stable Releases +

+I periodically make stable releases. This will typically happen +quarterly. +

+• http://forthworks.com/retro
+• http://forth.works
+

+Snapshots +

+A lot of development happens between releases. I make snapshots +of my working source tree nightly (and often more often). +

+The latest snapshot can be downloaded from the following stable +URLs: +

+• http://forthworks.com/retro/r/latest.tar.gz
+• gopher://forthworks.com/9/retro/r/latest.tar.gz
+

+Fossil Repository +

+I use a Fossil repository to manage development. To obtain a +copy of the repository install Fossil and: +

+fossil clone http://forthworks.com:8000 retro.fossil +mkdir retro +cd retro +fossil open /path/to/retro.fossil +

+See the Fossil documentation for details on using Fossil to +keep your local copy of the repository current. +

+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. +

+If you have problems, check the version of Fossil you are +using. I am currently using Fossil 2.10, you may experience +issues checking out or cloning if using older versions. +

+git Repository +

+There is now a read-only mirror of the fossil repository +provided via git. This is hosted on sr.ht. +

+git clone https://git.sr.ht/~crc_/retroforth +

+Notes +

+I personally recommend using either a recent snapshot or a +build from one of the repositories. This will reflect the +latest system as I use it, and are normally reliable as I +run them daily for my production systems. +

+ diff --git a/doc/html/chapters/building/unix.html b/doc/html/chapters/building/unix.html new file mode 100644 index 0000000..eb2c290 --- /dev/null +++ b/doc/html/chapters/building/unix.html @@ -0,0 +1,110 @@ + + + +. + + +

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

+RETRO is well supported on BSD (tested on FreeBSD, NetBSD, +OpenBSD), Linux, and macOS systems. It should build on any +of these without issue. +

+Requirements +

+• c compiler & linker
+• standard headers
+• make
+

+Process +

+For a standard 32-bit system: +

+Run make +

+For a 64-bit system: +

+Run make OPTIONS=-DBIT64 +

+This will build the toolchain and then the main retro +executable. +

+Executables +

+In the bin/ directory: +

+retro +retro-unu +retro-muri +retro-extend +retro-embedimage +retro-describe +

+Platform Specific Notes +

+In addition to the 64-bit build, it is possible to override the +image size, address stack depth, and data stack depth by defining +the appropriate elements. +

+E.g., for a 64-bit build with: +

+4,000,000 cells of memory +4,000     item limit on data stack +500       item limit on address stack +

+Run make OPTIONS="-DBIT64 -DIMAGE_SIZE=4000000 -DSTACK_DEPTH=4000 -DADDRESSES=500" +

+

+Haiku +

+To build on Haiku, you need to link with the network library. +E.g.: +

+make LDFLAGS=-lnetwork +

+Issues +

+If you run into any build issues, please send details to +crc@forth.works so I can work on addressing them as quickly +as possible. +

+ diff --git a/doc/html/chapters/building/windows.html b/doc/html/chapters/building/windows.html new file mode 100644 index 0000000..03cac4c --- /dev/null +++ b/doc/html/chapters/building/windows.html @@ -0,0 +1,81 @@ + + + +. + + +

Building RETRO on Windows +

+It is possible to build RETRO on Windows, though a few of the +extensions are not supported: +

+• no unix: words
+• no gopher: words
+

+This is currently more difficult than on a Unix host. If you have +Windows 10 and WSL, it may be better to build under that (using +the Unix instructions). +

+Setup Build Environment +

+RETRO on Windows is built with TCC. +

+Go to http://download.savannah.gnu.org/releases/tinycc/ +

+Download the winapi-full and tcc-xxxx-bin packages for your +system. Decompress them, copy the headers from the winapi +package into the tcc directory. +

+Prepare Source +

+Copy the source/interfaces/retro-windows.c and the +source/interfaces/retro-windows.c to the directory you setup +tcc into. +

+Build +

+Building will require use of the command line. Assuming that +tcc.exe is in the current directory along with the RETRO sources: +

+tcc retro-windows.c -o retro.exe +

+ diff --git a/doc/html/chapters/general/basic-interactions.html b/doc/html/chapters/general/basic-interactions.html new file mode 100644 index 0000000..f0d3117 --- /dev/null +++ b/doc/html/chapters/general/basic-interactions.html @@ -0,0 +1,65 @@ + + + +. + + +

Basic Interactions +

+Start RETRO in interactive mode: +

+```
retro -i
+```

+You should see something similar to this: +

+RETRO 12 (2019.6) +8388608 MAX, TIB @ 1025, Heap @ 9374 +

+At this point you are at the listener, which reads and +processes your input. You are now set to begin exploring +RETRO. +

+To exit, run bye: +

+```
bye
+```

+ diff --git a/doc/html/chapters/general/copyrights.html b/doc/html/chapters/general/copyrights.html new file mode 100644 index 0000000..e24f92e --- /dev/null +++ b/doc/html/chapters/general/copyrights.html @@ -0,0 +1,522 @@ + + + +. + + +

The text in these files is Copyright (c) 2018-2020 by +Charles Childers. +

+To the extent possible under law, Charles Childers has +waived all copyright and related or neighboring rights +to the RETRO Documentation. This work is published from: +United States. +

+The historical papers are Copyright (c) 1999-2000 by +Tom Novelli. +

+Legal Text +

+See https://creativecommons.org/publicdomain/zero/1.0/legalcode +

+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"). +

+Certain owners wish to permanently relinquish those rights to a Work for +the purpose of contributing to a commons of creative, cultural and +scientific works ("Commons") that the public can reliably and without +fear of later claims of infringement build upon, modify, incorporate in +other works, reuse and redistribute as freely as possible in any form +whatsoever and for any purposes, including without limitation commercial +purposes. These owners may contribute to the Commons to promote the +ideal of a free culture and the further production of creative, cultural +and scientific works, or to gain reputation or greater distribution for +their Work in part through the use and efforts of others. +

+For these and/or other purposes and motivations, and without any +expectation of additional consideration or compensation, the person +associating CC0 with a Work (the "Affirmer"), to the extent that he or +she is an owner of Copyright and Related Rights in the Work, voluntarily +elects to apply CC0 to the Work and publicly distribute the Work under +its terms, with knowledge of his or her Copyright and Related Rights in +the Work and the meaning and intended legal effect of CC0 on those +rights. +

+1. Copyright and Related Rights. A Work made available under CC0 may be +protected by copyright and related or neighboring rights ("Copyright and +Related Rights"). Copyright and Related Rights include, but are not +limited to, the following: +

+• the right to reproduce, adapt, distribute, perform, display,
+ communicate, and translate a Work; +

+• moral rights retained by the original author(s) and/or performer(s);
+

+• publicity and privacy rights pertaining to a person's image or
+ likeness depicted in a Work; +

+• rights protecting against unfair competition in regards to a Work,
+ subject to the limitations in paragraph 4(a), below; +

+• rights protecting the extraction, dissemination, use and reuse of data
+ in a Work; +

+• database rights (such as those arising under Directive 96/9/EC of the
+ European Parliament and of the Council of 11 March 1996 on the legal + protection of databases, and under any national implementation thereof, + including any amended or successor version of such directive); and +

+• other similar, equivalent or corresponding rights throughout the world
+ based on applicable law or treaty, and any national implementations + thereof. +

+2. Waiver. To the greatest extent permitted by, but not in contravention +of, applicable law, Affirmer hereby overtly, fully, permanently, +irrevocably and unconditionally waives, abandons, and surrenders all of +Affirmer's Copyright and Related Rights and associated claims and causes +of action, whether now known or unknown (including existing as well as +future claims and causes of action), in the Work (i) in all territories +worldwide, (ii) for the maximum duration provided by applicable law or +treaty (including future time extensions), (iii) in any current or +future medium and for any number of copies, and (iv) for any purpose +whatsoever, including without limitation commercial, advertising or +promotional purposes (the "Waiver"). Affirmer makes the Waiver for the +benefit of each member of the public at large and to the detriment of +Affirmer's heirs and successors, fully intending that such Waiver shall +not be subject to revocation, rescission, cancellation, termination, or +any other legal or equitable action to disrupt the quiet enjoyment of +the Work by the public as contemplated by Affirmer's express Statement +of Purpose. +

+3. Public License Fallback. Should any part of the Waiver for any reason +be judged legally invalid or ineffective under applicable law, then the +Waiver shall be preserved to the maximum extent permitted taking into +account Affirmer's express Statement of Purpose. In addition, to the +extent the Waiver is so judged Affirmer hereby grants to each affected +person a royalty-free, non transferable, non sublicensable, non +exclusive, irrevocable and unconditional license to exercise Affirmer's +Copyright and Related Rights in the Work (i) in all territories +worldwide, (ii) for the maximum duration provided by applicable law or +treaty (including future time extensions), (iii) in any current or +future medium and for any number of copies, and (iv) for any purpose +whatsoever, including without limitation commercial, advertising or +promotional purposes (the "License"). The License shall be deemed +effective as of the date CC0 was applied by Affirmer to the Work. Should +any part of the License for any reason be judged legally invalid or +ineffective under applicable law, such partial invalidity or +ineffectiveness shall not invalidate the remainder of the License, and +in such case Affirmer hereby affirms that he or she will not (i) +exercise any of his or her remaining Copyright and Related Rights in the +Work or (ii) assert any associated claims and causes of action with +respect to the Work, in either case contrary to Affirmer's express +Statement of Purpose. +

+4. Limitations and Disclaimers. +

+No trademark or patent rights held by Affirmer are waived, abandoned, +surrendered, licensed or otherwise affected by this document. +

+Affirmer offers the Work as-is and makes no representations or +warranties of any kind concerning the Work, express, implied, statutory +or otherwise, including without limitation warranties of title, +merchantability, fitness for a particular purpose, non infringement, or +the absence of latent or other defects, accuracy, or the present or +absence of errors, whether or not discoverable, all to the greatest +extent permissible under applicable law. +

+Affirmer disclaims responsibility for clearing rights of other persons +that may apply to the Work or any use thereof, including without +limitation any person's Copyright and Related Rights in the Work. +Further, Affirmer disclaims responsibility for obtaining any necessary +consents, permissions or other rights required for any use of the Work. +

+Affirmer understands and acknowledges that Creative Commons is not a +party to this document and has no duty or obligation with respect to +this CC0 or use of the Work. +

+ +

+The Code It Yourself Manifesto is Copyright (c) 2016 by +Christian Kellermann and is used under the +Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0) license. +

+This license reads: +

+THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE +COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY +COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS +AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. +

+BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE +TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY +BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS +CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND +CONDITIONS. +

+1. Definitions +

+"Adaptation" means a work based upon the Work, or upon the Work and +other pre-existing works, such as a translation, adaptation, derivative +work, arrangement of music or other alterations of a literary or +artistic work, or phonogram or performance and includes cinematographic +adaptations or any other form in which the Work may be recast, +transformed, or adapted including in any form recognizably derived from +the original, except that a work that constitutes a Collection will not +be considered an Adaptation for the purpose of this License. For the +avoidance of doubt, where the Work is a musical work, performance or +phonogram, the synchronization of the Work in timed-relation with a +moving image ("synching") will be considered an Adaptation for the +purpose of this License. +

+"Collection" means a collection of literary or artistic works, such as +encyclopedias and anthologies, or performances, phonograms or +broadcasts, or other works or subject matter other than works listed in +Section 1(f) below, which, by reason of the selection and arrangement of +their contents, constitute intellectual creations, in which the Work is +included in its entirety in unmodified form along with one or more other +contributions, each constituting separate and independent works in +themselves, which together are assembled into a collective whole. A work +that constitutes a Collection will not be considered an Adaptation (as +defined below) for the purposes of this License. +

+"Creative Commons Compatible License" means a license that is listed at +https://creativecommons.org/compatiblelicenses that has been approved by +Creative Commons as being essentially equivalent to this License, +including, at a minimum, because that license: (i) contains terms that +have the same purpose, meaning and effect as the License Elements of +this License; and, (ii) explicitly permits the relicensing of +adaptations of works made available under that license under this +License or a Creative Commons jurisdiction license with the same License +Elements as this License. +

+"Distribute" means to make available to the public the original and +copies of the Work or Adaptation, as appropriate, through sale or other +transfer of ownership. +

+"License Elements" means the following high-level license attributes as +selected by Licensor and indicated in the title of this License: +Attribution, ShareAlike. +

+"Licensor" means the individual, individuals, entity or entities that +offer(s) the Work under the terms of this License. +

+"Original Author" means, in the case of a literary or artistic work, the +individual, individuals, entity or entities who created the Work or if +no individual or entity can be identified, the publisher; and in +addition (i) in the case of a performance the actors, singers, +musicians, dancers, and other persons who act, sing, deliver, declaim, +play in, interpret or otherwise perform literary or artistic works or +expressions of folklore; (ii) in the case of a phonogram the producer +being the person or legal entity who first fixes the sounds of a +performance or other sounds; and, (iii) in the case of broadcasts, the +organization that transmits the broadcast. +

+"Work" means the literary and/or artistic work offered under the terms +of this License including without limitation any production in the +literary, scientific and artistic domain, whatever may be the mode or +form of its expression including digital form, such as a book, pamphlet +and other writing; a lecture, address, sermon or other work of the same +nature; a dramatic or dramatico-musical work; a choreographic work or +entertainment in dumb show; a musical composition with or without words; +a cinematographic work to which are assimilated works expressed by a +process analogous to cinematography; a work of drawing, painting, +architecture, sculpture, engraving or lithography; a photographic work +to which are assimilated works expressed by a process analogous to +photography; a work of applied art; an illustration, map, plan, sketch +or three-dimensional work relative to geography, topography, +architecture or science; a performance; a broadcast; a phonogram; a +compilation of data to the extent it is protected as a copyrightable +work; or a work performed by a variety or circus performer to the extent +it is not otherwise considered a literary or artistic work. +

+"You" means an individual or entity exercising rights under this License +who has not previously violated the terms of this License with respect +to the Work, or who has received express permission from the Licensor to +exercise rights under this License despite a previous violation. +

+"Publicly Perform" means to perform public recitations of the Work and +to communicate to the public those public recitations, by any means or +process, including by wire or wireless means or public digital +performances; to make available to the public Works in such a way that +members of the public may access these Works from a place and at a place +individually chosen by them; to perform the Work to the public by any +means or process and the communication to the public of the performances +of the Work, including by public digital performance; to broadcast and +rebroadcast the Work by any means including signs, sounds or images. +

+"Reproduce" means to make copies of the Work by any means including +without limitation by sound or visual recordings and the right of +fixation and reproducing fixations of the Work, including storage of a +protected performance or phonogram in digital form or other electronic +medium. +

+2. Fair Dealing Rights. Nothing in this License is intended to reduce, +limit, or restrict any uses free from copyright or rights arising from +limitations or exceptions that are provided for in connection with the +copyright protection under copyright law or other applicable laws. +

+3. License Grant. Subject to the terms and conditions of this License, +Licensor hereby grants You a worldwide, royalty-free, non-exclusive, +perpetual (for the duration of the applicable copyright) license to +exercise the rights in the Work as stated below: +

+• to Reproduce the Work, to incorporate the Work into one or more
+ Collections, and to Reproduce the Work as incorporated in the + Collections; +

+• to create and Reproduce Adaptations provided that any such Adaptation,
+ including any translation in any medium, takes reasonable steps to + clearly label, demarcate or otherwise identify that changes were made to + the original Work. For example, a translation could be marked "The + original work was translated from English to Spanish," or a modification + could indicate "The original work has been modified."; +

+• to Distribute and Publicly Perform the Work including as incorporated in
+ Collections; and, +

+• to Distribute and Publicly Perform Adaptations.
+

+For the avoidance of doubt: +

+Non-waivable Compulsory License Schemes. In those jurisdictions in which +the right to collect royalties through any statutory or compulsory +licensing scheme cannot be waived, the Licensor reserves the exclusive +right to collect such royalties for any exercise by You of the rights +granted under this License; +

+Waivable Compulsory License Schemes. In those jurisdictions in which the +right to collect royalties through any statutory or compulsory licensing +scheme can be waived, the Licensor waives the exclusive right to collect +such royalties for any exercise by You of the rights granted under this +License; and, +

+Voluntary License Schemes. The Licensor waives the right to collect +royalties, whether individually or, in the event that the Licensor is a +member of a collecting society that administers voluntary licensing +schemes, via that society, from any exercise by You of the rights +granted under this License. +

+The above rights may be exercised in all media and formats whether now +known or hereafter devised. The above rights include the right to make +such modifications as are technically necessary to exercise the rights +in other media and formats. Subject to Section 8(f), all rights not +expressly granted by Licensor are hereby reserved. +

+4. Restrictions. The license granted in Section 3 above is expressly +made subject to and limited by the following restrictions: +

+You may Distribute or Publicly Perform the Work only under the terms of +this License. You must include a copy of, or the Uniform Resource +Identifier (URI) for, this License with every copy of the Work You +Distribute or Publicly Perform. You may not offer or impose any terms on +the Work that restrict the terms of this License or the ability of the +recipient of the Work to exercise the rights granted to that recipient +under the terms of the License. You may not sublicense the Work. You +must keep intact all notices that refer to this License and to the +disclaimer of warranties with every copy of the Work You Distribute or +Publicly Perform. When You Distribute or Publicly Perform the Work, You +may not impose any effective technological measures on the Work that +restrict the ability of a recipient of the Work from You to exercise the +rights granted to that recipient under the terms of the License. This +Section 4(a) applies to the Work as incorporated in a Collection, but +this does not require the Collection apart from the Work itself to be +made subject to the terms of this License. If You create a Collection, +upon notice from any Licensor You must, to the extent practicable, +remove from the Collection any credit as required by Section 4(c), as +requested. If You create an Adaptation, upon notice from any Licensor +You must, to the extent practicable, remove from the Adaptation any +credit as required by Section 4(c), as requested. +

+You may Distribute or Publicly Perform an Adaptation only under the +terms of: (i) this License; (ii) a later version of this License with +the same License Elements as this License; (iii) a Creative Commons +jurisdiction license (either this or a later license version) that +contains the same License Elements as this License (e.g., +Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible +License. If you license the Adaptation under one of the licenses +mentioned in (iv), you must comply with the terms of that license. If +you license the Adaptation under the terms of any of the licenses +mentioned in (i), (ii) or (iii) (the "Applicable License"), you must +comply with the terms of the Applicable License generally and the +following provisions: (I) You must include a copy of, or the URI for, +the Applicable License with every copy of each Adaptation You Distribute +or Publicly Perform; (II) You may not offer or impose any terms on the +Adaptation that restrict the terms of the Applicable License or the +ability of the recipient of the Adaptation to exercise the rights +granted to that recipient under the terms of the Applicable License; +(III) You must keep intact all notices that refer to the Applicable +License and to the disclaimer of warranties with every copy of the Work +as included in the Adaptation You Distribute or Publicly Perform; (IV) +when You Distribute or Publicly Perform the Adaptation, You may not +impose any effective technological measures on the Adaptation that +restrict the ability of a recipient of the Adaptation from You to +exercise the rights granted to that recipient under the terms of the +Applicable License. This Section 4(b) applies to the Adaptation as +incorporated in a Collection, but this does not require the Collection +apart from the Adaptation itself to be made subject to the terms of the +Applicable License. +

+If You Distribute, or Publicly Perform the Work or any Adaptations or +Collections, You must, unless a request has been made pursuant to +Section 4(a), keep intact all copyright notices for the Work and +provide, reasonable to the medium or means You are utilizing: (i) the +name of the Original Author (or pseudonym, if applicable) if supplied, +and/or if the Original Author and/or Licensor designate another party or +parties (e.g., a sponsor institute, publishing entity, journal) for +attribution ("Attribution Parties") in Licensor's copyright notice, +terms of service or by other reasonable means, the name of such party or +parties; (ii) the title of the Work if supplied; (iii) to the extent +reasonably practicable, the URI, if any, that Licensor specifies to be +associated with the Work, unless such URI does not refer to the +copyright notice or licensing information for the Work; and (iv) , +consistent with Ssection 3(b), in the case of an Adaptation, a credit +identifying the use of the Work in the Adaptation (e.g., "French +translation of the Work by Original Author," or "Screenplay based on +original Work by Original Author"). The credit required by this Section +4(c) may be implemented in any reasonable manner; provided, however, +that in the case of a Adaptation or Collection, at a minimum such credit +will appear, if a credit for all contributing authors of the Adaptation +or Collection appears, then as part of these credits and in a manner at +least as prominent as the credits for the other contributing authors. +For the avoidance of doubt, You may only use the credit required by this +Section for the purpose of attribution in the manner set out above and, +by exercising Your rights under this License, You may not implicitly or +explicitly assert or imply any connection with, sponsorship or +endorsement by the Original Author, Licensor and/or Attribution Parties, +as appropriate, of You or Your use of the Work, without the separate, +express prior written permission of the Original Author, Licensor and/or +Attribution Parties. +

+Except as otherwise agreed in writing by the Licensor or as may be +otherwise permitted by applicable law, if You Reproduce, Distribute or +Publicly Perform the Work either by itself or as part of any Adaptations +or Collections, You must not distort, mutilate, modify or take other +derogatory action in relation to the Work which would be prejudicial to +the Original Author's honor or reputation. Licensor agrees that in those +jurisdictions (e.g. Japan), in which any exercise of the right granted +in Section 3(b) of this License (the right to make Adaptations) would be +deemed to be a distortion, mutilation, modification or other derogatory +action prejudicial to the Original Author's honor and reputation, the +Licensor will waive or not assert, as appropriate, this Section, to the +fullest extent permitted by the applicable national law, to enable You +to reasonably exercise Your right under Section 3(b) of this License +(right to make Adaptations) but not otherwise. +

+5. Representations, Warranties and Disclaimer +

+UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR +OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY +KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, +INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, +FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF +LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, +WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE +EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. +

+6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE +LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR +ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES +ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS +BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. +

+7. Termination +

+This License and the rights granted hereunder will terminate +automatically upon any breach by You of the terms of this License. +Individuals or entities who have received Adaptations or Collections +from You under this License, however, will not have their licenses +terminated provided such individuals or entities remain in full +compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will +survive any termination of this License. Subject to the above terms and +conditions, the license granted here is perpetual (for the duration of +the applicable copyright in the Work). Notwithstanding the above, +Licensor reserves the right to release the Work under different license +terms or to stop distributing the Work at any time; provided, however +that any such election will not serve to withdraw this License (or any +other license that has been, or is required to be, granted under the +terms of this License), and this License will continue in full force and +effect unless terminated as stated above. 8. Miscellaneous +

+Each time You Distribute or Publicly Perform the Work or a Collection, +the Licensor offers to the recipient a license to the Work on the same +terms and conditions as the license granted to You under this License. +

+Each time You Distribute or Publicly Perform an Adaptation, Licensor +offers to the recipient a license to the original Work on the same terms +and conditions as the license granted to You under this License. +

+If any provision of this License is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of +the remainder of the terms of this License, and without further action +by the parties to this agreement, such provision shall be reformed to +the minimum extent necessary to make such provision valid and +enforceable. +

+No term or provision of this License shall be deemed waived and no +breach consented to unless such waiver or consent shall be in writing +and signed by the party to be charged with such waiver or consent. +

+This License constitutes the entire agreement between the parties with +respect to the Work licensed here. There are no understandings, +agreements or representations with respect to the Work not specified +here. Licensor shall not be bound by any additional provisions that may +appear in any communication from You. This License may not be modified +without the mutual written agreement of the Licensor and You. +

+The rights granted under, and the subject matter referenced, in this +License were drafted utilizing the terminology of the Berne Convention +for the Protection of Literary and Artistic Works (as amended on +September 28, 1979), the Rome Convention of 1961, the WIPO Copyright +Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 and +the Universal Copyright Convention (as revised on July 24, 1971). These +rights and subject matter take effect in the relevant jurisdiction in +which the License terms are sought to be enforced according to the +corresponding provisions of the implementation of those treaty +provisions in the applicable national law. If the standard suite of +rights granted under applicable copyright law includes additional rights +not granted under this License, such additional rights are deemed to be +included in the License; this License is not intended to restrict the +license of any rights under applicable law. +

+ diff --git a/doc/html/chapters/general/deprecation.html b/doc/html/chapters/general/deprecation.html new file mode 100644 index 0000000..3eb4768 --- /dev/null +++ b/doc/html/chapters/general/deprecation.html @@ -0,0 +1,57 @@ + + + +. + + +

Deprecation Policy +

+As RETRO evolves, some words will become obsolete and no longer +be needed. In each release, these will be marked as deprecated +in the glossary. Any deprecated words will be removed in the +next quarterly release. +

+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. +

+ diff --git a/doc/html/chapters/general/introduction.html b/doc/html/chapters/general/introduction.html new file mode 100644 index 0000000..52c3741 --- /dev/null +++ b/doc/html/chapters/general/introduction.html @@ -0,0 +1,66 @@ + + + +. + + +

RETRO: a Modern, Pragmatic Forth +

+Welcome to RETRO, my personal take on the Forth language. This +is a modern system primarily targeting desktop, mobile, and +servers, though it can also be used on some larger (ARM, MIPS32) +embedded systems. +

+The language is Forth. It is untyped, uses a stack to pass data +between functions called words, and a dictionary which tracks +the word names and data structures. +

+But it's not a traditional Forth. RETRO draws influences from +many sources and takes a unique approach to the language. +

+RETRO has a large vocabulary of words. Keeping a copy of the +Glossary on hand is highly recommended as you learn to use RETRO. +

+This book will hopefully help you develop a better understanding +of RETRO and how it works. +

+ diff --git a/doc/html/chapters/general/markdown.html b/doc/html/chapters/general/markdown.html new file mode 100644 index 0000000..616049a --- /dev/null +++ b/doc/html/chapters/general/markdown.html @@ -0,0 +1,158 @@ + + + +. + + +

RETRO's Markdown Syntax +

+I use a variation of Markdown for writing documentation and +when commenting code written in RETRO. The syntax is +described below. +

+Basic Syntax +

+Headings +

+Headings start with one or more number (#) signs. The +number of number signs should correspond to the heading +level. +

+# Heading 1 +## Heading 2 +### Heading 3 +#### Heading 4 +

+My Markdown does not support the alternate underline +format for headings. +

+Paragraphs & Line Breaks +

+To create paragraphs, use a blank line to separate one or +more lines of text. +

+Do not add spaces or tabs at the start of a paragraph as +this may cause the Markdown tools to interpret the line +improperly. +

+Line breaks are entered at the end of each line. +

+Emphasis +

+Bold +

+To make text bold, surround it with asterisks. +

+The *bold* word. +

+Italic +

+To make text italic, surround it with front slashes. +

+The /italic words/. +

+Underline +

+To underline text, surround it with underscores. +

+Underline _some text_. +

+Horizontal Rules +

+Horizontal rules can be inserted by starting a line with a +sequence of four or more dashes (-) or four or more alternating +dash and plus (-+-+) characters. +

+---- +

+Lists +

+Lists start with a - or *, followed by a space, then the item +text. Additionally, nested lists starting with two spaces before +the list marker can be used. +

+- this is a list item +- so is this +

+  - this will be indented +  - likewise +

+- back to the standard level +

+Code +

+Code Blocks +

+Code blocks start and end with ~~~ on a line by themselves. +

+Sum the values. +

+~~~ +{ #10 #20 #13 #4 #22 } #0 [ + ] a:reduce +~~~ +

+You can also denote code by starting the line with four spaces. +

+    This line will be treated as code. +

+Test Blocks +

+Unit testing blocks start and end with on a line by +themselves. +

+``` +{ #10 #20 #13 #4 #22 } #0 [ + ] a:reduce +``` +

+Inline Code +

+To mark a sequence as inline code, surround it with backticks. +

+For instance, look at the value in `Compiler` to see if +the colon compiler is active. +

+Escaping +

+You can preceed a character with a backslash () to have it +not be processed as a Markdown element. +

+ diff --git a/doc/html/chapters/general/quick-tutorial.html b/doc/html/chapters/general/quick-tutorial.html new file mode 100644 index 0000000..8ca17b1 --- /dev/null +++ b/doc/html/chapters/general/quick-tutorial.html @@ -0,0 +1,83 @@ + + + +. + + +

A Quick Tutorial +

+Programming in RETRO is all about creating words to solve +the problem at hand. Words operate on data, which can be +kept in memory or on the stack. +

+Let's look at this by solving a small problem: writing a +word to determine if a string is a palindrome. +

+A palindrome is a phrase which reads the same backward +and forward. +

+We first need a string to look at. Starting with something +easy: +

+```
'anna
+```

+Looking in the Glossary, there is a s:reverse word for +reversing a string. We can find dup to copy a value, and +s:eq? to compare two strings. So testing: +

+```
'anna dup s:reverse s:eq?
+```

+This yields -1 (TRUE) as expected. So we can easily +name it: +

+```
:palindrome? dup s:reverse s:eq? ;
+```

+Naming uses the : prefix to add a new word to the dictionary. +The words that make up the definition are then placed, with a +final word (;) ending the definition. We can then use this: +

+```
'anna palindrome?
+```

+Once defined there is no difference between our new word and +any of the words already provided by the RETRO system. +

+ diff --git a/doc/html/chapters/general/retro-unu.html b/doc/html/chapters/general/retro-unu.html new file mode 100644 index 0000000..6251896 --- /dev/null +++ b/doc/html/chapters/general/retro-unu.html @@ -0,0 +1,97 @@ + + + +. + + +

Unu: Simple, Literate Source Files +

+RETRO is written in a literate style. Most of the sources +are in a format called Unu. This allows easy mixing of +commentary and code blocks, making it simple to document +the code. +

+As an example, +

+# Determine The Average Word Name Length +

+To determine the average length of a word name two values +are needed. First, the total length of all names in the +Dictionary: +

+~~~ +#0 [ d:name s:length + ] d:for-each +~~~ +

+And then the number of words in the Dictionary: +

+~~~ +#0 [ drop n:inc ] d:for-each +~~~ +

+With these, a simple division is all that's left. +

+~~~ +/ +~~~ +

+Finally, display the results: +

+

+~~~ +'Average_name_length:_%n\n s:format s:put +~~~ +

+This illustrates the format. Only code in the fenced blocks +(between ~~~ pairs) get extracted and run. +

+(Note: this only applies to source files; fences are not used +when entering code interactively). +

+On The Name +

+The name Unu comes from the Maori language, where it means: +

+(verb) (-hia) pull out, withdraw, draw out, extract. +Taken from https://maoridictionary.co.nz/ +

+ diff --git a/doc/html/chapters/general/starting.html b/doc/html/chapters/general/starting.html new file mode 100644 index 0000000..2260781 --- /dev/null +++ b/doc/html/chapters/general/starting.html @@ -0,0 +1,120 @@ + + + +. + + +

Starting RETRO +

+RETRO can be run for scripting or interactive use. +

+Interactive +

+To start it interactively, run: retro without any command line +arguments, or with -i, -s, or -i,c. +

+Starting the interactive system: +

+```
retro
+```

+Or: +

+```
retro -i
+```

+This should be sufficient for most uses. +

+Starting the interactive system (without displaying the +startup banner): +

+```
retro -s
+```

+Using In a Pipe +

+If using a Unix shell and piping input between processes, you +will probably want to use -s to suppress the startup messages +and Ok prompt that normally appear. +

+E.g., +

+```
echo "'lol s:put nl" | retro -s
+```

+Running A Program In A File +

+You can run code in a file very easily. This is simply: +

+```
retro filename
+```

+You can follow the filename with any arguments that it may need. +These will be accessible to the program via the script:arguments +and script:get-argument words. +

+Source files must be written in Unu format. +

+Scripting +

+You can use RETRO to write scripts. Add a shebang: +

+```
#!/usr/bin/env retro
+```

+And make the file executable. +

+Source files must be written in Unu format. +

+Command Line Arguments +

+For a summary of the full command line arguments available: +

+Scripting Usage: +

+    retro filename [script arguments...] +

+Interactive Usage: +

+    retro [-h] [-i] [-c] [-s] [-f filename] [-t] +

+  -h           Display this help text +  -i           Interactive mode (line buffered) +  -s           Suppress the startup text +  -f filename  Run the contents of the specified file +  -t           Run tests (in ``` blocks) in any loaded files +

+ diff --git a/doc/html/chapters/general/syntax.html b/doc/html/chapters/general/syntax.html new file mode 100644 index 0000000..d1c7aed --- /dev/null +++ b/doc/html/chapters/general/syntax.html @@ -0,0 +1,133 @@ + + + +. + + +

Syntax +

+RETRO has more syntax than a traditional Forth due to ideas +borrowed from ColorForth and some design decisions. This has +some useful traits, and helps to make the language more +consistent. +

+Tokens +

+Input is divided into a series of whitespace delimited tokens. +Each of these is then processed individually. There are no +parsing words in RETRO. +

+Tokens may have a single character prefix, which RETRO will +use to decide how to process the token. +

+Prefixes +

+Prefixes are single characters added to the start of a token +to guide the compiler. The use of these is a major way in +which RETRO differs from traditional Forth. +

+When a token is passed to interpret, RETRO first takes the +initial character and looks to see if there is a word that +matches this. If so, it will pass the rest of the token to +that word to handle. +

+In a traditional Forth, the interpret process is something +like: +

+get token +is token in the dictionary? +  yes: +    is it immediate? +      yes: call the word. +      no:  are we interpreting? +           yes: call the word +           no:  compile a call to the word +  no: +    is it a number? +      yes: are we interpreting? +           yes: push the number to the stack +           no:  compile the number as a literal +      no:  report an error ("not found") +

+In RETRO, the interpret process is basically: +

+get token +does the first character match a `prefix:` word? +  yes: pass the token to the prefix handler +  no:  is token a word in the dictionary? +       yes: push the XT to the stack and call the +            class handler +       no:  report an error ("not found") +

+All of the actual logic for how to deal with tokens is moved +to the individual prefix handlers, and the logic for handling +words is moved to word class handlers. +

+This means that prefixes are used for a lot of things. Numbers? +Handled by a # prefix. Strings? Use the ' prefix. Comments? +Use (. Making a new word? Use the : prefix. +

+The major prefixes are: +

+| Prefix | Used For                      | +| ------ | ----------------------------- | +| @      | Fetch from variable           | +| !      | Store into variable           | +| &      | Pointer to named item         | +| #      | Numbers                       | +| $      | ASCII characters              | +| '      | Strings                       | +| (      | Comments                      | +| :      | Define a word                 | +

+The individual prefixes will be covered in more detail in the +later chapters on working with different data types. +

+Word Classes +

+Word classes are words which take a pointer and do something +with it. These are covered in detail in their own chapter, +but essentially they decide how to execute or compile specific +types of words. +

+

+ diff --git a/doc/html/chapters/internals/image.html b/doc/html/chapters/internals/image.html new file mode 100644 index 0000000..b4cce0a --- /dev/null +++ b/doc/html/chapters/internals/image.html @@ -0,0 +1,100 @@ + + + +. + + +

Internals: The Retro Image +

+The actual RETRO language is stored as a memory image for Nga. +

+Format +

+The image file is a flat, linear sequence of signed 32-bit +values. Each value is stored in little endian format. The +size is not fixed. An interface should check when loading to +ensure that the physical image is not larger than the emulated +memory. +

+Header +

+The image will start with two cells. The first is a liju.... +instruction, the second is the target address for the jump. +This serves to skip over the rest of the data and reach the +actual entry point. +

+This is followed by a pointer to the most recent dictionary +header, a pointer to the next free address in memory, and +then the RETRO version number. +

+| Offset | Contains                    | +| ------ | --------------------------- | +| 0      | lit call nop nop            | +| 1      | Pointer to main entry point | +| 2      | Dictionary                  | +| 3      | Heap                        | +| 4      | RETRO version               | +

+The actual code starts after this header. +

+The version number is the year and month. As an example, +the 12.2019.6 release will have a version number of +201906. +

+Layout +

+Assuming an Nga built with 524287 cells of memory: +

+| RANGE           | CONTAINS                     | +| --------------- | ---------------------------- | +| 0 - 1024        | RETRO Core kernel            | +| 1025 - 1535     | token input buffer           | +| 1536 +          | start of heap space          | +| ............... | free memory for your use     | +| 506879          | buffer for string evaluate   | +| 507904          | temporary strings (32 * 512) | +| 524287          | end of memory                | +

+The buffers at the end of memory will resize when specific +variables related to them are altered. +

+ diff --git a/doc/html/chapters/internals/interface-layers.html b/doc/html/chapters/internals/interface-layers.html new file mode 100644 index 0000000..12822ac --- /dev/null +++ b/doc/html/chapters/internals/interface-layers.html @@ -0,0 +1,62 @@ + + + +. + + +

Internals: Interface Layers +

+Nga provides a virtual processor and an extensible way of adding +I/O devices, but does not provide any I/O itself. Adding I/O is +the responsability of the interface layer. +

+An interface layer will wrap Nga, providing at least one I/O +device (a generic output target), and a means of interacting +with the retro image. +

+It's expected that this layer will be host specific, adding any +system interactions that are needed via the I/O instructions. +The image will typically be extended with words to use these. +

+

+

+ diff --git a/doc/html/chapters/internals/io.html b/doc/html/chapters/internals/io.html new file mode 100644 index 0000000..6e86b65 --- /dev/null +++ b/doc/html/chapters/internals/io.html @@ -0,0 +1,82 @@ + + + +. + + +

Internals: I/O +

+RETRO provides three words for interacting with I/O. These are: +

+io:enumerate    returns the number of attached devices +io:query        returns information about a device +io:invoke       invokes an interaction with a device +

+As an example, with an implementation providing an output source, +a block storage system, and keyboard: +

+io:enumerate    will return `3` since there are three +                i/o devices +#0 io:query     will return 0 0, since the first device +                is a screen (type 0) with a version of 0 +#1 io:query     will return 1 3, since the second device is +                block storage (type 3), with a version of 1 +#2 io:query     will return 0 1, since the last device is a +                keyboard (type 1), with a version of 0 +

+In this case, some interactions can be defined: +

+:c:put #0 io:invoke ; +:c:get #2 io:invoke ; +

+Setup the stack, push the device ID, and then use io:invoke +to invoke the interaction. +

+A RETRO system requires one I/O device (a generic output for a +single character). This must be the first device, and must have +a device ID of 0. +

+All other devices are optional and can be specified in any +order. +

+

+ diff --git a/doc/html/chapters/internals/nga.html b/doc/html/chapters/internals/nga.html new file mode 100644 index 0000000..002880f --- /dev/null +++ b/doc/html/chapters/internals/nga.html @@ -0,0 +1,203 @@ + + + +. + + +

Internals: Nga Virtual Machine +

+Overview +

+At the heart of RETRO is a simple MISC (minimal instruction +set computer) processor for a dual stack architecture. +

+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. +

+Instruction Table +

+                                     |     Stacks      | +| Opcode | Muri | Full Name          | Data  | Address | +| ------ | ---- | ------------------ | ----- | ------- | +|  0     | ..   | nop                |   -   |   -     | +|  1     | li   | lit                |   -n  |   -     | +|  2     | du   | dup                |  n-nn |   -     | +|  3     | dr   | drop               |  n-   |   -     | +|  4     | sw   | swap               | xy-yx |   -     | +|  5     | pu   | push               |  n-   |   -n    | +|  6     | po   | pop                |   -n  |  n-     | +|  7     | ju   | jump               |  a-   |   -     | +|  8     | ca   | call               |  a-   |   -A    | +|  9     | cc   | conditional call   | af-   |   -A    | +| 10     | re   | return             |   -   |  A-     | +| 11     | eq   | equality           | xy-f  |   -     | +| 12     | ne   | inequality         | xy-f  |   -     | +| 13     | lt   | less than          | xy-f  |   -     | +| 14     | gt   | greater than       | xy-f  |   -     | +| 15     | fe   | fetch              |  a-n  |   -     | +| 16     | st   | store              | na-   |   -     | +| 17     | ad   | addition           | xy-n  |   -     | +| 18     | su   | subtraction        | xy-n  |   -     | +| 19     | mu   | multiplication     | xy-n  |   -     | +| 20     | di   | divide & remainder | xy-rq |   -     | +| 21     | an   | bitwise and        | xy-n  |   -     | +| 22     | or   | bitwise or         | xy-n  |   -     | +| 23     | xo   | bitwise xor        | xy-n  |   -     | +| 24     | sh   | shift              | xy-n  |   -     | +| 25     | zr   | zero return        |  n-?  |   -     | +| 26     | ha   | halt               |   -   |   -     | +| 27     | ie   | i/o enumerate      |   -n  |   -     | +| 28     | iq   | i/o query          |  n-xy |   -     | +| 29     | ii   | i/o invoke         | ...n- |   -     | +

+Encoding +

+Up to four instructions can be packed into each memory cell. +

+As an example, +

+Opcode 4 Opcode 3 Opcode 2 Opcode 1 +00000000:00000000:00000000:00000000 +

+If we have a bundle of duliswst, it would look like: +

+st       sw       li       du +00010000:00000100:00000001:00000010 +

+Each li should have a value in the following cell(s). These +values will be pushed to the stack. E.g., lili.... and +1, 2: +

+00000000:00000000:00000001:00000001 +00000000 00000000 00000000 00000001 (1) +00000000 00000000 00000000 00000010 (2) +

+Shifts +

+sh performs a bitwise arithmetic shift operation. +

+This takes two values: +

+xy +

+And returns a single one: +

+z +

+If y is positive, this shifts x right by y bits. If negative, +it shifts left. +

+Queries: Memory, Stacks +

+The fe instruction allows queries of some data related to +the Nga VM state. These are returned by reading from negative +addresses: +

+| Address | Returns                | +| ------- | ---------------------- | +| -1      | Data stack depth       | +| -2      | Address stack depth    | +| -3      | Maximum Image Size     | +| -4      | Minimum Integer Value  | +| -5      | Maximum Integer Value  | +

+I/O Devices +

+Nga provides three instructions for interacting with I/O devices. +These are: +

+ie   i/o enumerate    returns the number of attached devices +iq   i/o query        returns information about a device +ii   i/o interact     invokes an interaction with a device +

+As an example, with an implementation providing an output source, +a block storage system, and keyboard: +

+ie    will return `3` since there are three i/o devices +0 iq  will return 0 0, since the first device is a screen (0) +      with a version of 0 +1 iq  will return 1 3, since the second device is a block +      storage (3), with a version of 1 +2 iq  will return 0 1, since the third device is a keyboard +      (1), with a version of 0 +

+In this case, some interactions can be defined: +

+: c:put +i liiire.. +d 0 + +: c:get +i liiire.. +d 2 +

+Setup the stack, push the device ID to the stack, and then use +ii to invoke the interaction. +

+A RETRO system requires one I/O device (a generic output for a +single character). This must be the first device, and must have +a device ID of 0. +

+All other devices are optional and can be specified in any order. +

+The currently supported and reserved device identifiers are: +

+| ID   | Device Type      | Notes                      | +| ---- | ---------------- | -------------------------- | +| 0000 | Generic Output   | Always present as device 0 | +| 0001 | Keyboard         |                            | +| 0002 | Floating Point   |                            | +| 0003 | Block Storage    | Raw, 1024 cell blocks      | +| 0004 | Filesystem       | Unix-style Files           | +| 0005 | Network: Gopher  | Make gopher requests       | +| 0006 | Network: HTTP    | Make HTTP requests         | +| 0007 | Network: Sockets |                            | +| 0008 | Syscalls: Unix   |                            | +| 0009 | Scripting Hooks  |                            | +| 0010 | Random Number    |                            | +

+This list may be revised in the future. The only guaranteed +stable indentifier is 0000 for generic output. +

+ diff --git a/doc/html/chapters/tech-notes/code-it-yourself.html b/doc/html/chapters/tech-notes/code-it-yourself.html new file mode 100644 index 0000000..75f4440 --- /dev/null +++ b/doc/html/chapters/tech-notes/code-it-yourself.html @@ -0,0 +1,102 @@ + + + +. + + +

The Code It Yourself Manifesto +

+We use software for our everyday needs because we want to get +something done. We have goals to achieve and things to do. +

+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. +

+Over time these will diverge. +

+This means that the tools we depend on grow features we don't +use or understand. There will be bugs in these code parts which +will prevent us from reaching our goals. +

+So we are at a fork in the road: +

+• We have the choice of trying to understand the code and
+ fix it. +• We have the choice of trying another program, whose
+ creator's goals are closer to ours. +• We also have the choice of coding the software ourself.
+

+All but the last path mean endless seeking, evaluating and +further deviation from our goals. Therefore we replace programs +we do not understand fully with our own implementation. +

+The followers of the Code It Yourself Manifesto believe in +these things: +

+• We implement it according to our own goals.
+• We make mistakes and learn from them.
+• We learn how our tools we depend on need to work.
+• We gain a deep understanding of our problem domain.
+• We still embrace sharing of ideas and code.
+

+Sharing is only possible if we are excellent developers to +each other. The next developer reading our code will be us +in a not so distant future. Coding It Ourselves means we will +document our code, clearly stating the goal of the software +we write. +

+Together we enjoy the diversity of implementations and ideas. +

+We encourage our colleagues to +

+Code It Yourself. +

+ +

+Written by Christian Kellermann on 2016-01-12, licensed under +a CreativeCommonsAttribution-ShareAlike3.0UnportedLicense. +

+Original text taken from +http://pestilenz.org/~ckeen/blog/posts/ciy-manifesto.html +

+ diff --git a/doc/html/chapters/tech-notes/historical-papers.html b/doc/html/chapters/tech-notes/historical-papers.html new file mode 100644 index 0000000..6a5532a --- /dev/null +++ b/doc/html/chapters/tech-notes/historical-papers.html @@ -0,0 +1,200 @@ + + + +. + + +

Historical Papers and Notes +

+On the Naming of RETRO +

+Taken from http://lists.tunes.org/archives/tunes-lll/1999-July/000121.html +

+On Fri, Jul 30, 1999 at 07:43:54PM -0400, Paul Dufresne wrote: +

+> My brother did found it funny that Retro is called like that. +> For him retro means going back (generally in time) so this +> does not looks like a name of a OS to come. So he'd like to +> know from where the name came. +

+Heheh, here's the story: When I started playing with OS stuff +last year (not seriously), I was reading about some old things +like FORTH and ITS, dating back to the 1960's and 70's. The +past few years in America, there's been a revival of disco +music (along with bell bottoms, platform shoes, and all that +crap) and they call it "retro". Now, my OS was named by +musicians.. I was telling a fellow musician about my ideas, +how it would be cool to have a small OS that isn't bloated and +unmanageable like Windows... go back to the 70's and resurrect +a line of software that died out. He goes "hmm.. sounds kinda +retro.." +

+I think it sounds kinda rebellious, which is a Good Thing now +that everybody hates the M$ empire. :) It seems like other +people are as sick of the future as I am. Look at TUNES, the +idea there isn't to make some great new invention, just take +some decades-old ideas and combine them in one OS. The first +time I saw Knuth's "Art of Computer Programming" in the library +I thought "god that looks old.. 1973!!! nevermind.." Now it's +my programming bible. Find me something better published in +the 90's.. if such a thing exists, it'll be like a needle in a +haystack. "Newer" doesn't necessarily mean "better". +

+ New cars = flimsier + New farming methods = more devastating + New version of Netscape = more bloat, more bullshit +

+One thing is better now: computer hardware. Give me 70's +software on 90's and 00's hardware :) +

+• Tom Novelli <tcn@tunes.org>
+

+

+The Design Philosophy of RETRO Native Forth +

+Computer software is a technology in its infancy, a mere fifty years +old. The last 25 years in particular have seen an explosion in the +software business. However, software has seen little innovation while +hardware technology has improved phenomenally (notwithstanding the advent +of lousy slave-made parts). Proven software techniques of forty years ago +have yet to reach widespread use, in deference to the "latest and +greatest" proprietary solutions of dubious value. Thanks to agressive +marketing, we make huge investments in these dead-end technologies +(through our businesses and governments, if not personally) and we end up +with a reliance on a heap of complicated, error-prone, poorly understood +junk software. +

+Complexity will dominate the software industry for the foreseeable +future. The Retro philosophy is a simple alternative for those willing to +make a clean break with legacy software. A Retro system can communicate +with other systems, but it won't run much legacy software, especially +proprietary software without source code. An emulation layer could be +added, but doing so would defeat the purpose of a simple operating system. +I think TCP/IP support is all the compatibility that's needed. +

+At first Retro will appeal to computer hobbyists and electronic +engineers. Once the rough edges are smoothed out, it could catch on with +ordinary folks who don't like waiting five minutes just to check their +email (not to mention the long hours of setup and maintenance). Game +programmers who take their craft seriously may also be interested. +Businesses might even see a use for it, if the managers decide it's more +cost-effective to carefully design software for specific needs, rather +than buying off-the-shelf crap and spending countless manhours working +around the bugs. Since it's not practical for businesses to make a clean +break, my advice is to run Retro (and its ilk) on separate machines +connected by a network. Retro is efficient enough to run on older +machines that would otherwise sit idle, being too slow for the latest +Microsoft bloatware (or Linux, for that matter). +

+I strive to avoid the extraneous. That applies even to proven +technologies, if I don't need them. If my computer isn't set up for +people to log in over the network, I don't want security features; they +just get in the way. If I'm only running programs I wrote, I should be +able to run them with full access to the hardware; I don't need protection +from viruses. If I download something I don't trust, then I can run it in +an isolated process, which is customary with Unix and kin. But that's not +core functionality. All that's needed is the flexibility to add things +like security, graphical interfaces, and distributed processing - if the +need ever arises. +

+In programming languagues, I was misled. It's the Tower of Babel all +over again. The thousands of languages in existence all fall into a +handful of archetypes: Assembler, LISP, FORTRAN and FORTH represent the +earliest descendants of nearly all languages. I hesitate to name a +definitive "object-oriented" language, and here's why: Object-Oriented +programming is just a technique, and any language will suffice, even +Assembler. The complexites of fancy languages like Ada and C++ are a +departure from reality -- the reality of the actual physical machine. +When it all boils down, even LISP, FORTRAN and FORTH are only extensions +of the machine. +

+I chose FORTH as the "native tongue" of Retro. LISP, FORTRAN, and +other languages can be efficiently implemented as extensions of FORTH, but +the reverse isn't so efficient. Theoretically all languages are +equivalent, but when design time, compilation time, and complexity are +accounted for, FORTH is most efficient. FORTH also translates most +directly to the hardware. (In fact, FORTH has been implemented in +hardware; these "stack machines" are extremely efficient.) FORTH is also +the easiest language to implement from scratch - a major concern when +you're trying to make a clean break. So with simplicity in mind, FORTH +was the obvious choice. +

+I'm perfectly happy working with text only, and I go to great lengths +to avoid using the standard graphical environments, which have major +problems: windows, pulldown menus, and mice. Windows can't share the +screen nicely; that idea is hopeless. Pulldowns are tedious. Mice get in +the way of typing without reducing the need for it; all they give me is +tendonitis. Their main use is for drawing. +

+Some of my favorite interfaces: Telix, Telegard BBS, Pine, Pico, Lynx, +and ScreamTracker. All "hotkey" interfaces where you press a key or two +to perform an action. Usually the important commands are listed at the +bottom of the screen, or at least on a help screen. The same principles +apply to graphical interfaces: use the full screen, except for a status +and menu area on one edge. Resist the temptation to clutter up the +screen. +

+As for switching between programs, the Windows methods suck; the only +thing worse is Unix job control (jobs, fg, and such). The Linux method is +tolerable: Alt-Arrows, Alt-F1, Alt-F2, etc. Still, things could be +better: F11 and F12 cycle back and forth through all open programs; Alt-F1 +assigns the currently selected program to F1, and likewise for the other +function keys. Programs just won't use function keys - Control and Alt +combinations are less awkward and easier to remember, besides. I'll also +want a "last channel" key and a "task list" key; maybe I'll borrow those +stupid Win95 keys. The Pause key will do like it says - pause the current +program - and Ctrl-Pause (Break) will kill it. +

+One more thing: consistency. I like programs to look different so I +can tell them apart, but the keys should be the same as much as possible. +Keys should be configured in one place, for all programs. Finally, +remember the most consistent interface, one of the few constants +throughout the history of computing - the text screen and keyboard, and +the teletypewriter before that. Don't overlook it. +

+More to come, maybe... :) +

+"If it's on line, it's a work in progress." +

+Tom Novelli, 3/4/2000 +

+ diff --git a/doc/html/chapters/tech-notes/kernel-words.html b/doc/html/chapters/tech-notes/kernel-words.html new file mode 100644 index 0000000..62156d3 --- /dev/null +++ b/doc/html/chapters/tech-notes/kernel-words.html @@ -0,0 +1,122 @@ + + + +. + + +

On The Kernel Wordset +

+In implementing the RETRO 12 kernel (called RETRO Core, and +defined in image/retro.muri) I had to decide on what functionality +would be needed. It was important to me that this be kept clean +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. +

+So what made it in? +

+Primitives +

+These are words that map directly to Nga instructions. +

+dup      drop     swap   call   eq?   -eq?   lt?   gt? +fetch    store    +      -      *     /mod   and   or +xor      shift    push   pop    0; +

+Memory +

+fetch-next    store-next    ,    s, +

+Strings +

+s:to-number    s:eq?    s:length +

+Flow Control +

+choose    if    -if    repeat    again +

+Compiler & Interpreter +

+Compiler    Heap        ;       [    ]      Dictionary +d:link      d:class     d:xt    d:name      d:add-header +class:word  class:primitive     class:data  class:macro +prefix::    prefix:#    prefix:&    prefix:$ +interpret   d:lookup    err:notfound +

+Assembler +

+i           d           r +

+I could slightly reduce this. The $ prefix could be defined in +higher level code, and I don't strictly need to expose the +fetch-next and store-next here. But since the are already +implemented as dependencies of the words in the kernel, it would +be a bit wasteful to redefine them later in higher level code. +

+A recent change was the addition of the assembler into the +kernel. This allows the higher levels to use assembly as needed, +which gives more flexibility and allows for more optimal code +in the standard library. +

+With these words the rest of the language can be built up. Note +that the RETRO kernel does not provide any I/O words. It's assumed +that the RETRO interfaces will add these as best suited for the +systems they run on. +

+There is another small bit. All images start with a few key +pointers in fixed offsets of memory. These are: +

+| Offset | Contains                    | +| ------ | --------------------------- | +| 0      | lit call nop nop            | +| 1      | Pointer to main entry point | +| 2      | Dictionary                  | +| 3      | Heap                        | +| 4      | RETRO version identifier    | +

+An interface can use the dictionary pointer and knowledge of the +dictionary format for a specific RETRO version to identify the +location of essential words like interpret and err:notfound +when implementing the user facing interface. +

+ diff --git a/doc/html/chapters/tech-notes/metacompilation.html b/doc/html/chapters/tech-notes/metacompilation.html new file mode 100644 index 0000000..1cbc05c --- /dev/null +++ b/doc/html/chapters/tech-notes/metacompilation.html @@ -0,0 +1,123 @@ + + + +. + + +

Metacompilation and Assembly +

+RETRO 10 and 11 were written in themselves using a metacompiler. +I had been fascinated by this idea for a long time and was able +to explore it heavily. While I still find it to be a good idea, +the way I ended up doing it was problematic. +

+The biggest issue I faced was that I wanted to do this in one +step, where loading the RETRO source would create a new image +in place of the old one, switch to the new one, and then load +the higher level parts of the language over this. In retrospect, +this was a really bad idea. +

+My earlier design for RETRO was very flexible. I allowed almost +everything to be swapped out or extended at any time. This made +it extremely easy to customize the language and environment, but +made it crucial to keep track of what was in memory and what had +been patched so that the metacompiler wouldn't refer to anything +in the old image during the relocation and control change. It +was far too easy to make a mistake, discover that elements of +the new image were broken, and then have to go and revert many +changes to try to figure out what went wrong. +

+This was also complicated by the fact that I built new images +as I worked, and, while a new image could be built from the last +built one, it wasn't always possible to build a new image from +the prior release version. (Actually, it was often worse - I +failed to check in every change as I went, so often even the +prior commits couldn't rebuild the latest images). +

+For RETRO 12 I wanted to avoid this problem, so I decided to go +back to writing the kernel ("Rx") in assembly. I actually wrote +a Machine Forth dialect to generate the initial assembly, before +eventually hand tuning the final results to its current state. +

+I could (and likely will eventually) write the assembler in +RETRO, but the current one is in C, and is built as part of the +standard toolchain. +

+My VM actually has two assemblers. The older one is Naje. This +was intended to be fairly friendly to work with, and handles +many of the details of packing instructions for the user. Here +is an example of a small program in it: +

+:square +  dup +  mul +  ret +:main +  lit 35 +  lit &square +  call +  end +

+The other assembler is Muri. This is a far more minimalistic +assembler, but I've actually grown to prefer it. The above +example in Muri would become: +

+i liju.... +r main +: square +i dumure.. +: main +i lilica.. +d 35 +r square +i en...... +

+In Muri, each instruction is reduced to two characters, and the +bundlings are listed as part of an instruction bundle (lines +starting with i). This is less readable if you aren't very +familiar with Nga's assembly and packing rules, but allows a +very quick, efficient way of writing assembly for those who are. +

+I eventually rewrote the kernel in the Muri style as it's what +I prefer, and since there's not much need to make changes in it. +

+ diff --git a/doc/html/chapters/tech-notes/ngaro-to-nga.html b/doc/html/chapters/tech-notes/ngaro-to-nga.html new file mode 100644 index 0000000..e0493d5 --- /dev/null +++ b/doc/html/chapters/tech-notes/ngaro-to-nga.html @@ -0,0 +1,120 @@ + + + +. + + +

On The Evolution Of Ngaro Into Nga +

+When I decided to begin work on what became RETRO 12, I knew +the process would involve updating Ngaro, the virtual machine +that RETRO 10 and 11 ran on. +

+Ngaro rose out of an earlier experimental virtual machine I had +written back in 2005-2006. This earlier VM, called Maunga, was +very close to what Ngaro ended up being, though it had a very +different approach to I/O. (All I/O in Maunga was intended to be +memory mapped; Ngaro adopted a port based I/O system). +

+Ngaro itself evolved along with RETRO, gaining features like +automated skipping of NOPs and a LOOP opcode to help improve +performance. But the I/O model proved to be a problem. When I +created Ngaro, I had the idea that I would always be able to +assume a console/terminal style environment. The assumption was +that all code would be entered via the keyboard (or maybe a +block editor), and that proved to be the fundamental flaw as +time went on. +

+As RETRO grew it was evident that the model had some serious +problems. Need to load code from a file? The VM and language had +functionality to pretend it was being typed in. Want to run on +something like a browser, Android, or iOS? The VM would need to +be implemented in a way that simulates input being typed into +the VM via a simulated keyboard. And RETRO was built around this. +I couldn't change it because of a promise to maintain, as much +as possible, source compatibility for a period of at least five +years. +

+When the time came to fix this, I decided at the start to keep +the I/O model separate from the core VM. I also decided that the +core RETRO language would provide some means of interpreting +code without requiring an assumption that a traditional terminal +was being used. +

+So Nga began. I took the opportunity to simplify the instruction +set to just 26 essential instructions, add support for packing +multiple instructions per memory location (allowing a long due +reduction in memory footprint), and to generally just make a far +simpler design. +

+I've been pleased with Nga. On its own it really isn't useful +though. So with RETRO I embed it into a larger framework that +adds some basic I/O functionality. The interfaces handle the +details of passing tokens into the language and capturing any +output. They are free to do this in whatever model makes most +sense on a given platform. +

+So far I've implemented: +

+- a scripting interface, reading input from a file and +  offering file i/o, gopher, and reading from stdin, and +  sending output to stdout. +- an interactive interface, built around ncurses, reading +  input from stdin, and displaying output to a scrolling +  buffer. +- an iOS interface, built around a text editor, directing +  output to a separate interface pane. +- an interactive block editor, using a gopher-based block +  data store. Output is displayed to stdout, and input is +  done via the blocks being evaluated or by reading from +  stdin. +

+In all cases, the only common I/O word that has to map to an +exposed instruction is putc, to display a single character to +some output device. There is no requirement for a traditional +keyboard input model. +

+By doing this I was able to solve the biggest portability issue +with the RETRO 10/11 model, and make a much simpler, cleaner +language in the end. +

+ diff --git a/doc/html/chapters/tech-notes/prefixes.html b/doc/html/chapters/tech-notes/prefixes.html new file mode 100644 index 0000000..2f6eea7 --- /dev/null +++ b/doc/html/chapters/tech-notes/prefixes.html @@ -0,0 +1,93 @@ + + + +. + + +

Prefixes as a Language Element +

+A big change in RETRO 12 was the elimination of the traditional +parser from the language. This was a sacrifice due to the lack +of an I/O model. RETRO has no way to know how input is given +to the interpret word, or whether anything else will ever be +passed into it. +

+And so interpret operates only on the current token. The core +language does not track what came before or attempt to guess at +what might come in the future. +

+This leads into the prefixes. RETRO 11 had a complicated system +for prefixes, with different types of prefixes for words that +parsed ahead (e.g., strings) and words that operated on the +current token (e.g., @). RETRO 12 eliminates all of these in +favor of just having a single prefix model. +

+The first thing interpret does is look to see if the first +character in a token matches a prefix: word. If it does, it +passes the rest of the token as a string pointer to the prefix +specific handler to deal with. If there is no valid prefix +found, it tries to find it in the dictionary. Assuming that it +finds the words, it passes the d:xt field to the handler that +d:class points to. Otherwise it calls err:notfound. +

+This has an important implication: words can not reliably +have names that start with a prefix character. +

+It also simplifies things. Anything that would normally parse +becomes a prefix handler. So creating a new word? Use the : +prefix. Strings? Use '. Pointers? Try &. And so on. E.g., +

+In ANS                  | In RETRO +: foo ... ;             | :foo ... ; +' foo                   | &foo +: bar ... ['] foo ;     | :bar ... &foo ; +s" hello world!"        | 'hello_world! +

+If you are familiar with ColorForth, prefixes are a similar +idea to colors, but can be defined by the user as normal words. +

+After doing this for quite a while I rather like it. I can see +why Chuck Moore eventually went towards ColorForth as using +color (or prefixes in my case) does simplify the implementation +in many ways. +

+ diff --git a/doc/html/chapters/tech-notes/retro11-retrospective.html b/doc/html/chapters/tech-notes/retro11-retrospective.html new file mode 100644 index 0000000..c173ce4 --- /dev/null +++ b/doc/html/chapters/tech-notes/retro11-retrospective.html @@ -0,0 +1,126 @@ + + + +. + + +

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

+So it's now been about five years since the last release of RETRO +11. While I still see some people obtaining and using it, I've +moved on to the twelth generation of RETRO. It's time for me to +finally retire RETRO 11. +

+As I prepare to do so, I thought I'd take a brief look back. +

+RETRO 11 began life in 2011. It grew out of RETRO 10, which was +the first version of RETRO to not be written in x86 assembly +language. For R10 and R11, I wrote a portable virtual machine +(with numerous implementations) and the Forth dialect was kept +in an image file which ran on the VM. +

+RETRO 10 worked, but was always a bit too sloppy and changed +drastically between releases. The major goal of RETRO 11 was to +provide a stable base for a five year period. In retrospect, +this was mostly achieved. Code from earlier releases normally +needed only minor adjustments to run on later releases, though +newer releases added significantly to the language. +

+There were seven releases. +

+• Release 11.0: 2011, July
+• Release 11.1: 2011, November
+• Release 11.2: 2012, January
+• Release 11.3: 2012, March
+• Release 11.4: 2012, July
+• Release 11.5: 2013, March
+• Release 11.6: 2014, August
+

+Development was fast until 11.4. This was the point at which I +had to slow down due to RSI problems. It was also the point +which I started experiencing some problems with the metacompiler +(as discussed previously). +

+RETRO 11 was flexible. All colon definitions were setup as hooks, +allowing new functionality to be layered in easily. This allowed +the later releases to add things like vocabularies, search order, +tab completion, and keyboard remapping. This all came at a cost +though: later things could use the hooks to alter behavior of +existing words, so it was necessary to use a lot of caution to +ensure that the layers didn't break the earlier code. +

+The biggest issue was the I/O model. RETRO 11 and the Ngaro VM +assumed the existence of a console environment. All input was +required to be input at the keyboard, and all output was to be +shown on screen. This caused some problems. Including code from +a file required some tricks, temporarily rewriting the keyboard +input function to read from the file. It also became a major +issue when I wrote the iOS version. The need to simulate the +keyboard and console complicated everything and I had to spend +a considerable amount of effort to deal with battery performance +resulting from the I/O polling and wait states. +

+But on the whole it worked well. I used RETRO 11.6 until I started +work on RETRO 12 in late 2016, and continued running some tools +written in R11 until the first quarter of last year. +

+The final image file was 23,137 cells (92,548 bytes). This was +bloated by keeping some documentation (stack comments and short +descriptions) in the image, which started in 11.4. This contained +269 words. +

+I used RETRO 11 for a wide variety of tasks. A small selection of +things that were written includes: +

+• a pastebin
+• front end to ii (irc client)
+• small explorations of interactive fiction
+• irc log viewer
+• tool to create html from templates
+• tool to automate creation of an SVCD from a set of photos
+• tools to generate reports from data sets for my employer
+

+In the end, I'm happy with how RETRO 11 turned out. I made some +mistakes in embracing too much complexity, but despite this it +was a successful system for many years. +

+ diff --git a/doc/html/chapters/tech-notes/security.html b/doc/html/chapters/tech-notes/security.html new file mode 100644 index 0000000..4748171 --- /dev/null +++ b/doc/html/chapters/tech-notes/security.html @@ -0,0 +1,91 @@ + + + +. + + +

Security Concerns +

+The standard RETRO is not a good choice for applications +needing to be highly secure. +

+Runtime Checks +

+The RETRO system performs only minimal checks. It will not +load an image larger than the max set at build time. And +stack over/underflow are checked for as code executes. +

+The system does not attempt to validate anything else, it's +quite easy to crash. +

+Isolation +

+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. +

+I/O presents a bigger issue. Anything involving I/O, especially +with the unix: words, may be a vector for attacks. +

+Future Direction +

+I'm not planning to add anything to the image side as, for me, +the performance hit due to added checks is bigger than the +benefits. +

+The story is different on the VM side. I've already begun taking +steps to address some of the issues, using functions that check +for overruns with strings and doing some minor testing for these +conditions. I will be gradually addressing the various I/O +related extensions, though it's unlikely to ever be fully guarded +against attacks. +

+Rationale +

+RETRO is, primarily, a personal system. I'm running code I wrote +to solve problems I face. On the occasions where I run code sent +to me by others, I read it carefully first and then run inside a +sandboxed environment if I'm worried about anything in it. +

+ diff --git a/doc/html/chapters/tech-notes/self-hosting.html b/doc/html/chapters/tech-notes/self-hosting.html new file mode 100644 index 0000000..7d654a1 --- /dev/null +++ b/doc/html/chapters/tech-notes/self-hosting.html @@ -0,0 +1,169 @@ + + + +. + + +

The Path to Self Hosting +

+RETRO is an image based Forth system running on a lightweight +virtual machine. This is the story of how that image is made. +

+The first RETRO to use an image based approach was RETRO 10. +The earliest images were built using a compiler written in +Toka, an earlier experimental stack language I had written. +It didn't take long to want to drop the dependency on Toka, +so I rewrote the image compiler in RETRO and then began +development at a faster pace. +

+RETRO 11 was built using the last RETRO 10 image and an +evolved version of the metacompiler. This worked well, but +I eventually found it to be problematic. +

+One of the issues I faced was the inability to make a new +image from the prior stable release. Since I develop and +test changes incrementally, I reached a point where the +current metacompiler and image required each other. This +wasn't a fatal flaw, but it was annoying. +

+Perhaps more critical was the fragility of the system. In +R11 small mistakes could result in a corrupt image. The test +suite helped identify some of these, but there were a few +times I was forced to dig back through the version control +history to recover a working image. +

+The fragile nature was amplified by some design decisions. +In R11, after the initial kernel was built, it would be +moved to memory address 0, then control would jump into the +new kernel to finish building the higher level parts. +

+Handling this was a tricky task. In R11 almost everything +could be revectored, so the metacompiler had to ensure that +it didn't rely on anything in the old image during the move. +This caused a large number of issues over R11's life. +

+So on to RETRO 12. I decided that this would be different. +First, the kernel would be assembly, with an external tool +to generate the core image. The kernel is in Rx.md and the +assembler is Muri. To load the standard library, I wrote a +second tool, retro-extend. This separation has allowed me +many fewer headaches as I can make changes more easily and +rebuild from scratch when necessary. +

+But I miss self-hosting. So last fall I decided to resolve +this. And today I'm pleased to say that it is now done. +

+There are a few parts to this. +

+Unu. I use a Markdown variation with fenced code blocks. +The tool I wrote in C to extract these is called unu. For +a self hosting RETRO, I rewrote this as a combinator that +reads in a file and runs another word against each line in the +file. So I could display the code block contents by doing: +

+'filename [ s:put nl ] unu +

+This made it easier to implement the other tools. +

+Muri. This is my assembler. It's minimalistic, fast, and +works really well for my purposes. RETRO includes a runtime +version of this (using as{, }as, i, d, and r), so +all I needed for this was to write a few words to parse the +lines and run the corresponding runtime words. As with the C +version, this is a two pass assembler. +

+Muri generates a new ngaImage with the kernel. To create a +full image I needed a way to load in the standard library and +I/O extensions. +

+This is handled by retro-extend. This is where it gets +more complex. I implemented the Nga virtual machine in RETRO +to allow this to run the new image in isolation from the +host image. The new ngaImage is loaded, the interpreter is +located, and each token is passed to the interpreter. Once +done, the new image is written to disk. +

+So at this point I'm pleased to say that I can now develop +RETRO using only an existing copy of RETRO (VM+image) and +tools (unu, muri, retro-extend, and a line oriented text +editor) written in RETRO. +

+This project has delivered some additional side benefits. +During the testing I was able to use it to identify a few +bugs in the I/O extensions, and the Nga-in-RETRO will replace +the older attempt at this in the debugger, allowing a safer +testing environment. +

+What issues remain? +

+The extend process is slow. On my main development server +(Linode 1024, OpenBSD 6.4, 64-bit) it takes a bit over five +minutes to complete loading the standard library, and a few +additional depending on the I/O drivers selected. +

+Most of the performance issues come from running Nga-in-RETRO +to isolate the new image from the host one. It'd be possible +to do something a bit more clever (e.g., running a RETRO +instance using the new image via a subprocess and piping in +the source, or doing relocations of the data), but this is +less error prone and will work on all systems that I plan to +support (including, with a few minor adjustments, the native +hardware versions [assuming the existance of mass storage]). +

+Sources: +

+Unu +

+• http://forth.works/c8820f85e0c52d32c7f9f64c28f435c0
+• gopher://forth.works/0/c8820f85e0c52d32c7f9f64c28f435c0
+

+Muri +

+• http://forth.works/09d6c4f3f8ab484a31107dca780058e3
+• gopher://forth.works/0/09d6c4f3f8ab484a31107dca780058e3
+

+retro-extend +

+• http://forth.works/c812416f397af11db58e97388a3238f2
+• gopher://forth.works/0/c812416f397af11db58e97388a3238f2
+

+ diff --git a/doc/html/chapters/tech-notes/underscores-in-names.html b/doc/html/chapters/tech-notes/underscores-in-names.html new file mode 100644 index 0000000..315b71c --- /dev/null +++ b/doc/html/chapters/tech-notes/underscores-in-names.html @@ -0,0 +1,96 @@ + + + +. + + +

On The Use Of Underscores In Word Names +

+In brief: don't use underscores in word names. +

+There is a good reason for this, and it has to do with how RETRO +processes strings. By default, underscores in strings are replaced +by spaces. This is problematic when dealing with words like var, +const, and d:create which take word names as strings. +

+Consider: +

+:hello_msg 'hello_user ; +'test_name var +#188 !test_name +

+In the first case, the : prefix handles the token, so the +underscore is not remapped to a space, creating a word name as +hello_msg. But in the second, the ' prefix remaps the +underscore to a space, giving a variable name of test name. +In the third line, the name lookup will fail as test_name is +not defined, so the store will be done to an incorrect address. +

+Because of this, it's best to avoid underscores in names. +

+Having covered this, if you do need to use them for some reason, +you can replace d:add-header with a version that remaps spaces +back to underscores before creating the header. The following +will allow for this. +

+~~~ +{{ +  :fields        @Dictionary , (link) , (xt) , (class) ; +  :invalid-name? dup ASCII:SPACE s:contains-char? ; +  :rewrite       [ ASCII:SPACE [ $_ ] case ] s:map ; +  :entry         here &call dip !Dictionary ; +  [ [ fields invalid-name? &rewrite if s, (name) ] entry ] +}} +

+#1793 &d:add-header store +&d:add-header n:inc store +~~~ +

+Additional Note: +

+Some version of RETRO have included the above patch. The last +release that will include this by default is 2020.4 as it is +not needed by the majority of users. If you want to keep it in +your system, you will need to load it yourself or add it to +your package/list.forth (for Unix users) before building. +

+ diff --git a/doc/html/chapters/techniques/arrays.html b/doc/html/chapters/techniques/arrays.html new file mode 100644 index 0000000..c82f04b --- /dev/null +++ b/doc/html/chapters/techniques/arrays.html @@ -0,0 +1,154 @@ + + + +. + + +

Working With Arrays +

+RETRO offers a number of words for operating on statically sized +arrays. +

+Namespace +

+The words operating on arrays are kept in an a: namespace. +

+Creating Arrays +

+The easiest way to create an array is to wrap the values in a +{ and } pair: +

+```
{ #1 #2 #3 #4 }
+{ 'this 'is 'an 'array 'of 'strings }
+{ 'this 'is 'a 'mixed 'array #1 #2 #3 }
+```

+You can also make an array from a quotation which returns +values and the number of values to store in the a: +

+```
[ #1 #2 #3  #3 ] a:counted-results
+[ #1 #2 #3  #3 ] a:make
+```

+Accessing Elements +

+You can access a specific value with a:th and fetch or +store: +

+```
{ #1 #2 #3 #4 } #3 a:th fetch
+```

+Find The Length +

+Use a:length to find the size of the array. +

+```
{ #1 #2 #3 #4 } a:length
+```

+Duplicate +

+Use a:dup to make a copy of an a: +

+```
{ #1 #2 #3 #4 } a:dup
+```

+Filtering +

+RETRO provides a:filter which extracts matching values +from an array. This is used like: +

+```
{ #1 #2 #3 #4 #5 #6 #7 #8 } [ n:even? ] a:filter
+```

+The quote will be passed each value in the array and should +return TRUE or FALSE. Values that lead to TRUE will be collected +into a new array. +

+Mapping +

+a:map applies a quotation to each item in an array and +constructs a new array from the returned values. +

+Example: +

+```
{ #1 #2 #3 } [ #10 * ] a:map
+```

+Reduce +

+a:reduce takes an array, a starting value, and a quote. It +executes the quote once for each item in the array, passing the +item and the value to the quote. The quote should consume both +and return a new value. +

+```
{ #1 #2 #3 } #0 [ + ] a:reduce
+```

+Search +

+RETRO provides a:contains? and a:contains-string? +to search an array for a value (either a number or string) and +return either TRUE or FALSE. +

+```
#100  { #1 #2 #3 } a:contains?
+'test { 'abc 'def 'test 'ghi } a:contains-string?
+```

+Implementation +

+In memory, an array is a count followed by the values. As an +example, if you have an array: +

+{ #10 #20 #30 } +

+In memory this would be setup as: +

+| Offset | Value | +| ------ | ----- | +| 000    | 3     | +| 001    | 10    | +| 002    | 20    | +| 003    | 30    | +

+You can construct one on the fly by keeping a pointer to +here and using , to place the values. E.g., +

+here [ #3 , #10 , #20 , #30 , ] dip +

+An example of this can be seen in this excerpt from an example +(example/Primes.forth): +

+:create-set (-a)  +    here #3000 , #2 #3002 [ dup , n:inc ] times drop ; +

+ diff --git a/doc/html/chapters/techniques/assembly.html b/doc/html/chapters/techniques/assembly.html new file mode 100644 index 0000000..65fea15 --- /dev/null +++ b/doc/html/chapters/techniques/assembly.html @@ -0,0 +1,165 @@ + + + +. + + +

Working With Assembly Language +

+RETRO runs on a virtual machine called Nga. It provides a +standard assembler for this called Muri. +

+Muri is a simple, multipass model that's not fancy, but +suffices for RETRO's needs. +

+Assembling A Standalone File +

+A small example (test.muri) +

+~~~ +i liju.... +r main +: c:put +i liiire.. +i 0 +: main +i lilica.. +d 97 +i liju.... +r main +~~~ +

+Assembling it: +

+retro-muri test.muri +

+So breaking down: Muri extracts the assembly code blocks to +assemble, then proceeds to do the assembly. Each source line +starts with a directive, followed by a space, and then ending +with a value. +

+The directives are: +

+:    value is a label +i    value is an instruction bundle +d    value is a numeric value +r    value is a reference +s    value is a string to inline +

+Instructions for Nga are provided as bundles. Each memory +location can store up to four instructions. And each instruction +gets a two character identifier. +

+From the list of instructions: +

+0 nop   5 push  10 ret   15 fetch 20 div   25 zret +1 lit   6 pop   11 eq    16 store 21 and   26 halt +2 dup   7 jump  12 neq   17 add   22 or    27 ienum +3 drop  8 call  13 lt    18 sub   23 xor   28 iquery +4 swap  9 ccall 14 gt    19 mul   24 shift 29 iinvoke +

+This reduces to: +

+0 ..    5 pu    10 re    15 fe    20 di    25 zr +1 li    6 po    11 eq    16 st    21 an    26 ha +2 du    7 ju    12 ne    17 ad    22 or    27 ie +3 dr    8 ca    13 lt    18 su    23 xo    28 iq +4 sw    9 cc    14 gt    19 mu    24 sh    29 ii +

+Most are just the first two letters of the instruction name. I +use .. instead of no for NOP, and the first letter of +each I/O instruction name. So a bundle may look like: +

+dumure.. +

+(This would correspond to dup multiply return nop). +

+Runtime Assembler +

+RETRO also has a runtime variation of Muri that can be used +when you need to generate more optimal code. So one can write: +

+:n:square dup * ; +

+Or: +

+:n:square \dumure.. ; +

+The second one will be faster, as the entire definition is one +bundle, which reduces memory reads and decoding by 2/3. +

+Doing this is less readable, so I only recommend doing so after +you have finalized working RETRO level code and determined the +best places to optimize. +

+The runtime assembler has the following directives: +

+i    value is an instruction bundle +d    value is a numeric value +r    value is a reference +

+Additionally, in the runtime assembler, these are reversed: +

+'dudumu.. i +

+Instead of: +

+i dudumu.. +

+The runtime assembler also provides three prefixes for use in +inlining machine code into a definition. These are: +

+ \    Treat token as an assembly sequence + `    Treat token as a numeric value + ^    Treat token as a reference +

+E.g., instead of doing something like: +

+:n:square as{ 'dumu.... i }as ; +:test as{ 'lilica.... i #22 d 'n:square r }as ; +

+Just write: +

+:n:square \dumu.... ; +:test     \lilica.. `22 ^n:square ;  +

+ diff --git a/doc/html/chapters/techniques/buffer.html b/doc/html/chapters/techniques/buffer.html new file mode 100644 index 0000000..1157d71 --- /dev/null +++ b/doc/html/chapters/techniques/buffer.html @@ -0,0 +1,186 @@ + + + +. + + +

Working With a Buffer +

+RETRO provides words for operating on a linear memory area. +This can be useful in building strings or custom data +structures. +

+Namespace +

+Words operating on the buffer are kept in the buffer: +namespace. +

+Implementation +

+A buffer is a linear sequence of memory. The buffer words +provide a means of incrementally storing and retrieving +values from it. +

+The buffer words keep track of the start and end of the +buffer. They also ensure that an ASCII:NULL is written +after the last value, which make using them for string +data easy. +

+Limitations +

+Only one buffer can be active at a time. RETRO provides a +buffer:preserve combinator to allow using a second one +before returning to the prior one. +

+Set The Active Buffer +

+To set a buffer as the active one use buffer:set. This takes +an address. +

+The buffer will be assumed to be empty. The initial value will +be set to ASCII:NULL. +

+Add Value +

+Use buffer:add to append a value to the buffer. This takes +a single value and will also add an ASCII:NULL after the end +of the buffer. +

+Fetch Last Value +

+To return the last value in the buffer you can use buffer:get. +This removes the value and sets an ASCII:NULL in the memory +location the returned value occupied. +

+Get Data About The Buffer +

+RETRO provides buffer:start to get the initial address in +the buffer, buffer:end to get the last address (ignoring the +ASCII:NULL), and buffer:size to return the number of values +in the buffer. +

+Reset +

+You can reset a buffer to the empty state using buffer:empty. +

+Example +

+To begin, create a memory region to use as a buffer. +

+```
'Test d:create #1025 allot
+```

+Then you can set this as the current buffer: +

+```
&Test buffer:set
+```

+When a buffer is set, the vocabulary sets an internal +index to the first address in it. This will be +incremented when you add data and decremented when you +remove data. +

+Let's add some stuff using buffer:add: +

+```
#100 buffer:add
+#200 buffer:add
+#300 buffer:add
+```

+And then retrieve the values: +

+```
buffer:get n:put nl
+buffer:get n:put nl
+buffer:get n:put nl
+```

+You can remove all values using buffer:empty: +

+```
#100 buffer:add
+#200 buffer:add
+#300 buffer:add
+buffer:empty
+```

+And ask the buffer how many items it contains: +

+```
buffer:size n:put nl
+#100 buffer:add
+#200 buffer:add
+#300 buffer:add
+buffer:size n:put nl
+buffer:empty
+```

+The other functions are buffer:start, which returns +the address of the buffer, buffer:end, which returns +the address of the last value, and buffer:preserve. +The first is easy to demo: +

+```
buffer:start Test eq? n:put nl
+```

+The last one is useful. Only one buffer is ever active +at a given time. The buffer:preserve combinator lets +you execute a word, saving and restoring the current +buffer indexes. So the word could assign and use a new +buffer and this will reset the previous one after +control returns. +

+There are a few notes that need to be considered. The +preserve combinator saves the start and current index +but not the contents. If the word you call uses the +same buffer, the contents will remain altered. +

+Finally, the buffer words have one interesting trait: +they store an ASCII NULL after adding each item to the +buffer. This lets one use them to build strings easily. +

+```
Test buffer:set
+$h buffer:add
+$e buffer:add
+$l buffer:add
+$l buffer:add
+$o buffer:add
+$, buffer:add
+#32 buffer:add
+$w buffer:add
+$o buffer:add
+$r buffer:add
+$l buffer:add
+$d buffer:add
+buffer:start s:put nl
+```

+ diff --git a/doc/html/chapters/techniques/characters.html b/doc/html/chapters/techniques/characters.html new file mode 100644 index 0000000..66a97f7 --- /dev/null +++ b/doc/html/chapters/techniques/characters.html @@ -0,0 +1,110 @@ + + + +. + + +

Working With Characters +

+RETRO provides words for working with ASCII characters. +

+Prefix +

+Character constants are returned using the $ prefix. +

+Namespace +

+Words operating on characters are in the c: namespace. +

+Classification +

+RETRO provides a number of words to determine if a character +fits into predefined groups. +

+The primary words for this are: +

+• c:consonant?
+• c:digit?
+• c:letter?
+• c:lowercase?
+• c:uppercase?
+• c:visible?
+• c:vowel?
+• c:whitespace?
+

+There are also corresponding "not" forms: +

+• c:-consonant?
+• c:-digit?
+• c:-lowercase?
+• c:-uppercase?
+• c:-visible?
+• c:-vowel?
+• c:-whitespace?
+

+All of these take a character and return either a TRUE or +FALSE flag. +

+Conversions +

+A few words are provided to convert case. Each takes a character +and returns the modified character. +

+• c:to-lower
+• c:to-number
+• c:to-upper
+• c:toggle-case
+

+RETRO also has c:to-string, which takes a character and +creates a new temporary string with the character. +

+I/O +

+Characters can be displayed using c:put. +

+```
$a c:put
+```

+With the default system on BSD, Linux, and macOS (and other +Unix style hosts), c:get is provided to read input. This +may be buffered, depending on the host. +

+ diff --git a/doc/html/chapters/techniques/checking-the-version.html b/doc/html/chapters/techniques/checking-the-version.html new file mode 100644 index 0000000..24e720f --- /dev/null +++ b/doc/html/chapters/techniques/checking-the-version.html @@ -0,0 +1,69 @@ + + + +. + + +

Checking The Version +

+RETRO releases add and change things. You can use the Version +variable to determine the version in use and react accordingly. +

+```
@Version #201906 eq? [ 'Needs_2019.6! s:put nl bye ] if
+```

+This can be also be used to conditionally load compatibility files: +

+```
(If_newer_than_2016.6,_load_aliases_for_renamed_words)
+@Version #201906 gt? [ 'Renamed_2019.6.forth include ] if
+```

+Version Number Format +

+The version is a six digit number encoding the year and month of +the release. So: +

+201901  is  2019.1 +201906  is  2019.6 +201911  is  2019.11 +

+A #100 /mod will suffice to split these if needed. +

+ diff --git a/doc/html/chapters/techniques/definitions.html b/doc/html/chapters/techniques/definitions.html new file mode 100644 index 0000000..d4eaf8c --- /dev/null +++ b/doc/html/chapters/techniques/definitions.html @@ -0,0 +1,57 @@ + + + +. + + +

Defining Words +

+Words are named functions. To start a word, preceed it's name +with a colon. Follow this by the definition, and end with a +semicolon. +

+E.g., +

+:do-nothing ; +:square dup * ; +

+ diff --git a/doc/html/chapters/techniques/dictionary.html b/doc/html/chapters/techniques/dictionary.html new file mode 100644 index 0000000..c827a79 --- /dev/null +++ b/doc/html/chapters/techniques/dictionary.html @@ -0,0 +1,148 @@ + + + +. + + +

Working With The Dictionary +

+The Dictionary is a linked list containing the dictionary +headers. +

+Namespace +

+Words operating on the dictionary are in the d: namespace. +

+Variables +

+Dictionary is a variable holding a pointer to the most recent +header. +

+Header Structure +

+Each entry follows the following structure: +

+Offset   Contains +------   --------------------------- +0000     Link to Prior Header +0001     Link to XT +0002     Link to Class Handler +0003+    Word name (null terminated) +

+RETRO provides words for accessing the fields in a portable +manner. It's recommended to use these to allow for future +revision of the header structure. +

+Accessing Fields +

+Given a pointer to a header, you can use d:xt, d:class, +and d:name to access the address of each specific field. +There is no d:link, as the link will always be the first +field. +

+Shortcuts For The Latest Header +

+RETRO provides several words for operating on the most recent +header. +

+d:last returns a pointer to the latest header. d:last.xt +will give the contents of the d:xt field for the latest +header. There are also d:last.class and d:last.name. +

+Adding Headers +

+Two words exist for making new headers. The easy one is +d:create. This takes a string for the name and makes a +new header with the class set to class:data and the XT +field pointing to here. +

+Example: +

+```
'Base d:create
+```

+The other is d:add-header. This takes a string, a pointer +to the class handler, and a pointer for the XT field and +builds a new header using these. +

+Example: +

+```
'Base &class:data #10000 d:add-header
+```

+Searching +

+RETRO provides two words for searching the dictionary. +

+d:lookup takes a string and tries to find it in the +dictionary. It will return a pointer to the dictionary header +or a value of zero if the word was not found. +

+d:lookup-xt takes a pointer and will return the dictionary +header that has this as the d:xt field, or zero if no match +is found. +

+Iteration +

+You can use the d:for-each combinator to iterate over all +entries in the dictionary. For instance, to display the names +of all words: +

+```
[ d:name s:put sp ] d:for-each
+```

+For each entry, this combinator will push a pointer to the +entry to the stack and call the quotation. +

+Listing Words +

+Most Forth systems provide WORDS for listing the names of all +words in the dictionary. RETRO does as well, but this is named +d:words. +

+This isn't super useful as looking through several hundred +names is annoying. RETRO also provides d:words-with to help +in filtering the results. +

+Example: +

+```
'class: d:words-with
+```

+

+ diff --git a/doc/html/chapters/techniques/errors.html b/doc/html/chapters/techniques/errors.html new file mode 100644 index 0000000..6b82ad2 --- /dev/null +++ b/doc/html/chapters/techniques/errors.html @@ -0,0 +1,81 @@ + + + +. + + +

Errors +

+RETRO does only minimal error checking. +

+Non-Fatal +

+A non-fatal error will be reported on word not found during +interactive or compile time. Note that this only applies to +calls: if you try to get a pointer to an undefined word, the +returned pointer will be zero. +

+Fatal +

+A number of conditions are known to cause fatal errors. The +main ones are stack overflow, stack underflow, and division +by zero. +

+On these, RETRO will generally exit. For stack depth issues, +the VM will attempt to display an error prior to exiting. +

+In some cases, the VM may get stuck in an endless loop. If this +occurs, try using CTRL+C to kill the process, or kill it using +whatever means your host system provides. +

+Rationale +

+Error checks are useful, but slow - especially on a minimal +system like RETRO. The overhead of doing depth or other checks +adds up quickly. +

+As an example, adding a depth check to drop increases the +time to use it 250,000 times in a loop from 0.16 seconds to +1.69 seconds. +

+

+ diff --git a/doc/html/chapters/techniques/files.html b/doc/html/chapters/techniques/files.html new file mode 100644 index 0000000..7ad06e1 --- /dev/null +++ b/doc/html/chapters/techniques/files.html @@ -0,0 +1,212 @@ + + + +. + + +

Working With Files +

+On Unix and Windows systems RETRO provides a set of words for +working with files. As a pragmatic choice these are mostly +modeled after the file functions in libc. +

+The file words are in the file: namespace. +

+File Access Modes +

+You can open a file for various operations. The functionality +allowed depends on the file access mode. Valid modes in RETRO +are: +

+file:A    Open for appending; file pointer set to end of file +file:R    Open for reading; file pointer set to start of file +file:R+   Open for reading and writing +file:W    Open for writing +

+Opening A File +

+To open a file, pass the file name and a file mode to file:open. +

+'/etc/motd file:R file:open +

+On a successful open this will return a file handle greater than +zero. +

+Additionally, RETRO provides a few other forms for opening files. +

+To open a file for reading: +

+'/etc/motd file:open-for-reading +

+This will return the size of the file (as NOS) and the file handle +(as TOS). +

+To open a file for writing: +

+'/tmp/test file:open-for-writing +

+This returns the file handle. +

+To open a file for append operations: +

+'/tmp/test file:open-for-append +

+As with file:open-for-reading, this returns both the size of +the file and the file handle. +

+Closing A File +

+To close a file, pass the file handle to file:close. +

+'/etc/motd file:A file:open file:close +

+Reading From A File +

+To read a byte from an open file, pass the file handle to the +file:read word. +

+@FID file:read n:put +

+To read a line from a file, pass the file handle to the word +file:read-line. +

+@FID file:read-line s:put +

+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. +

+Writing To A File +

+To write a byte to a file, pass it and the file handle to +file:write. +

+$h @FID file:write +$e @FID file:write +$l @FID file:write +$l @FID file:write +$o @FID file:write +

+Though cells are 32 or 64 bits in size, only the byte value will +be written to the file. +

+Deleting Files +

+You can delete a file by passing the file name to file:delete. +

+/tmp/test file:delete +

+Check For File Existance +

+Use file:exists? to detect the existance of a file. Pass it a +file name and it will return TRUE if existing or FALSE if +it does not. +

+'/etc/motd file:exists? +

+This will also return TRUE if the filename is a directory. +

+Flush Caches +

+Use file:flush to flush the system caches for a file. Pass a +file handle to this. +

+@FID file:flush +

+Seek A Position Within A File +

+You can use file:seek to move the internal file pointer +for a given file. Pass this the new location and a file. +

+#100 @FID file:seek +

+The location for the file pointer is a fixed offset from the +start of the file, not a relative offset. +

+Get The Current Position Within A File +

+To find the current value of the file pointer within a file +just pass the file handle to file:tell. +

+@FID file:tell +

+This returns a number that is the number of bytes into the file +that the file pointer is currently at. +

+Determine The Size Of A File +

+Use file:size to return the size of a file. Pass this a file +handle and it will return the size of a file, or 0 if empty. If +the file is a directory, it returns -1. +

+@FID file:size +

+Reading An Entire File +

+If you want to read an entire file into memory you can use +file:slurp. This takes the starting address of a memory +region and the name of the file. +

+here '/etc/motd file:slurp +

+Take care that the memory buffer is large enough for the file +being read or you will run into problems. +

+Writing A String To A File +

+If you have a string that you want to write to a file, replacing +any existing contents, you can use file:spew. This takes the +string to write and a file name. +

+'hello_world '/tmp/test.txt file:spew +

+Iterating Over A File, Line By Line +

+You can easily iterate over each line in a file using the word +file:for-each-line. This will take a file name and a quote, +read each line into a temporary string, then pass this string to +the quote. +

+'/etc/motd [ s:put nl ] file:for-each-line +

+ diff --git a/doc/html/chapters/techniques/floating-point.html b/doc/html/chapters/techniques/floating-point.html new file mode 100644 index 0000000..089030f --- /dev/null +++ b/doc/html/chapters/techniques/floating-point.html @@ -0,0 +1,224 @@ + + + +. + + +

Working With Floating Point +

+Some RETRO systems include support for floating point numbers. +When present, this is built over the system libm using the +C double type. +

+Floating point values are typically 64 bit IEEE 754 double +precision (1 bit for the sign, 11 bits for the exponent, and +the remaining 52 bits for the value), i.e. 15 decimal digits +of precision. +

+Prefix +

+Floating point numbers start with a . +

+Examples: +

+ Token Value +.1       1.0 +.0.5     0.5 +.-.4    -0.4 +.1.3     1.3 +

+Namespace +

+Floating point words are in the f: namespace. There is also +a related e: namespace for encoded values, which allows +storing of floats in standard memory. +

+Operation +

+Floating point values exist on a separate stack, and are bigger +than the standard memory cells, so can not be directly stored +and fetched from memory. +

+The floating point system also provides an alternate stack that +can be used to temporarily store values. +

+The following words exist for arranging values on the floating +point stack. These are direct analogs to the non-prefiexd words +for dealing with the data stack. +

+• f:nip
+• f:over
+• f:depth
+• f:drop
+• f:drop-pair
+• f:dup
+• f:dup-pair
+• f:dump-stack
+• f:tuck
+• f:swap
+• f:rot
+

+For the secondary floating point stack, the following words are +provided: +

+• f:push
+• f:pop
+• f:adepth
+• f:dump-astack
+

+Constants +

+| Name     | Returns           | +| -------- | ----------------- | +| `f:E`    | Euler's number    | +| `f:-INF` | Negative infinity | +| `f:INF`  | Positive infinity | +| `f:NAN`  | Not a Number      | +| `f:PI`   | PI                | +

+Comparisons +

+The basic set of comparators are the same as those for +operating on integers. These are: +

+• f:-eq?
+• f:between?
+• f:eq?
+• f:gt?
+• f:lt?
+• f:negative?
+• f:positive?
+• f:case
+

+There are also a few additions for comparing to special values +like infinity and NaN. +

+• f:-inf?
+• f:inf?
+• f:nan?
+

+Basic Math +

+• f:*
+• f:+
+• f:-
+• f:/
+• f:abs
+• f:floor
+• f:inc
+• f:limit
+• f:max
+• f:min
+• f:negate
+• f:power
+• f:ceiling
+• f:dec
+• f:log
+• f:sqrt
+• f:square
+• f:round
+• f:sign
+• f:signed-sqrt
+• f:signed-square
+

+Geometry +

+RETRO provides a small number of words for doing geometric +related calculations. +

+| Word | Returns | +| -------- | ------------ | +| f:acos | arc cosine | +| f:asin | arc sine | +| f:atan | arc tangent | +| f:cos | cosine | +| f:sin | sine | +| f:tan | tangent | +

+Storage and Retrieval +

+By leveraging the encoded value functions, RETRO is able to +allow storage of floating point values in memory. This does +have a tradeoff in accuracy as the memory cells are considerably +smaller than a full floating point size. +

+You can use f:fetch to fetch a floating point value and +f:store to store one. +

+If you need more precision, try Kiyoshi Yoneda's FloatVar +example (example/FloatVar.forth), which includes words to +store and retrieve values using multiple cells. +

+• f:to-number
+• f:to-string
+

+I/O +

+The floating point vocabulary has a single I/O word, f:put, +for the display of floating point numbers. +

+Encoded Values +

+RETRO provides a means of encoding and decoding floating point +values into standard integer cells. This is based on the paper +"Encoding floating point values to shorter integers" by Kiyoshi +Yoneda and Charles Childers. +

+• f:E1
+• f:to-e
+• e:-INF
+• e:-inf?
+• e:INF
+• e:MAX
+• e:MIN
+• e:NAN
+• e:clip
+• e:inf?
+• e:max?
+• e:min?
+• e:n?
+• e:nan?
+• e:put
+• e:to-f
+• e:zero?
+

+ diff --git a/doc/html/chapters/techniques/lexical-scope.html b/doc/html/chapters/techniques/lexical-scope.html new file mode 100644 index 0000000..ca790a2 --- /dev/null +++ b/doc/html/chapters/techniques/lexical-scope.html @@ -0,0 +1,85 @@ + + + +. + + +

Lexical Scope +

+RETRO has a single dictionary, but does provide a means of using +lexical scope to keep this dictionary clean. +

+Example +

+```
{{
+  'A var
+  :++A  &A v:inc ;
+---reveal---
+  :B ++A ++A @A n:put nl ;
+}}
+```

+In this example, the lexical namespace is created with {{. A +variable (A) and word (++A) are defined. Then a marker is +set with ---reveal---. Another word (B) is defined, and the +lexical area is closed with }}. +

+The headers between {{ and ---reveal--- are then hidden from +the dictionary, leaving only the headers between ---reveal--- +and }} exposed. +

+Notes +

+This only affects word visibility within the scoped area. As an +example: +

+```
:a #1 ;
+ 
+{{
+  :a #2 ;
+---reveal---
+  :b 'a s:evaluate n:put ;
+}}
+```

+In this, after }} closes the area, the :a #2 ; is hidden and +the s:evaluate will find the :a #1 ; when b is run. +

+ diff --git a/doc/html/chapters/techniques/loops.html b/doc/html/chapters/techniques/loops.html new file mode 100644 index 0000000..1e84526 --- /dev/null +++ b/doc/html/chapters/techniques/loops.html @@ -0,0 +1,110 @@ + + + +. + + +

Loops +

+RETRO provides several words for creating loops. +

+Unconditional Loops +

+An unconditional loop begins with repeat and ends with again. +

+:test repeat #1 n:put sp again ; +test +

+Unconditional loops must be inside a definition or quote. To exit +one of these, use 0;, -if; or if;. +

+:test #100 repeat 0; dup n:put sp n:dec again ; +test +

+:test #100 repeat dup #50 eq? [ 'done! s:put nl ] if; n:dec again ; +test +

+You can also achieve this via recursion: +

+:test 0; dup n:put sp n:dec test ; +#100 test +

+Be careful with recursion as the virtual machine will have a limited +amount of space for the address stack and recursing too many times +can cause a stack overflow. +

+Conditional Loops +

+There are two conditional looping combinators: while and until. +Both take a quote and execute it, checking a returned flag to decide +when to stop running. +

+#0 [ dup n:put sp n:inc dup #10 eq? ] until +#10 [ dup n:put sp n:dec dup n:-zero? ] while +

+Counted Loops +

+There are two combinators for counted loops. These are times and +indexed-times. +

+#0 #10 [ dup n:put sp n:inc ] times nl +#10 [ I n:put sp ] indexed-times +

+The indexed-times provides an index via the I, J, and +K words. I will be the index of the current loop, with J and +K being the indexes of the next two older loops. +

+The loop indexes can be accessed outside the loop body: +

+:display I n:square n:put sp ; +:squares [ display ] indexed-times nl ; +#100 squares +

+Tradeoffs +

+The unconditional loop form is more efficient as it's just a +simple jump operation. The times counted loops are a little +slower, but can be cleaner and more readable in many cases. The +indexed-times form is significantly slower than the other +two forms. +

+ diff --git a/doc/html/chapters/techniques/naming-conventions.html b/doc/html/chapters/techniques/naming-conventions.html new file mode 100644 index 0000000..5dfd43a --- /dev/null +++ b/doc/html/chapters/techniques/naming-conventions.html @@ -0,0 +1,143 @@ + + + +. + + +

Naming Conventions +

+Word names in RETRO generally follow the following conventions. +

+General Guidelines +

+• Readability is important
+• Be consistent
+• Don't use a prefix as the first character of a name
+• Don't use underscores in word names
+• Use short names for indices
+• Word names start with a - for "not"
+• Words returning a flag end in ?
+

+Typical Format +

+The word names will generally follow a form like: +

+[namespace:]name +

+The namespace: is optional, but recommended for consistency +with the rest of the system and to make it easier to identify +related words. +

+Case +

+Word names are lowercase, with a dash (-) for compound names. +

+hello +drop-pair +s:for-each +

+Variables use TitleCase, with no dash between compound names. +

+Base +Heap +StringBuffers +

+Constants are UPPERCASE, with a dash (-) for compound names. +

+TRUE +FALSE +f:PI +MAX-STRING-LENGTH +

+Namespaces +

+Words are grouped into broad namespaces by attaching a short +prefix string to the start of a name. +

+The common namespaces are: +

+| Prefix  | Contains                                               | +| ------- | ------------------------------------------------------ | +| a:      | Words operating on simple arrays                       | +| ASCII:  | ASCII character constants for control characters       | +| buffer: | Words for operating on a simple linear LIFO buffer     | +| c:      | Words for operating on ASCII character data            | +| class:  | Contains class handlers for words                      | +| d:      | Words operating on the Dictionary                      | +| err:    | Words for handling errors                              | +| io:     | General I/O words                                      | +| n:      | Words operating on numeric data                        | +| prefix: | Contains prefix handlers                               | +| s:      | Words operating on string data                         | +| v:      | Words operating on variables                           | +| file:   | File I/O words                                         | +| f:      | Floating Point words                                   | +| unix:   | Unix system call words                                 | +

+Tips +

+Don't Start Names With Prefix Characters +

+Avoid using a prefix as the first character of a word name. RETRO +will look for prefixes first, this will prevent direct use of +the work in question. +

+To find a list of prefix characters, do: +

+'prefix: d:words-with +

+Don't Use Underscores +

+Underscores in strings are replaced by spaces. This is problematic, +especially with variables. Consider: +

+'test_name var +#188 !test_name +

+In this, the string for the name is converted to "test name". The +store in the second line will not add the space, so resolves to an +incorrect address. +

+I personally recommend avoiding the use of underscores in any word +names. +

+ diff --git a/doc/html/chapters/techniques/numbers.html b/doc/html/chapters/techniques/numbers.html new file mode 100644 index 0000000..52bad5b --- /dev/null +++ b/doc/html/chapters/techniques/numbers.html @@ -0,0 +1,129 @@ + + + +. + + +

Working With Numbers +

+Numbers in RETRO are signed integers. +

+Token Prefix +

+All numbers start with a # prefix. +

+Namespace +

+Most words operating on numbers are in the n: namespace. +

+Range of Values +

+A default RETRO system with 32 bit cells provides a range of +-2,147,483,648 to 2,147,483,647. For 64 bit systems, the range +will be -9,223,372,036,854,775,807 to 9,223,372,036,854,775,806. +

+You can check the range your VM and image support using: +

+n:MIN +n:MAX +

+These will return the limits for your system. +

+Comparisons +

+RETRO provides a number of comparison words for numeric values. +

+The basic comparators are: +

+-eq? +eq? +lt? +lteq? +gt? +gteq? +

+Additionally RETRO also provides: +

+n:-zero? +n:between? +n:even? +n:negative? +n:odd? +n:positive? +n:strictly-positive? +n:zero? +

+Basic Operations +

++ +- +* +/ +mod +/mod +n:abs +n:dec +n:inc +n:limit +n:max +n:min +n:negate +n:pow +n:sqrt +n:square +

+Conversions +

+You can convert a number to a string with n:to-string or +to a floating point value with n:to-float. +

+#123 n:to-float  f:put +

+#123 n:to-string s:put +

+Display +

+To display a number, use n:put. +

+#123 n:put +

+ diff --git a/doc/html/chapters/techniques/pointers.html b/doc/html/chapters/techniques/pointers.html new file mode 100644 index 0000000..c474a63 --- /dev/null +++ b/doc/html/chapters/techniques/pointers.html @@ -0,0 +1,80 @@ + + + +. + + +

Working With Pointers +

+Prefix +

+Pointers are returned by the & prefix. +

+Examples +

+```
'Base var
+&Base fetch
+#10 &Base store
+ 
+#10 &n:inc call
+```

+Notes +

+The use of & to get a pointer to a data structure (with a +word class of class:data) is not required. I like to use it +anyway as it makes my intent a little clearer. +

+Pointers are useful with combinators. Consider: +

+```
:abs dup n:negative? [ n:negate ] if ;
+```

+Since the target quote body is a single word, it is more +efficient to use a pointer instead: +

+```
:abs dup n:negative? &n:negate if ;
+```

+The advantages are speed (saves a level of call/return by +avoiding the quotation) and size (for the same reason). +This may be less readable though, so consider the balance +of performance to readability when using this approach. +

+ diff --git a/doc/html/chapters/techniques/quotes.html b/doc/html/chapters/techniques/quotes.html new file mode 100644 index 0000000..54bc5f1 --- /dev/null +++ b/doc/html/chapters/techniques/quotes.html @@ -0,0 +1,133 @@ + + + +. + + +

Quotations +

+Quotes are anonymous functions. RETRO uses these as the basis for +executable flow control and combinatorial logic. +

+Using Quotations +

+To make a quotation, surround the code with square brackets. E.g., +

+#1 #2 eq? [ 'No_match s:put nl ] -if +

+Quotes can be nested: +

+[ #3 [ #4 ] dip ] call +

+After creation, a pointer to the quotation is left on the stack +(or is compiled into the current definition). +

+Combinators +

+Words operating on quotations are called combinators; these are +discussed in Using Combinators. +

+Implementation +

+A quotation is compiled as: +

+... code before quotation ... +i liju....                    (if_compiling_only) +d address after quotation     (if_compiling_only) +... code for quotation +i re......                    (this_is_where_the_quote_ends) +i li...... +d address of code for quotation +... code after quotation .... +

+Other Notes +

+Quotations are used heavily in RETRO. They give the source a +feel that's different from traditional Forth, and allow for +a more consistent syntax. +

+For instance, in a traditional Forth, you might have some +conditionals: +

+IF ... THEN +IF ... ELSE ... THEN +IF ... EXIT THEN +

+RETRO uses conditional combinators for these: +

+[ ... ] if +[ ... ] [ ... ] choose +[ ... ] if; +

+Or loops: +

+FOR ... NEXT +

+Is replaced by: +

+[ ... ] times +

+This can also extend to stack flow. Sequences like: +

+>R ... >R +DUP >R ... >R +

+Become: +

+[ ... ] dip +[ ... ] sip +

+And forms like: +

+1 2 3 * swap 3 * swap +

+Can be replaced with a combinator like: +

+#1 #2 [ #3 * ] bi@ +

+While there is a different set of words to learn, I find that +overall there's less noise from low level stack shuffling words +and the added consistency with regards to overall syntax has +been nice as I was never fond of the multiple forms that existed +in traditional Forth. +

+ diff --git a/doc/html/chapters/techniques/return-stack.html b/doc/html/chapters/techniques/return-stack.html new file mode 100644 index 0000000..0e58c48 --- /dev/null +++ b/doc/html/chapters/techniques/return-stack.html @@ -0,0 +1,54 @@ + + + +. + + +

The Return Stack +

+RETRO has two stacks. The primary one is used to pass data +between words. The second one primarily holds return addresses. +

+Each time a word is called, the next address is pushed to +the return stack. +

+ diff --git a/doc/html/chapters/techniques/scripting.html b/doc/html/chapters/techniques/scripting.html new file mode 100644 index 0000000..68bf372 --- /dev/null +++ b/doc/html/chapters/techniques/scripting.html @@ -0,0 +1,99 @@ + + + +. + + +

Unix Scripting +

+RETRO on Unix hosts is designed to play well with scripting. +

+Shebang +

+To run an entire program directly, start the file with the +standard shebang and make the file executable: +

+#!/usr/bin/env retro +

+This requires the retro binary to be in your path. +

+Arguments +

+RETRO provides several words in the script: namespace for accessing +command line arguments. +

+The number of arguments can be accessed via script:arguments. This +will return a number with the arguments, other than the script +name. +

+script:arguments '%n_arguments_passed\n s:format s:put +

+To retreive an argument, pass the argument number to script:get-argument: +

+script:arguments [ I script:get-argument s:put nl ] indexed-times  +

+And to get the name of the script, use script:name. +

+script:name s:put +

+Mixing +

+With use of the Unu literate format, it's possible to mix both +shell and RETRO code into a single script. As an example, this +is a bit of shell that runs itself via retro for each .retro +file in the current directory tree: +

+#!/bin/sh +

+# shell part +find . -name '*.retro' -print0 | xargs -0 -n 1 retro $0 +exit +

+# retro part +

+This will scan a source file and do something with it: +

+~~~ +... do stuff ... +~~~ +

+ diff --git a/doc/html/chapters/techniques/sockets.html b/doc/html/chapters/techniques/sockets.html new file mode 100644 index 0000000..a43b12e --- /dev/null +++ b/doc/html/chapters/techniques/sockets.html @@ -0,0 +1,114 @@ + + + +. + + +

Sockets +

+On Unix hosts, RETRO provides an optional set of words for using +network sockets. +

+Create a Socket +

+To create a new socket, just run: +

+socket:create +

+This will return a socket handle. +

+Bind To A Port +

+To bind to a port, pass the port number and socket handle +to socket:bind. The port should be a string. This will return +0 if successful, -1 if not successful, and an error code. +

+'9998 @Sock socket:bind +

+Configure To Allow Incoming Connections +

+To prepare a socket for incoming connections use socket:listen. This +will take a backlog count and a socket handle. It returns a flag +(0 success, -1 failed) and an error code. +

+#3 @Sock socket:listen +

+Accept Connections +

+To accept connections pass the socket handle to socket:accept. +This returns a new socket for the connection and an error code. +

+@Sock socket:accept +

+Make A Connection +

+To connect to a server using the socket: +

+'forth.works '70 socket:configure +@Sock socket:connect +

+socket:connect will return a status code and an error code. +

+Writing To A Socket +

+To write a string to a socket, use socket:send. This will +take a string and a socket handle and will return the number +of bytes sent and an error code. +

+'test @Sock socket:send +

+Reading From A Socket +

+To read data from a socket pass an address, a maximum number of +bytes, and the socket handle to socket:recv. This will return +the number of bytes received and an error code. The bytes will +be stored in memory starting at the specified address. +

+here #1024 @Sock socket:recv +

+Close a Socket +

+To close a socket, pass the socket handle to socket:close. +

+@Socket socket:close +

+ diff --git a/doc/html/chapters/techniques/stack-diagrams.html b/doc/html/chapters/techniques/stack-diagrams.html new file mode 100644 index 0000000..a0495c9 --- /dev/null +++ b/doc/html/chapters/techniques/stack-diagrams.html @@ -0,0 +1,79 @@ + + + +. + + +

Stack Diagrams +

+Most words in RETRO have a stack comment. These look like: +

+(-) +(nn-n) +

+As with all comments, a stack comment begins with ( and +should end with a ). There are two parts to the comment. +On the left side of the - is what the word consumes. On +the right is what it leaves. +

+RETRO uses a short notation, with one character per value +taken or left. In general, the following symbols represent +certain types of values. +

+| Notation            | Represents              | +| ------------------- | ----------------------- | +| b, n, m, o, x, y, z | generic numeric values  | +| s                   | string                  | +| v                   | variable                | +| p, a                | pointers                | +| q                   | quotation               | +| d                   | dictionary header       | +| f                   | `TRUE` or `FALSE` flag. | +

+In the case of something like (xyz-m), RETRO expects z to be +on the top of the stack, with y below it and x below the y +value. And after execution, a single value (m) will be left on +the stack. +

+Words with no stack effect have a comment of (-) +

+ diff --git a/doc/html/chapters/techniques/strings.html b/doc/html/chapters/techniques/strings.html new file mode 100644 index 0000000..1918c01 --- /dev/null +++ b/doc/html/chapters/techniques/strings.html @@ -0,0 +1,209 @@ + + + +. + + +

Working With Strings +

+Strings in RETRO are NULL terminated sequences of values +representing characters. Being NULL terminated, they can't +contain a NULL (ASCII 0). +

+The character words in RETRO are built around ASCII, but +strings can contain UTF8 encoded data if the host platform +allows. Words like s:length will return the number of bytes, +not the number of logical characters in this case. +

+Prefix +

+Strings begin with a single '. +

+'Hello +'This_is_a_string +'This_is_a_much_longer_string_12345_67890_!!! +

+RETRO will replace spaces with underscores. If you need both +spaces and underscores in a string, escape the underscores and +use s:format: +

+'This_has_spaces_and_under\_scored_words. s:format +

+Namespace +

+Words operating on strings are in the s: namespace. +

+Lifetime +

+At the interpreter, strings get allocated in a rotating buffer. +This is used by the words operating on strings, so if you need +to keep them around, use s:keep or s:copy to move them to +more permanent storage. +

+In a definition, the string is compiled inline and so is in +permanent memory. +

+You can manually manage the string lifetime by using s:keep +to place it into permanent memory or s:temp to copy it to +the rotating buffer. +

+Mutability +

+Strings are mutable. If you need to ensure that a string is +not altered, make a copy before operating on it or see the +individual glossary entries for notes on words that may do +this automatically. +

+Searching +

+RETRO provides four words for searching within a string. +

+• s:contains-char?
+• s:contains-string?
+• s:index-of
+• s:index-of-string
+

+Comparisons +

+• s:eq?
+• s:case
+

+Extraction +

+To obtain a new string containing the first n characters from +a source string, use s:left: +

+'Hello_World #5 s:left +

+To obtain a new string containing the last n characters from +a source string, use s:right: +

+'Hello_World #5 s:right +

+If you need to extract data from the middle of the string, use +s:substr. This takes a string, the offset of the first +character, and the number of characters to extract. +

+'Hello_World #3 #5 s:substr +

+Joining +

+You can use s:append or s:prepend to merge two strings. +

+'First 'Second s:append +'Second 'First s:prepend +

+Tokenization +

+• s:tokenize
+• s:tokenize-on-string
+• s:split
+• s:split-on-string
+

+Conversions +

+To convert the case of a string, RETRO provides s:to-lower +and s:to-upper. +

+s:to-number is provided to convert a string to an integer +value. This has a few limitations: +

+• only supports decimal
+• non-numeric characters will result in incorrect values
+

+Cleanup +

+RETRO provides a handful of words for cleaning up strings. +

+s:chop will remove the last character from a string. This +is done by replacing it with an ASCII:NULL. +

+s:trim removes leading and trailing whitespace from a string. +For more control, there is also s:trim-left and s:trim-right +which let you trim just the leading or trailing end as desired. +

+Combinators +

+• s:for-each
+• s:filter
+• s:map
+

+Other +

+• s:evaluate
+• s:copy
+• s:reverse
+• s:hash
+• s:length
+• s:replace
+• s:format
+• s:empty
+

+Controlling The Temporary Buffers +

+As dicussed in the Lifetime subsection, temporary strings are +allocated in a rotating buffer. The details of this can be +altered by updating two variables. +

+| Variable      | Holds                                    | +| ------------- | ---------------------------------------- | +| TempStrings   | The number of temporary strings          | +| TempStringMax | The maximum length of a temporary string | +

+For example, to increase the number of temporary strings to +48: +

+#48 !TempStrings +

+The defaults are: +

+| Variable      | Default | +| ------------- | ------- | +| TempStrings   | 32      | +| TempStringMax | 512     | +

+It's also important to note that altering these will affect +the memory map for all temporary buffers. Do not use anything +already in the buffers after updating these or you will risk +data corruption and possible crashes. +

+ diff --git a/doc/html/chapters/techniques/the-stacks.html b/doc/html/chapters/techniques/the-stacks.html new file mode 100644 index 0000000..d1ac617 --- /dev/null +++ b/doc/html/chapters/techniques/the-stacks.html @@ -0,0 +1,169 @@ + + + +. + + +

The Stacks +

+The stacks are a defining feature of Forth. They are are used +to pass data between words and to track return addresses for +function calls. +

+RETRO always has two stacks, and optionally (if built with +floating point support) a third. +

+Data Stack +

+This is the primary stack. Values are placed here, passed to +words which consume them and then return results. When I +refer to "the stack", this is the one I mean. Learning to use +the stack is a crucial part to making effective use of RETRO. +

+Placing Values On The Stack +

+Values can be placed on the stack directly. +

+| Example        | Action                                   | +| -------------- | ---------------------------------------- | +| `#300123`      | Push the number `300123` to the stack    | +| `$h`           | Push the ASCII code for `h` to the stack | +| `'hello_world` | Push a pointer to a string to the stack  | +| `&fetch`       | Push the address of `fetch` to the stack | +

+Reordering The Stack +

+RETRO provides a number of shufflers for reordering items +on the stack. +

+Some of the most common ones are: +

+| Word    | Before   | After    | +| ------- |--------- | -------- | +| dup     | #1       | #1 #1    | +| drop    | #1 #2    | #1       | +| swap    | #1 #2    | #2 #1    | +| over    | #1 #2    | #1 #2 #1 | +| tuck    | #1 #2    | #2 #1 #2 | +| nip     | #1 #2    | #2       | +| rot     | #1 #2 #3 | #3 #1 #2 | +

+You can use push and pop to move values to and from the +address stack. Make sure you pop them back before the word +ends or RETRO will crash. These two words can not be used +at the interpreter. +

+There is also a special one, reorder, which allows for big +stack restructuring. This is slow but can be very useful. +

+As an example, let's say we have four values: +

+#1 #2 #3 #4 +

+And we want them to become: +

+#4 #3 #2 #1 +

+Doing this with the basic shufflers is difficult. You could end +up with something similar to: +

+swap rot push rot pop swap  +

+But with reorder, you can just express the before and after +states: +

+'abcd 'dcba reorder +

+Resetting The Stack +

+If you need to quickly empty the stack, use reset. +

+Get The Stack Depth +

+To find out how many items are on the stack, use depth. +

+Displaying The Stack +

+You can display the stack by running dump-stack. +

+Data Flow Combinators +

+RETRO provides combinators for working with data order on +the stack. These are covered in a later chapter and are worth +learning to use as they can help provide a cleaner, more +structured means of working. +

+Tips +

+The stack is not an array in addressable memory. Don't try +to treat it like one. +

+Address Stack +

+This stack primarily holds return addresses for function calls. +You normally won't need to directly interact with this stack, +but you can use push and pop to move values between the +data stack and this. +

+Floating Point Stack +

+If you are using a build with floating point support a third +stack will be present. Floating point values are kept and +passed between words using this. +

+See the Floating Point chapter for more details on this. +

+Tips +

+I recommend keeping the data stack shallow. Don't try to juggle +too much; it's better to factor definitions into shorter ones +that deal with simpler parts of the stack values than to have +a big definition with a lot of complex shuffling. +

+Notes +

+The standard system is configured with a very deep data stack +(around 2,000 items) and an address stack that is 3x deeper. +In actual use, your programs are unlikely to ever need this, +but if you do, keep the limits in mind. +

+ diff --git a/doc/html/chapters/techniques/using-combinators.html b/doc/html/chapters/techniques/using-combinators.html new file mode 100644 index 0000000..7fcd43a --- /dev/null +++ b/doc/html/chapters/techniques/using-combinators.html @@ -0,0 +1,239 @@ + + + +. + + +

Using Combinators +

+A combinator is a function that consumes functions as input. +They are used heavily by the RETRO system. +

+Types of Combinators +

+Combinators are divided into three primary types: compositional, +execution flow, and data flow. +

+Compositional +

+A compositional combinator takes elements from the stack and +returns a new quote. +

+curry takes a value and a quote and returns a new quote +applying the specified quote to the specified value. As an +example, +

+```
:acc (n-)  here swap , [ dup v:inc fetch ] curry ;
+```

+This would create an accumulator function, which takes an +initial value and returns a quote that will increase the +accumulator by 1 each time it is invoked. It will also return +the latest value. So: +

+```
#10 acc
+dup call n:put
+dup call n:put
+dup call n:put
+```

+Execution Flow +

+Combinators of this type execute other functions. +

+Fundamental +

+call takes a quote and executes it immediately. +

+```
[ #1 n:put ] call
+&words call
+```

+Conditionals +

+RETRO provides three primary combinators for use with +conditional execution of quotes. These are choose, if, +and -if. +

+choose takes a flag and two quotes from the stack. If the +flag is true, the first quote is executed. If false, the +second quote is executed. +

+```
#-1 [ 'true s:put ] [ 'false s:put ] choose
+ #0 [ 'true s:put ] [ 'false s:put ] choose
+```

+if takes a flag and one quote from the stack. If the flag is +true, the quote is executed. If false, the quote is discarded. +

+```
#-1 [ 'true s:put ] if
+ #0 [ 'true s:put ] if
+```

+-if takes a flag and one quote from the stack. If the flag is +false, the quote is executed. If true, the quote is discarded. +

+```
#-1 [ 'false s:put ] -if
+ #0 [ 'false s:put ] -if
+```

+RETRO also provides case and s:case for use when you have +multiple values to check against. This is similar to a switch +in C. +

+case takes two numbers and a quote. The initial value is +compared to the second one. If they match, the quote is +executed. If false, the quote is discarded and the initial +value is left on the stack. +

+Additionally, if the first value was matched, case will exit +the calling function, but if false, it returns to the calling +function. +

+s:case works the same way, but for strings instead of simple +values. +

+```
:test (n-)
+  #1 [ 'Yes s:put ] case
+  #2 [ 'No  s:put ] case
+  drop 'No idea s:put ;
+```

+Looping +

+Several combinators are available for handling various looping +constructs. +

+while takes a quote from the stack and executes it repeatedly +as long as the quote returns a true flag on the stack. This flag +must be well formed and equal -1 or 0. +

+```
#10 [ dup n:put sp n:dec dup 0 -eq? ] while
+```

+times takes a count and quote from the stack. The quote will +be executed the number of times specified. No indexes are pushed +to the stack. +

+```
#1 #10 [ dup n:put sp n:inc ] times drop
+```

+There is also a indexed-times variation that provides +access to the loop index (via I) and parent loop indexes +(via J and K). +

+```
#10 [ I n:put sp ] indexed-times
+```

+Data Flow +

+These combinators exist to simplify stack usage in various +circumstances. +

+Preserving +

+Preserving combinators execute code while preserving portions +of the data stack. +

+dip takes a value and a quote, moves the value off the main +stack temporarily, executes the quote, and then restores the +value. +

+```
#10 #20 [ n:inc ] dip
+```

+Would yield the following on the stack: +

+```
11 20
+```

+sip is similar to dip, but leaves a copy of the original +value on the stack during execution of the quote. So: +

+```
#10 [ n:inc ] sip
+```

+Leaves us with: +

+```
11 10
+```

+Cleave +

+Cleave combinators apply multiple quotations to a single value +or set of values. +

+bi takes a value and two quotes, it then applies each quote to +a copy of the value. +

+```
#100 [ n:inc ] [ n:dec ] bi
+```

+tri takes a value and three quotes. It then applies each quote +to a copy of the value. +

+```
#100 [ n:inc ] [ n:dec ] [ dup * ] tri
+```

+Spread +

+Spread combinators apply multiple quotations to multiple values. +The asterisk suffixed to these function names signifies that +they are spread combinators. +

+bi* takes two values and two quotes. It applies the first +quote to the first value and the second quote to the second +value. +

+```
#1 #2 [ n:inc ] [ #2 * ] bi*
+```

+tri* takes three values and three quotes, applying the +first quote to the first value, the second quote to the +second value, and the third quote to the third value. +

+```
#1 #2 #3 [ n:inc ] [ #2 * ] [ n:dec ] tri*
+```

+Apply +

+Apply combinators apply a single quotation to multiple values. +The @ sign suffixed to these function names signifies that they +are apply combinators. +

+bi@ takes two values and a quote. It then applies the quote to +each value. +

+```
#1 #2 [ n:inc ] bi@
+```

+tri@ takes three values and a quote. It then applies the quote +to each value. +

+```
#1 #2 #3 [ n:inc ] tri@
+```

+RETRO also provides for-each combinators for various data +structures. The exact usage of these varies; consult the +Glossary and relevant chapters for more details on these. +

+ diff --git a/doc/html/chapters/techniques/word-classes.html b/doc/html/chapters/techniques/word-classes.html new file mode 100644 index 0000000..16d7d1b --- /dev/null +++ b/doc/html/chapters/techniques/word-classes.html @@ -0,0 +1,97 @@ + + + +. + + +

Word Classes +

+Word classes are one of the two elements at the heart of +RETRO's interpreter. +

+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. +

+In RETRO I define special words which receive a pointer and +decide how to deal with it. These are grouped into a class: +namespace. +

+How It Works +

+When a word is found in the dictionary, RETRO will push a +pointer to the definition (the d:xt field) to the stack +and then call the word specified by the d:class field. +

+The word called is responsible for processing the pointer +passed to it. +

+As a simple case, let's look at immediate words. These are +words which will always be called when encountered. A common +strategy is to have an immediacy bit which the interpreter +will look at, but RETRO uses a class for this. The class is +defined: +

+```
:class:immediate (a-)  call ;
+```

+Or a normal word. These should be called at interpret time +or compiled into definitions. The handler for this can look +like: +

+```
:class:word (a-) compiling? [ compile:call ] [ call ] choose ;
+```

+Using Classes +

+The ability to add new classes is useful. If I wanted to add +a category of word that preserves an input value, I could do +it with a class: +

+```
:class:duplicating (a-)
+  compiling? [ &dup compile:call ] [ &dup dip ] choose
+  class:word ;  
+ 
+:duplicating &class:duplicating reclass ;
+ 
+:. n:put nl ; duplicating
+#100 . . .
+```

+ diff --git a/doc/html/chapters/toolchain/info/additional-tools.html b/doc/html/chapters/toolchain/info/additional-tools.html new file mode 100644 index 0000000..c3d250b --- /dev/null +++ b/doc/html/chapters/toolchain/info/additional-tools.html @@ -0,0 +1,129 @@ + + + +. + + +

Additional Tools +

+In addition to the core retro binary, the bin directory +will contain a few other tools. +

+retro +

+This is the main RETRO binary. +

+retro-describe +

+This is a program that looks up entries in the Glossary. +

+At the command line, you can use it like: +

+retro-describe s:for-each +

+You can pass multiple word names to it: +

+retro-describe s:for-each nl d:words +

+retro-embedimage +

+This is a program which generates a C file with the ngaImage +contents. It's used when building retro. +

+retro-embedimage ngaImage +

+The output is written to stdout; redirect it as needed. +

+retro-extend +

+This is a program which compiles code into the ngaImage. +It's used when building retro and when you want to make a +standalone image with custom additions. +

+Example command line: +

+retro-extend ngaImage example/rot13.forth +

+Pass the image name as the first argument, and then file names +as subsequent ones. Do not use this for things relying on I/O +apart from the basic console output as it doesn't emulate other +devices. If you need to load in things that rely on using the +optional I/O devices, see the Advanced Builds chapter. +

+retro-muri +

+This is the assembler for Nga. It's used to build the initial +RETRO kernel and can be used by other tools as well. +

+retro-muri retro.muri +

+retro-tags and retro-locate +

+These tools are intended to be used together. The first tool, +retro-tags, will recursively scan the current directory for +RETRO source files and extract the locations of words defined +in them. These will be written to disk in a tags file, using +the standard ctags format. +

+retro-locate takes a word name, and returns the location(s) +where it is defined. This requires a tags file to be present. +

+Create the tags file: +

+retro-tags +

+Locate a word: +

+retro-locate n:square +

+retro-unu +

+This is the literate source extraction tool for RETRO. It +is used in building retro. +

+Example usage: +

+retro-unu literate/RetroForth.md +

+Output is written to stdout; redirect as neeeded. +

+ diff --git a/doc/html/chapters/toolchain/info/retro-compiler.html b/doc/html/chapters/toolchain/info/retro-compiler.html new file mode 100644 index 0000000..bd8077a --- /dev/null +++ b/doc/html/chapters/toolchain/info/retro-compiler.html @@ -0,0 +1,101 @@ + + + +. + + +

The Optional Retro Compiler +

+In addition to the base system, users of RETRO on Unix hosts +with ELF executables can build and use the retro-compiler +to generate turnkey executables. +

+Requirements +

+• Unix host
+• ELF executable support
+• objcopy in the $PATH
+

+Building +

+ make bin/retro-compiler +

+Installing +

+Copy bin/retro-compiler to somewhere in your $PATH. +

+Using +

+retro-compiler takes two arguments: the source file to +compile and the name of the word to use as the main entry +point. +

+Example: +

+Given a hello.forth: +

+~~~ +:hello 'Hello_World! s:put nl ; +~~~ +

+Use: +

+retro-compiler hello.forth hello +

+The compiler will generate an a.out file which you can +then rename. +

+Known Limitations +

+This does not provide the scripting support for command line +arguments that the standard retro interface offers. +

+A copy of objcopy needs to be in the path for compilation +to work. +

+The current working directory must be writable. +

+This only supports hosts using ELF executables. +

+The output file name is fixed to a.out. +

+ diff --git a/doc/html/chapters/toolchain/man/retro-describe.html b/doc/html/chapters/toolchain/man/retro-describe.html new file mode 100644 index 0000000..c631a90 --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro-describe.html @@ -0,0 +1,67 @@ + + + +. + + +

RETRO-DESCRIBE(1) General Commands Manual RETRO-DESCRIBE(1) +

+RETRO-DESCRIBE + retro-describe - a modern, pragmatic forth development system +

+SYNOPSIS + retro-describe wordname [additional wordnames] +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro-describe is a tool for looking up the description and stack + comments for words in the core language and extensions.  It will write + output to stdout. +

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.4 May 2019 OpenBSD 6.4 +

+ diff --git a/doc/html/chapters/toolchain/man/retro-document.html b/doc/html/chapters/toolchain/man/retro-document.html new file mode 100644 index 0000000..277dddc --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro-document.html @@ -0,0 +1,67 @@ + + + +. + + +

RETRO-DOCUMENT(1) General Commands Manual RETRO-DOCUMENT(1) +

+RETRO-DOCUMENT + retro-document - a modern, pragmatic forth development system +

+SYNOPSIS + retro-document filename +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro-document is a tool for generating a listing of the descriptions and + stack comments for all standard word used in a source file. It will write + output to stdout. +

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.4 May 2019 OpenBSD 6.4 +

+ diff --git a/doc/html/chapters/toolchain/man/retro-embedimage.html b/doc/html/chapters/toolchain/man/retro-embedimage.html new file mode 100644 index 0000000..db0abd0 --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro-embedimage.html @@ -0,0 +1,68 @@ + + + +. + + +

RETRO-EMBEDIMAGE(1) General Commands Manual RETRO-EMBEDIMAGE(1) +

+RETRO-EMBEDIMAGE + retro-embedimage - a modern, pragmatic forth development system +

+SYNOPSIS + retro-embedimage [filename] +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro-embedimage loads the specified image (or `ngaImage` from the + current directory if none is specified). It converts this into C code + that can be compiled for inclusion in a RETRO executable. It will write + the output to stdout. +

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.4 February 2019 OpenBSD 6.4 +

+ diff --git a/doc/html/chapters/toolchain/man/retro-extend.html b/doc/html/chapters/toolchain/man/retro-extend.html new file mode 100644 index 0000000..f797eb6 --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro-extend.html @@ -0,0 +1,75 @@ + + + +. + + +

RETRO-EXTEND(1) General Commands Manual RETRO-EXTEND(1) +

+RETRO-EXTEND + retro-extend - a modern, pragmatic forth development system +

+SYNOPSIS + retro-extend image filename [filenames] +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro-extend is a tool to load additional code into an image file. It + takes the name of an image file and one or more source files to load into + the image. After completion the image file will be updated with the + changes. +

+

+CAVEATS + retro-extend only emulates the minimal console output device. If the + source files require additional I/O to be present, the extend process + will likely fail to work correctly. +

+

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.4 January 2021 OpenBSD 6.4 +

+ diff --git a/doc/html/chapters/toolchain/man/retro-locate.html b/doc/html/chapters/toolchain/man/retro-locate.html new file mode 100644 index 0000000..77b2a49 --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro-locate.html @@ -0,0 +1,66 @@ + + + +. + + +

RETRO-LOCATE(1) General Commands Manual RETRO-LOCATE(1) +

+RETRO-LOCATE + retro-locate - a modern, pragmatic forth development system +

+SYNOPSIS + retro-locate wordname +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro-locate searches the tags file generated by retro-tags for the + desired word name. Any matches are displayed, along with the line number. +

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.6 January 2020 OpenBSD 6.6 +

+ diff --git a/doc/html/chapters/toolchain/man/retro-muri.html b/doc/html/chapters/toolchain/man/retro-muri.html new file mode 100644 index 0000000..f858b3a --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro-muri.html @@ -0,0 +1,70 @@ + + + +. + + +

RETRO-MURI(1) General Commands Manual RETRO-MURI(1) +

+RETRO-MURI + retro-muri - a modern, pragmatic forth development system +

+SYNOPSIS + retro-muri filename +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro-muri is an assembler for Nga, the virtual machine at the heart of + Retro. It is used to build the image file containing the actual Retro + language. +

+ This will extract the code blocks in the specified file and generate an + image file named `ngaImage`. +

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.4 February 2019 OpenBSD 6.4 +

+ diff --git a/doc/html/chapters/toolchain/man/retro-tags.html b/doc/html/chapters/toolchain/man/retro-tags.html new file mode 100644 index 0000000..b0fe6b2 --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro-tags.html @@ -0,0 +1,66 @@ + + + +. + + +

RETRO-TAGS(1) General Commands Manual RETRO-TAGS(1) +

+RETRO-TAGS + retro-tags - a modern, pragmatic forth development system +

+SYNOPSIS + retro-tags +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro-tags is a tool for extracting code from fenced blocks in literate + sources and generating a tags file compatible with ctags. +

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.4 August 2019 OpenBSD 6.4 +

+ diff --git a/doc/html/chapters/toolchain/man/retro.html b/doc/html/chapters/toolchain/man/retro.html new file mode 100644 index 0000000..ed78dfc --- /dev/null +++ b/doc/html/chapters/toolchain/man/retro.html @@ -0,0 +1,91 @@ + + + +. + + +

RETRO(1) General Commands Manual RETRO(1) +

+RETRO + retro - a modern, pragmatic forth development system +

+SYNOPSIS + retro [-h] [-i] [-t] [-f filename] [-u filename] [-r filename] + [filename script-args] +

+DESCRIPTION + RETRO is a modern, pragmatic Forth drawing influences from many sources. + It's clean, elegant, tiny, and easy to grasp and adapt to various uses. +

+ retro is the main interface for interacting with Retro. It provides both + an interactive and a scripting  model. +

+OPTIONS + -h       Display a help screen. +

+ -i       Start Retro in interactive mode. +

+ -s       Start Retro in interactive mode and supress the startup message. +

+ -t       Run any test blocks in the loaded files. +

+ -f filename + Run any code blocks in the specified file. +

+ -u filename + Load and use the specified image file rather than the integral + one. +

+ -r filename + Load and run the code in the specified image file rather than + the integral one. +

+ filename script-args + Run code blocks in a single file. Pass script-args to the code + being run. +

+AUTHORS + Charles Childers <crc@forthworks.com> +

+OpenBSD 6.4 September 2019 OpenBSD 6.4 +

+ diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000..c199fd9 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1 @@ + Retro Forth: Manual

Retro Forth

• Introduction
• Obtaining RETRO
• Building on Unix
• Building on Windows
• Building Alternative Implementations
• Advanced and Custom Builds
• Starting RETRO
• Basic User Interactions
• Literate Source With Unu
• Markdown
• A Quick Tutorial
• Syntax
• Toolchain: Additional Tools
• Toolchain: retro-compiler
• Manpage: retro(1)
• Manpage: retro-describe(1)
• Manpage: retro-document(1)
• Manpage: retro-embedimage(1)
• Manpage: retro-extend(1)
• Manpage: retro-locate(1)
• Manpage: retro-muri(1)
• Manpage: retro-tags(1)
• Naming Conventions
• The Return Stack
• Stack Diagrams
• Arrays
• Assembly
• Buffer
• Characters
• Defining Words
• The Dictionary
• Floating Point
• Working With Files
• Loops
• Numbers
• Pointers
• Quotes
• Sockets
• Scripting
• Strings
• Using Combinators
• Word Classes
• Checking the Version
• Errors
• Lexical Scope
• The Stacks
• The Nga Virtual Machine
• Interface Layers
• I/O
• Image
• Historical Papers
• Metacompiling
• Self-Hosting
• Prefixes
• Kernel Words
• Ngaro to Nga
• RETRO11 Retrospective
• Security
• Underscores in Names
• Code It Yourself Manifesto
• Deprecation Policy
• Copyrights
\ No newline at end of file diff --git a/tools/generate-html-docs.retro b/tools/generate-html-docs.retro new file mode 100755 index 0000000..0ca31c6 --- /dev/null +++ b/tools/generate-html-docs.retro @@ -0,0 +1,81 @@ +#!/usr/bin/env retro + +This tool is intended to be used to create an HTML version of the +standard documentation. + +Our structure will look like: + + Book Root Directory + |-- index.html + |-- chapters/... + +Begin by defining some helper functions for writing to a +file. + +~~~ +'tools/book-chapters.retro include + +'FID var +:file:s:put [ @FID file:write ] s:for-each ; +:file:nl ASCII:CR @FID file:write ; +:unix:mkdir 'mkdir_-p_%s s:format unix:system ; +~~~ + +Create the directories needed. + +~~~ +'Create_directories s:put nl +{ 'chapters + 'chapters/building + 'chapters/general + 'chapters/internals + 'chapters/tech-notes + 'chapters/techniques + 'chapters/toolchain + 'chapters/toolchain/info + 'chapters/toolchain/man + 'html +} [ dup tab s:put nl unix:mkdir ] a:for-each +~~~ + +# Create the Index file + +~~~ +'Generate_`index.html` s:put nl +'html/index.html file:open-for-writing !FID + +{ ' + ' + '____ + '____Retro_Forth:_Manual + ' + ' + '

Retro_Forth

+} [ file:s:put file:nl ] a:for-each + +:a:unpack [ ] a:for-each ; + +TOC [ a:unpack '____•_%s
s:format file:s:put file:nl ] a:for-each + +{ ' + ' +} [ file:s:put file:nl ] a:for-each + +@FID file:close +~~~ + +# Generate the Chapters + +~~~ +'Convert_chapters_to_XHTML s:put nl +'retro_tools/epub/chapters-to-xhtml.retro unix:system +~~~ + +# Relocate Files + +~~~ +'Relocate_files s:put nl +'rm_-rf_doc/html unix:system +'mv_chapters_html unix:system +'mv_html_doc unix:system +~~~