diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 70 |
1 files changed, 62 insertions, 8 deletions
diff --git a/README.txt b/README.txt index c03533c..71ff62c 100644 --- a/README.txt +++ b/README.txt @@ -1,8 +1,13 @@ -~~~~~~~~~~~~~~ -~~ Welcome! ~~~~~~ -~~~~~~~~~~~~~~~~~ -~~~~~~~~~~~~~ -~~~~~~~~~~~~~~~ + . ~ . + ~ ~~ . + ~~ ~~~ + ~ ~~~ ~~~~ ~ + ~~~~~~~ ~~~~~ + ~~~~~~~~~~~~~~ . + ~~ Evocation! ~~ + ~~~~~~~~~~~~~~~ or, how to call the blue-green flame + ~~~~~~~~~~~~~~ + ~~~~~~~~~~~~~~~ The documentation is a work in progress. It doesn't say most of the things it needs to, yet. @@ -34,6 +39,8 @@ are ready, we have maintained compatibility with the original version of Evocation which was written in a program called flatassembler, which you will have to acquire. +TODO mention the terminal + To get started, first build the flatassembler version: $ fasmg quine.asm quine @@ -68,7 +75,10 @@ versions as you modify Evocation. See what it prints! +TODO give examples of RPN for arithmetic + Some helpful words to try to get started are list-dictionary and describe. +TODO show how to use them The syntax for a string literal is s" ...". There's something very subtle happening: it's the lowercase letter "s", a double quote, and a space. Then @@ -97,6 +107,31 @@ really is that short and simple. Part of why it's able to be that easy is that words such as s" that introduce special syntaxes do their own lexing for whatever comes after them. +TODO show how to define words + + Evocation has high-level flow-control words: if, unless, if-else, forever, +and while. High-level flow control is a common thing for modern Forth dialects +to add, but every dialect does it a bit differently. Evocation's flow-control +words are postfix operations and work with curly braces, like this: + + $ ./evoke + : count 10 0 { 2dup < } { space dup . 1+ } while 2drop newline ; + count + + What will it print? :) + + Evocation's high-level flow control works only in compiled code; this +example defines and compiles a new word called "count", in order to show it +off. If you try to use the "{ ... } { ... } while" syntax outside of a word +definition, it won't do what you expect. + + This is because, unlike some modern Forths, Evocation doesn't have a +general-purpose memory management facility; it uses something called the log, +which makes it easy to allocate things but hard to deallocate them. In order +to loop through a code block, it has to be allocated somewhere. So, the design +takes care not to encourage programming habits that would burn through memory +space. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~ Reading Evocation's source code ~~ @@ -134,9 +169,28 @@ input, and there's elf.e which contains words for outputting the special file headers that let the operating system understand that a file is an executable program. - TODO output.e interpret.e dynamic.e flow-control.e execution-support.e - - TODO talk about transformations + In terms of the Forth-y bits, input.e and output.e are concerned with +getting text into and out of the language. The infrastructure to define words +is in dynamic.e, and the syntax for it is in interpret.e. The high-level flow +control words are in flow-control.e. Some of the features of execution.e had +to be separated out into their own file, because of details about how the +compiler works; that stuff is in execution-suport.e. + + So, there's all those relatively normal compiler internals in those various +files, which are all fairly self-contained... and then there's the +transformation facility. This is Evocation's most unique archictural decision, +and it's in transform.e. It's well documented, but it's also extremely +conceptually dense. Feel free to give it a skim, that's the only way to build +familiarity with these things, but you should probably have a solid +understanding of the rest of the internals before you place any high +expectations on yourself around understanding the transformation facility. + + It's okay, you can benefit from it before you understand it: Transformation +provides the core tricks that make it possible to compile Forth code into +standalone executables. The call to label-transform in evoke.e, and the call +to log-load-transform in execution.e, are the two spots where compilation is +handed off to the transformation facility, and you can pretty much just take +it for granted that it works, until you feel ready. If you want examples of programs that are smaller than Evocation itself, quine.e is a tiny program written in proper Evocation that outputs its own |