From 01c40d9d3d6c86cf9564246c14b697bd18490bab Mon Sep 17 00:00:00 2001 From: crc Date: Sun, 22 Oct 2017 18:39:45 +0000 Subject: [PATCH] shorter lines in docs FossilOrigin-Name: a3102b7f4f5bd64f79d0ead274320061feb044e888718ffe45464a52ee4cf612 --- doc/Architecture.md | 23 ++++++++++++---- doc/Examples.md | 54 ++++++++++++++++++++----------------- doc/Hyperstatic.md | 16 ++++++----- doc/Namespaces.md | 3 ++- doc/NamingConventions.md | 7 +++-- doc/QuotesAndCombinators.md | 32 +++++++++++++++------- doc/Syntax.md | 7 +++-- 7 files changed, 91 insertions(+), 51 deletions(-) diff --git a/doc/Architecture.md b/doc/Architecture.md index c475379..28b225b 100644 --- a/doc/Architecture.md +++ b/doc/Architecture.md @@ -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. diff --git a/doc/Examples.md b/doc/Examples.md index 26976bb..7099a8a 100644 --- a/doc/Examples.md +++ b/doc/Examples.md @@ -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 | diff --git a/doc/Hyperstatic.md b/doc/Hyperstatic.md index 92cec7b..2ba96d3 100644 --- a/doc/Hyperstatic.md +++ b/doc/Hyperstatic.md @@ -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 @@ -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. diff --git a/doc/Namespaces.md b/doc/Namespaces.md index 84d7477..e7fd7fa 100644 --- a/doc/Namespaces.md +++ b/doc/Namespaces.md @@ -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: diff --git a/doc/NamingConventions.md b/doc/NamingConventions.md index 0253c8f..182d2e2 100644 --- a/doc/NamingConventions.md +++ b/doc/NamingConventions.md @@ -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 diff --git a/doc/QuotesAndCombinators.md b/doc/QuotesAndCombinators.md index 83a5f29..d7becf2 100644 --- a/doc/QuotesAndCombinators.md +++ b/doc/QuotesAndCombinators.md @@ -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* diff --git a/doc/Syntax.md b/doc/Syntax.md index bf7bbe6..89437d6 100644 --- a/doc/Syntax.md +++ b/doc/Syntax.md @@ -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: