diff options
Diffstat (limited to 'doc/locals.html')
| -rw-r--r-- | doc/locals.html | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/doc/locals.html b/doc/locals.html new file mode 100644 index 000000000000..c6c78d0206c6 --- /dev/null +++ b/doc/locals.html @@ -0,0 +1,253 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> +<META name='Description' content='Ficl - embedded scripting with object oriented programming'> +<META name='Keywords' content='scripting prototyping tcl OOP Forth interpreter C'> +<LINK rel='SHORTCUT ICON' href='ficl.ico'> +<TITLE>local variables in Ficl</TITLE> +<style> + +blockquote { margin-left: 1em } + +</style> + +</HEAD> +<BODY> + +<table border=0 cellspacing=0 width=100%%><tr> + + +<td width=112 bgcolor=#004968 colspan=3> +<img src=graphics/ficl.4.96.jpg height=96 width=96> +</td> + +<td bgcolor=#004968> +<font face=arial,helvetica color=white size=7><b><i> +local variables in Ficl +</i></b></font> +</td></tr> + + +<tr> +<td bgcolor=#004968 width=10></td> +<td bgcolor=#004968 valign=top> +<br><p> +<a href=index.html><font face=arial,helvetica color=white><b>Index</b></font></a><p> +<p><br> +<a href=dpans.html><font face=arial,helvetica color=white><b>ANS</b></font></a><br> +<a href=api.html><font face=arial,helvetica color=white><b>API</b></font></a><br> +<a href=debugger.html><font face=arial,helvetica color=white><b>Debugger</b></font></a><br> +<a href=http://sourceforge.net/project/showfiles.php?group_id=24441><font face=arial,helvetica color=white><b>Download</b></font></a><br> +<a href=license.html><font face=arial,helvetica color=white><b>Licensing</b></font></a><br> +<a href=links.html><font face=arial,helvetica color=white><b>Links</b></font></a><br> +<a href=locals.html><font face=arial,helvetica color=white><b>Locals</b></font></a><br> +<a href=oop.html><font face=arial,helvetica color=white><b>OOP In Ficl</b></font></a><br> +<a href=parsesteps.html><font face=arial,helvetica color=white><b>Parse Steps</b></font></a><br> +<a href=releases.html><font face=arial,helvetica color=white><b>Release History</b></font></a><br> +<a href=upgrading.html><font face=arial,helvetica color=white><b>Upgrading To 4.0</b></font></a><br> +</td><td bgcolor=#004968 width=5></td><td valign=top><blockquote><p> + + + + + +<p> +</blockquote><table border=0 bgcolor=#a0a0a0 width=100%><tr> + +<td width=1em></td> +<td> +<font face=arial,helvetica color=#004968 size=5><b><i> +<a name='AnOverviewAndAHistory'> +An Overview And A History +</a></i></b></font></td></tr></table><p><blockquote> + + + + + +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, and they complain that novices use +global variables too frequently. But 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). +<p> + +Ficl provides excellent support +for local variables, and the purists be damned—we use 'em all the time. +<p> + +Local variables can only be declared inside a definition, +and are only visible in that definition. Please refer to +<a href="http://ficl.sourceforge.net/dpans/dpans13.htm"> +the ANS standard for FORTH +</a> for more general information on local variables. + + + +<p> +</blockquote><table border=0 bgcolor=#a0a0a0 width=100%><tr> + +<td width=1em></td> +<td> +<font face=arial,helvetica color=#004968 size=5><b><i> +<a name='John-HopkinsForthArgumentSyntax'> +John-Hopkins Forth Argument Syntax +</a></i></b></font></td></tr></table><p><blockquote> + + + +ANS Forth does not specify a complete 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, as developed by John +Hayes et al. However, Ficl extends this syntax with support for double-cell and +floating-point numbers. + +<p> + +Here's the basic syntax of a JH-local variable declaration: +<blockquote><code> +<b>{</b> <i>arguments</i> +<b>|</b> <i>locals</i> +<b>--</b> <i>ignored</i> +<b>}</b> +</code></blockquote> +(For experienced FORTH programmers: the declaration is designed to look like a stack comment, +but it uses curly braces instead of parentheses.) Each section must list zero or more +legal Ficl word names; comments and preprocessing are not allowed here. +Here's what each section denotes: + +<ul> + +<li> +The <i>arguments</i> section lists local variables which are initialized from the stack when the word executes. +Each argument is set to the top value of the stack, starting at the rightmost argument name and moving left. +You can have zero or more arguments. +<p> + +<li> +The <i>locals</i> section lists local variables which are set to zero when the word executes. +You can have zero or more locals. +<p> + +<li> +Any characters between <code>--</code> and <code>}</code> are treated as a comment, and ignored. + +</ul> + +(The <code>|</code> and <code>--</code> sections are optional, +but they must appear in the order shown if they appear at all.) +<p> + + + +<p> +</blockquote><table border=0 bgcolor=#b8b8b8 width=100%><tr> + +<td width=1em></td> +<td> +<font face=arial,helvetica color=#004968 size=4><b><i> +<a name='ArgumentTypes'> +Argument Types +</a></i></b></font></td></tr></table><p><blockquote> + + + +Every time you specify a local variable (in either the <i>arguments</i> or the <i>locals</i> section), +you can also specify the <i>type</i> of the local variable. By default, a local variable +is a single-cell integer; you can specify that the local be a double-cell integer, and/or a +floating-point number. +<p> + +To specify the type of a local, specify one or more of the following single-character specifiers, +followed by a colon (<code>:</code>). + +<table> + +<tr><td bgcolor=#e0e0e0> +<b>1</b> +</td><td bgcolor=#f0f0f0> +single-cell +</td></tr> + + + +<tr><td bgcolor=#e0e0e0> +<b>2</b> +</td><td bgcolor=#f0f0f0> +double-cell +</td></tr> + + + +<tr><td bgcolor=#e0e0e0> +<b>d</b> +</td><td bgcolor=#f0f0f0> +double-cell +</td></tr> + + + +<tr><td bgcolor=#e0e0e0> +<b>f</b> +</td><td bgcolor=#f0f0f0> +floating-point (use floating stack) +</td></tr> + + + +<tr><td bgcolor=#e0e0e0> +<b>i</b> +</td><td bgcolor=#f0f0f0> +integer (use data stack) +</td></tr> + + + +<tr><td bgcolor=#e0e0e0> +<b>s</b> +</td><td bgcolor=#f0f0f0> +single-cell +</td></tr> + + + +</table> + +For instance, the argument <code>f2:foo</code> would specify a double-width floating-point +number. +<p> + +The type specifiers are read right-to left, and when two specifiers conflict, the rightmost +one takes priority. So <code>2is1f2:foo</code> would still specifiy a double-width floating-point +number. +<p> + +Note that this syntax <i>only works</i> for Ficl's JH-locals. Locals +defined in some other way (say, with the FORTH standard word <code>LOCALS|</code>) +will ignore this syntax, and the entire string will be used as the name of +the local (type and all). + + +<p> +</blockquote><table border=0 bgcolor=#b8b8b8 width=100%><tr> + +<td width=1em></td> +<td> +<font face=arial,helvetica color=#004968 size=4><b><i> +<a name='ASimpleExample'> +A Simple Example +</a></i></b></font></td></tr></table><p><blockquote> + + + +<pre> +: DEMONSTRATE-JH-LOCALS { c b a f:float -- a+b f:float*2 } + a b + + 2.0e float f* + ; +</pre> + + +</blockquote><p></td></tr></table></body></html> + |