ref: bbe9ffba8e10e6a99ddbf37cf9ce7736ba2cb4a1
parent: 95b4ab0e4c91aace77aba972819a12c4f430e8f1
author: jsadler <jsadler@ficl.sf.net>
date: Sat Jun 17 09:44:00 CDT 2000
Intermediate release of OO stuff for dcs/freebsd
--- a/ReadMe.txt
+++ b/ReadMe.txt
@@ -1,11 +1,7 @@
Coming up:
Web server scripting extension (GoAhead port)
-"Private" flag for methods?
method: defining word for public methods
-my=>
-catch a method invocation
-2value 2variable
ficlwin Debugger pane - step, stack trace, breakpoint
Design:
@@ -17,26 +13,41 @@
Requires a debug VM that checks for breaks, step mode, etc.
How to get stack parameters to execution vm, or get input text to debug vm?
->>> rel 2.05
-Alpha patches from the freeBSD team incorporated
-Split SEARCH and SEARCH EXT words form words.c to search.c
-ABORT" now complies with the ANS (-2 THROWs)
-2LOCALS in jhlocal syntax now lose the first 2 in their names.
+rel 2.05 -- June 2000
+- *** HTML documentation extensively revised ***
+- Incorporated Alpha (64 bit) patches from the freeBSD team.
+- Split SEARCH and SEARCH EXT words from words.c to search.c
+- ABORT" now complies with the ANS (-2 THROWs)
+- 2LOCALS defined in jhlocal syntax now lose the first
+ '2' in their names. See ficl_loc.html
-ANS DOUBLE words: 2r@ 2r> 2>r
-
ficl words
+- ABORT" works correctly (oops)
+- REFILL works correctly
+- ANS CORE EXT words: 2r@ 2r> 2>r
+- ANS DOUBLE words: 2variable
+- .S now displays all stack entries on one line, like a stack comment
- wid-get-name given a wid, returns the address and count of its name. If no name, count is 0
- wid-set-name set optional wid name pointer to the \0 terminated string address specified.
+- ficl-named-wordlist creates a ficl-wordlist and names it
- last-word returns the xt of the word being defined or most recently defined.
- q@ and q! operate on quadbyte quantities for 64 bit friendliness
+
softcore.fr words
- ORDER now lists wordlists by name
- ficl-named-wordlist
- brand-wordlist
+
New OO stuff
+- Class methods ALLOT and ALLOT-ARRAY
+- METHOD define method names globally
+- my=> early bind a method call to "this" class
+- my=[ ] early bind a string of method calls to "this" class and obj members
+- c-> late bind method invocation with CATCH
- metaclass method resume-class and instance word suspend-class to create
mutually referring classes. Example in string.fr
+- early binding words are now in the instance-vars wordlist,
+ not visible unless defining a class.
rel 2.04 -- May 2000
--- a/dict.c
+++ b/dict.c
@@ -3,7 +3,7 @@
** Forth Inspired Command Language - dictionary methods
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 19 July 1997
-** $Header: /home/grobe0ba/cvs/ficl/Attic/dict.c,v 1.5 2000/06/09 19:18:19 jsadler Exp $
+** $Id: dict.c,v 1.6 2000/06/17 14:43:44 jsadler Exp $
*******************************************************************/
/*
** This file implements the dictionary -- FICL's model of
--- a/doc/ficl.html
+++ b/doc/ficl.html
@@ -5,13 +5,12 @@
<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 release notes</title>
+ <title>Ficl Documentation</title>
</head>
<body>
-
-<center>
+<link REL="SHORTCUT ICON" href="ficl.ico">
<h1>
-<b>ficl 2.04 release notes</b></h1></center>
+<b>Ficl Documentation</b></h1>
<table BORDER=0 CELLSPACING=3 WIDTH="600" >
<tr>
@@ -29,7 +28,7 @@
</tr>
<tr>
-<td><b>Revision 2.04: 20 May 2000</b></td>
+<td><b>Revision 2.05: June 2000</b></td>
</tr>
</table>
@@ -38,12 +37,25 @@
<ul>
<li>
-<a href="#whatsnew">Release notes</a></li>
+<a href="ficl_rel.html">Release notes</a></li>
<li>
<a href="#whatis">What is ficl?</a></li>
<li>
+<a href="#download"><b>Download</b> the latest version</a></li>
+
+<li>
+<a href="#links">More information on Ficl</a></li>
+
+<li>
+<font color="#000000"><a href="#includesficl">Some software that incorporates
+Ficl</a></font></li>
+
+<li>
+<a href="#lawyerbait">Disclaimer & License</a></li>
+
+<li>
<a href="#features">Ficl features</a></li>
<li>
@@ -56,7 +68,7 @@
<a href="#manifest">Distribution source files</a></li>
<li>
-<a href="#locals">Local variables</a></li>
+<a href="ficl_loc.html">Local variables</a></li>
<li>
<a href="ficl_oop.html">Object Oriented Programming in ficl</a></li>
@@ -66,472 +78,169 @@
<li>
<a href="#ansinfo">ANS required information</a></li>
-
-<li>
-<a href="#links">Forth and Ficl references, <b><font color="#000000">download</font></b></a></li>
-
-<li>
-<font color="#000000"><a href="#includesficl">Some software that includes
-ficl</a></font></li>
-
-<li>
-<a href="#lawyerbait">Disclaimer & License</a></li>
</ul>
<br>
-<table BORDER=0 CELLPADDING=3 COLS=1 WIDTH="600" >
+<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
<tr>
<td>
-<h2>
-<a NAME="whatsnew"></a>What's new in version 2.04</h2>
+<h1>
+<a NAME="whatis"></a>What is ficl?</h1>
+<font size=+1>Ficl (Forth inspired command language) a complete programming
+language interpreter based on ANS Forth and written in Standard C. Ficl
+is designed to be embedded into other systems as a command/macro/development
+prototype language. Ficl provides object extensions that can be used to
+wrap methods and structures of the host system without altering them. See
+below for examples of <a href="#includesficl">software that includes ficl</a>.</font></td>
+</tr>
-<h3>
-ficlwin</h3>
+<tr>
+<td>Where Forths usually view themselves as the center of the system and
+expect the rest of the system to be coded in Forth, Ficl acts as a component
+of the system. It is easy to export code written in C or ASM to Ficl in
+the style of TCL, or to invoke Ficl code from a compiled module. This allows
+you to do incremental development in a way that combines the best features
+of threaded languages (rapid development, quick code/test/debug cycle,
+reasonably fast) with the best features of C (everyone knows it, easier
+to support large blocks of code, efficient, type checking). In addition,
+Ficl provides a simple and powerful object model that can act as an object
+oriented adapter for code written in C (or asm, Forth, C++...). </td>
+</tr>
+<tr>
+<td><b>Ficl Design goals</b>
<ul>
<li>
-Catches exceptions thrown by VM in ficlThread (0 @ for example) rather
-than passing them off to the OS. </li>
-</ul>
+Target 32 bit processors (<i>version 2.03 targets 64 bit processors too</i>)</li>
-<h3>
-ficl bugs vanquished</h3>
-
-<ul>
<li>
-Fixed leading delimiter bugs in s" ." .( and ( (reported by Reuben Thomas)</li>
+Scripting, prototyping, and extension language for systems written also
+in C</li>
<li>
-Makefile tabs restored (thanks to Michael Somos)</li>
+Supportable - code is as transparent as I can make it</li>
<li>
-ABORT" now throws -2 per the DPANS (thanks to Daniel Sobral for sharp eyes
-again) </li>
+Interface to functions written in C</li>
<li>
-ficlExec does not print the prompt string unless (source-id == 0)</li>
+Conform to the Forth DPANS 94</li>
<li>
-Various fixes contributed by the FreeBSD team.</li>
-</ul>
+Minimize porting effort - require an ANSI C runtime environment and minimal
+glue code</li>
-<h3>
-ficl enhancements</h3>
-
-<ul>
<li>
-Words.c: modified ficlCatch to use vmExecute and vmInnerLoop (request of
-Daniel Sobral) Added vmPop and vmPush functions (by request of Lars Krueger
-) in vm.c These are shortcuts to the param stack. (Use LVALUEtoCELL to
-get things into CELL form) </li>
-
-<li>
-Added function vmGetStringEx with a flag to specify whether or not to skip
-lead delimiters</li>
-
-<li>
-Added non-std word: number?</li>
-
-<li>
-Added CORE EXT word AGAIN (by request of Reuben Thomas) </li>
-
-<li>
-Added double cell local (2local) support</li>
-
-<li>
-Augmented Johns Hopkins local syntax so that locals whose names begin with
-char 2 are treated as 2locals (OK - it's goofy, but handy for OOP)</li>
-
-<li>
-C-string class revised and enhanced - now dynamically sized</li>
-
-<li>
-C-hashstring class derived from c-string computes hashcode too.</li>
+Provide object oriented extensions</li>
</ul>
</td>
</tr>
+</table>
-<tr>
-<td>
+<p>
+<hr>
<h2>
-What's new in version 2.03</h2>
-This is the first version of Ficl that includes contributed code. Thanks
-especially to Daniel Sobral, Michael Gauland for contributions and bug
-finding.
-<p>New words
-<ul>
-<li>
-<tt><a href="#clock">clock</a>
-(FICL)</tt></li>
+<a NAME="download"></a>Download</h2>
-<li>
-<tt><a href="#clockspersec">clocks/sec</a>
-(FICL)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans8.htm#8.6.1.1230">dnegate</a>
-(DOUBLE)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans10.htm#10.6.2.1905">ms</a>
-(FACILITY EXT - replaces MSEC <i>ficlWin only</i>)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans9.htm#9.6.1.2275">throw</a>
-(EXCEPTION)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans9.htm#9.6.1.0875">catch</a>
-(EXCEPTION)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans14.htm#14.6.1.0707">allocate</a>
-(MEMORY)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans14.htm#14.6.1.1605">free</a>
-(MEMORY)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans14.htm#14.6.1.2145">resize</a>
-(MEMORY)</tt></li>
-
-<li>
-<tt><a href="http://www.taygeta.com/forth/dpans6.htm#6.2.2440">within</a>
-(CORE EXT)</tt></li>
-
-<li>
-<tt><a href="#alloc">alloc</a>
-(class method)</tt></li>
-
-<li>
-<tt><a href="#allocarray">alloc-array</a>
-(class method)</tt></li>
-
-<li>
-<tt><a href="#oofree">free</a>
-(class method)</tt></li>
-</ul>
-Bugs Fixed
<ul>
<li>
-Bug fix in isNumber(): used to treat chars between 'Z' and 'a' as valid
-in base 10... (harmless, but weird)</li>
+<b><a href="ftp://ftp.taygeta.com/pub/Forth/Compilers/native/misc/ficl205/ficl205.zip">Download
+ficl 2.05</a></b></li>
<li>
-ficlExec pushes the <i>ip</i> and <tt>interpret</tt>s at the right times
-so that nested calls to ficlExec behave the way you'd expect them to.</li>
-
-<li>
-<tt>evaluate</tt> respects count parameter, and also passes exceptional
-return conditions back out to the calling instance of ficlExec.</li>
-
-<li>
-VM_QUIT now clears the locals dictionary in ficlExec.</li>
+<b><a href="ftp://ftp.taygeta.com/pub/Forth/Compilers/native/misc/ficl205/ficlwin.zip">Download
+ficlWin</a> (not for resale. please contact me for resale license arrangements)</b></li>
</ul>
-Ficlwin Enhancements
-<ul>
-<li>
-File Menu: recent file list and Open now load files.</li>
-<li>
-Text ouput function is now faster through use of string caching. Cache
-flushes at the end of each line and each time ficlExec returns.</li>
+<h2>
+<a NAME="links"></a>More information on Ficl and Forth</h2>
-<li>
-Edit/paste now behaves more reasonably for text. File/open loads the specified
-file.</li>
-
-<li>
-Registry entries specify dictionary and stack sizes, default window placement,
-and whether or not to create a splitter for multiple VMs. See HKEY_CURRENT_USER/Software/CodeLab/ficlwin/Settings</li>
-</ul>
-Ficl Enhancements
<ul>
<li>
-This version includes changes to make it <b>64 bit friendly</b>. This unfortunately
-meant that I had to tweak some core data types and structures. I've tried
-to make this transparent to 32 bit code, but a couple of things got renamed.
-INT64 is now DPINT. UNS64 is now DPUNS. FICL_INT and FICL_UNS are synonyms
-for INT32 and UNS32 in 32 bit versions, but a are obsolescent. Please use
-the new data types instead. Typed stack operations on INT32 and UNS32 have
-been renamed because they operate on CELL scalar types, which are 64 bits
-wide on 64 bit systems. Added BITS_PER_CELL, which has legal values of
-32 or 64. Default is 32.</li>
+<a href="http://www.taygeta.com/ficl.html">Web home of Ficl</a></li>
<li>
-ficl.c: Added ficlExecXT() - executes an xt completely before returning,
-passing back any exception codes generated in the process. Normal exit
-code is VM_INNEREXIT.</li>
+<a href="ficlddj.pdf">Manuscript of Ficl article for January 1999 Dr. Dobb's
+Journal</a></li>
<li>
-ficl.c: Added ficlExecC() to operate on counted strings as opposed to zero
-terminated ones.</li>
+<a href="jwsforml.pdf">1998 FORML Conference paper - OO Programming in
+Ficl</a></li>
<li>
-ficlExec pushes ip and executes interpret at the right times so that nested
-calls to ficlExec behave the way you'd expect them to.</li>
+<a href="http://www.taygeta.com/forthlit.html">Forth literature index on
+Taygeta</a></li>
-<li>
-ficlSetStackSize() allows specification of stack size at run-time (affects
-subsequent invocations of ficlNewVM()).</li>
-
-<li>
-vm.c: vmThrow() checks for (pVM->pState != NULL) before longjmping it.
-vmCreate nulls this pointer initially. </li>
-
-<li>
-EXCEPTION wordset contributed by Daniel Sobral of FreeBSD</li>
-
-<li>
-MEMORY-ALLOC wordset contributed by Daniel Sobral, too. Added class methods
-<tt>alloc</tt> and <tt>alloc-array</tt> in softwords/oo.fr to allocate
-objects from the heap.</li>
-
-<li>
-Control structure match check upgraded (thanks to Daniel Sobral for this
-suggestion). Control structure mismatches are now errors, not warnings,
-since the check accepts all syntactally legal constructs.</li>
-
-<li>
-Added vmInnerLoop() to vm.h. This function/macro factors the inner
-interpreter out of ficlExec so it can be used in other places. Function/macro
-behavior is conditioned on INLINE_INNER_LOOP in sysdep.h. Default: 1 unless
-_DEBUG is set. In part, this is because VC++ 5 goes apoplectic when trying
-to compile it as a function. See </li>
-
-<li>
-</li>
-
-<br>comments in vm.c
-<li>
-EVALUATE respects the count parameter, and also passes exceptional return
-conditions back out to the calling instance of ficlExec.</li>
-
-<li>
-VM_QUIT clears locals dictionary in ficlExec()</li>
-
-<li>
-Added Michael Gauland's ficlLongMul and ficlLongDiv and support routines
-to math64.c and .h. These routines are coded in C, and are compiled only
-if PORTABLE_LONGMULDIV == 1 (default is 0).</li>
-
-<li>
-Added definition of ficlRealloc to sysdep.c (needed for memory allocation
-wordset). If your target OS supports realloc(), you'll probably want to
-redefine ficlRealloc in those terms. The default version does ficlFree
-followed by ficlMalloc.</li>
-
-<li>
-testmain.c: Changed gets() in testmain to fgets() to appease the security
-gods.</li>
-
-<li>
-testmain: <tt>msec</tt> renamed to <tt><a href="#ficlms">ms</a></tt> in
-line with the ANS</li>
-
-<li>
-softcore.pl now removes comments & spaces at the start and end of lines.
-As a result: sizeof (softWords) == 7663 bytes (used to be 20000)
-and consumes 11384 bytes of dictionary when compiled</li>
-
-<li>
-Deleted license paste-o in readme.txt (oops).</li>
-</ul>
-</td>
-</tr>
-
-<tr>
-<td>
-<h2>
-What's new in version 2.02</h2>
-New words
<ul>
<li>
-<tt><a href="http://www.taygeta.com/forth/dpans6.htm#6.2.1850">marker</a>
-(CORE EXT)</tt></li>
+<a href="http://www.taygeta.com/forth_intro/stackflo.html">An Introduction
+to Forth using Stack Flow</a></li>
<li>
-<tt><a href="http://www.taygeta.com/forth/dpans15.htm#15.6.2.1580">forget</a>
-(TOOLS EXT)</tt></li>
+<a href="http://www.softsynth.com/pforth/pf_tut.htm">Phil Burk's Forth
+Tutorial</a></li>
<li>
-<tt><a href="#ficlforgetwid">forget-wid</a>
-(FICL)</tt></li>
-
-<li>
-<tt><a href="#ficlwordlist">ficl-wordlist</a> (FICL)</tt></li>
-
-<li>
-<tt><a href="#ficlvocabulary">ficl-vocabulary</a> (FICL)</tt></li>
-
-<li>
-<tt><a href="#ficlhide">hide</a>
-(FICL)</tt></li>
-
-<li>
-<tt><a href="#ficlhidden">hidden</a>
-(FICL)</tt></li>
-
-<li>
-<a href="#jhlocal">Johns Hopkins local variable syntax</a> (as best I can
-determine)</li>
+<a href="http://www.taygeta.com/forth/dpans.html">Draft Proposed American
+National Standard for Forth</a></li>
</ul>
-Bugs Fixed
-<ul>
-<li>
-<tt>forget</tt> now adjusts the dictionary pointer to remove the name of
-the word being forgotten (name chars come before the word header in ficl's
-dictionary)</li>
<li>
-<tt>:noname</tt> used to push the colon control marker and its execution
-token in the wrong order</li>
-
-<li>
-<tt>source-id</tt> now behaves correctly when loading a file.</li>
-
-<li>
-<tt>refill</tt> returns zero at EOF (Win32 load). Win32 <tt><a href="#ficlload">load</a></tt>
-command continues to be misnamed. Really ought to be called <tt>included</tt>,
-but does not exactly conform to that spec either (because <tt>included</tt>
-expects a string signature on the stack, while Ficl's <tt><a href="#ficlload">load</a></tt>
-expects a filename upon invocation). The "real" <tt>LOAD</tt> is a <tt>BLOCK</tt>
-word.</li>
+<a href="http://www.forth.org">Forth Interest Group</a></li>
</ul>
-Enhancements (IMHO)
-<ul>
-<li>
-dictUnsmudge no longer links anonymous definitions into the dictionary</li>
-<li>
-<tt>oop</tt> is no longer the default compile wordlist at startup, nor
-is it in the search order. Execute <b><tt>also oop definitions</tt></b>
-to use Ficl OOP.</li>
-
-<li>
-Revised oo.fr extensively to make more use of early binding</li>
-
-<li>
-Added <tt>meta</tt> - a constant that pushes the address of metaclass.
-See oo.fr for examples of use.</li>
-
-<li>
-Added classes: <tt>c-ptr c-bytePtr c-2bytePtr c-cellPtr
-</tt>These classes model pointers to non-object data, but each knows the
-size of its referent.</li>
-</ul>
-</td>
-</tr>
-
-<tr>
-<td>
<h2>
-What's new in version 2.01</h2>
+<a NAME="includesficl"></a>Some software that uses ficl</h2>
<ul>
<li>
-Bug fix: <tt>(local)</tt> used to leave a value on the stack between the
-first and last locals declared. This value is now stored in a static.</li>
+<a href="http://www.freebsd.org/">FreeBSD</a> boot loader</li>
<li>
-Added new local syntax with parameter re-ordering. <a href="#newlocal">See
-description below</a>. (No longer compiled in version 2.02, in favor of
-the Johns Hopkins syntax)</li>
-</ul>
-</td>
-</tr>
+<a href="http://www.pagesz.net/~sessoms/debuffer/">Palm Pilot Debuffer</a>
+(Eric Sessoms)</li>
-<tr>
-<td>
-<h2>
-What's new in version 2.0</h2>
-
-<ul>
<li>
-New ANS Forth words: <tt>TOOLS</tt> and part of <tt>TOOLS EXT, SEARCH</tt>
-and <tt>SEARCH EXT, LOCALS</tt> and <tt>LOCALS EXT</tt> word sets, additional
-words from <tt>CORE EXT, DOUBLE</tt>, and <tt>STRING</tt>. (See the function
-ficlCompileCore in words.c for an alphabetical list by word set).</li>
+<a href="http://www.swcp.com/~jchavez/osmond.html">Mac PC Board Layout
+tool</a> (J Chavez)</li>
<li>
-Simple <tt>USER</tt> variable support - a user variable is a virtual machine
-instance variable. User variables behave as <tt>VARIABLE</tt>s in all other
-respects.</li>
-
-<li>
-Object oriented syntax extensions (see below)</li>
-
-<li>
-Optional stack underflow and overflow checking in many CORE words (enabled
-when FICL_ROBUST >= 2)</li>
-
-<li>
-Various bug fixes</li>
+<a href="http://www.netcomsystems.com">NetCom Systems</a> ML7710 (Martin
+Usher)</li>
</ul>
-</td>
-</tr>
-</table>
<hr>
<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
<tr>
<td>
-<h1>
-<a NAME="whatis"></a>What is ficl?</h1>
-<font size=+1>Ficl (Forth inspired command language) is an ANS Forth interpreter
-written in C. Unlike traditional Forths, this interpreter is designed to
-be embedded into other systems as a command/macro/development prototype
-language. Ficl provides object extensions that can be used to wrap methods
-and structures of the host system without altering them. See below for
-examples of <a href="#includesficl">software that includes ficl</a>.</font></td>
+<h2>
+<a NAME="lawyerbait"></a>DISCLAIMER OF WARRANTY and LICENSE</h2>
+<i>Ficl is freeware. Use it in any way that you like, with the understanding
+that the code is not supported.</i>
+<p>Any third party may reproduce, distribute, or modify the ficl software
+code or any derivative works thereof without any compensation or license,
+provided that the original author information and this disclaimer text
+are retained in the source code files. The ficl software code is provided
+on an "as is" basis without warranty of any kind, including, without limitation,
+the implied warranties of merchantability and fitness for a particular
+purpose and their equivalents under the laws of any jurisdiction.
+<p>The FiclWin distribution, a derivative work of the ficl source code,
+is hereby licensed for unrestricted non-commercial use under the ficl license
+provided the user notifies the author (John Sadler) in writing or by electronic
+mail or their intended use of the FiclWin sources. You may freely redistribute
+the FiclWin distribution provided it contains this notice and adheres to
+all other provisions of this license.
+<p>Reselling the FiclWin source code, executable, or works derived from
+the FiclWin source code is prohibited under this license. Please contact
+me directly in order to discuss license terms for commercial use and distribution.
+<p>I am interested in hearing from anyone who uses ficl. If you have a
+problem, a success story, a defect, an enhancement request, or if you would
+like to contribute to the ficl release, please <a href="mailto:john_sadler@alum.mit.edu">send
+me email</a>. </td>
</tr>
-
-<tr>
-<td>Where Forths usually view themselves as the center of the system and
-expect the rest of the system to be coded in Forth, Ficl acts as a component
-of the system. It is easy to export code written in C or ASM to Ficl in
-the style of TCL, or to invoke Ficl code from a compiled module. This allows
-you to do incremental development in a way that combines the best features
-of threaded languages (rapid development, quick code/test/debug cycle,
-reasonably fast) with the best features of C (everyone knows it, easier
-to support large blocks of code, efficient, type checking). In addition,
-Ficl provides a simple object model that can act as an object oriented
-adapter for code written in C (or asm, Forth, C++...). </td>
-</tr>
-
-<tr>
-<td><b>Ficl Design goals</b>
-<ul>
-<li>
-Target 32 bit processors (<i>version 2.03 targets 64 bit processors too</i>)</li>
-
-<li>
-Scripting, prototyping, and extension language for systems written also
-in C</li>
-
-<li>
-Supportable - code is as transparent as I can make it</li>
-
-<li>
-Interface to functions written in C</li>
-
-<li>
-Conform to the Forth DPANS 94</li>
-
-<li>
-Minimize porting effort - require an ANSI C runtime environment and minimal
-glue code</li>
-
-<li>
-Provide object oriented extensions</li>
-</ul>
-</td>
-</tr>
</table>
<br>
-<br>
<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
<tr>
<td>
@@ -565,13 +274,14 @@
This function is stubbed out by default (See FICL_MULTITHREAD in sysdep.h).
As long as there is only one "session" that can compile words into the
dictionary, you do not need exclusive dictionary access for multithreading.
-<font color="#000099"><b>Note</b>: while the code is re-entrant, there
-are still restrictions on how you can use it safely in a multithreaded
-system. Specifically, the VM itself maintains state, so you generally need
-a VM per thread in a multithreaded system. If interrupt service routines
-make calls into Ficl code that alters VM state, then these generally need
-their own VM as well. Alternatively, you could provide a mutual exclusion
-mechanism to serialize access to a VM from multiple threads.</font></li>
+<font color="#000099"><b>Note</b>:
+while the code is re-entrant, there are still restrictions on how you can
+use it safely in a multithreaded system. Specifically, the VM itself maintains
+state, so you generally need a VM per thread in a multithreaded system.
+If interrupt service routines make calls into Ficl code that alters VM
+state, then these generally need their own VM as well. Alternatively, you
+could provide a mutual exclusion mechanism to serialize access to a VM
+from multiple threads.</font></li>
<li>
Simple incorporation into existing systems: the sample implementation requires
@@ -608,12 +318,14 @@
its runtime library. Inspect the system dependent macros and functions
in <tt>sysdep.h</tt> and <tt>sysdep.c</tt> and edit them to suit your system.
For example, <tt>INT16</tt> is a <tt>short</tt> on some compilers and an
-<tt>int</tt> on others. Check the default <tt>CELL</tt> alignment controlled
-by <tt>FICL_ALIGN</tt>. If necessary, add new definitions of <tt>ficlMalloc,
-ficlFree, ficlLockDictionary</tt>, and <tt>ficlTextOut</tt> to work with
-your operating system. Finally, use <tt>testmain.c</tt> as a guide to installing
-the ficl system and one or more virtual machines into your code. You do
-not need to include <tt>testmain.c</tt> in your build.
+<tt>int</tt>
+on others. Check the default <tt>CELL</tt> alignment controlled by <tt>FICL_ALIGN</tt>.
+If necessary, add new definitions of <tt>ficlMalloc, ficlFree, ficlRealloc,
+ficlLockDictionary</tt>, and <tt>ficlTextOut</tt> to work with your operating
+system. Finally, use
+<tt>testmain.c</tt> as a guide to installing the ficl
+system and one or more virtual machines into your code. You do not need
+to include <tt>testmain.c</tt> in your build.
<p>Feel free to stub out the double precision math functions (which are
presently implemented as inline assembly because it's so easy on many 32
bit processors) with kludge code that only goes to 32 bit precision. In
@@ -629,6 +341,16 @@
3200 cells for a full system, about 2000 if you strip out most of the "soft"
words.
<h3>
+Soft Words</h3>
+Many words from all the supported wordsets are written in Forth, and stored
+as a big string that Ficl compiles when it starts. The sources for all
+of these words are in directory ficl/softwords. There is a .bat file (softcore.bat)
+and a PERL 5 script (softcore.pl) that convert Forth files into the file
+softcore.c, so softcore.c is really dependent on the Forth sources. This
+is not reflected in the Visual C++ project database. For the time being,
+it's a manual step. You can edit softcore.bat to change the list of files
+that contribute to softcore.c.
+<h3>
To-Do List (target system dependent words)</h3>
<ul>
@@ -649,8 +371,12 @@
<td>
<h2>
<a NAME="api"></a>Application Programming Interface</h2>
-<i>See the comments in ficl.c and ficl.h for additional information, and
-the example in file testmain.c.</i>
+The following is a partial listing of functions that interface your system
+or program to ficl. For a complete listing, see ficl.h (heavily commented).
+For examples, see testmain.c and the ficlwin sources (<a href="#download">below</a>).
+<i>See
+the comments in ficl.c and ficl.h for additional information, and the example
+in file testmain.c.</i>
<dl>
<dt>
<b>void ficlInitSystem(int nDictCells)</b></dt>
@@ -708,6 +434,15 @@
overhead.</dd>
<dt>
+<b>void ficlFreeVM(FICL_VM *pVM)</b></dt>
+
+<dd>
+Removes the VM in question from the system VM list and deletes the
+memory allocated to it. This is an optional call, since ficlTermSystem
+will do this cleanup for you. This function is handy if you're going to
+do a lot of dynamic creation of VMs.</dd>
+
+<dt>
<b>FICL_VM *ficlNewVM(void)</b></dt>
<dd>
@@ -845,6 +580,13 @@
</tr>
<tr>
+<td><b>search.c</b></td>
+
+<td>Contains C implementations of several of the SEARCH and SEARCH EXT
+words</td>
+</tr>
+
+<tr>
<td><b>softcore.c</b></td>
<td>Contains all of the "soft" words - those written in Forth and compiled
@@ -869,115 +611,10 @@
</tr>
</table>
-<hr>
+<hr WIDTH="100%">
<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
<tr>
<td>
-<h2>
-<a NAME="locals"></a>Local Variables</h2>
-Locally scoped variables came late to Forth. Purists seem to feel that
-experienced Forth programmers can 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.
-<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>
-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: much of the OOP code described below uses 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.
-<br>The default maximum number of local variables is 16. It's controlled
-by FICL_MAX_LOCALS in sysdep.h.
-<p><a NAME="jhlocal"></a>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:
-<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>In ficl 2.04 and later, this facilty can also declare double cell locals
-(this is handy for <a href="#ootutorial">OOP</a>, where objects take two
-cells to represent on the stack). Double cell locals (AKA 2locals) have
-names that start with 2. See ficl/softwords/string.fr for examples.
-<p><a NAME="newlocal"></a>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>
-
-<h3>
-Search Order</h3>
-Ficl implements many of the search order words in terms of two primitives
-called <tt><a href="#tosearch">>SEARCH</a></tt> and <tt><a href="#searchfrom">SEARCH></a></tt>.
-As their names suggest (assuming you're familiar with Forth), they push
-and pop the search order stack. See the list of <a href="#extras">Ficl
-extras</a> for details.
-<br>The standard does not appear to specify any conditions under which
-the search order is reset to a sane state. Ficl resets the search order
-to its default state whenever <tt>ABORT</tt> happens. This includes stack
-underflows and overflows. <tt>QUIT</tt> does not affect the search order.
-The minimum search order (set by <tt>ONLY</tt>) is equivalent to
-<br><b><tt>FORTH-WORDLIST 1 SET-ORDER</tt></b>
-<br>There is a default maximum of 16 wordlists in the search order. This
-can be changed by redefining FICL_DEFAULT_VOCS (declared in sysdep.h).
-<h3>
-Soft Words</h3>
-Many words from all the supported wordsets are written in Forth, and stored
-as a big string that Ficl compiles when it starts. The sources for all
-of these words are in directory ficl/softwords. There is a .bat file (softcore.bat)
-and a PERL 5 script (softcore.pl) that convert Forth files into the file
-softcore.c, so softcore.c is really dependent on the Forth sources. This
-is not reflected in the Visual C++ project database. For the time being,
-it's a manual step. You can edit softcore.bat to change the list of files
-that contribute to softcore.c. </td>
-</tr>
-</table>
-
-<hr>
-<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
-<tr>
-<td>
<dl>
<h2>
<a NAME="extras"></a>Ficl extras</h2>
@@ -996,8 +633,21 @@
<h3>
Search order words</h3>
-Note: Ficl resets the search order whenever it does <tt>ABORT</tt>. If
-you don't like this behavior, just comment out the dictResetSearchOrder()
+Ficl implements many of the search order words in terms of two primitives
+called <tt><a href="#tosearch">>SEARCH</a></tt> and <tt><a href="#searchfrom">SEARCH></a></tt>.
+As their names suggest (assuming you're familiar with Forth), they push
+and pop the search order stack. See the list of <a href="#extras">Ficl
+extras</a> for details.
+<br>The standard does not appear to specify any conditions under which
+the search order is reset to a sane state. Ficl resets the search order
+to its default state whenever <tt>ABORT</tt> happens. This includes stack
+underflows and overflows. <tt>QUIT</tt> does not affect the search order.
+The minimum search order (set by <tt>ONLY</tt>) is equivalent to
+<dl><b><tt>FORTH-WORDLIST 1 SET-ORDER</tt></b></dl>
+There is a default maximum of 16 wordlists in the search order. This can
+be changed by redefining FICL_DEFAULT_VOCS (declared in sysdep.h).
+<p><b>Note</b>: Ficl resets the search order whenever it does <tt>ABORT</tt>.
+If you don't like this behavior, just comment out the dictResetSearchOrder()
lines in ficlExec().
<br>
<dt>
@@ -1070,6 +720,33 @@
see what's in there, try: <b><tt>hide words previous set-current</tt></b></dd>
<dt>
+<tt>last-word ( -- xt )</tt></dt>
+
+<dd>
+Pushes the xt address of the most recently defined word. This applies to
+colon definitions, constants, variables, and words that use <tt>create</tt>.
+You can print the name of the most recently defined word with <tt>last-word
+>name type</tt> </dd>
+
+<dt>
+<tt>wid-get-name ( wid -- c-addr u )</tt></dt>
+
+<dd>
+Ficl wordlists (2.05 and later) have a name property that can be assigned.
+This is used by <tt>ORDER</tt> to list the names of wordlists in the search
+order. </dd>
+
+<dt>
+<tt>wid-set-name ( c-addr wid -- )</tt></dt>
+
+<dd>
+Ficl wordlists (2.05 and later) have a name property that can be assigned.
+This is used by <tt>ORDER</tt> to list the names of wordlists in the search
+order. The name is assumed to be a \0 terminated string (C style), which
+conveniently is how Ficl stores word names. See softwords/softcore.fr
+definition of <tt>brand-wordlist</tt> </dd>
+
+<dt>
<tt>wid-set-super ( wid -- )</tt></dt>
<dd>
@@ -1336,9 +1013,6 @@
<li>
<b>aligned address requirements (3.1.3.3 Addresses);</b> </li>
-<li>
-</li>
-
<br><font color="#000000">System dependent. You can change the default
address alignment by defining FICL_ALIGN on your compiler's command line.
The default value is set to 2 in sysdep.h. This causes dictionary entries
@@ -1347,17 +1021,11 @@
<li>
<b>behavior of 6.1.1320 EMIT for non-graphic characters</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Depends on target system, C runtime library,
and your implementation of ficlTextOut().</font>
<li>
<b>character editing of 6.1.0695 ACCEPT and 6.2.1390 EXPECT</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">None implemented in the versions supplied in
words.c. Because ficlExec() is supplied a text buffer externally, it's
up to your system to define how that buffer will be obtained.</font>
@@ -1364,17 +1032,11 @@
<li>
<b>character set (3.1.2 Character types, 6.1.1320 EMIT, 6.1.1750 KEY)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Depends on target system and implementation of
ficlTextOut()</font>
<li>
<b>character-aligned address requirements (3.1.3.3 Addresses)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl characters are one byte each. There are
no alignment requirements.</font>
<li>
@@ -1381,9 +1043,6 @@
<b>character-set-extensions matching characteristics (3.4.2 Finding definition
n<font color="#000000">ames)</font></b><font color="#000000">; </font></li>
-<li>
-</li>
-
<br><font color="#000000">No special processing is performed on characters
beyond case-folding. Therefore, extended characters will not match their
unaccented counterparts.</font>
@@ -1391,24 +1050,15 @@
<b>conditions under which control characters match a space delimiter (3.4.1.1
Delimiters)</b>;<font color="#FF6666"> </font></li>
-<li>
-</li>
-
<br><font color="#000000">Ficl uses the Standard C function isspace() to
distinguish space characters. The rest is up to your library vendor.</font>
<li>
<b>format of the control-flow stack (3.2.3.2 Control-flow stack)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Uses the data stack</font>
<li>
<b>conversion of digits larger than thirty-five (3.2.1.2 Digit conversion)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">The maximum supported value of <tt>BASE</tt>
is 36. Ficl will assertion fail in function ltoa of vm.c if the base is
found to be larger than 36 or smaller than 2. There will be no effect if
@@ -1416,23 +1066,14 @@
<li>
<b>display after input terminates in 6.1.0695 ACCEPT and 6.2.1390 EXPECT</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Target system dependent</font>
<li>
<b>exception abort sequence (as in 6.1.0680 ABORT")</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Does <tt>ABORT</tt></font>
<li>
<b>input line terminator (3.2.4.1 User input device)</b>;<font color="#FF0000"> </font></li>
-<li>
-</li>
-
<br><font color="#000000">Target system dependent (implementation of outer
loop that calls ficlExec)</font>
<li>
@@ -1439,16 +1080,10 @@
<b>maximum size of a counted string, in characters (3.1.3.4 Counted strings,
6.1.2450 WORD)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">255</font>
<li>
<b>maximum size of a parsed string (3.4.1 Parsing)</b>; </li>
-<li>
-</li>
-
<br>Limited by available memory and the maximum unsigned value that can
fit in a CELL (2<sup>32</sup>-1).
<li>
@@ -1455,31 +1090,19 @@
<b>maximum size of a definition name, in characters (3.3.1.2 Definition
names)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl stores the first 31 characters of a definition
name.</font>
<li>
<b>maximum string length for 6.1.1345 ENVIRONMENT?, in characters</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Same as maximum definition name length</font>
<li>
<b>method of selecting 3.2.4.1 User input device</b>; </li>
-<li>
-</li>
-
<br>None supported. This is up to the target system
<li>
<b>method of selecting 3.2.4.2 User output device</b>; </li>
-<li>
-</li>
-
<br>None supported. This is up to the target system
<li>
<b>methods of dictionary compilation (3.3 The Forth dictionary)</b>; </li>
@@ -1487,9 +1110,6 @@
<li>
<b>number of bits in one address unit (3.1.3.3 Addresses)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Target system dependent. Ficl generally supports
processors that can address 8 bit quantities, but there is no dependency
that I'm aware of.</font>
@@ -1496,9 +1116,6 @@
<li>
<b>number representation and arithmetic (3.2.1.1 Internal number representation)</b>; </li>
-<li>
-</li>
-
<br>System dependent. Ficl represents a CELL internally as a union that
can hold INT32 (a signed 32 bit scalar value), UNS32 (32 bits unsigned),
and an untyped pointer. No specific byte ordering is assumed.
@@ -1506,9 +1123,6 @@
<b>ranges for n, +n, u, d, +d, and ud (3.1.3 Single-cell types, 3.1.4 Cell-pair
types)</b>; </li>
-<li>
-</li>
-
<br>Assuming a 32 bit implementation, range for signed single-cell values
is -2<sup>31</sup>..2<sup>31</sup>-1. Range for unsigned single cell values
is 0..2<sup>32</sup>-1. Range for signed double-cell values is -2<sup>63</sup>..2<sup>63</sup>-1.
@@ -1516,37 +1130,22 @@
<li>
<b>read-only data-space regions (3.3.3 Data space)</b>;</li>
-<li>
-</li>
-
<br>None
<li>
<b>size of buffer at 6.1.2450 WORD (3.3.3.6 Other transient regions)</b>; </li>
-<li>
-</li>
-
<br>Default is 255. Depends on the setting of nPAD in ficl.h.
<li>
<b>size of one cell in address units (3.1.3 Single-cell types)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">System dependent, generally four.</font>
<li>
<b>size of one character in address units (3.1.2 Character types)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">System dependent, generally one.</font>
<li>
<b>size of the keyboard terminal input buffer (3.3.3.5 Input buffers)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">This buffer is supplied by the host program.
Ficl imposes no practical limit.</font>
<li>
@@ -1553,61 +1152,37 @@
<b>size of the pictured numeric output string buffer (3.3.3.6 Other transient
regions)</b>; </li>
-<li>
-</li>
-
<br>Default is 255 characters. Depends on the setting of nPAD in ficl.h.
<li>
<b>size of the scratch area whose address is returned by 6.2.2000 PAD (3.3.3.6
Other transient regions)</b>; </li>
-<li>
-</li>
-
<br>Not presently supported
<li>
<b>system case-sensitivity characteristics (3.4.2 Finding definition names)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl is not case sensitive</font>
<li>
<b>system prompt (3.4 The Forth text interpreter, 6.1.2050 QUIT)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">"ok>"</font>
<li>
<b>type of division rounding (3.2.2.1 Integer division, 6.1.0100 */, 6.1.0110
*/MOD, 6.1.0230 /, 6.1.0240 /MOD, 6.1.1890 MOD)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Symmetric</font>
<li>
<b>values of 6.1.2250 STATE when true</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">One (no others)</font>
<li>
<b>values returned after arithmetic overflow (3.2.2.2 Other integer operations)</b>; </li>
-<li>
-</li>
-
<br>System dependent. Ficl makes no special checks for overflow.
<li>
<b>whether the current definition can be found after 6.1.1250 DOES> (6.1.0450
:)</b>. </li>
-<li>
-</li>
-
<br><font color="#000000">No. Definitions are unsmudged after ; only, and
only then if no control structure matching problems have been detected.</font></ul>
@@ -1623,9 +1198,6 @@
<b>a name is neither a valid definition name nor a valid number during
text interpretation (3.4 The Forth text interpreter)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl does <tt>ABORT</tt> and prints the name
followed by " not found".</font>
<li>
@@ -1632,9 +1204,6 @@
<b>a definition name exceeded the maximum length allowed (3.3.1.2 Definition
names)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl stores the first 31 characters of the definition
name, and uses all characters of the name in computing its hash code. The
actual length of the name, up to 255 characters, is stored in the definition's
@@ -1642,9 +1211,6 @@
<li>
<b>addressing a region not listed in 3.3.3 Data Space</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">No problem: all addresses in ficl are absolute.
You can reach any 32 bit address in Ficl's address space.</font>
<li>
@@ -1651,9 +1217,6 @@
<b>argument type incompatible with specified input parameter, e.g., passing
a flag to a word expecting an n (3.1 Data types)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl makes no check for argument type compatibility.
Effects of a mismatch vary widely depending on the specific problem and
operands.</font>
@@ -1661,9 +1224,6 @@
<b>attempting to obtain the execution token, (e.g., with 6.1.0070 ', 6.1.1550
FIND, etc.) of a definition with undefined interpretation semantics</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl returns a valid token, but the result of
executing that token while interpreting may be undesirable.</font>
<li>
@@ -1671,9 +1231,6 @@
/MOD, 6.1.1561 FM/MOD, 6.1.1890 MOD, 6.1.2214 SM/REM, 6.1.2370 UM/MOD,
8.6.1.1820 M*/)</b>;</li>
-<li>
-</li>
-
<br><font color="#000000">Results are target procesor dependent. Generally,
Ficl makes no check for divide-by-zero. The target processor will probably
throw an exception.</font>
@@ -1680,9 +1237,6 @@
<li>
<b>insufficient data-stack space or return-stack space (stack overflow)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">With FICL_ROBUST (sysdep.h) set >= 2, most parameter
stack operations are checked for underflow and overflow. Ficl does not
check the return stack.</font>
@@ -1689,16 +1243,10 @@
<li>
<b>insufficient space for loop-control parameters</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">No check - Evil results.</font>
<li>
<b>insufficient space in the dictionary</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl generates an error message if the dictionary
is too full to create a definition header. It checks <tt>ALLOT</tt> as
well, but it is possible to make an unchecked allocation request that overflows
@@ -1706,9 +1254,6 @@
<li>
<b>interpreting a word with undefined interpretation semantics</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl protects all ANS Forth words with undefined
interpretation semantics from being executed while in interpret state.
It is possible to defeat this protection using ' (tick) and <tt>EXECUTE</tt>,
@@ -1717,9 +1262,6 @@
<b>modifying the contents of the input buffer or a string literal (3.3.3.4
Text-literal regions, 3.3.3.5 Input buffers)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Varies depending on the nature of the buffer.
The input buffer is supplied by ficl's host function, and may reside in
read-only memory. If so, writing the input buffer can ganerate an exception.
@@ -1727,9 +1269,6 @@
<li>
<b>overflow of a pictured numeric output string</b>;</li>
-<li>
-</li>
-
<br>In the unlikely event you are able to construct a pictured numeric
string of more than 255 characters, the system will be corrupted unpredictably.
The buffer area that holds pictured numeric output is at the end of the
@@ -1738,9 +1277,6 @@
<li>
<b>parsed string overflow</b>;</li>
-<li>
-</li>
-
<br>Ficl does not copy parsed strings unless asked to. Ordinarily, a string
parsed from the input buffer during normal interpretation is left in-place,
so there is no possibility of overflow. If you ask to parse a string into
@@ -1752,16 +1288,10 @@
*, 6.1.0100 */, 6.1.0110 */MOD, 6.1.0570 >NUMBER, 6.1.1561 FM/MOD, 6.1.2214
SM/REM, 6.1.2370 UM/MOD, 6.2.0970 CONVERT, 8.6.1.1820 M*/)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Value will be truncated</font>
<li>
<b>reading from an empty data stack or return stack (stack underflow)</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Most stack underflows are detected and prevented
if FICL_ROBUST (sysdep.h) is set to 2 or greater. Otherwise, the stack
pointer and size are likely to be trashed.</font>
@@ -1769,9 +1299,6 @@
<b>unexpected end of input buffer, resulting in an attempt to use a zero-length
string as a name</b>; </li>
-<li>
-</li>
-
<br><font color="#000000">Ficl returns for a new input buffer until a non-empty
one is supplied.</font></ul>
The following specific ambiguous conditions are noted in the glossary entries
@@ -1780,33 +1307,21 @@
<li>
<b>>IN greater than size of input buffer (3.4.1 Parsing)</b></li>
-<li>
-</li>
-
<br>Bad Things occur - unpredictable bacause the input buffer is supplied
by the host program's outer loop.
<li>
<b>6.1.2120 RECURSE appears after 6.1.1250 DOES></b></li>
-<li>
-</li>
-
<br>It finds the address of the definition before <tt>DOES></tt>
<li>
<b>argument input source different than current input source for 6.2.2148
RESTORE-INPUT</b></li>
-<li>
-</li>
-
<br>Not implemented
<li>
<b>data space containing definitions is de-allocated (3.3.3.2 Contiguous
regions)</b></li>
-<li>
-</li>
-
<br>This is OK until the cells are overwritten with something else. The
dictionary maintains a hash table, and the table must be updated in order
to de-allocate words without corruption.
@@ -1813,24 +1328,15 @@
<li>
<b>data space read/write with incorrect alignment (3.3.3.1 Address alignment)</b></li>
-<li>
-</li>
-
<br>Target processor dependent. Consequences include: none (Intel), address
error exception (68K).
<li>
<b>data-space pointer not properly aligned (6.1.0150 ,, 6.1.0860 C,)</b></li>
-<li>
-</li>
-
<br>See above on data space read/write alignment
<li>
<b>less than u+2 stack items (6.2.2030 PICK, 6.2.2150 ROLL)</b></li>
-<li>
-</li>
-
<br>Ficl detects a stack underflow and reports it, executing <tt>ABORT,</tt>
as long as FICL_ROBUST is two or larger.
<li>
@@ -1837,9 +1343,6 @@
<b>loop-control parameters not available ( 6.1.0140 +LOOP, 6.1.1680 I,
6.1.1730 J, 6.1.1760 LEAVE, 6.1.1800 LOOP, 6.1.2380 UNLOOP)</b></li>
-<li>
-</li>
-
<br>Loop initiation words are responsible for checking the stack and guaranteeing
that the control parameters are pushed. Any underflows will be detected
early if FICL_ROBUST is set to two or greater. Note however that Ficl only
@@ -1847,47 +1350,30 @@
<li>
<b>most recent definition does not have a name (6.1.1710 IMMEDIATE)</b></li>
-<li>
-</li>
-
<br>No problem.
<li>
<b>name not defined by 6.2.2405 VALUE used by 6.2.2295 TO</b></li>
-<li>
-</li>
-
<br>Ficl's version of <tt>TO</tt> works correctly with <tt>VALUE</tt>s,
-<tt>CONSTANT</tt>s and <tt>VARIABLE</tt>s.
+<tt>CONSTANT</tt>s
+and <tt>VARIABLE</tt>s.
<li>
<b>name not found (6.1.0070 ', 6.1.2033 POSTPONE, 6.1.2510 ['], 6.2.2530
[COMPILE])</b></li>
-<li>
-</li>
-
<br>Ficl prints an error message and does <tt>ABORT</tt>
<li>
<b>parameters are not of the same type (6.1.1240 DO, 6.2.0620 ?DO, 6.2.2440
WITHIN)</b></li>
-<li>
-</li>
-
<br>No check. Results vary depending on the specific problem.
<li>
<b>6.1.2033 POSTPONE or 6.2.2530 [COMPILE] applied to 6.2.2295 TO</b></li>
-<li>
-</li>
-
<br>The word is postponed correctly.
<li>
<b>string longer than a counted string returned by 6.1.2450 WORD</b></li>
-<li>
-</li>
-
<br>Ficl stores the first FICL_STRING_MAX-1 chars in the destination buffer.
(The extra character is the trailing space required by the standard. Yuck.)
<li>
@@ -1894,9 +1380,6 @@
<b>u greater than or equal to the number of bits in a cell (6.1.1805 LSHIFT,
6.1.2162 RSHIFT)</b></li>
-<li>
-</li>
-
<br>Depends on target process or and C runtime library implementations
of the << and >> operators on unsigned values. For I386, the processor
appears to shift modulo the number of bits in a cell.
@@ -1903,9 +1386,6 @@
<li>
<b>word not defined via 6.1.1000 CREATE (6.1.0550 >BODY, 6.1.1250 DOES>)</b></li>
-<li>
-</li>
-
<br><b>words improperly used outside 6.1.0490 <# and 6.1.0040 #> (6.1.0030
#, 6.1.0050 #S, 6.1.1670 HOLD, 6.1.2210 SIGN)</b>
<br>Don't. <tt>CREATE</tt> reserves a field in words it builds for <tt>DOES></tt>to
@@ -1923,9 +1403,6 @@
<b>maximum number of locals in a definition (13.3.3 Processing locals,
13.6.2.1795 LOCALS|)</b></li>
-<li>
-</li>
-
<br>Default is 16. Change by redefining FICL_MAX_LOCALS, defined in sysdep.h</ul>
<h3>
@@ -1935,9 +1412,6 @@
<li>
<b>executing a named local while in interpretation state (13.6.1.0086 (LOCAL))</b></li>
-<li>
-</li>
-
<br>Locals can be found in interpretation state while in the context of
a definition under construction. Under these circumstances, locals behave
correctly. Locals are not visible at all outside the scope of a definition.
@@ -1944,9 +1418,6 @@
<li>
<b>name not defined by VALUE or LOCAL (13.6.1.2295 TO)</b></li>
-<li>
-</li>
-
<br>See the CORE ambiguous conditions, above (no change)</ul>
<h3>
@@ -1956,9 +1427,6 @@
<li>
<b>source and format of display by 15.6.1.2194 SEE</b></li>
-<li>
-</li>
-
<br>SEE de-compiles definitions from the dictionary. Because Ficl words
are threaded by their header addresses, it is very straightforward to print
the name and other characteristics of words in a definition. Primitives
@@ -1974,17 +1442,11 @@
<b>maximum number of word lists in the search order (16.3.3 Finding definition
names, 16.6.1.2197 SET-ORDER)</b> </li>
-<li>
-</li>
-
<br>Defaults to 16. Can be changed by redefining FICL_DEFAULT_VOCS, declared
in sysdep.h
<li>
<b>minimum search order (16.6.1.2197 SET-ORDER, 16.6.2.1965 ONLY)</b> </li>
-<li>
-</li>
-
<br>Equivalent to <tt>FORTH-WORDLIST 1 SET-ORDER</tt></ul>
<h3>
@@ -1994,9 +1456,6 @@
<li>
<b>changing the compilation word list (16.3.3 Finding definition names)</b></li>
-<li>
-</li>
-
<br>Ficl stores a link to the current definition independently of the compile
wordlist while it is being defined, and links it into the compile wordlist
only after the definition completes successfully. Changing the compile
@@ -2005,110 +1464,14 @@
<li>
<b>search order empty (16.6.2.2037 PREVIOUS)</b></li>
-<li>
-</li>
-
<br>Ficl prints an error message if the search order underflows, and resets
the order to its default state.
<li>
<b>too many word lists in search order (16.6.2.0715 ALSO)</b></li>
-<li>
-</li>
-
<br>Ficl prints an error message if the search order overflows, and resets
the order to its default state.</ul>
</td>
-</tr>
-</table>
-
-<hr>
-<p><a NAME="links"></a>
-<p>For more information
-<ul>
-<li>
-<a href="http://www.taygeta.com/ficl.html">Web home of ficl</a></li>
-
-<li>
-<b><a href="ftp://ftp.taygeta.com/pub/Forth/Compilers/native/misc/ficl204/ficl204.zip">Download
-ficl 2.04</a></b></li>
-
-<li>
-<b><a href="ftp://ftp.taygeta.com/pub/Forth/Compilers/native/misc/ficl204/ficlwin.zip">Download
-ficlWin</a> (not for resale. please contact me for resale license arrangements)</b></li>
-
-<li>
-<a href="ficlddj.pdf">Manuscript of Ficl article for January 1999 Dr. Dobb's
-Journal</a></li>
-
-<li>
-<a href="jwsforml.pdf">1998 FORML Conference paper</a></li>
-
-<li>
-<a href="http://www.taygeta.com/forthlit.html">Forth literature</a></li>
-
-<ul>
-<li>
-<a href="http://www.softsynth.com/pforth/pf_tut.htm">Phil Burk's Forth
-Tutorial</a></li>
-
-<li>
-<a href="http://www.taygeta.com/forth/dpans.html">Draft Proposed American
-National Standard for Forth</a></li>
-</ul>
-
-<li>
-<a href="http://www.forth.org">Forth Interest Group</a></li>
-</ul>
-
-<h2>
-<a NAME="includesficl"></a>Some software that uses ficl</h2>
-
-<ul>
-<li>
-<a href="http://www.freebsd.org/">FreeBSD</a> boot loader</li>
-
-<li>
-<a href="http://www.pagesz.net/~sessoms/debuffer/">Palm Pilot Debuffer</a>
-(Eric Sessoms)</li>
-
-<li>
-<a href="http://www.swcp.com/~jchavez/osmond.html">Mac PC Board Layout
-tool</a> (J Chavez)</li>
-
-<li>
-<a href="http://www.netcomsystems.com">NetCom Systems</a> ML7710 (Martin
-Usher)</li>
-</ul>
-
-<hr>
-<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
-<tr>
-<td>
-<h2>
-<a NAME="lawyerbait"></a>DISCLAIMER OF WARRANTY and LICENSE</h2>
-<i>Ficl is freeware. Use it in any way that you like, with the understanding
-that the code is not supported.</i>
-<p>Any third party may reproduce, distribute, or modify the ficl software
-code or any derivative works thereof without any compensation or license,
-provided that the original author information and this disclaimer text
-are retained in the source code files. The ficl software code is provided
-on an "as is" basis without warranty of any kind, including, without limitation,
-the implied warranties of merchantability and fitness for a particular
-purpose and their equivalents under the laws of any jurisdiction.
-<p>The FiclWin distribution, a derivative work of the ficl source code,
-is hereby licensed for unrestricted non-commercial use under the ficl license
-provided the user notifies the author (John Sadler) in writing or by electronic
-mail or their intended use of the FiclWin sources. You may freely redistribute
-the FiclWin distribution provided it contains this notice and adheres to
-all other provisions of this license.
-<p>Reselling the FiclWin source code, executable, or works derived from
-the FiclWin source code is prohibited under this license. Please contact
-me directly in order to discuss license terms for commercial use and distribution.
-<p>I am interested in hearing from anyone who uses ficl. If you have a
-problem, a success story, a defect, an enhancement request, or if you would
-like to contribute to the ficl release, please <a href="mailto:john_sadler@alum.mit.edu">send
-me email</a>. </td>
</tr>
</table>
--- a/doc/ficl_oop.html
+++ b/doc/ficl_oop.html
@@ -3,15 +3,14 @@
<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="Description" content="object oriented programming in the coolest embedded scripting language ever">
<meta name="GENERATOR" content="Mozilla/4.73 [en] (Win98; U) [Netscape]">
- <title>ficl release notes</title>
+ <title>Ficl Object Oriented Programming</title>
</head>
<body>
-<center>
<h1>
-<b>Object Oriented Programming in ficl</b></h1></center>
+<b>Object Oriented Programming in ficl</b></h1>
<table BORDER=0 CELLSPACING=3 WIDTH="600" >
<tr>
@@ -25,11 +24,11 @@
</tr>
<tr>
-<td><b>This file created: 6 June 2000</b></td>
+<td><b>Created: 6 June 2000</b></td>
</tr>
<tr>
-<td><b>Revised:</b></td>
+<td><b>Revised: </b></td>
</tr>
</table>
@@ -49,7 +48,6 @@
<li>
<a href="ficl.html#oopgloss">OOP glossary</a></li>
-<ul>
<li>
<a href="#glossinstance">Instance variable glossary</a></li>
@@ -57,12 +55,11 @@
<a href="#glossclass">Class methods glossary</a></li>
<li>
-<a href="#objectgloss">Object base class methods glossary</a></li>
+<a href="#objectgloss"><tt>OBJECT</tt> base class methods glossary</a></li>
<li>
<a href="#stockclasses">Supplied Classes</a></li>
</ul>
-</ul>
<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
<tr>
@@ -71,9 +68,10 @@
<a NAME="objects"></a>Object Oriented Programming in ficl</h2>
<h3>
-Review of OO ideas</h3>
-Click <a href="oo_in_c.html#review">here</a> for a short review of OO ideas
-and implementations in other languages
+Review of <a href="http://www.whatis.com/oop.htm">OO</a> ideas</h3>
+Click <a href="oo_in_c.html#review">here</a> for a short review of OO ideas,
+terms, and implementations in other languages, or <a href="http://www.soft-design.com/softinfo/objects.html">here</a>
+for an introduction to the terms and principles of Object Oriented Programming
<h3>
Design goals of Ficl OO syntax</h3>
Ficl's object extensions provide the traditional OO benefits of associating
@@ -124,29 +122,32 @@
</tr>
</table>
+<br>
<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
<tr>
<td>
<h3>
Ficl Object Model</h3>
-All classes in Ficl are derived from the common base class <tt><a href="#objectgloss">OBJECT</a></tt>.
-All classes are instances of <tt><a href="#glossclass">METACLASS</a></tt>.
-This means that classes are objects, too. <tt>METACLASS</tt> implements
-the methods for messages sent to classes. Class methods create instances
-and subclasses, and give information about the class. Classes have exactly
-three elements:
+All classes in Ficl are derived from the common base class <tt><a href="#objectgloss">OBJECT,</a></tt>
+as shown in the <a href="#figure1">figure</a> below. All classes are instances
+of <tt><a href="#glossclass">METACLASS</a></tt>. This means that classes
+are objects, too. <tt>METACLASS</tt> implements the methods for messages
+sent to classes. Class methods create instances and subclasses, and give
+information about the class. Each class is represented by a data stucture
+of three elements:
<ul>
<li>
-The address ( <tt>.CLASS</tt> ) of a parent class, or zero if it's a base
-class (only <tt>OBJECT</tt> and <tt>METACLASS</tt> have this property)</li>
+The address (named <tt>.CLASS</tt> ) of a parent class, or zero if it's
+a base class (only <tt>OBJECT</tt> and <tt>METACLASS</tt> have this property)</li>
<li>
-The size ( <tt>.SIZE</tt> ) in address units of an instance of the class</li>
+The size (named <tt>.SIZE</tt> ) in address units of an instance of the
+class</li>
<li>
-A wordlist ID ( <tt>.WID</tt> ) for the methods of the class</li>
+A wordlist ID (named <tt>.WID</tt> ) for the methods of the class</li>
</ul>
-In the figure below, <tt>METACLASS</tt> and <tt>OBJECT</tt> are system-supplied
+In the figure below, <tt>METACLASS</tt> and <tt>OBJECT</tt> are real system-supplied
classes. The others are contrived to illustrate the relationships among
derived classes, instances, and the two system base classes. The dashed
line with an arrow at the end indicates that the object/class at the arrow
@@ -160,7 +161,7 @@
</tr>
</table>
-<p><img SRC="ficl_oop.jpg" VSPACE=10 height=442 width=652>
+<p><a NAME="figure1"></a><img SRC="ficl_oop.jpg" VSPACE=10 height=442 width=652>
<br>
<table BORDER=0 CELLSPACING=3 COLS=1 WIDTH="600" >
<tr>
@@ -170,19 +171,32 @@
<h3>
Introduction</h3>
-Ficl objects associate a class with an instance (really the storage for
-one set of instance variables). This is done explicitly, in that any Ficl
-object is represented by the cell pair:
+It's helpful to have some familiarity with Forth and the customary Forth
+stack notation to understand this tutorial. To get started, take a look
+at this <a href="http://www.taygeta.com/forth_intro/stackflo.html">web-based
+Forth tutorial</a>. If you're comfortable with both OO and Forth, you can
+<a href="#ootutoial-finally">jump ahead</a>.
+<p>A Ficl <a href="oo_in_c.html#object-def">object</a> associates a <a href="oo_in_c.html#class-def">class</a>
+with an <a href="oo_in_c.html#instance-def">instance</a> (the storage for
+one set of instance variables). This is done explicitly on Ficl's stack,
+in that any Ficl object is represented by a cell pair:
<blockquote><b><tt>( instance-addr class-addr )</tt></b></blockquote>
-on the stack. Whenever a named Ficl object executes, it leaves this "signature".
-All methods expect a class and instance on the stack when they execute,
-too. In many other OO languages, including C++, instances contain information
-about their classes (a vtable pointer, for example). By making this pairing
-explicit rather than implicit, Ficl can be OO about chunks of data that
-don't realize that they are objects, without sacrificing any robustness
-for native objects. Whenever you create an object in Ficl, you specify
-its class. After that, the object always pushes its class and the address
-of its payload (instance variable space) when invoked by name.
+The instance-addr is the address of the object's storage, and the class-addr
+is the address of its class. Whenever a named Ficl object executes (eg.
+when you type its name and press enter at the Ficl prompt), it leaves this
+"signature". All methods by convention expect a class and instance on the
+stack when they execute, too. In many other OO languages, including C++,
+instances contain information about their classes (a <a href="http://www.mvps.org/vbvision/vtable.htm">vtable</a>
+pointer, for example). By making this pairing explicit rather than implicit,
+Ficl can be OO about chunks of data that don't realize that they are objects,
+without sacrificing any robustness for native objects. That means that
+you can use Ficl to write object wrappers for data structures created in
+C or assembly language, as long as you can determine how they're laid out
+in memory.
+<br>Whenever you create an object in Ficl, you specify its class.
+After that, the object always pushes its class and the address of its <a href="http://www.aware.com/Glossary/main.htm#P">payload
+</a>(instance
+variable space) when invoked by name.
<p>Classes are special kinds of objects that store the methods of their
instances, the size of an instance's payload, and a parent class pointer.
Classes themselves are instances of a special base class called <tt>METACLASS</tt>,
@@ -190,19 +204,20 @@
first, but it means that Ficl has a very simple syntax for constructing
and using objects. Class methods include subclassing (<tt>SUB</tt>), creating
initialized and uninitialized instances (<tt>NEW</tt> and <tt>INSTANCE</tt>),
-and creating reference instances (<tt>REF</tt>). Classes also have methods
-for disassembling their methods (<tt>SEE</tt>), identifying themselves
-(<tt>ID</tt>), and listing their pedigree (<tt>PEDIGREE</tt>). All objects
-inherit methods for initializing instances and arrays of instances, for
-performing array operations, and for getting information about themselves.
+and creating reference instances (<tt>REF</tt>), described later. Classes
+also have methods for disassembling their methods (<tt>SEE</tt>), identifying
+themselves (<tt>ID</tt>), and listing their pedigree (<tt>PEDIGREE</tt>).
+All objects inherit (from <tt>OBJECT</tt>) methods for initializing instances
+and arrays of instances, for performing array operations, and for getting
+information about themselves.
<h3>
Methods and messages</h3>
-Methods are the chunks of code that objects execute in response to messages.
+Methods are the functions that objects execute in response to messages.
A message is a request to an object for a behavior that the object supports.
When it receives a message, the target object looks up a method that performs
-the behavior for its class, and executes it. Any specific message will
-be bound to different methods in different objects, according to class.
-This separation of messages and methods allows objects to behave polymorphically.
+the behavior for its class, and executes it. Any specific message may be
+bound to different methods in different objects, according to class. This
+separation of messages and methods allows objects to behave <a href="http://www.whatis.com/polymorp.htm">polymorphically</a>.
(In Ficl, methods are words defined in the context of a class, and messages
are the names of those words.) Ficl classes associate messages with methods
for their instances (a fancy way of saying that each class owns a wordlist).
@@ -219,17 +234,19 @@
<tr>
<td>
<h3>
-Tutorial (finally!)</h3>
-Since this is a tutorial, I'm assuming you're following along by pasting
-the examples into ficlWin, the Win32 version of Ficl (or some other build
-that includes the OO part of softcore.c). I also assume that you're familiar
-with Forth. If not, please see one of the <a href="#links">references</a>,
-below. Ficl's OOP words are in vocabulary OOP. To put OOP in the search
-order and make it the compilation wordlist from the default search order
-(as set by <tt>ONLY</tt>), type:
+<a NAME="ootutoial-finally"></a>Tutorial (finally!)</h3>
+This is a tutorial. It works best if you follow along by pasting the examples
+into ficlWin, the Win32 version of Ficl included with the release sources
+(or some other build that includes the OO part of softcore.c). If you're
+not familiar with Forth, please see one of these <a href="#links">references</a>.
+Ficl's OOP words are in vocabulary <tt>OOP</tt>. To put <tt>OOP</tt> in
+the search order and make it the compilation wordlist, type:
<blockquote><b><tt>ONLY ( reset to default search order )</tt></b>
<br><b><tt>ALSO OOP DEFINITIONS</tt></b></blockquote>
-To start, we'll work with the two base classes <tt>OBJECT</tt> and <tt>METACLASS</tt>.
+(<b>Note for beginners</b>: to see the effect of the commands above, type
+<tt>ORDER</tt>
+after each line. You can repeat the sequence above if you like.)
+<p>To start, we'll work with the two base classes <tt>OBJECT</tt> and <tt>METACLASS</tt>.
Try this:
<blockquote><b><tt>metaclass --> methods</tt></b></blockquote>
The line above contains three words. The first is the name of a class,
@@ -241,66 +258,123 @@
executes it. In this case, the name of the method is <tt>methods</tt>.
Its job is to list all the methods that a class knows. What you get when
you execute this line is a list of all the class methods Ficl provides.
-<blockquote><b><tt>object --> sub c-foo</tt></b></blockquote>
+<blockquote><b><tt>object --> sub c-led</tt></b></blockquote>
Causes base-class <tt>OBJECT</tt> to derive from itself a new class called
-c-foo. Now we'll add some instance variables and methods to the new class...
-<blockquote><b><tt>cell: m_cell1</tt></b>
-<br><b><tt>4 chars: m_chars</tt></b>
-<br><b><tt>: init ( inst class -- )</tt></b>
-<br><b><tt> locals| class inst |</tt></b>
-<br><b><tt> 0 inst class --> m_cell1 !</tt></b>
-<br><b><tt> inst class --> m_chars 4 0 fill</tt></b>
-<br><b><tt> ." initializing an instance of c_foo at "
-inst x. cr</tt></b>
-<br><b><tt>;</tt></b>
-<br><b><tt>end-class</tt></b></blockquote>
-The first two lines add named instance variables to the class, and create
-a method for each. <i>Untyped</i> instance variable methods (like those
-created by <tt>cell: cells: char:</tt> and <tt>chars:</tt>) just push the
-address of the corresponding instance variable when invoked on an instance
-of the class. It's up to you to remember the size of the instance variable
-and manipulate it with the usual Forth words for fetching and storing (we'll
-see below how to aggregate objects, which do know their size). We've also
-defined a method called <tt>init</tt> that clears the instance variables.
-Notice that the method expects the addresses of the class and instance
-when it's called. It stashes those in local variables to avoid stack tricks,
-and puts them onto the stack whenever it calls a method. In this case,
-we're storing zero to the two member variables.
-<p>The <tt>init</tt> method is special for Ficl objects: whenever you create
-an initialized instance using <b><tt>new</tt></b> or <b><tt>new-array</tt></b>,
+c-led. Now we'll add some instance variables and methods to the new class...
+<br><b>Note</b>: I like to prefix the names of classes with "c-", and the
+names of member variables with a dot, but this is just a convention. If
+you don't like it, you can pick your own.
+<blockquote>
+<pre><b><tt>c-byte obj: .state</tt></b></pre>
+<b><tt>: init { 2this -- }</tt></b>+<br><b><tt> this --> super --> init</tt></b>
+<br><b><tt> ." initializing an instance of " </tt></b>
+<br><b><tt> this --> class --> id type cr ;</tt></b>
+<p><b><tt>: on { led# 2this -- }</tt></b>+<br><b><tt> this --> .state --> get</tt></b>
+<br><b><tt> 1 led# lshift or dup !oreg</tt></b>
+<br><b><tt> this --> .state --> set ;</tt></b>
+<p><b><tt>: off { led# 2this -- }</tt></b>+<br><b><tt> this --> .state --> get</tt></b>
+<br><b><tt> 1 led# lshift invert and dup !oreg</tt></b>
+<br><b><tt> this --> .state --> set ;</tt></b>
+<p><b><tt>end-class</tt></b></blockquote>
+The first line adds an instance variable called <tt>.state</tt> to the
+class. This particular instance variable is an object - it will be an instance
+of c-byte, one of ficl's stock classes (the source for which can be found
+in the distribution in sorftowrds/classes.fr).
+<br>Next we've defined a method called <tt>init</tt>. This line also declares
+a <a href="ficl_loc.html">local variable</a> called <b><tt>this</tt></b>
+(the 2 in front tells Ficl that this is a double-cell local). All methods
+by convention expect the address of the class and instance on top of the
+stack when called. The next three lines define <tt>init</tt>'s behavior.
+It first calls its superclass's version of <tt>init</tt> (which in this
+case is <tt>object => init</tt> - this default implementation clears all
+instance variables). The rest displays some text and causes the instance
+to print its class name (<tt>this --> class --> id</tt>).
+<br>The <b><tt>init</tt></b> method is special for Ficl objects: whenever
+you create an initialized instance using <b><tt>new</tt></b> or <b><tt>new-array</tt></b>,
Ficl calls the class's <tt>init</tt> method for you on that instance. The
-default <tt>init</tt> method supplied by class <tt>object</tt> clears the
-instance, so we didn't really need to override it in this case (see the
-source code in ficl/softwords/oo.fr).
-<br>Now make an instance of the new class:
-<blockquote><b><tt>c-foo --> new foo-instance</tt></b></blockquote>
+default <tt>init</tt> method supplied by <tt>object</tt> clears the instance,
+so we didn't really need to override it in this case (see the source code
+in ficl/softwords/oo.fr).
+<br>The <tt>ON</tt> and <tt>OFF</tt> methods defined above hide the details
+of turning LEDs on and off. The interface to FiclWin's simulated hardware
+is handled by <tt>!OREG</tt>. The class keeps the LED state in a shadow
+variable (<tt>.STATE</tt>) so that <tt>ON</tt> and <tt>OFF</tt> can work
+in terms of LED number rather than a bitmask.
+<p>Now make an instance of the new class:
+<blockquote><b><tt>c-led --> new led</tt></b></blockquote>
And try a few things...
-<blockquote><b><tt>foo-instance --> methods</tt></b>
-<br><b><tt>foo-instance --> pedigree</tt></b></blockquote>
+<blockquote><b><tt>led --> methods</tt></b>
+<br><b><tt>led --> pedigree</tt></b>
+<br><b><tt>1 led --> on</tt></b>
+<br><b><tt>1 led --> off</tt></b></blockquote>
Or you could type this with the same effect:
-<blockquote><b><tt>foo-instance 2dup --> methods --> pedigree</tt></b></blockquote>
-Notice that we've overridden the init method supplied by object, and added
-two more methods for the member variables. If you type WORDS, you'll see
-that these methods are not visible outside the context of the class that
-contains them. The method finder --> uses the class to look up methods.
-You can use this word in a definition, as we did in <tt>init</tt>, and
-it performs late binding, meaning that the mapping from message (method
-name) to method (the code) is deferred until run-time. To see this, you
-can decompile the init method like this:
-<blockquote><b><tt>c-foo --> see init</tt></b>
+<blockquote><b><tt>led 2dup --> methods --> pedigree</tt></b></blockquote>
+Notice (from the output of <tt>methods</tt>) that we've overridden the
+init method supplied by object, and added two more methods for the member
+variables. If you type <tt>WORDS</tt>, you'll see that these methods are
+not visible outside the context of the class that contains them. The method
+finder <b><tt>--></tt></b> uses the class to look up methods. You can use
+this word in a definition, as we did in <tt>init</tt>, and it performs
+late binding, meaning that the mapping from message (method name) to method
+(the code) is deferred until run-time. To see this, you can decompile the
+init method like this:
+<blockquote><b><tt>c-led --> see init</tt></b>
<br>or
-<br><b><tt>foo-instance --> class --> see init</tt></b></blockquote>
-Ficl also provides early binding, but you have to ask for it. Ficl's early
-binding operator pops a class off the stack and compiles the method you've
-named, so that that method executes regardless of the class of object it's
-used on. This can be dangerous, since it defeats the data-to-code matching
-mechanism object oriented languages were created to provide, but it does
-increase run-time speed by binding the method at compile time. In many
-cases, such as the init method, you can be reasonably certain of the class
-of thing you're working on. This is also true when invoking class methods,
-since all classes are instances of <tt>metaclass</tt>. Here's an example
-from the definition of <tt>metaclass</tt> in oo.fr (don't paste this into
-ficlWin - it's already there):
+<br><b><tt>led --> class --> see init</tt></b></blockquote>
+
+<h3>
+Early binding</h3>
+Ficl also provides early binding if you ask for it. Early binding is not
+as safe as late binding, but it produces code that is more compact and
+effiecient because it compiles method addresses rather then their names.
+Here's an example that illustrates a potential problem:
+<blockquote><b><tt>object --> sub c1</tt></b>
+<br><b><tt>: m1 { 2this -- } ." c1's m1" cr ;</tt></b>+<br><b><tt>: m2 { 2this -- } ." Running " this+my=> m1 ; ( early )</tt></b>
+<br><b><tt>: m3 { 2this -- } ." Running " this+--> m1 ; ( late )</tt></b>
+<br><b><tt>end-class</tt></b>
+<p><b><tt>c1 --> sub c2</tt></b>
+<br><b><tt>: m1 { 2this -- } ." c2's m1" cr ;</tt></b>+<br><b><tt>end-class</tt></b>
+<p><b><tt>c2 --> new i2</tt></b>
+<br><b><tt>i2 --> m1 ( runs the m1 defined in c2 )</tt></b>
+<br><b><tt>i2 --> m2 ( is this what you wanted? )</tt></b>
+<br><b><tt>i2 --> m3 { runs the overridden m1)</tt></b></blockquote>+Even though we overrode method m1 in class c2, the definition of m2 with
+early binding forced the use of m1 as defined in c1. If that's what you
+want, great, but more often you'll want the flexibility of overriding parent
+class behaviors appropriately.
+<ol>
+<li>
+<b><tt>my=> </tt></b>binds early to a method in the class being defined,
+as in the example above.</li>
+
+<li>
+<b><tt>my=[ ] </tt></b>binds a sequence of methods in the current class.
+Useful when the class has object members. Lines like <b><tt>this --> state
+--> set</tt></b> in the definition of c-led above can be replaced with
+<b><tt>this
+my=[ state set ]</tt></b> to get early binding.</li>
+
+<li>
+<b><tt>=> </tt>(dangerous)</b> pops a class off the stack and compiles
+the method in that class. Since you have to specify the class explicitly,
+there is a real danger that this will be out of sync with the class you
+really wanted. I recommend the <b><tt>my=</tt></b> operations.</li>
+</ol>
+Early binding can be dangerous because it partially defeats the data-to-code
+matching mechanism object oriented languages were created to provide, but
+it does increase run-time speed by binding the method at compile time.
+In many cases, such as the <tt>init</tt> method, you can be reasonably
+certain of the class of thing you're working on. This is also true when
+invoking class methods, since all classes are instances of <tt>metaclass</tt>.
+Here's an example from the definition of <tt>metaclass</tt> in oo.fr (don't
+paste this into ficlWin - it's already there):
<blockquote><b><tt>: new \ ( class metaclass "name" -- )</tt></b>
<br><b><tt> metaclass => instance --> init ;</tt></b></blockquote>
Try this...
@@ -309,11 +383,19 @@
two strategies. The early bound method is compiled inline, while the late-binding
operator compiles the method name and code to find and execute it in the
context of whatever class is supplied on the stack at run-time.
-<br>Notice that the early-binding operator requires a class at compile
-time. For this reason, classes are <tt>IMMEDIATE</tt>, meaning that they
-push their signature at compile time or run time. I'd recommend that you
-avoid early binding until you're very comfortable with Forth, object-oriented
-programming, and Ficl's OOP syntax.
+<br>Notice that the primitive early-binding operator <tt>=></tt> requires
+a class at compile time. For this reason, classes are <tt>IMMEDIATE</tt>,
+meaning that they push their signature at compile time or run time. I'd
+recommend that you avoid early binding until you're very comfortable with
+Forth, object-oriented programming, and Ficl's OOP syntax.
+<br>
+<h3>
+More About Instance Variables</h3>
+<i>Untyped</i> instance variable methods (created by <tt>cell: cells: char:</tt>
+and <tt>chars:</tt>) just push the address of the corresponding instance
+variable when invoked on an instance of the class. It's up to you to remember
+the size of the instance variable and manipulate it with the usual Forth
+words for fetching and storing.
<p>As advertised earlier, Ficl provides ways to objectify existing data
structures without changing them. Instead, you can create a Ficl class
that models the structure, and instantiate a <b>ref </b>from this class,
@@ -320,21 +402,22 @@
supplying the address of the structure. After that, the <i>ref instance</i>
behaves as a Ficl object, but its instance variables take on the values
in the existing structure. Example (from ficlclass.fr):
-<br>
-<blockquote><b><tt>object subclass c-wordlist \ OO model of FICL_HASH</tt></b>
-<br><b><tt> cell: .parent</tt></b>
-<br><b><tt> cell: .size</tt></b>
-<br><b><tt> cell: .hash</tt></b></blockquote>
-
-<blockquote><b><tt> : push drop >search ;</tt></b>
-<br><b><tt> : pop 2drop previous ;</tt></b>
-<br><b><tt> : set-current drop set-current ;</tt></b>
-<br><b><tt> : words --> push words previous ;</tt></b>
+<blockquote><b><tt>object subclass c-wordlist</tt></b>
+<br><b><tt> c-wordlist ref: .parent</tt></b>
+<br><b><tt> c-ptr obj:
+.name</tt></b>
+<br><b><tt> c-cell obj: .size</tt></b>
+<br><b><tt> c-word ref: .hash</tt></b>
+<p><b><tt> : ?</tt></b>
+<br><b><tt> 2drop ." ficl wordlist
+" cr ;</tt></b>
+<br><b><tt> : push drop >search ;</tt></b>
+<br><b><tt> : pop 2drop previous ;</tt></b>
+<br><b><tt> : set-current drop set-current
+;</tt></b>
+<br><b><tt> : words --> push words
+previous ;</tt></b>
<br><b><tt>end-class</tt></b></blockquote>
-
-<blockquote><b><tt>: named-wid ( "name" -- ) </tt></b>
-<br><b><tt> wordlist postpone c-wordlist
-metaclass => ref ;</tt></b></blockquote>
In this case, <tt>c-wordlist</tt> describes Ficl's wordlist structure;
named-wid creates a wordlist and binds it to a ref instance of <tt>c-wordlist</tt>.
The fancy footwork with <tt>POSTPONE</tt> and early binding is required
@@ -409,6 +492,31 @@
the class on top of the stack. </dd>
<dt>
+<b><tt>c-> ( instance class "method-name" -- xn exc )</tt></b></dt>
+
+<dd>
+Late binding with <tt>CATCH</tt>: looks up and <tt>CATCH</tt>es the given
+method in the context of the class on top of the stack, pushes zero or
+exception code upon return.</dd>
+
+<dt>
+<b><tt>my=> comp: ( "method-name" -- ) exec: ( inst class -- xn )</tt></b></dt>
+
+<dd>
+Early binding: compiles code to execute the method of the class being defined.
+Only visible and valid in the scope of a <tt>--> sub</tt> .. <tt>end-class</tt>
+class definition.</dd>
+
+<dt>
+<b><tt>my=[ comp: ( "obj1 obj2 .. method ]" -- ) exec:( inst class -- xn
+)</tt></b></dt>
+
+<dd>
+Early binding: compiles code to execute a chain of methods of the class
+being defined. Only visible and valid in the scope of a <tt>--> sub</tt>
+.. <tt>end-class</tt> class definition.</dd>
+
+<dt>
<b><tt>=> comp: ( class meta "method-name" -- ) exec:
( inst class -- xn )</tt></b></dt>
@@ -683,8 +791,7 @@
<dt>
<b><tt>new ( class
-metaclass
-"name" -- )</tt></b> </dt>
+metaclass "name" -- )</tt></b> </dt>
<dd>
Create an initialized instance of class, giving it the name specified.
@@ -1075,9 +1182,8 @@
<b><tt>c-4byte</tt></b> </dt>
<dd>
-Primitive class derived from <tt>object</tt>, with a 4-byte (cell) payload.
-Set and get methods perform correct width fetch and store. Methods &
-members:</dd>
+Primitive class derived from <tt>object</tt>, with a 4-byte payload. Set
+and get methods perform correct width fetch and store. Methods & members:</dd>
<dd>
<tt>get ( inst class -- x )</tt></dd>
@@ -1090,6 +1196,24 @@
value</dd>
<dt>
+<b><tt>c-cell</tt></b> </dt>
+
+<dd>
+Primitive class derived from <tt>object</tt>, with a cell payload (equivalent
+to c-4byte in 32 bit implementations, 64 bits wide on Alpha). Set and get
+methods perform correct width fetch and store. Methods & members:</dd>
+
+<dd>
+<tt>get ( inst class -- x )</tt></dd>
+
+<dd>
+<tt>set ( x inst class -- )</tt></dd>
+
+<dd>
+<tt>.payload ( inst class -- addr ) </tt>member holds instance's
+value</dd>
+
+<dt>
<b><tt>c-ptr</tt></b></dt>
<dd>
@@ -1154,6 +1278,24 @@
address</dd>
<dt>
+<b><tt>c-4bytePtr</tt></b></dt>
+
+<dd>
+Pointer to quad-byte derived from c-ptr. Methods & members:</dd>
+
+<dd>
+<tt>@size ( inst class -- size )</tt> Push size of the pointed-to
+thing</dd>
+
+<dd>
+<tt>get ( inst class -- x ) </tt>Fetch the pointer's
+referent 2byte</dd>
+
+<dd>
+<tt>set ( x inst class -- )</tt> Store 2byte x at the pointer
+address</dd>
+
+<dt>
<b><tt>c-cellPtr</tt></b></dt>
<dd>
@@ -1171,7 +1313,7 @@
<tt>set ( x inst class -- )</tt> Storex at the pointer address</dd>
<dt>
-<b><tt>c-string</tt></b> </dt>
+<b><tt>c-string</tt></b> (see string.fr)</dt>
<dd>
Dynamically allocated string similar to MFC CString (Partial list of methods
@@ -1204,6 +1346,12 @@
<dd>
<font face="Courier New"><font size=-1>free ( 2this -- ) Release internal
buffer</font></font></dd>
+
+<dt>
+<b><tt>c-hashstring</tt> </b>(see string.fr)</dt>
+
+<dd>
+Derived from c-string. This class adds a hashcode member variable.</dd>
</dl>
</td>
</tr>
--- a/doc/ficl_rel.html
+++ b/doc/ficl_rel.html
@@ -27,7 +27,7 @@
</tr>
<tr>
-<td><b></b></td>
+<td></td>
</tr>
</table>
@@ -36,9 +36,102 @@
<tr>
<td>
<h2>
-<a NAME="whatsnew"></a>What's new in version 2.04</h2>
+<a NAME="whatsnew"></a>What's new in version 2.05</h2>
<h3>
+General </h3>
+
+<ul>
+<li>
+HTML documentation extensively revised</li>
+
+<li>
+Incorporated Alpha (64 bit) patches from the freeBSD team.</li>
+
+<li>
+Split SEARCH and SEARCH EXT words from words.c to search.c</li>
+
+<li>
+2LOCALS defined in <a href="ficl_loc.html#jhlocal">Johns Hopkins local
+syntax</a> now lose the first '2' in their names.</li>
+</ul>
+
+<h3>
+Bug fixes</h3>
+<a href="http://www.taygeta.com/forth/dpans9.htm#9.6.2.0680">ABORT"</a>
+now works correctly (I promise!)
+<br><a href="http://www.taygeta.com/forth/dpans6.htm#6.2.2125">REFILL</a>
+works better
+<h3>
+New words</h3>
+
+<ul>
+<li>
+ANS CORE EXT words: <a href="http://www.taygeta.com/forth/dpans6.htm#6.2.0415">2r@</a><a href="http://www.taygeta.com/forth/dpans6.htm#6.2.0410">2r></a>
+<a href="http://www.taygeta.com/forth/dpans6.htm#6.2.0340">2>r</a> </li>
+
+<li>
+ANS DOUBLE words: <a href="http://www.taygeta.com/forth/dpans8.htm#8.6.1.0440">2VARIABLE</a></li>
+
+<li>
+ANS ORDER now lists wordlists by name</li>
+
+<li>
+ANS .S now displays all stack entries on one line, like a stack comment</li>
+
+<li>
+<tt>wid-get-name</tt> given a wid, returns the address and
+count of its name. If no name, count is 0</li>
+
+<li>
+<tt>wid-set-name</tt> set optional wid name pointer to the
+\0 terminated string address specified.</li>
+
+<li>
+<tt>ficl-named-wordlist</tt> creates a ficl-wordlist and names it. This
+is now used in <tt>vocabulary</tt> and <tt>ficl-vocabulary</tt> </li>
+
+<li>
+<tt>last-word</tt> returns the xt of the word being defined or most
+recently defined.</li>
+
+<li>
+<tt>q@</tt> and <tt>q!</tt> operate on quadbyte quantities for 64 bit friendliness</li>
+</ul>
+
+<h3>
+New OO stuff</h3>
+
+<ul>
+<li>
+Class methods <tt>ALLOT</tt> and <tt>ALLOT-ARRAY</tt></li>
+
+<li>
+<tt>METHOD</tt> define method names globally</li>
+
+<li>
+<tt>MY=></tt> early bind a method call to "this" class</li>
+
+<li>
+<tt>MY=[ ]</tt> early bind a string of method calls to "this" class and
+obj members</li>
+
+<li>
+<tt>C-></tt> late bind method invocation with CATCH</li>
+
+<li>
+Metaclass method <tt>resume-class</tt> and instance word <tt>suspend-class</tt>
+create mutually referring classes. Example in string.fr</li>
+
+<li>
+Early binding words are now in the instance-vars wordlist, not visible
+unless defining a class.</li>
+</ul>
+
+<h2>
+Version 2.04</h2>
+
+<h3>
ficlwin</h3>
<ul>
@@ -107,7 +200,7 @@
<tr>
<td>
<h2>
-What's new in version 2.03</h2>
+Version 2.03</h2>
This is the first version of Ficl that includes contributed code. Thanks
especially to Daniel Sobral, Michael Gauland for contributions and bug
finding.
@@ -254,7 +347,7 @@
_DEBUG is set. In part, this is because VC++ 5 goes apoplectic when trying
to compile it as a function. See </li>
-<br>comments in vm.c
+<br>comments in vm.c
<li>
EVALUATE respects the count parameter, and also passes exceptional return
conditions back out to the calling instance of ficlExec.</li>
@@ -295,7 +388,7 @@
<tr>
<td>
<h2>
-What's new in version 2.02</h2>
+Version 2.02</h2>
New words
<ul>
<li>
@@ -379,7 +472,7 @@
<tr>
<td>
<h2>
-What's new in version 2.01</h2>
+Version 2.01</h2>
<ul>
<li>
@@ -397,7 +490,7 @@
<tr>
<td>
<h2>
-What's new in version 2.0</h2>
+Version 2.0</h2>
<ul>
<li>
--- a/doc/oo_in_c.html
+++ b/doc/oo_in_c.html
@@ -15,8 +15,8 @@
OO Characteristics</font></font></b>
<h3>
<b><i><font face="Arial">Object</font></i></b></h3>
-<font face="Times New Roman,Times"><b>"A package of information and descriptions
-of its manipulation"</b> [<a href="#robson">Robson</a>]</font>
+<a NAME="object-def"></a><font face="Times New Roman,Times"><b>"A package
+of information and descriptions of its manipulation"</b> [<a href="#robson">Robson</a>]</font>
<p><font face="Times New Roman,Times">Objects separate interface from implementation,
"what" is wanted (on the outside) from "how" it is accomplished (on the
inside). This idea of hiding the data inside a package with a fixed set
@@ -49,15 +49,18 @@
of the mapping from methods to messages.</font>
<h3>
<b><i><font face="Arial">Class</font></i></b></h3>
-<b><font face="Times New Roman,Times">"A description of one or more similar
-objects"</font></b> [<a href="#robson">Robson</a>]
-<p>A specific object described by a particular class is called an instance
-of the class. A class can be thought of as an object whose members are
-the methods of instances of the class, and whose methods provide for creation,
-initialization, and destruction of an instance. All instances of a particular
-class use the same method to respond to a given message. Classes may define
-other members that are shared by all instances of the class. These are
-called class variables. (In C++, these would be static members.)
+<a NAME="class-def"></a><b><font face="Times New Roman,Times">"A description
+of one or more similar objects"</font></b> [<a href="#robson">Robson</a>]
+<p><a NAME="instance-def"></a>A specific object described by a particular
+class is called an <b>instance</b> of the class.
+<br>(Example: Dog is a class; Poodle is a subclass of Dog; FiFi is an object,
+an instance of Poodle).
+<br>A class is a kind of object that describes the behaviors (methods)
+of its instances, and whose methods provide for creation, initialization,
+and destruction of an instance. All instances of a particular class use
+the same method to respond to a given message. Classes may define other
+members that are shared by all instances of the class. These are called
+class variables. (In C++, these would be static members.)
<h3>
<b><i><font face="Arial">Inheritance</font></i></b></h3>
<font face="Times New Roman,Times">A means for creating a new object or
@@ -147,15 +150,15 @@
<b><font face="Arial"><font size=+1>Strategy 1: message maps and aggregation</font></font></b></h3>
<font face="Times New Roman,Times">Class: a struct with a pointer to a
method table (message map). Contructor and destuctor are really initializer
-and destructor, and are invoked manually at beginning and end of lifetime.</font><font face="Times New Roman,Times"></font>
+and destructor, and are invoked manually at beginning and end of lifetime.</font>
<p><font face="Times New Roman,Times">Messages and methods: mapping table
(first cut: use macros like MFC to create a mapping between messages and
methods). Alternative: message map can be built at run-time (hash, tree,
-linked list) � method resolution may be slower.</font><font face="Times New Roman,Times"></font>
+linked list) � method resolution may be slower.</font>
<p><font face="Times New Roman,Times">Inheritance: aggregate the parent
struct (recursively) at the beginning of the derived one, link the child
method table to the parent and search recursively to resolve messages to
-methods</font><font face="Times New Roman,Times"></font>
+methods</font>
<p><font face="Times New Roman,Times">Pros and cons:</font>
<blockquote><font face="Times New Roman,Times">+ flexible and minimal manual
steps required</font>
@@ -165,12 +168,12 @@
penalty</font>
<br><font face="Times New Roman,Times">­ defeats compile time type
checking, may require a single prototype for all methods</font></blockquote>
-<font face="Times New Roman,Times"></font>
+
<p><br><b><font face="Arial"><font size=+1>Strategy 2: manual name mangling</font></font></b>
<br><font face="Times New Roman,Times">This is how the <a href="#samek">Samek</a>
article handles encapsulation</font>
<p><b><font face="Arial"><font size=+1>Strategy 3: preprocessor</font></font></b>
-<br><font face="Times New Roman,Times">This is how C++ started out.</font><font face="Times New Roman,Times"></font>
+<br><font face="Times New Roman,Times">This is how C++ started out.</font>
<p><b><font face="Arial"><font size=+1>References</font></font></b>
<ul>
<li>
--- a/ficl.c
+++ b/ficl.c
@@ -3,7 +3,7 @@
** Forth Inspired Command Language - external interface
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 19 July 1997
-** $Header: /home/grobe0ba/cvs/ficl/Attic/ficl.c,v 1.5 2000/06/09 19:18:18 jsadler Exp $
+** $Id: ficl.c,v 1.6 2000/06/17 14:43:45 jsadler Exp $
*******************************************************************/
/*
** This is an ANS Forth interpreter written in C.
@@ -239,8 +239,8 @@
case 0:
if (pVM->fRestart)
{- pVM->fRestart = 0;
pVM->runningWord->code(pVM);
+ pVM->fRestart = 0;
}
else
{ /* set VM up to interpret text */--- a/ficl.h
+++ b/ficl.h
@@ -3,7 +3,7 @@
** Forth Inspired Command Language
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 19 July 1997
-** $Header: /home/grobe0ba/cvs/ficl/ficl.h,v 1.6 2000/06/09 19:18:15 jsadler Exp $
+** $Id: ficl.h,v 1.7 2000/06/17 14:43:46 jsadler Exp $
*******************************************************************/
/*
** N O T I C E -- DISCLAIMER OF WARRANTY
--- a/math64.c
+++ b/math64.c
@@ -5,7 +5,7 @@
** Created: 25 January 1998
** Rev 2.03: Support for 128 bit DP math. This file really ouught to
** be renamed!
-** $Header: /home/grobe0ba/cvs/ficl/Attic/math64.c,v 1.2 2000/06/09 19:18:18 jsadler Exp $
+** $Id: math64.c,v 1.3 2000/06/17 14:43:47 jsadler Exp $
*******************************************************************/
#include "ficl.h"
--- a/math64.h
+++ b/math64.h
@@ -3,7 +3,7 @@
** Forth Inspired Command Language - 64 bit math support routines
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 25 January 1998
-** $Header: /home/grobe0ba/cvs/ficl/Attic/math64.h,v 1.2 2000/06/09 19:18:20 jsadler Exp $
+** $Id: math64.h,v 1.3 2000/06/17 14:43:47 jsadler Exp $
*******************************************************************/
/*
** N O T I C E -- DISCLAIMER OF WARRANTY
--- a/search.c
+++ b/search.c
@@ -4,7 +4,7 @@
** ANS Forth SEARCH and SEARCH-EXT word-set written in C
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 6 June 2000
-** $Header: /home/grobe0ba/cvs/ficl/search.c,v 1.1 2000/06/09 19:18:17 jsadler Exp $
+** $Id: search.c,v 1.2 2000/06/17 14:43:57 jsadler Exp $
*******************************************************************/
#include <string.h>
--- a/softwords/ficlclass.fr
+++ b/softwords/ficlclass.fr
@@ -4,7 +4,7 @@
\ John Sadler 14 Sep 1998
\
\ ** C - W O R D
-\ Models a ficl word...
+\ Models a FICL_WORD
object subclass c-word
c-word ref: .link
@@ -37,6 +37,7 @@
end-class
\ ** C - W O R D L I S T
+\ Models a FICL_HASH
\ Example of use:
\ get-current c-wordlist --> ref current
\ current --> ?
@@ -44,17 +45,26 @@
\ current --> .hash --> next --> ?
object subclass c-wordlist
- c-wordlist ref: .parent
- c-4byte obj: .size
- c-word ref: .hash
+ c-wordlist ref: .parent
c-ptr obj: .name
+ c-cell obj: .size
+ c-word ref: .hash ( first entry in hash table )
: ?
- 2drop ." ficl wordlist " cr ;
- : push drop >search ;
- : pop 2drop previous ;
- : set-current drop set-current ;
- : words --> push words previous ;
+ --> get-name ." ficl wordlist " type cr ;
+ : push drop >search ;
+ : pop 2drop previous ;
+ : set-current drop set-current ;
+ : get-name drop wid-get-name ;
+ : words { 2this -- }+ this my=[ .size get ] 0 do
+ i this my=[ .hash index ] ( 2list-head )
+ begin
+ 2dup --> get-name type space
+ --> next over
+ 0= until 2drop cr
+ loop
+ ;
end-class
\ : named-wid wordlist postpone c-wordlist metaclass => ref ;
--- a/softwords/ifbrack.fr
+++ b/softwords/ifbrack.fr
@@ -2,7 +2,7 @@
\ ** ANS conditional compile directives [if] [else] [then]
\ ** Requires ficl 2.0 or greater...
-hidden dup >search ficl-set-current
+hide
: ?[if] ( c-addr u -- c-addr u flag )
2dup 2dup
--- a/softwords/oo.fr
+++ b/softwords/oo.fr
@@ -55,25 +55,29 @@
\ parse-method compiles the method name so that it pushes
\ the string base address and count at run-time.
\
+
+hide
+
: parse-method \ name run: ( -- c-addr u )
parse-word
postpone sliteral
; compile-only
-: lookup-method ( class c-addr u -- class xt )
- 2dup
- local u
- local c-addr
- end-locals
- 2 pick cell+ @ ( -- class c-addr u wid )
- search-wordlist ( -- class 0 | xt 1 | xt -1 )
+: lookup-method { class 2name -- class xt }+ name class cell+ @ ( c-addr u wid )
+ search-wordlist ( 0 | xt 1 | xt -1 )
0= if
- c-addr u type ." not found in "
- body> >name type
+ name type ." not found in "
+ class body> >name type
cr abort
- endif
+ endif
+ class swap
;
+: catch-method ( instance class c-addr u -- <method-signature> exc-flag )
+ lookup-method catch
+;
+
: exec-method ( instance class c-addr u -- <method-signature> )
lookup-method execute
;
@@ -82,6 +86,7 @@
parse-word lookup-method
;
+set-current ( stop hiding definitions )
\ Method lookup operator takes a class-addr and instance-addr
\ and executes the method from the class's wordlist if
@@ -95,7 +100,20 @@
endif
; immediate
+\ Method lookup with CATCH in case of exceptions
+: c-> ( instance class -- ?? exc-flag )
+ state @ 0= if
+ find-method-xt catch
+ else
+ parse-method postpone catch-method
+ endif
+; immediate
+\ METHOD makes global words that do method invocations by late binding
+\ in case you prefer this style (no --> in your code)
+: method create does> body> >name lookup-method execute ;
+
+
\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\ ** E A R L Y B I N D I N G
\ Early binding operator compiles code to execute a method
@@ -106,11 +124,28 @@
\ Usage
\ my-class get-wid ( -- wid-of-my-class )
\
+1 ficl-named-wordlist instance-vars
+instance-vars dup >search ficl-set-current
+
: => \ c:( class meta -- ) run: ( -- ??? ) invokes compiled method
drop find-method-xt compile, drop
; immediate compile-only
+: my=> \ c:( -- ) run: ( -- ??? ) late bind compiled method of current-class
+ current-class @ dup postpone =>
+; immediate compile-only
+: my=[ \ same as my=> , but binds a chain of methods
+ current-class @
+ begin
+ parse-word 2dup
+ s" ]" compare while ( class c-addr u )
+ lookup-method nip dup ( xt xt )
+ compile, >body cell+ @ ( class' )
+ repeat 2drop drop
+; immediate compile-only
+
+
\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\ ** I N S T A N C E V A R I A B L E S
\ Instance variables (IV) are represented by words in the class's
@@ -125,9 +160,6 @@
\ prior state. Note that these words are hidden in their own
\ wordlist to prevent accidental use outside a SUB END-CLASS pair.
\
-1 ficl-named-wordlist instance-vars
-instance-vars @ constant instance-vars
-instance-vars dup >search ficl-set-current
: do-instance-var
does> ( instance class addr[offset] -- addr[field] )
nip @ +
@@ -269,8 +301,6 @@
create .size ( class metaclass -- size ) \ return class's payload size
2 cells , do-instance-var
-previous
-
: get-size metaclass => .size @ ;
: get-wid metaclass => .wid @ ;
: get-super metaclass => .super @ ;
@@ -325,6 +355,21 @@
class
;
+\ Create an anonymous initialized instance from the dictionary
+: allot { 2this -- 2instance }+ here ( instance-address )
+ this my=> get-size allot
+ this drop 2dup --> init
+;
+
+\ Create an anonymous array of initialized instances from the dictionary
+: allot-array { nobj 2this -- 2instance }+ here ( instance-address )
+ this my=> get-size nobj * allot
+ this drop 2dup ( 2instance 2instance )
+ nobj -rot --> array-init
+;
+
\ create a proxy object with initialized payload address given
: ref ( instance-addr class metaclass "name" -- )
drop create , ,
@@ -356,6 +401,7 @@
\ and sets the compilation wordlist to be the private wordlist of the
\ new class. The class's wordlist is deliberately NOT in the search order -
\ to prevent methods from getting used with wrong data.
+\ Postcondition: leaves the address of the new class in current-class
: sub ( class metaclass "name" -- old-wid addr[size] size )
wordlist
locals| wid meta parent |
@@ -409,7 +455,7 @@
: see ( class meta -- )
metaclass => get-wid >search see previous ;
-set-current
+previous set-current
\ E N D M E T A C L A S S
\ META is a nickname for the address of METACLASS...
@@ -439,6 +485,7 @@
object drop current-class !
do-do-instance
+instance-vars >search
\ O B J E C T M E T H O D S
\ Convert instance cell-pair to class cell-pair
@@ -522,8 +569,8 @@
inst swap -
class ;
-set-current
+previous set-current
\ E N D O B J E C T
-previous definitions
+only definitions
--- a/softwords/softcore.fr
+++ b/softwords/softcore.fr
@@ -30,19 +30,32 @@
: spaces ( n -- ) 0 ?do space loop ;
: abort"
- postpone if
- postpone ."
- postpone cr
- [ -2 ] literal ,
- postpone throw
- postpone endif
-; immediate
+ state @ if
+ postpone if
+ postpone ."
+ postpone type
+ postpone cr
+ -2
+ postpone literal
+ postpone throw
+ postpone endif
+ else
+ [char] " parse
+ rot if
+ type
+ cr
+ -2 throw
+ else
+ 2drop
+ endif
+ endif
+; immediate
\ ** CORE EXT
.( loading CORE EXT words ) cr
0 constant false
--1 constant true
+false invert constant true
: <> = 0= ;
: 0<> 0= 0= ;
: compile, , ;
@@ -89,8 +102,8 @@
\ gets the name of the word made by create and applies it to the wordlist...
: brand-wordlist ( wid -- ) last-word >name drop wid-set-name ;
-: ficl-named-wordlist ( name -- )
- ficl-wordlist dup create , brand-wordlist ;
+: ficl-named-wordlist \ ( hash-size name -- ) run: ( -- wid )
+ ficl-wordlist dup create , brand-wordlist does> @ ;
: wordlist ( -- )
1 ficl-wordlist ;
@@ -122,7 +135,7 @@
\ previous ( pop HIDDEN off the search order )
1 ficl-named-wordlist hidden
-: hide hidden @ dup >search ficl-set-current ;
+: hide hidden dup >search ficl-set-current ;
\ ALSO dups the search stack...
: also ( -- )
--- a/softwords/string.fr
+++ b/softwords/string.fr
@@ -20,33 +20,33 @@
c-ptr obj: .buf
32 constant min-buf
- : get-count ( 2this -- count ) c-string => .count c-4byte => get ;
- : set-count ( count 2this -- ) c-string => .count c-4byte => set ;
+ : get-count ( 2this -- count ) my=[ .count get ] ;
+ : set-count ( count 2this -- ) my=[ .count set ] ;
: ?empty ( 2this -- flag ) --> get-count 0= ;
- : get-buflen ( 2this -- len ) c-string => .buflen c-4byte => get ;
- : set-buflen ( len 2this -- ) c-string => .buflen c-4byte => set ;
+ : get-buflen ( 2this -- len ) my=[ .buflen get ] ;
+ : set-buflen ( len 2this -- ) my=[ .buflen set ] ;
- : get-buf ( 2this -- ptr ) c-string => .buf c-ptr => get-ptr ;
+ : get-buf ( 2this -- ptr ) my=[ .buf get-ptr ] ;
: set-buf { ptr len 2this -- } - ptr this c-string => .buf c-ptr => set-ptr
- len this c-string => set-buflen
+ ptr this my=[ .buf set-ptr ]
+ len this my=> set-buflen
;
\ set buffer to null and buflen to zero
: clr-buf ( 2this -- )
- 0 0 2over c-string => set-buf
- 0 -rot c-string => set-count
+ 0 0 2over my=> set-buf
+ 0 -rot my=> set-count
;
\ free the buffer if there is one, set buf pointer to null
: free-buf { 2this -- }- this c-string => get-buf
+ this my=> get-buf
?dup if
free
abort" c-string free failed"
- this c-string => clr-buf
+ this my=> clr-buf
endif
;
@@ -58,7 +58,7 @@
endif
\ force buflen to be a positive multiple of min-buf chars
- c-string => min-buf size over / 1+ * chars to size
+ my=> min-buf size over / 1+ * chars to size
\ if buffer is null, allocate one, else resize it
this --> get-buflen 0=
--- a/stack.c
+++ b/stack.c
@@ -3,7 +3,7 @@
** Forth Inspired Command Language
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 16 Oct 1997
-** $Header: /home/grobe0ba/cvs/ficl/stack.c,v 1.2 2000/06/09 19:18:17 jsadler Exp $
+** $Id: stack.c,v 1.3 2000/06/17 14:43:48 jsadler Exp $
*******************************************************************/
#include <stdlib.h>
--- a/sysdep.c
+++ b/sysdep.c
@@ -6,7 +6,7 @@
** Implementations of FICL external interface functions...
**
** (simple) port to Linux, Skip Carter 26 March 1998
-** $Header: /home/grobe0ba/cvs/ficl/Attic/sysdep.c,v 1.3 2000/06/09 19:18:16 jsadler Exp $
+** $Id: sysdep.c,v 1.4 2000/06/17 14:43:49 jsadler Exp $
*******************************************************************/
#include <stdlib.h>
--- a/sysdep.h
+++ b/sysdep.h
@@ -9,7 +9,7 @@
** FICL_ROBUST is enabled. This may require some consideration
** in firmware systems since assert often
** assumes stderr/stdout.
-** $Header: /home/grobe0ba/cvs/ficl/Attic/sysdep.h,v 1.3 2000/06/09 19:18:20 jsadler Exp $
+** $Id: sysdep.h,v 1.4 2000/06/17 14:43:49 jsadler Exp $
*******************************************************************/
/*
** N O T I C E -- DISCLAIMER OF WARRANTY
--- a/testmain.c
+++ b/testmain.c
@@ -1,6 +1,6 @@
/*
** stub main for testing FICL under Win32
-** $Header: /home/grobe0ba/cvs/ficl/Attic/testmain.c,v 1.5 2000/06/09 19:18:16 jsadler Exp $
+** $Id: testmain.c,v 1.6 2000/06/17 14:43:50 jsadler Exp $
*/
#include <stdlib.h>
--- a/vm.c
+++ b/vm.c
@@ -3,7 +3,7 @@
** Forth Inspired Command Language - virtual machine methods
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 19 July 1997
-** $Header: /home/grobe0ba/cvs/ficl/vm.c,v 1.5 2000/06/09 19:18:19 jsadler Exp $
+** $Id: vm.c,v 1.6 2000/06/17 14:43:50 jsadler Exp $
*******************************************************************/
/*
** This file implements the virtual machine of FICL. Each virtual
--- a/words.c
+++ b/words.c
@@ -4,7 +4,7 @@
** ANS Forth CORE word-set written in C
** Author: John Sadler (john_sadler@alum.mit.edu)
** Created: 19 July 1997
-** $Header: /home/grobe0ba/cvs/ficl/Attic/words.c,v 1.6 2000/06/09 19:18:11 jsadler Exp $
+** $Id: words.c,v 1.7 2000/06/17 14:43:51 jsadler Exp $
*******************************************************************/
#include <stdlib.h>
@@ -675,13 +675,14 @@
vmCheckStack(pVM, 0, 0);
if (d == 0)
- vmTextOut(pVM, "(Stack Empty)", 1);
+ vmTextOut(pVM, "(Stack Empty) ", 0);
else
{- pCell = pVM->pStack->sp;
+ pCell = pVM->pStack->base;
for (i = 0; i < d; i++)
{- vmTextOut(pVM, ltoa((*--pCell).i, pVM->pad, pVM->base), 1);
+ vmTextOut(pVM, ltoa((*pCell++).i, pVM->pad, pVM->base), 0);
+ vmTextOut(pVM, " ", 0);
}
}
}
@@ -1911,7 +1912,17 @@
}
+static void twoVariable(FICL_VM *pVM)
+{+ FICL_DICT *dp = ficlGetDict();
+ STRINGINFO si = vmGetWord(pVM);
+ dictAppendWord2(dp, si, variableParen, FW_DEFAULT);
+ dictAllotCells(dp, 2);
+ return;
+}
+
+
/**************************************************************************
b a s e & f r i e n d s
**
@@ -1949,7 +1960,7 @@
FICL_DICT *dp = ficlGetDict();
FICL_INT i = stackPopINT(pVM->pStack);
#if FICL_ROBUST
- dictCheck(dp, pVM, i);
+ dictCheck(dp, pVM, (i+sizeof(CELL)-1)/sizeof(CELL));
#endif
dictAllot(dp, i);
return;
@@ -3886,6 +3897,24 @@
/**************************************************************************
+ s o u r c e - i d
+** CORE EXT, FILE ( -- 0 | -1 | fileid )
+** Identifies the input source as follows:
+**
+** SOURCE-ID Input source
+** --------- ------------
+** fileid Text file fileid
+** -1 String (via EVALUATE)
+** 0 User input device
+**************************************************************************/
+static void sourceid(FICL_VM *pVM)
+{+ stackPushINT(pVM->pStack, pVM->sourceID.i);
+ return;
+}
+
+
+/**************************************************************************
r e f i l l
** CORE EXT ( -- flag )
** Attempt to fill the input buffer from the input source, returning a true
@@ -3901,9 +3930,10 @@
static void refill(FICL_VM *pVM)
{FICL_INT ret = (pVM->sourceID.i == -1) ? FICL_FALSE : FICL_TRUE;
+ if (ret && (pVM->fRestart == 0))
+ vmThrow(pVM, VM_RESTART);
+
stackPushINT(pVM->pStack, ret);
- if (ret)
- vmThrow(pVM, VM_OUTOFTEXT);
return;
}
@@ -4326,6 +4356,7 @@
dictAppendWord(dp, "pick", pick, FW_DEFAULT);
dictAppendWord(dp, "roll", roll, FW_DEFAULT);
dictAppendWord(dp, "refill", refill, FW_DEFAULT);
+ dictAppendWord(dp, "source-id", sourceid, FW_DEFAULT);
dictAppendWord(dp, "to", toValue, FW_IMMEDIATE);
dictAppendWord(dp, "value", constant, FW_DEFAULT);
dictAppendWord(dp, "\\", commentLine, FW_IMMEDIATE);
@@ -4354,6 +4385,7 @@
*/
dictAppendWord(dp, "2constant", twoConstant, FW_IMMEDIATE);
dictAppendWord(dp, "2literal", twoLiteralIm, FW_IMMEDIATE);
+ dictAppendWord(dp, "2variable", twoVariable, FW_IMMEDIATE);
dictAppendWord(dp, "dnegate", dnegate, FW_DEFAULT);