diff options
Diffstat (limited to 'doc/ficl_loc.html')
| -rw-r--r-- | doc/ficl_loc.html | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/doc/ficl_loc.html b/doc/ficl_loc.html new file mode 100644 index 0000000000000..6e00e74b9ee30 --- /dev/null +++ b/doc/ficl_loc.html @@ -0,0 +1,161 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="Author" content="john sadler"> + <meta name="Description" content="the coolest embedded scripting language ever"> + <meta name="GENERATOR" content="Mozilla/4.73 [en] (Win98; U) [Netscape]"> + <title>ficl Local Variables</title> +</head> +<body> + +<h1> +<b>Local Variables in Ficl</b></h1> + + +<script language="javascript" src="ficlheader.js"></script> + + +<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="675" > +<tr> +<td> +<h2> +<a NAME="locals"></a>Local Variables</h2> +Named locally scoped variables came late to Forth. Purists feel that experienced +Forth programmers can (and should) write supportable code using only anonymous +stack variables and good factoring, but they complain that novices use +global variables too much. Local variables cost little in terms of code +size and execution speed, and are very convenient for OO programming, where +stack effects are more complex. I use them a lot (maybe I'm a weenie). +<br><a href="http://www.taygeta.com/forth/dpans13.htm">Please refer to +the Standard</a> for more information on local variables. +<h2> +<a NAME="jhlocal"></a>Johns-Hopkins local variables</h2> +ANS Forth does not specify a complete and satisfying local variable facility. +Instead it defines a foundation upon which to build one. Ficl comes with +an adaptation of the Johns-Hopkins local variable syntax developed by John +Hayes et al. This is my preferred form, and I've extended it to make <a href="ficl_oop.html">OOP</a> +a bit simpler. Local variables can only be declared inside a definition, +and are only visible in that definition. Here's the syntax of a JH local +variable declaration: +<blockquote><tt><b>{ </b><initialized-locals><b> | </b><cleared-locals><b> +-- </b><ignored><b> }</b></tt></blockquote> +The declaration is designed to look like a stack comment, but it uses curly +braces instead of parens. The <initialized-locals> names get their initial +values from the stack when the word executes. The <cleared-locals> names +are (you guessed it) set to zero when the word executes, and any characters +between -- and } are treated as a comment. The | and -- sections are optional, +but they must appear in the order shown if they appear at all. +<br><b>Double cell locals </b>(AKA 2locals): ordinarily, each local represents +one cell. Local variable names prefixed with the characters "2:" in the declaration +are double-cell locals. The prefix is not part of the local variable's name, only +part of the declaration. +They behave the same as single cell locals in all +other respects. I use 2locals quite a bit in Ficl's OO classes, because +objects in Ficl require two cells on the stack. You can modify the +value of a double cell local with <tt><a href="http://www.taygeta.com/forth/dpans13.htm#13.6.1.2295">TO</a></tt> +the same as you would a single cell local. +<br>Following are some examples to illustrate usage (they are not intended +to be good code otherwise). Try these out in FiclWin to get a feeling for +how they work. Also see <code>softwords/string.fr</code> for an example of use of locals +in OO code. +<blockquote><b><tt>: local-demo { a b | c -- }</tt></b> +<br><b><tt> ." a = " a . cr</tt></b> +<br><b><tt> ." b = " b . cr</tt></b> +<br><b><tt> ." c = " c . cr ;</tt></b> +<br><b><tt>1 2 local-demo ( you should see 1 2 0 )</tt></b> +<p><b><tt>: my2dup { 2:x } x x ; ( uses a 2local +)</tt></b> +<br><b><tt>1 2 my2dup .s </tt></b> +<br><b><tt>.( you should see 1 2 1 2 on the stack ) cr empty</tt></b> +<p><b><tt>: my2swap { 2:x 2:y -- y x } y x ; +( note use of 2locals )</tt></b> +<br><b><tt>1 2 3 4 my2swap .s</tt></b> +<br><b><tt>.( you should see 3 4 1 2 on the stack ) cr empty</tt></b> +<p><b><tt>: totally-lame-swap { x y | temp -- y x }</tt></b> +<br><b><tt> y to temp</tt></b> +<br><b><tt> x to y</tt></b> +<br><b><tt> temp to x</tt></b> +<br><b><tt> x y ;</tt></b></blockquote> +The last definition introduces the use of <tt>TO</tt> applied to local +variables. <tt>TO</tt> knows whether it's operating on a <tt>LOCAL</tt>, +a <tt>2LOCAL</tt>, or a <tt>VALUE</tt>, and does the right thing accordingly. +<br> +<h2>Other local variable syntaxes (deprecated)</h2> +There are other syntaxes in use for local variables. You get the same compiled +code regardless of which style of local declaration you choose, but the +Johns-Hopkins syntax is more readable, more flexible, and supports <tt>2LOCAL</tt>s +- if you agree, then skip this section. +<p>Ficl includes support for <tt>LOCALS</tt> and <tt>LOCALS EXT</tt> words +(all three of them!). I've implemented both of the local variable syntaxes +suggested in DPANS Appendix A.13. Examples: (By the way, Ficl implements +<tt>-ROT</tt> +as <tt>: -rot 2 -roll ;</tt> ) +<blockquote><b><tt>\ Using LOCALS| from LOCALS EXT</tt></b> +<br><b><tt>: -rot ( a b c -- c a b )</tt></b> +<br><b><tt> locals| c b a |</tt></b> +<br><b><tt> c a b </tt></b> +<br><b><tt>;</tt></b></blockquote> + +<ul><b><tt>\ Using LOCAL END-LOCAL</tt></b> +<br><b><tt>: -rot ( a b c -- c a b )</tt></b> +<br><b><tt> local c</tt></b> +<br><b><tt> local b</tt></b> +<br><b><tt> local a</tt></b> +<br><b><tt> end-locals</tt></b> +<br><b><tt> c a b</tt></b> +<br><b><tt>;</tt></b></ul> + +<h2> +Build Controls</h2> +Local variable support is optional because it adds a small amount of overhead +to the outer interpreter. You can disable it by setting FICL_WANT_LOCALS +to 0 in sysdep.h. Beware: <a href="ficl_oop.html">Ficl's OOP</a> code makes +heavy use of local variables, so if you disable locals, you're going to +lose other capabilities too. Local variables can make Forth code quite +a bit easier to read, so I'd encourage you to experiment with them. +<p>The default maximum number of local variables is 16. It's controlled +by FICL_MAX_LOCALS in sysdep.h. +<h2> +Release notes for local variables</h2> +<p>Ficl 2.05 adds 2LOCALS using the "2:" prefix</p> +<p>Ficl 2.02 includes by default an implementation of the Johns Hopkins local +syntax (as best I can determine it from examples on the web). This syntax +lets you declare local variables that look very much like a stack comment. +Variables in the declaration appear in the "correct" order for a stack +comment. Everything after the -- is treated as a comment. In addition, +you can insert a | before the -- to declare one or more zero-initialized +locals. Example: </p> +<blockquote><b><tt>:tuck0 { a b c | d -- 0 a b c }</tt></b> +<br><b><tt> d a b c ;</tt></b></blockquote> +The | and -- delimiters can appear at most once, and must appear in the +order shown in the example to work correctly. The local declaration ends +at the first occurrence of }. The declaration must all be on one line as +presently implemented. +<p><b>Deprecated</b>: Ficl 2.01 added yet another local syntax that models +a stack comment. This one is not compiled in the release, but you can add +it by editing softwords/softcore.bat to include the file ficllocal.fr. +In this case, parameters are re-ordered so that the rightmost initialized +param comes from the top of the stack. The syntax is: +<blockquote><b><tt>{{ <initialized params> -- <cleared params> }}</tt></b></blockquote> +You can omit either the initialized or the cleared parameters. Parameters +after the double dash are set to zero initially. Those to the left are +initialized from the stack at execution time. Examples (lame ones, admittedly): +<br> +<blockquote> +<pre><b><tt>: -rot ( a b c -- c a b ) + {{ a b c }}</tt></b> + <b><tt>c a b </tt></b> +<b><tt>;</tt></b> + +<b><tt>: tuck0 ( a b c -- 0 a b c )</tt></b> +<b><tt> {{ a b c -- d }}</tt></b> +<b><tt> d a b c </tt></b> +<b><tt>; </tt></b></pre> +</blockquote> +</td> +</tr> +</table> + +</body> +</html> |