--- gforth/doc/gforth.ds 1998/11/22 21:23:26 1.19
+++ gforth/doc/gforth.ds 1998/12/13 23:30:00 1.20
@@ -4311,6 +4311,7 @@ of Bernd Paysan in comp.arch.
@menu
* Mini-OOF Usage::
* Mini-OOF Example::
+* Mini-OOF Implementation::
@end menu
@c -------------------------------------------------------------
@@ -4356,7 +4357,7 @@ doc-object
Is the base class of all objects
@c -------------------------------------------------------------
-@node Mini-OOF Example, , Mini-OOF Usage, Mini-OOF
+@node Mini-OOF Example, Mini-OOF Implementation, Mini-OOF Usage, Mini-OOF
@subsubsection Mini-OOF Example
@cindex mini-oof example
@@ -4419,6 +4420,140 @@ with
100 100 my-circle draw
@end example
+@node Mini-OOF Implementation, , Mini-OOF Example, Mini-OOF
+@subsubsection Mini-OOF Implementation
+
+Object oriented system with late binding typically use a
+"vtable"-approach: the first variable in each object is a pointer to a
+table, which contains the methods as function pointers. This vtable
+may contain some other informations, too.
+
+So first, let's declare methods:
+
+@example
+: method ( m v -- m' v ) Create over , swap cell+ swap
+ DOES> ( ... o -- ... ) @ over @ + @ execute ;
+@end example
+
+During method declaration, the number of methods and instance
+variables is on the stack (in address units). @code{method} creates
+one method and increments the method number. To execute a method, it
+takes the object, fetches the vtable pointer, adds the offset, and
+executes the xt stored there. Each method takes the object it is
+invoked from as top of stack parameter. The method itself should
+consume that object.
+
+Now, we also have to declare instance variables
+
+@example
+: var ( m v size -- m v' ) Create over , +
+ DOES> ( o -- addr ) @ + ;
+@end example
+
+Same as above, a word is created with the current offset. Instance
+variables can have different sizes (cells, floats, doubles, chars), so
+all we do is take the size and add it to the offset. If your machine
+has alignment restrictions, put the proper @code{aligned} or
+@code{faligned} before the variable, it will adjust the variable
+offset. That's why it is on the top of stack.
+
+We need a starting point (the empty object) and some syntactic sugar:
+
+@example
+Create object 1 cells , 2 cells ,
+: class ( class -- class methods vars ) dup 2@ ;
+@end example
+
+Now, for inheritance, the vtable of the parent object has to be
+copied, when a new, derived class is declared. This gives all the
+methods of the parent class, which can be overridden, though.
+
+@example
+: end-class ( class methods vars -- )
+ Create here >r , dup , 2 cells ?DO ['] noop , 1 cells +LOOP
+ cell+ dup cell+ r> rot @ 2 cells /string move ;
+@end example
+
+The first line creates the vtable, initialized with
+@code{noop}s. The second line is the inheritance mechanism, it
+copies the xts from the parent vtable.
+
+We still have no way to define new methods, let's do that now:
+
+@example
+: defines ( xt class -- ) ' >body @ + ! ;
+@end example
+
+To allocate a new object, we need a word, too:
+
+@example
+: new ( class -- o ) here over @ allot swap over ! ;
+@end example
+
+And sometimes derived classes want to access the method of the
+parent object. There are two ways to achieve this with this OOF:
+first, you could use named words, and second, you could look up the
+vtable of the parent object.
+
+@example
+: :: ( class "name" -- ) ' >body @ + @ compile, ;
+@end example
+
+
An Example
+
+Nothing can be more confusing than a good example, so here is
+one. First let's declare a text object (further called
+@code{button}), that stores text and position:
+
+@example
+object class
+ cell var text
+ cell var len
+ cell var x
+ cell var y
+ method init
+ method draw
+end-class button
+@end example
+
+Now, implement the two methods, @code{draw} and @code{init}:
+
+@example
+:noname ( o -- ) >r
+ r@ x @ r@ y @ at-xy r@ text @ r> len @ type ;
+ button defines draw
+:noname ( addr u o -- ) >r
+ 0 r@ x ! 0 r@ y ! r@ len ! r> text ! ;
+ button defines init
+@end example
+
+For inheritance, we define a class @code{bold-button}, with no
+new data and no new methods.
+
+@example
+button class
+end-class bold-button
+
+: bold 27 emit ." [1m" ;
+: normal 27 emit ." [0m" ;
+
+:noname bold [ button :: draw ] normal ; bold-button defines draw
+@end example
+
+And finally, some code to demonstrate how to create objects and
+apply methods:
+
+@example
+button new Constant foo
+s" thin foo" foo init
+page
+foo draw
+bold-button new Constant bar
+s" fat bar" bar init
+1 bar y !
+bar draw
+@end example
+
@c -------------------------------------------------------------
@node Tokens for Words, Wordlists, Object-oriented Forth, Words
@section Tokens for Words
@@ -4501,6 +4636,38 @@ doc-name>string
@node Files, Including Files, Wordlists, Words
@section Files
+This chapter describes how to operate on files from Forth.
+
+Files have the following types for opening and creating:
+
+doc-r/o
+doc-r/w
+doc-w/o
+doc-bin
+
+Files are opened/created by name and type, and return a file
+identifier.
+
+doc-open-file
+doc-create-file
+
+This identifier is used for all other file commands.
+
+doc-close-file
+doc-delete-file
+doc-rename-file
+doc-read-file
+doc-read-line
+doc-write-file
+doc-emit-file
+doc-flush-file
+
+doc-file-status
+doc-file-position
+doc-reposition-file
+doc-file-size
+doc-resize-file
+
@node Including Files, Blocks, Files, Words
@section Including Files
@cindex including files
@@ -4598,7 +4765,6 @@ use this Gforth feature in your applicat
doc-open-fpath-file
-
@node General Search Paths, , Changing the Search Path, Including Files
@subsection General Search Paths
@cindex search paths for user applications
@@ -4627,6 +4793,34 @@ doc-open-path-file
@node Blocks, Other I/O, Including Files, Words
@section Blocks
+This chapter describes how to use block files within Gforth.
+
+Block files are traditionally means of data and source storage in
+Forth. They have been very important in resource-starved computers
+without OS in the past. Gforth doesn't encourage to use blocks as
+source, and provides blocks only for backward compatibility. The ANS
+standard requires blocks to be available when files are.
+
+doc-open-blocks
+doc-use
+doc-get-block-fid
+doc-block-position
+doc-update
+doc-save-buffer
+doc-empty-buffer
+doc-flush
+doc-get-buffer
+doc-block
+doc-buffer
+doc-updated?
+doc-list
+doc-load
+doc-thru
+doc-+load
+doc-+thru
+doc---block--->
+doc-block-included
+
@node Other I/O, Programming Tools, Blocks, Words
@section Other I/O
@@ -7327,16 +7521,16 @@ through my mailbox to extract your names
Gforth also owes a lot to the authors of the tools we used (GCC, CVS,
and autoconf, among others), and to the creators of the Internet: Gforth
was developed across the Internet, and its authors have not met
-physically yet.
+physically for the first 4 years of development.
@section Pedigree
@cindex Pedigree of Gforth
-Gforth descends from BigForth (1993) and fig-Forth. Gforth and PFE (by
+Gforth descends from bigFORTH (1993) and fig-Forth. Gforth and PFE (by
Dirk Zoller) will cross-fertilize each other. Of course, a significant
part of the design of Gforth was prescribed by ANS Forth.
-Bernd Paysan wrote BigForth, a descendent from TurboForth, an unreleased
+Bernd Paysan wrote bigFORTH, a descendent from TurboForth, an unreleased
32 bit native code version of VolksForth for the Atari ST, written
mostly by Dietrich Weineck.