gforth/doc/gforth.ds - diff

Return to gforth.ds CVS log

Up to [gforth] / gforth / doc

Diff for /gforth/doc/gforth.ds between versions 1.74 and 1.75

version 1.74, 2000/08/16 09:26:53	version 1.75, 2000/08/17 12:46:58
Line 333 The Text Interpreter	Line 333 The Text Interpreter

Word Lists	Word Lists

* Why use word lists?::
* Word list examples::
* Vocabularies::	* Vocabularies::
	* Why use word lists?::
	* Word list example::

Files	Files

Line 345 Files	Line 345 Files

Search Paths	Search Paths

* Forth Search Paths::	* Source Search Paths::
* General Search Paths::	* General Search Paths::

Other I/O	Other I/O
Line 7749 doc-context	Line 7749 doc-context


@menu	@menu
* Why use word lists?::
* Word list examples::
* Vocabularies::	* Vocabularies::
	* Why use word lists?::
	* Word list example::
@end menu	@end menu

@node Why use word lists?, Word list examples, Word Lists, Word Lists	@node Vocabularies, Why use word lists?, Word Lists, Word Lists
	@subsection Vocabularies
	@cindex Vocabularies, detailed explanation

	Here is an example of creating and using a new wordlist using ANS
	Forth words:

	@example
	wordlist constant my-new-words-wordlist
	: my-new-words get-order nip my-new-words-wordlist swap set-order ;

	\ add it to the search order
	also my-new-words

	\ alternatively, add it to the search order and make it
	\ the compilation word list
	also my-new-words definitions
	\ type "order" to see the problem
	@end example

	The problem with this example is that @code{order} has no way to
	associate the name @code{my-new-words} with the wid of the word list (in
	Gforth, @code{order} and @code{vocs} will display @code{???} for a wid
	that has no associated name). There is no Standard way of associating a
	name with a wid.

	In Gforth, this example can be re-coded using @code{vocabulary}, which
	associates a name with a wid:

	@example
	vocabulary my-new-words

	\ add it to the search order
	also my-new-words

	\ alternatively, add it to the search order and make it
	\ the compilation word list
	my-new-words definitions
	\ type "order" to see that the problem is solved
	@end example


	@node Why use word lists?, Word list example, Vocabularies, Word Lists
@subsection Why use word lists?	@subsection Why use word lists?
@cindex word lists - why use them?	@cindex word lists - why use them?

Line 7792 separate word list which is used when a	Line 7834 separate word list which is used when a
To organize the words of an application or library into a user-visible	To organize the words of an application or library into a user-visible
set (in @code{forth-wordlist} or some other common wordlist) and a set	set (in @code{forth-wordlist} or some other common wordlist) and a set
of helper words used just for the implementation (hidden in a separate	of helper words used just for the implementation (hidden in a separate
wordlist). This keeps the @code{words} output cleaner, provides a	wordlist). This keeps @code{words}' output smaller, separates
separation of implementation and interface, and reduces the chance of	implementation and interface, and reduces the chance of name conflicts
name conflicts within the common wordlist.	within the common wordlist.

@item	@item
To prevent a name-space clash between multiple definitions with the same	To prevent a name-space clash between multiple definitions with the same
Line 7819 Name conflicts worked around with wordli	Line 7861 Name conflicts worked around with wordli
have to arrange the search order carefully to get the desired results;	have to arrange the search order carefully to get the desired results;
if you forget to do that, you get hard-to-find errors (as in any case	if you forget to do that, you get hard-to-find errors (as in any case
where you read the code differently from the compiler; @code{see} can	where you read the code differently from the compiler; @code{see} can
help in such cases). Using unique names is a better approach to avoid	help seeing which of several possible words the name resolves to in such
name conflicts.	cases). @code{See} displays just the name of the words, not what
	wordlist they belong to, so it might be misleading. Using unique names
	is a better approach to avoid name conflicts.

@item	@item
You have to explicitly undo any changes to the search order. In many	You have to explicitly undo any changes to the search order. In many
Line 7830 future.	Line 7874 future.
@end itemize	@end itemize


@node Word list examples, Vocabularies, Why use word lists?, Word Lists	@node Word list example, , Why use word lists?, Word Lists
@subsection Word list examples	@subsection Word list example
@cindex word lists - examples	@cindex word lists - example

The following example is from the	The following example is from the
@uref{http://www.complang.tuwien.ac.at/forth/garbage-collection.zip,	@uref{http://www.complang.tuwien.ac.at/forth/garbage-collection.zip,
Line 7849 vocabulary garbage-collector also garbag	Line 7893 vocabulary garbage-collector also garbag
previous \ restore original search order (helper words become invisible)	previous \ restore original search order (helper words become invisible)
@end example	@end example

@node Vocabularies, , Word list examples, Word Lists
@subsection Vocabularies
@cindex Vocabularies, detailed explanation

Here is an example of creating and using a new wordlist using ANS
Forth words:

@example
wordlist constant my-new-words-wordlist
: my-new-words get-order nip my-new-words-wordlist swap set-order ;

\ add it to the search order
also my-new-words

\ alternatively, add it to the search order and make it
\ the compilation word list
also my-new-words definitions
\ type "order" to see the problem
@end example

The problem with this example is that @code{order} has no way to
associate the name @code{my-new-words} with the wid of the word list (in
Gforth, @code{order} and @code{vocs} will display @code{???} for a wid
that has no associated name). There is no Standard way of associating a
name with a wid.

In Gforth, this example can be re-coded using @code{vocabulary}, which
associates a name with a wid:

@example
vocabulary my-new-words

\ add it to the search order
also my-new-words

\ alternatively, add it to the search order and make it
\ the compilation word list
my-new-words definitions
\ type "order" to see that the problem is solved
@end example

@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Environmental Queries, Files, Word Lists, Words	@node Environmental Queries, Files, Word Lists, Words
@section Environmental Queries	@section Environmental Queries
Line 7933 Here are some examples of using environm	Line 7936 Here are some examples of using environm
s" address-unit-bits" environment? 0=	s" address-unit-bits" environment? 0=
[IF]	[IF]
cr .( environmental attribute address-units-bits unknown... ) cr	cr .( environmental attribute address-units-bits unknown... ) cr
	[ELSE]
	drop \ ensure balanced stack effect
[THEN]	[THEN]

s" block" environment? [IF] DROP include block.fs [THEN]	\ this might occur in the prelude of a standard program that uses THROW
	s" exception" environment? [IF]
s" gforth" environment? [IF] 2DROP include compat/vocabulary.fs [THEN]	0= [IF]
	: throw abort" exception thrown" ;
	[THEN]
	[ELSE] \ we don't know, so make sure
	: throw abort" exception thrown" ;
	[THEN]

s" gforth" environment? [IF] .( Gforth version ) TYPE	s" gforth" environment? [IF] .( Gforth version ) TYPE
[ELSE] .( Not Gforth..) [THEN]	[ELSE] .( Not Gforth..) [THEN]
@end example

	\ a program using v*
	s" gforth" environment? [IF]
	s" 0.5.0" compare 0< [IF] \ v* is a primitive since 0.5.0
	: v* ( f_addr1 nstride1 f_addr2 nstride2 ucount -- r )
	>r swap 2swap swap 0e r> 0 ?DO
	dup f@ over + 2swap dup f@ f* f+ over + 2swap
	LOOP
	2drop 2drop ;
	[THEN]
	[ELSE] \
	: v* ( f_addr1 nstride1 f_addr2 nstride2 ucount -- r )
	...
	[THEN]
	@end example

Here is an example of adding a definition to the environment word list:	Here is an example of adding a definition to the environment word list:

Line 7956 set-current	Line 7979 set-current
You can see what definitions are in the environment word list like this:	You can see what definitions are in the environment word list like this:

@example	@example
get-order 1+ environment-wordlist swap set-order words previous	environment-wordlist push-order words previous
@end example	@end example


Line 7977 Files that are processed by the Text Int	Line 8000 Files that are processed by the Text Int
Files that are processed by some other program (@dfn{general files}).	Files that are processed by some other program (@dfn{general files}).
@end itemize	@end itemize

doc-loadfilename
doc-sourcefilename
doc-sourceline#

@menu	@menu
* Forth source files::	* Forth source files::
* General files::	* General files::
* Search Paths::	* Search Paths::
@end menu	@end menu


@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Forth source files, General files, Files, Files	@node Forth source files, General files, Files, Files
@subsection Forth source files	@subsection Forth source files
Line 8002 include mysource.fs	Line 8020 include mysource.fs
s" mysource.fs" included	s" mysource.fs" included
@end example	@end example

Sometimes you want to include a file only if it is not included already	You usually want to include a file only if it is not included already
(by, say, another source file). In that case, you can use one of these	(by, say, another source file). In that case, you can use one of these
three formats:	three formats:

Line 8019 does not change the stack. Source files	Line 8037 does not change the stack. Source files
@code{required} and friends without complications. For example:	@code{required} and friends without complications. For example:

@example	@example
1 require foo.fs drop	1024 require foo.fs drop
@end example	@end example

	Here you want to pass the argument 1024 (e.g., a buffer size) to
	@file{foo.fs}. Interpreting @file{foo.fs} has the stack effect ( n -- n
	), which allows its use with @code{require}. Of course with such
	parameters to required files, you have to ensure that the first
	@code{require} fits for all uses (i.e., @code{require} it early in the
	master load file).

doc-include-file	doc-include-file
doc-included	doc-included
Line 8030 doc-include	Line 8054 doc-include
doc-required	doc-required
doc-require	doc-require
doc-needs	doc-needs
doc-init-included-files	@c doc-init-included-files @c internal
	@c doc-loadfilename @c internal word
	doc-sourcefilename
	doc-sourceline#

A definition in ANS Forth for @code{required} is provided in	A definition in ANS Forth for @code{required} is provided in
@file{compat/required.fs}.	@file{compat/required.fs}.
Line 8042 A definition in ANS Forth for @code{requ	Line 8068 A definition in ANS Forth for @code{requ
@cindex general files	@cindex general files
@cindex file-handling	@cindex file-handling

Files are opened/created by name and type. The following types are	Files are opened/created by name and type. The following file access
recognised:	methods (FAMs) are recognised:


	@cindex fam (file access method)
doc-r/o	doc-r/o
doc-r/w	doc-r/w
doc-w/o	doc-w/o
Line 8092 If you specify an absolute filename (i.e	Line 8118 If you specify an absolute filename (i.e
@samp{C:...})) for @code{included} and friends, that file is included	@samp{C:...})) for @code{included} and friends, that file is included
just as you would expect.	just as you would expect.

For relative filenames, Gforth uses a search path similar to Forth's	If the filename starts with @file{./}, this refers to the directory that
search order (@pxref{Word Lists}). It tries to find the given filename	the present file was @code{included} from. This allows files to include
in the directories present in the path, and includes the first one it	other files relative to their own position (irrespective of the current
finds. There are separate search paths for Forth source files and	working directory or the absolute position). This feature is essential
general files.	for libraries consisting of several files, where a file may include
	other files from the library. It corresponds to @code{#include "..."}
If the search path contains the directory @file{.} (as it should), this	in C. If the current input source is not a file, @file{.} refers to the
refers to the directory that the present file was @code{included}	directory of the innermost file being included, or, if there is no file
from. This allows files to include other files relative to their own	being included, to the current working directory.
position (irrespective of the current working directory or the absolute
position). This feature is essential for libraries consisting of	For relative filenames (not starting with @file{./}), Gforth uses a
several files, where a file may include other files from the library.	search path similar to Forth's search order (@pxref{Word Lists}). It
It corresponds to @code{#include "..."} in C. If the current input	tries to find the given filename in the directories present in the path,
source is not a file, @file{.} refers to the directory of the innermost	and includes the first one it finds. There are separate search paths for
file being included, or, if there is no file being included, to the	Forth source files and general files. If the search path contains the
current working directory.	directory @file{.}, this refers to the directory of the current file, or
	the working directory, as if the file had been specified with @file{./}.

Use @file{~+} to refer to the current working directory (as in the	Use @file{~+} to refer to the current working directory (as in the
@code{bash}).	@code{bash}).

If the filename starts with @file{./}, the search path is not searched	@c anton: fold the following subsubsections into this subsection?
(just as with absolute filenames), and the @file{.} has the same meaning
as described above.

@menu	@menu
* Forth Search Paths::	* Source Search Paths::
* General Search Paths::	* General Search Paths::
@end menu	@end menu

@c ---------------------------------------------------------	@c ---------------------------------------------------------
@node Forth Search Paths, General Search Paths, Search Paths, Search Paths	@node Source Search Paths, General Search Paths, Search Paths, Search Paths
@subsubsection Forth Search Paths	@subsubsection Source Search Paths
@cindex search path control - Forth	@cindex search path control, source files

The search path is initialized when you start Gforth (@pxref{Invoking	The search path is initialized when you start Gforth (@pxref{Invoking
Gforth}). You can display it and change it using these words:	Gforth}). You can display it and change it using @code{fpath} in
	combination with the general path handling words.

doc-.fpath
doc-fpath+
doc-fpath=
doc-open-fpath-file

	doc-fpath
	@c the functionality of the following words is easily available through
	@c fpath and the general path words. The may go away.
	@c doc-.fpath
	@c doc-fpath+
	@c doc-fpath=
	@c doc-open-fpath-file

@noindent	@noindent
Here is an example of using @code{fpath} and @code{require}:	Here is an example of using @code{fpath} and @code{require}:

@example	@example
fpath= /usr/lib/forth/\|./	fpath path= /usr/lib/forth/\|./
require timer.fs	require timer.fs
@end example	@end example


@c ---------------------------------------------------------	@c ---------------------------------------------------------
@node General Search Paths, , Forth Search Paths, Search Paths	@node General Search Paths, , Source Search Paths, Search Paths
@subsubsection General Search Paths	@subsubsection General Search Paths
@cindex search path control - for user applications	@cindex search path control, source files

Your application may need to search files in several directories, like	Your application may need to search files in several directories, like
@code{included} does. To facilitate this, Gforth allows you to define	@code{included} does. To facilitate this, Gforth allows you to define
and use your own search paths, by providing generic equivalents of the	and use your own search paths, by providing generic equivalents of the
Forth search path words:	Forth search path words:

	doc-open-path-file
	doc-path-allot
	doc-clear-path
	doc-also-path
doc-.path	doc-.path
doc-path+	doc-path+
doc-path=	doc-path=
doc-open-path-file

	@c anton: better define a word for it, say "path-allot ( ucount -- path-addr )

Here's an example of creating a search path:	Here's an example of creating an empty search path:
	@c
@example	@example
\ Make a buffer for the path:	create mypath 500 path-allot \ maximum length 500 chars (is checked)
create mypath 100 chars , \ maximum length (is checked)
0 , \ real len
100 chars allot \ space for path
@end example	@end example

@c -------------------------------------------------------------	@c -------------------------------------------------------------
Line 8206 bytes, corresponding to the number of bl	Line 8234 bytes, corresponding to the number of bl
mechanism that Gforth uses.	mechanism that Gforth uses.

@cindex @file{blocks.fb}	@cindex @file{blocks.fb}
Only 1 blocks file can be open at a time. If you use block words without	Only one blocks file can be open at a time. If you use block words without
having specified a blocks file, Gforth defaults to the blocks file	having specified a blocks file, Gforth defaults to the blocks file
@file{blocks.fb}. Gforth uses the Forth search path when attempting to	@file{blocks.fb}. Gforth uses the Forth search path when attempting to
locate a blocks file (@pxref{Forth Search Paths}).	locate a blocks file (@pxref{Source Search Paths}).

@cindex block buffers	@cindex block buffers
When you read and write blocks under program control, Gforth uses a	When you read and write blocks under program control, Gforth uses a
number of @dfn{block buffers} as intermediate storage. These buffers are	number of @dfn{block buffers} as intermediate storage. These buffers are
not used when you use @code{load} to interpret the contents of a block.	not used when you use @code{load} to interpret the contents of a block.

The behaviour of the block buffers is directly analagous to that of a	The behaviour of the block buffers is analagous to that of a cache.
cache. Each block buffer has three states:	Each block buffer has three states:

@itemize @bullet	@itemize @bullet
@item	@item
Line 8244 available. Otherwise, @code{buffer} will	Line 8272 available. Otherwise, @code{buffer} will
block buffer for the block.}.	block buffer for the block.}.

Once a block has been assigned to a block buffer using @code{block} or	Once a block has been assigned to a block buffer using @code{block} or
@code{buffer}, that block buffer becomes the @i{current block buffer}	@code{buffer}, that block buffer becomes the @i{current block
and its state changes to @i{assigned-clean}. Data may only be	buffer}. Data may only be manipulated (read or written) within the
manipulated (read or written) within the current block buffer.	current block buffer.

When the contents of the current block buffer has been modified it is	When the contents of the current block buffer has been modified it is
necessary, @emph{before calling @code{block} or @code{buffer} again}, to	necessary, @emph{before calling @code{block} or @code{buffer} again}, to
either abandon the changes (by doing nothing) or commit the changes,	either abandon the changes (by doing nothing) or mark the block as
using @code{update}. Using @code{update} does not change the blocks	changed (assigned-dirty), using @code{update}. Using @code{update} does
file; it simply changes a block buffer's state to @i{assigned-dirty}.	not change the blocks file; it simply changes a block buffer's state to
	@i{assigned-dirty}. The block will be written implicitly when it's
The word @code{flush} causes all @i{assigned-dirty} blocks to be	buffer is needed for another block, or explicitly by @code{flush} or
written back to the blocks file on disk. Leaving Gforth using @code{bye}	@code{save-buffers}.
also causes a @code{flush} to be performed.
	word @code{Flush} writes all @i{assigned-dirty} blocks back to the
	blocks file on disk. Leaving Gforth with @code{bye} also performs a
	@code{flush}.

In Gforth, @code{block} and @code{buffer} use a @i{direct-mapped}	In Gforth, @code{block} and @code{buffer} use a @i{direct-mapped}
algorithm to assign a block buffer to a block. That means that any	algorithm to assign a block buffer to a block. That means that any
Line 8316 integrated into a Forth programming envi	Line 8347 integrated into a Forth programming envi

doc-open-blocks	doc-open-blocks
doc-use	doc-use
	doc-block-offset
doc-get-block-fid	doc-get-block-fid
doc-block-position	doc-block-position

doc-scr
doc-list	doc-list
	doc-scr

doc---gforthman-block	doc---gforthman-block
doc-buffer	doc-buffer

	doc-empty-buffers
	doc-empty-buffer
doc-update	doc-update
doc-updated?	doc-updated?
doc-save-buffers	doc-save-buffers
doc-empty-buffers	doc-save-buffer
doc-empty-buffer
doc-flush	doc-flush

doc-load	doc-load
Line 8405 extraction process. The completed string	Line 8438 extraction process. The completed string
and length and can be manipulated (@code{TYPE}ed, copied, modified)	and length and can be manipulated (@code{TYPE}ed, copied, modified)
under program control.	under program control.

All of the words described in the previous section for simple numeric	All of the integer output words described in the previous section
output are implemented in Gforth using pictured numeric output.	(@pxref{Simple numeric output}) are implemented in Gforth using pictured
	numeric output.

Three important things to remember about pictured numeric output:	Three important things to remember about pictured numeric output:

Line 8442 Here are some examples of using pictured	Line 8476 Here are some examples of using pictured
: my-u. ( u -- )	: my-u. ( u -- )
\ Simplest use of pns.. behaves like Standard u.	\ Simplest use of pns.. behaves like Standard u.
0 \ convert to unsigned double	0 \ convert to unsigned double
<# \ start conversion	<<# \ start conversion
#s \ convert all digits	#s \ convert all digits
#> \ complete conversion	#> \ complete conversion
TYPE SPACE ; \ display, with trailing space	TYPE SPACE \ display, with trailing space
	#>> ; \ release hold area

: cents-only ( u -- )	: cents-only ( u -- )
0 \ convert to unsigned double	0 \ convert to unsigned double
<# \ start conversion	<<# \ start conversion
# # \ convert two least-significant digits	# # \ convert two least-significant digits
#> \ complete conversion, discard other digits	#> \ complete conversion, discard other digits
TYPE SPACE ; \ display, with trailing space	TYPE SPACE \ display, with trailing space
	#>> ; \ release hold area

: dollars-and-cents ( u -- )	: dollars-and-cents ( u -- )
0 \ convert to unsigned double	0 \ convert to unsigned double
<# \ start conversion	<<# \ start conversion
# # \ convert two least-significant digits	# # \ convert two least-significant digits
[char] . hold \ insert decimal point	[char] . hold \ insert decimal point
#s \ convert remaining digits	#s \ convert remaining digits
[char] $ hold \ append currency symbol	[char] $ hold \ append currency symbol
#> \ complete conversion	#> \ complete conversion
TYPE SPACE ; \ display, with trailing space	TYPE SPACE \ display, with trailing space
	#>> ; \ release hold area

: my-. ( n -- )	: my-. ( n -- )
\ handling negatives.. behaves like Standard .	\ handling negatives.. behaves like Standard .
s>d \ convert to signed double	s>d \ convert to signed double
swap over dabs \ leave sign byte followed by unsigned double	swap over dabs \ leave sign byte followed by unsigned double
<# \ start conversion	<<# \ start conversion
#s \ convert all digits	#s \ convert all digits
rot sign \ get at sign byte, append "-" if needed	rot sign \ get at sign byte, append "-" if needed
#> \ complete conversion	#> \ complete conversion
TYPE SPACE ; \ display, with trailing space	TYPE SPACE \ display, with trailing space
	#>> ; \ release hold area

: account. ( n -- )	: account. ( n -- )
\ accountants don't like minus signs, they use braces	\ accountants don't like minus signs, they use parentheses
\ for negative numbers	\ for negative numbers
s>d \ convert to signed double	s>d \ convert to signed double
swap over dabs \ leave sign byte followed by unsigned double	swap over dabs \ leave sign byte followed by unsigned double
<# \ start conversion	<<# \ start conversion
2 pick \ get copy of sign byte	2 pick \ get copy of sign byte
0< IF [char] ) hold THEN \ right-most character of output	0< IF [char] ) hold THEN \ right-most character of output
#s \ convert all digits	#s \ convert all digits
rot \ get at sign byte	rot \ get at sign byte
0< IF [char] ( hold THEN	0< IF [char] ( hold THEN
#> \ complete conversion	#> \ complete conversion
TYPE SPACE ; \ display, with trailing space	TYPE SPACE \ display, with trailing space
	#>> ; \ release hold area

@end example	@end example

Here are some examples of using these words:	Here are some examples of using these words:
Line 8510 hex -1 my-u. decimal FFFFFFFF	Line 8550 hex -1 my-u. decimal FFFFFFFF
@cindex strings - see character strings	@cindex strings - see character strings
@cindex character strings - formats	@cindex character strings - formats
@cindex I/O - see character strings	@cindex I/O - see character strings
	@cindex counted strings

	@c anton: this does not really belong here; maybe the memory section,
	@c or the principles chapter

Forth commonly uses two different methods for representing character	Forth commonly uses two different methods for representing character
strings:	strings:
Line 8529 first byte of the string.	Line 8573 first byte of the string.
@end itemize	@end itemize

ANS Forth encourages the use of the second format when representing	ANS Forth encourages the use of the second format when representing
strings on the stack, whilst conceeding that the counted string format	strings.
remains useful as a way of storing strings in memory.


doc-count	doc-count
Line 8656 doc->number	Line 8699 doc->number
doc->float	doc->float
doc-accept	doc-accept
doc-pad	doc-pad
	@c anton: these belong in the input stream section
doc-parse	doc-parse
doc-word	doc-word
doc-sword	doc-sword
doc-(name)	doc-name
doc-refill	doc-refill
@comment obsolescent words..	@comment obsolescent words..
doc-convert	doc-convert

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>

Removed from v.1.74
changed lines
	Added in v.1.75