crc/retroforth
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

shorter lines in docs

Browse source 
FossilOrigin-Name: a3102b7f4f5bd64f79d0ead274320061feb044e888718ffe45464a52ee4cf612
This commit is contained in:
crc 2017-10-22 18:39:45 +00:00
parent 4044f88cfa
commit 01c40d9d3d
7 changed files with 91 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
doc/Architecture.md
View file

@ -2,14 +2,27 @@
RETRO has a multilayer design.
At the heart of the system is a virtual machine called Nga. This emulates a 32-bit stack processor with a MISC based instruction set.
At the heart of the system is a virtual machine called Nga. This emulates
a 32-bit stack processor with a MISC based instruction set.
The core RETRO language is stored as a memory image for Nga. The *image file* contains this and is loaded on startup. It holds all of the compiled words and data and interacts with Nga.
The core RETRO language is stored as a memory image for Nga. The *image
file* contains this and is loaded on startup. It holds all of the compiled
words and data and interacts with Nga.
The third layer is the user interface. RETRO doesn't specify any required I/O other than a console log capable of receiving a single character at a time. Each host system can implement this and any additional desired I/O by extending Nga.
The third layer is the user interface. RETRO doesn't specify any required
I/O other than a console log capable of receiving a single character at a
time. Each host system can implement this and any additional desired I/O
by extending Nga.
# Specifics
On iOS the user interface is setup around an editor and an output area. The editor extracts code from fenced regions, splits it into tokens (elements separated by whitespace) and passes each of these into RETRO for processing. After the tokens are processed, the console is updated.
On iOS the user interface is setup around an editor and an output area.
The editor extracts code from fenced regions, splits it into tokens
(elements separated by whitespace) and passes each of these into RETRO
for processing. After the tokens are processed, the console is updated.
The iOS code provides additional I/O functionality. In the `file:` namespace there are words for creating and using files. There's a `pb:` vocabulary for interacting with the clipboard. And a `clock:` namespace which provides access to the system time and date. These are mapped to higher opcodes outside of the core set used by Nga.
The iOS code provides additional I/O functionality. In the `file:`
namespace there are words for creating and using files. There's a
`pb:` vocabulary for interacting with the clipboard. And a `clock:`
namespace which provides access to the system time and date. These
are mapped to higher opcodes outside of the core set used by Nga.

54
doc/Examples.md
View file

@ -1,27 +1,31 @@
# Examples
| Filename | Description |
| -------------------------- | --------------------------------------- |
| 99Bottles.forth | Display "99 bottles of beer" song |
| AddingVectors.forth | Adding values in two arrays |
| Atua-WWW.forth | Atua HTTP server |
| Atua.forth | Atua Gopher server |
| Autopsy.forth | Debugging aids |
| Cat.forth | Display a file to the output |
| Chess.forth | Simple ASCII-based chess game |
| Echo.forth | Echo command line arguments |
| GCD.forth | Greatest common denominator |
| IterativeFibonacci.forth | Fibonacci sequence, iterative |
| LeastCommonMultiple.forth | Find least common multiple |
| Primes.forth | Prime sieve |
| RecursiveFactorial.forth | Factorial of a number, recursive |
| RecursiveFibonacci.forth | Fibonacci sequence, recursive |
| Roo.forth | Block editor using Tuporo backend |
| 1D-Cellular-Automota.forth | 1D Cellular Automota (Rosetta Code) |
| is-palindrome.forth | Is string a palindrome? |
| Tuporo.forth | Block storage via Gopher protocol |
| VT100.forth | Example VT100 namespace |
| sort-on-stack.forth | Sort numbers on the stack |
| accumulator.forth | Sample use of `does` |
| Parse-UPS.forth | Break a UPS Tracking # apart |
| rot13.forth | ROT13 "encryption" |
| Filename | Description |
| ---------------------------- | --------------------------------------- |
| 99Bottles.forth | Display "99 bottles of beer" song |
| AddingVectors.forth | Adding values in two arrays |
| Atua-WWW.forth | Atua HTTP server |
| Atua.forth | Atua Gopher server |
| Autopsy.forth | Debugging aids |
| Cat.forth | Display a file to the output |
| Chess.forth | Simple ASCII-based chess game |
| Echo.forth | Echo command line arguments |
| GCD.forth | Greatest common denominator |
| IterativeFibonacci.forth | Fibonacci sequence, iterative |
| LeastCommonMultiple.forth | Find least common multiple |
| Primes.forth | Prime sieve |
| RecursiveFactorial.forth | Factorial of a number, recursive |
| RecursiveFibonacci.forth | Fibonacci sequence, recursive |
| Roo.forth | Block editor using Tuporo backend |
| 1D-Cellular-Automota.forth | 1D Cellular Automota (Rosetta Code) |
| is-palindrome.forth | Is string a palindrome? |
| Tuporo.forth | Block storage via Gopher protocol |
| VT100.forth | Example VT100 namespace |
| sort-on-stack.forth | Sort numbers on the stack |
| accumulator.forth | Sample use of `does` |
| Parse-UPS.forth | Break a UPS Tracking # apart |
| rot13.forth | ROT13 "encryption" |
| hanoi.forth | Towers of Hanoi solver |
| StringToNumberWithBase.forth | Numbers in misc. bases |
| DictionaryStats.forth | Use of `d:for-each` to find info about |
| | word names |

16
doc/Hyperstatic.md
View file

@ -1,7 +1,8 @@
# Hyperstatic Global Environment
This now brings up an interesting subpoint. Retro provides a *hyper-static global environment.* This can be difficult to explain, so
let's take a quick look at how it works:
This now brings up an interesting subpoint. Retro provides a *hyper-
static global environment.* This can be difficult to explain, so let's
take a quick look at how it works:
````
#1000 'a var<n>
@ -20,8 +21,11 @@ let's take a quick look at how it works:
Output is marked with **\>\>\>**.
Note that we create two variables with the same name (*a*). The definition for `scale` still refers to the old variable, even though we
can no longer directly manipulate it.
Note that we create two variables with the same name (*a*). The definition
for `scale` still refers to the old variable, even though we can no longer
directly manipulate it.
In a hyper-static global environment, functions continue to refer to the variables and earlier functions that existed when they were defined. If
you create a new variable or function with the same name as an existing one, it only affects future code.
In a hyper-static global environment, functions continue to refer to the
variables and earlier functions that existed when they were defined. If
you create a new variable or function with the same name as an existing
one, it only affects future code.

3
doc/Namespaces.md
View file

@ -1,6 +1,7 @@
# Namespaces
Retro organizes words into *namespaces*. These are short prefix strings at the start of a word name.
Retro organizes words into *namespaces*. These are short prefix
strings at the start of a word name.
The primary namespaces are:

7
doc/NamingConventions.md
View file

@ -25,14 +25,17 @@ These are UPPERCASE, with a dash separating compound names.
# Words
Most named items are words. As such, most of the conventions are under this category.
Most named items are words. As such, most of the conventions are under
this category.
Word names are lowercase, with a dash between compound names.
drop
drop-pair
Use a namespace prefix to group related words. This is a short string, separated from the rest of the name by a colon. See doc|Namespaces.md for a list of the major namespaces in RETRO.
Use a namespace prefix to group related words. This is a short string,
separated from the rest of the name by a colon. See Namespaces.md for a
list of the major namespaces in RETRO.
d:for-each
s:to-upper

32
doc/QuotesAndCombinators.md
View file

@ -1,8 +1,10 @@
# Quotes and Combinators
RETRO makes extensive use of two elements that need some explanation. These are called quotes and combinators.
RETRO makes extensive use of two elements that need some explanation. These
are called quotes and combinators.
A *quote* is an anonymous function. They are nestable and can be created at any time.
A *quote* is an anonymous function. They are nestable and can be created at
any time.
Example:
@ -10,13 +12,16 @@ Example:
#12 [ dup * ] call
````
In this, the code stating with `[` and ending with `]` is the quote. Here it's just `call`ed immediately, but you can also pass it to other words.
In this, the code stating with `[` and ending with `]` is the quote. Here
it's just `call`ed immediately, but you can also pass it to other words.
We use the word *combinator* to refer to words that operate on quotes.
You'll use quotes and combinators extensively for controlling the flow of execution. This begins with conditionals.
You'll use quotes and combinators extensively for controlling the flow of
execution. This begins with conditionals.
Assuming that we have a flag on the stack, you can run a quote if the flag is `TRUE`:
Assuming that we have a flag on the stack, you can run a quote if the
flag is `TRUE`:
````
#1 #2 eq?
@ -58,19 +63,24 @@ Or while it returns `FALSE`:
#100 [ n:dec dup n:zero? ] until
````
In RETRO you can also use combinators to iterate over data structures. For instance, many structures provide a `for-each` combinator which can be run once for each item in the structure. E.g., with a string:
In RETRO you can also use combinators to iterate over data structures. For
instance, many structures provide a `for-each` combinator which can be run
once for each item in the structure. E.g., with a string:
````
'Hello [ putc ] s:for-each
````
Moving further, combinators are also used for filters and operations on data. Again with strings:
Moving further, combinators are also used for filters and operations on
data. Again with strings:
````
'Hello_World! [ c:-vowel? ] s:filter
````
This runs `s:filter` which takes a quote returning a flag. For each `TRUE` it appends the character into a new string, while `FALSE` results are discarded.
This runs `s:filter` which takes a quote returning a flag. For each `TRUE`
it appends the character into a new string, while `FALSE` results are
discarded.
You might also use a `map`ping combinator to update a data set:
@ -78,9 +88,11 @@ You might also use a `map`ping combinator to update a data set:
'Hello_World [ c:to-upper ] s:map
````
This takes a quote that modifies a value which is then used to build a new string.
This takes a quote that modifies a value which is then used to build a
new string.
There are many more combinators. Look in the Glossary to find them. Some notable ones include:
There are many more combinators. Look in the Glossary to find them. Some
notable ones include:
bi
bi*

7
doc/Syntax.md
View file

@ -1,12 +1,15 @@
# Syntax
RETRO code consists of a series of whitespace delimited tokens. Each of these can have an optional prefix telling RETRO how to treat the token. If the token lacks a valid prefix, it will be treated as a word name.
RETRO code consists of a series of whitespace delimited tokens. Each of
these can have an optional prefix telling RETRO how to treat the token.
If the token lacks a valid prefix, it will be treated as a word name.
So:
[prefix][token]
Prefixes are single character modifiers. They are similar to colors in ColorForth, but are handled via words in the `prefix:` namespace.
Prefixes are single character modifiers. They are similar to colors in
ColorForth, but are handled via words in the `prefix:` namespace.
The major prefixes are: