Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FTH(1)			FreeBSD	General	Commands Manual			FTH(1)

NAME
     fth -- Forth script and extension language

SYNOPSIS
     fth [-DdQqrv] [-C so-lib-path] [-Ee pattern] [-F fs] [-f init-file]
	 [-I fs-path] [-S "lib init"] [-s file]	[file ...]
     fth [-al] [-i [suffix]] [-n | -p] -e pattern [file	| -]
     fth [-V]

DESCRIPTION
     This is the manual	page for the interactive and script processing Forth
     interpreter fth.  It is based on Ficl.  This manual page provides infor-
     mation for	running	fth in a UNIX command line environment.	 See libfth(3)
     for Forth as an extension language.

   Argument list processing
     -a	  Split	every line to array *farray* before evaluation.	 The split
	  string is field separator *fs*.  Used	with -n	or -p option.
     -C	path
	  Prepend path to *load-lib-path*, multiple calls possible.
     -D	  Show backtrace and exit with return code 1 if	an exception was found
	  evaluating the initialization	file, running a	script,	loading	addi-
	  tional source	files, or evaluating strings from the command line.
     -d	  Set global variable *fth-debug* to #t.
     -E	pattern
     -e	pattern
	  Evaluate pattern.  After evaluation, if options -e was specified,
	  exit,	if option -E was specified, start read-eval-print-loop.	 Mul-
	  tiple	calls possible.	 If -D was given and evaluation	was not	suc-
	  cessful, show	backtrace and exit with	return code 1, otherwise exit
	  with return code 0.  The last	or only	-e pattern can be considered
	  between
		lambda:	<{}> pattern ;
	  and is in compile state!  If multiple	-e pattern appear, all but the
	  last are in interpret	state.
     -F	fs
	  Set global variable *fs* to field separator fs.
     -f	file
	  Take initialization file file	instead	of ~/.fthrc.  Use -Q to	pre-
	  vent loading initialization files.
     -I	path
	  Prepend path to *load-path*, multiple	calls possible.
     -i	[suffix]
	  The -e pattern will be applied to files or stdin.  If	suffix is
	  specified, a backup file will	be created with	that suffix.
     -l	  Remove line ending \n	when used with -n or -p	option.
     -n	  Suppress output of current *line*.  If not in-place -i, start	an im-
	  plicit loop.
     -p	  Print	current	*line* to stdout.  If not in-place -i, start an	im-
	  plicit loop.
     -Q	  Neither load the system wide nor the local initialization file.
     -q	  Do not print banner and set global variable *fth-verbose* to #f.
     -r	  Start	a conventional Forth-like session with data stack left un-
	  touched after	pressing <Return>.  Normally the data stack is printed
	  and cleared but -r changes this behavior to something	like a
	  read-eval-loop instead of a read-eval-print-loop.  If	-D was given
	  and evaluation was not successful, show backtrace and	exit with re-
	  turn code 1, otherwise exit with return code 0.
     -S	"lib init"
	  Load C extension library lib and call	the initialization function
	  init.	 lib and init must be enclosed in quotations
		-S "dbm	Init_dbm"
	  Multiple calls possible.
     -s	file
	  Evaluate file	as a Forth script and exit.  It	doesn't	read the ini-
	  tialization file.  The global	Forth variables	*argc* and *argv* are
	  set and filled with the count	and command line options appearing af-
	  ter -s file.	This must be the last option given to the fth inter-
	  preter.  Options after that are taken	as script options.  If -D was
	  given	and evaluation was not successful, show	a backtrace and	exit
	  with return code 1, otherwise	exit with return code 0.
     -V	  Display version info and exit.
     -v	  Set global variable *fth-verbose* to #t (default).

   Forth variables
     *0*  Entire current input line, read-only.
     *1* ... *9*
	  Corresponding	single element of *farray*, read-only.
     .*0*
	  Print	entire current input line.
     .*1* ... .*9*
	  Print	corresponding single element of	*farray* with *ofs* attached,
	  normally a single space.
     *argc*
	  Number of arguments in *argv*.
     *argv*
	  Array	of command line	arguments.  Return array of all	exceptions.
     *farray*
	  Auto-splitted	array of strings of current line.
     *features*
	  Return array of all features.
     *filename*
	  Current filename.
     *fname*
	  Current in-place filename.
     *fnr*
	  Input	record number in current file.
     *fs*
	  Input	field separator, default one space.
     *fth-debug*
	  If #t, show more diagnostic output.
     *fth-verbose*
	  If #t, show more output.
     *key*
	  Hold current value in	a map--end-map loop.
     *last-exception*
	  Hold last raised exception.
     *line*
	  Current in-place processing line.
     *lineno*
	  Current line number.
     *load-lib-path*
	  Array	of directories where fth searchs for *.so C-library files.
     *load-path*
	  Array	of directories where fth searchs for *.fs script files.
     *loaded-files*
	  Array	of already loaded files.
     *nr*
	  Input	record number over all files.
     *ofs*
	  Output field separator, default one space.
     *re*
	  Array	with last regexp match.
     *re-syntax-options*
	  Regexp syntax	option,	default	REG_EXTENDED.
     *re0*
	  Last entire match of regexp search, read-only.
     *re1* ... *re9*
	  Last subexpression match of regexp search, read-only.
     optarg
	  Getopt variable with current option argument string, default #f.
     opterr
	  If #t, getopt	print error message for	wrong or missing arguments;
	  default #t.
     optind
	  Getopt variable with index of	next element in	*argv* array, default
	  1.
     optopt
	  Getopt variable with last known option, default #f.

   Hook	variables
     fth calls five hooks if they are not empty: before	and after loading
     source files and in interactive mode before starting and after ending the
     repl as well as every time	before showing the prompt.
     before-load-hook (	filename -- f )
	  Called before	loading	filename.  If hook returns #f, filename	won't
	  be loaded.
		before-load-hook lambda: <{ fname -- f }>
			"\\ loading %s\n" #( fname ) fth-print
			#t
		; add-hook!
     after-load-hook ( filename	-- )
	  Called after loading filename	and updating global variable
	  *loaded-files*.
		after-load-hook	lambda:	<{ fname -- }>
			"\\ %s loaded\n" #( fname ) fth-print
		; add-hook!
     before-repl-hook (	-- )
	  Called after initializing the	tecla(7) command-line editing library
	  but before starting the repl.	 A predefined hook showing some	help
	  lines	can be replaced	by your	own message.
		before-repl-hook reset-hook!
		before-repl-hook lambda: <{ -- }>
			." \" cr
			." \ Starting FTH on " date .string ." !" cr
			." \" cr
		; add-hook!
     after-repl-hook ( history-file -- )
	  Called after leaving the repl	and writing the	history	file but be-
	  fore leaving the program.  Its only argument is the history file-
	  name.	 You may manipulate the	history	data entries.  One history en-
	  try consists of two lines: a time stamp preceded by a	Forth comment
	  backslash and	the actual history line.
		after-repl-hook	lambda:	<{ history -- }>
			\ Remove duplicates from history file.
			history	readlines array-reverse! { hary	}
			#() "" "" { nhary hline	tline }
			hary array-length 0 ?do
				hary i	  array-ref to hline
				hary i 1+ array-ref to tline
				nhary hline array-member? unless
					nhary hline array-unshift
					tline array-unshift drop
				then
			2 +loop
			history	nhary writelines
		; add-hook!
     before-prompt-hook	( prompt pos --	new-prompt )
	  Called before	printing a new prompt to customize the output of it.
	  prompt is the	old prompt and pos the current history position.  The
	  return value,	preferable a string, is	the prompt argument for	the
	  next hook procedure if any.
		before-prompt-hook lambda: <{ prompt pos -- new-prompt }>
			"fth (%d) ok " #( pos )	string-format
		; add-hook!
	  Or with standout and bold mode, see gl_prompt_style(3) and
	  *promptstyle*	below:
		#t to *promptstyle*
		before-prompt-hook lambda: <{ prompt pos -- new-prompt }>
			"%%Sfth	(%d)%%s	%%Bok%%b " #( pos ) string-format
		; add-hook!

   The command-line editor
     Command-line editing similar to tcsh(1) is	handled	by the tecla(7)	li-
     brary if installed.  Predefined key bindings exist	for those similar to
     vi(1) and emacs(1).  The default editing mode is emacs-mode.  You can
     switch from emacs-mode to vi-mode via M-^V	and from vi-mode to emacs-mode
     via M-^E.	To start in vi-mode, put a line	like
	   edit-mode vi
     in	your ~/.teclarc	file.  A history of the	last command-lines can be
     listed with ^Xh, the last 10 history entries can be listed	with M-10^Xh.
     The Tab-key or ^I initiates word completion.  If the Forth	dictionary has
     more than one entry starting with characters before the cursor, show all,
     if	only one definition exists, complete it	and add	a space	after the com-
     pleted word.  If the Forth	dictionary has no entries starting with	the
     characters	before the cursor, try filename	completion.  For complete key
     listings and function descriptions, see tecla(7).

     If	the first character of the command-line	is an exclamation point	!, try
     history expansion similar to csh(1).

     !123    repeat event 123
     !-123   repeat 123rd last event
     !!	     repeat last event (same as	!-1)
     !?str(?)
	     repeat last event containing str; the last	? is optional
     !str    repeat last event starting	with str

     If	the first character of the command-line	is a caret ^, try history sub-
     stitution similar to csh(1).

     ^search^replace(^)
	     repeat last event containing search and replace this string with
	     replace; the last ^ is optional

   Tecla variables
     *histdup*
	  If set to gl-all, only unique	history	events are entered in the his-
	  tory list.  If set to	gl-prev	and the	last history event is the same
	  as the current, the current command is not entered.  If not defined
	  (undef, the default),	all history events are entered.
     *histfile*
	  Can be set to	the pathname where history is going to be saved	and
	  restored.  If	not set, use $FTH_HISTORY or ~/.fth-history.  Default
	  is undef.
     *history*
	  Can be given a numeric value to control the size of the history
	  list.	 If not	set, use $FTH_HISTORY_LENGTH or	100.  Default is un-
	  def.
     *savehist*
	  If true, save	history	events,	otherwise not.	Default	is #t.
     *promptstyle*
	  If true, enable special formatting directives	within the prompt, see
	  gl_prompt_style(3).  Default is #f.

   Tecla words
     bindkey ( :optional key action -- )
	  Key bindings and others can be set in	~/.fthrc to control libtecla
	  and getline.
	  no argument
		  Show user-defined key-bindings set for example in ~/.fthrc.
	  one argument
		  If key is a string, take it as configure string.  If key is
		  a predefined constant, set specific value as configure
		  string.  Valid constants:
		  gl-vi	  edit-mode vi
		  gl-emacs
			  edit-mode emacs
		  gl-none
			  edit-mode none
		  gl-nobeep
			  nobeep
			"edit-mode vi \n nobeep" bindkey
			gl-vi bindkey
	  two arguments
		  If key and action are	strings, bind action to	key.  If key
		  is a string and action is anything else, unbind key from
		  last bind.  See tecla(7) for key-bindings and	actions.
			"^G" "user-interrupt" bindkey
			"^G" #f	bindkey
     history ( :optional action	arg -- )
	  History events can be	displayed, loaded, saved, and cleared where
	  action can be	one of
	  gl-show
		  show arg or all history events
	  gl-load
		  load history events from arg or *histfile*
	  gl-save
		  save history events to arg or	*histfile*
	  gl-clear
		  clear	all history events
			     history =>	show entire history
		gl-show	     history =>	same as	above
			10   history =>	show 10	last history events
		gl-show	10   history =>	same as	above
		gl-load	     history =>	load from *histfile*
		gl-load	nil  history =>	same as	above
		gl-load	file history =>	load from file
		gl-save	     history =>	save to	*histfile*
		gl-save	nil  history =>	same as	above
		gl-save	file history =>	save to	file
		gl-clear     history =>	clear all history events

   Loops
     Forth has loop constructs for compile state and interpret state.  In ad-
     dition to the usual do--loop, fth provides	each--end-each and map--end-
     map loops for objects.
     do	( limit	start -- ) compile-only
     ?do ( limit start -- ) compile-only
     loop ( -- ) compile-only
	  Run loop from	start up to but	not including limit.  ?do starts only
	  if limit is greater than start.
		3 0 do	i .  loop => 0 1 2
     each ( obj	-- val ) compile-only
     end-each (	-- ) compile-only
	  Push each element of obj in order on stack and repeat	execution of
	  body.
		#( 0 1 2 ) each	 .  end-each =>	0 1 2
     map ( obj -- ) compile-only
     map! ( obj	-- ) compile-only
     end-map ( -- obj )	compile-only
	  Set each element of obj in order to global variable *key* and	repeat
	  execution of body.  The current element of obj with map! or a	copy
	  of obj with map is set to top	of stack before	end-map.
		#( 0 1 2 ) value a1
		a1 map	 i *key* +  end-map => #( 0 2 4	) \ a copy of a1
		a1 .$ => #( 0 1	2 )
		a1 map!	 i *key* +  end-map => #( 0 2 4	) \ a1 has changed
		a1 .$ => #( 0 2	4 )
     Interpret state loops for use outside word	definitions in scripts or in
     the repl work like	their compile state cousins above.  The	body of	the
     following [do]--[loop], [each]--[end-each]	and [map]--[end-map] is	in
     compile state, loop indexes i, j, k and leave etc can be used like	in
     colon definitions.
     [do] ( limit start	-- )
     [loop] ( -- )
		3 0 [do]  i .  [loop] => 0 1 2
     [each] ( obj -- val )
     [end-each]	( -- )
		#( 0 1 2 ) [each]  .  [end-each] => 0 1	2
     [map] ( obj -- )
     [map!] ( obj -- )
     [end-map] ( -- obj	)
		#( 0 1 2 ) value a1
		a1 [map]   i *key* +  [end-map]	=> #( 0	2 4 ) \	a copy of a1
		a1 .$ => #( 0 1	2 )
		a1 [map!]  i *key* +  [end-map]	=> #( 0	2 4 ) \	a1 has changed
		a1 .$ => #( 0 2	4 )

   Arrays and Lists
     Arrays:
     #() ( -- ary )
	  Return array of length 0 for array-append, array-push	etc.
     .array ( ary -- )
	  Print	array object ary to current output.
     >array ( vals len -- ary )
	  Return array object with len objects found on	parameter stack.
	  Raise	an out-of-range	exception if len < 0.
     array->array ( ary1 -- ary2 )
	  Return copy of ary1 only with	references of each element in contrary
	  to array-copy.  If ary1 is not an array, return #( ary1 ).
		#( 0 #{	'foo 10	} 2 ) value ary1
		ary1 array->array value	ary2
		ary1 1 array-ref 'foo 30 hash-set!
		ary1 =>	#( 0 #{	'foo 30	} 2 )
		ary2 =>	#( 0 #{	'foo 30	} 2 )
     array->list ( ary -- lst )
	  Return copy of ary as	list only with references of each elements in
	  contrary to array-copy.  If ary is not an array, return '( ary ).
		#( 0 #{	'foo 10	} 2 ) value ary
		ary array->list	value lst
		ary 1 array-ref	'foo 30	hash-set!
		lst => '( 0 #{ 'foo 30 } 2 )
		ary => #( 0 #{ 'foo 30 } 2 )
     array-append ( ary1 ary2 -- ary1+ary2 )
	  Append two arrays and	return new one.	 If ary2 is not	an array, ap-
	  pend it as a single element.
		#( 0 1 2 ) #( 3	4 ) array-append => #( 0 1 2 3 4 )
		#( 0 1 2 ) 10 array-append => #( 0 1 2 10 )
     array-clear ( ary -- )
	  Clear	array and set all elements to #f.
     array-compact ( ary1 prc args -- ary2 )
	  Return new array object with nil elements removed.
     array-compact! ( ary prc args -- ary' )
	  Remove all nil elements from ary and return changed array object.
     array-concat ( vals len --	ary ) alias for	_array
     array-copy	( ary1 -- ary2 )
	  Return copy of ary1 with all elements	new created in contrary	to
	  array-_array.
		#( 0 #{	'foo 10	} 2 ) value ary1
		ary1 array-copy	value ary2
		ary1 1 array-ref 'foo 30 hash-set!
		ary1 =>	#( 0 #{	'foo 30	} 2 )
		ary2 =>	#( 0 #{	'foo 10	} 2 )
     array-delete! ( ary idx --	val )
	  Delete and return one	element	from ary at position idx.  Negative
	  index	counts from backward.  Raise an	out-of-range exception if idx
	  is not in ary's range.
     array-delete-key (	ary key	-- val )
	  Delete and return key	from ary if found, otherwise return #f.
     array-fill	( ary val -- )
	  Set all elements of ary to val.
     array-find	( ary key -- key )
	  Return key if	key exists in ary, otherwise #f.
     array-index ( ary key -- idx )
	  Return index of key in ary or	-1 if not found.
     array-insert ( ary1 idx val -- ary2 )
	  Insert val to	ary1 at	position idx and return	new array.  val	can be
	  an array or any other	object.	 Negative idx counts from backward.
	  Raise	an out-of-range	exception if idx is not	in ary1's range.
     array-insert! ( ary idx val -- ary' )
	  Insert val to	ary at position	idx and	return changed array.  val can
	  be a single object or	an array.  Negative idx	counts from backward.
	  Raise	an out-of-range	exception if idx is not	in ary's range.
     array-join	( ary sep -- str )
	  Return string	with all elements of ary converted to their string
	  representation and joined together separated by the string sep.  If
	  sep is not a string, a space will be used as separator.
		#( 0 1 2 ) "--"	array-join => "0--1--2"
		#( 0 1 2 ) nil array-join => "0	1 2"
     array-length ( obj	-- len )
	  If obj is an array object, return its	length,	otherwise -1.
     array-member? ( ary key --	f )
	  Return #t if key exists in ary, otherwise #f.
     array-pop ( ary --	val )
	  Remove and return last element from ary.  If ary is empty, return
	  #f.
     array-push	( ary val -- ary' )
	  Append val to	ary.
		#( 0 1 2 ) 10 array-push => #( 0 1 2 10	)
     array-ref ( ary idx -- val	)
	  Return value at position idx.	 Negative index	counts from backward.
	  Raise	an out-of-range	exception if index is not in ary's range.
     array-reject ( ary1 prc args -- ary2 )
	  prc will be called with args,	an array of zero or more proc argu-
	  ments, and the current array element set as first arg	in args	array.
	  The length of	args + 1 is the	required arity of prc.	If prc returns
	  neither #f nor nil nor 0, this element will be pushed	in a new array
	  object.  The new array object	will be	returned.  In the example n1
	  corresponds to the current array element and n2 comes	from args,
	  here 2.
		#( 0 1 2 ) lambda: <{ n1 n2 -- f }>
			n1 n2 >
		; #( 2 ) array-reject => #( 0 1	)
	  The same a bit shorter:
		#( 0 1 2 ) <'> > #( 2 )	array-reject =>	#( 0 1 )
     array-reject! ( ary prc args -- ary' )
	  prc will be called with args,	an array of zero or more proc argu-
	  ments, and the current array element set as first arg	in args	array.
	  The length of	args + 1 is the	required arity of prc.	If prc returns
	  neither #f nor nil nor 0, the	element	will be	removed.  In the exam-
	  ple n1 corresponds to	the current array element and n2 comes from
	  args,	here 2.
     array-reverse ( ary1 -- ary2 )
	  Return new array with	elements reversed.
     array-reverse! ( ary -- ary' )
	  Return ary with elements reversed.
     array-set!	( ary idx val -- )
	  Store	val at position	idx.  Negative index counts from backward.
	  Raise	an out-of-range	exception if index is not in ary's range.
     array-shift ( ary -- val )
	  Remove and return first element from ary.  If	ary is empty, return
	  #f.
     array-sort	( ary1 prc -- ary2 )
	  Return new sorted array.  prc	compares two elements A	and B and
	  should return	a negative integer if A	< B, 0 if A == B, and a	posi-
	  tive integer if A > B.  Raise	a bad-arity exception if prc doesn't
	  take two arguments.
		#( 2 1 0 ) lambda: <{ a	b -- f }>
			a b < if
				-1
			else
				a b > if
					1
				else
					0
				then
			then
		; array-sort =>	#( 0 1 2 )
     array-sort! ( ary prc -- ary' )
	  Return the sorted ary.  prc compares two elements A and B and	should
	  return a negative integer if A < B, 0	if A ==	B, and a positive in-
	  teger	if A > B.  Raise a bad-arity exception if prc doesn't take two
	  arguments.
     array-subarray ( ary start	end -- subary )
	  Return array built from ary beginning	with index start up to but ex-
	  cluding index	end.  If end is	nil, up	to end of array	will be	re-
	  turned.  Negative index counts from backward.	 Raise an out-of-range
	  exception if start is	not in ary's range.
		#( 0 1 2 3 4 ) 2 4 array-subarray => #(	2 3 )
		#( 0 1 2 3 4 ) -3 -1 array-subarray => #( 2 3 4	)
		#( 0 1 2 3 4 ) -3 nil array-subarray =>	#( 2 3 4 )
     array-uniq	( ary1 -- ary2 )
	  Return new array without duplicated elements of ary1.
     array-uniq! ( ary -- ary' )
	  Return ary without duplicated	elements.
     array-unshift ( ary val --	ary' )
	  Prepend val to ary.
		#( 0 1 2 ) 10 array-unshift => #( 10 0 1 2 )
     array= ( ary1 ary2	-- f )
	  Return #t if ary1 and	ary2 are array objects of same length and con-
	  tent,	otherwise #f.
     array? ( obj -- f )
	  Return #t if obj is an array object, otherwise #f.
     make-array	( len :key initial-element -- ary )
	  Return array of length len filled with keyword INITIAL-ELEMENT val-
	  ues.	initial-element	defaults to nil	if not specified.  Raise an
	  out-of-range exception if len	< 0.

     Assoc arrays:
     >assoc ( vals len -- ary )
	  Return assoc array object with len / 2 key-value pairs found on pa-
	  rameter stack.  Raise	an out-of-range	exception if len < 0 or	not
	  even.
     array-assoc ( ass key -- ret )
	  If key matches, return corresponding key-value pair, otherwise #f.
     array-assoc-ref ( ass key -- val )
	  If key matches, return corresponding value, otherwise	#f.
     array-assoc-remove! ( ass key -- 'ass )
	  If key matches, remove key-value pair	from ass.
     array-assoc-set! (	ass key	val -- 'ass )
	  If key matches, set key-value	pair, otherwise	add new	pair.
     assoc ( ass key val -- 'ass )
	  Build	sorted assoc array.  ass must be an assoc array	or an empty
	  array	#().
		#() value ass
		ass 'a 10 assoc	=> #a( '( 'a . 10 ) )
		ass 'b 20 assoc	=> #a( '( 'a . 10 ) '( 'b . 20 ) )
     assoc? ( obj -- f )
	  Return #t if obj is an assoc array object, otherwise #f.

     Lists:
     '() ( -- lst )
	  Return empty list.
     .list ( lst -- )
	  Print	list object lst	to current output.
     >list ( vals len -- lst )
	  Return list object with len objects found on parameter stack.	 Raise
	  an out-of-range exception if len < 0.
     cadddr ( lst -- val )
	  Return fourth	entry, the cadddr, of list or nil.
     caddr ( lst -- val	)
	  Return third entry, the caddr, of list or nil.
     cadr ( lst	-- val )
	  Return second	entry, the cadr, of list or nil.
     car ( lst -- val )
	  Return first entry, the car, of list or nil.
     cddr ( lst	-- val )
	  Return rest, the cddr, of list without its first and second entries.
     cdr ( lst -- val )
	  Return rest, the cdr,	of list	without	its first entry.
     cons ( val	lst1 --	lst2 )
	  Return Lisp-like cons	pointer	with val as car	and list as cdr.
     cons2 ( val1 val2 lst1 -- lst2 )
	  Return Lisp-like cons	pointer	with val1 as car, val2 as cadr and
	  list as cddr.
     cons? ( obj -- f )
	  Return #t if obj is a	cons pointer, otherwise	#f.
     last-pair ( lst --	lp )
	  Return last pair of lst.
		'( 0 1 2 3 ) last-pair => '( 3 )
     list->array ( lst -- ary )
	  Return copy of lst as	array only with	references of each element in
	  contrary to list-copy.  lst is not a cons pointer, return #( lst ).
		'( 0 #{	'foo 10	} 2 ) value lst1
		lst1 list->array value ary2
		lst1 1 list-ref	'foo 30	hash-set!
		lst1 =>	'( 0 #{	'foo 30	} 2 )
		ary2 =>	#( 0 #{	'foo 30	} 2 )
     list-append ( arg0	arg1 ... argn n	-- lst )
	  Return list object with n objects found on parameter stack.  Raise
	  an out-of-range exception if n < 0.
     list-copy ( lst1 -- ary2 )
	  Return copy of lst1 with all elements	new created in contrary	to
	  list-_array.
		'( 0 #{	'foo 10	} 2 ) value lst1
		lst1 list-copy value lst2
		lst1 1 list-ref	'foo 30	hash-set!
		lst1 =>	'( 0 #{	'foo 30	} 2 )
		lst2 =>	'( 0 #{	'foo 10	} 2 )
     list-delete ( lst1	key -- lst2 )
	  Return new list without all elements equal key.
     list-delete! ( lst	key -- lst' )
	  Return lst without all elements equal	key.
     list-fill ( lst val -- lst' )
	  Set all elements of lst to val.
     list-head ( lst1 idx -- lst2 )
	  Return first idx entries of lst1 in a	new list or nil.
     list-index	( lst key -- idx )
	  Return index of key in lst or	-1 if not found.
     list-insert ( lst1	idx val	-- lst2	)
	  Insert val to	lst1 at	position idx and return	new list.  val can be
	  a list or any	other object.  Negative	idx counts from	backward.
	  Raise	an out-of-range	exception if idx is not	in lst1's range.
     list-length ( obj -- len )
	  If obj is a list (or array), return length of	list, if obj is	nil,
	  return 0 otherwise -1.
     list-member? ( lst	key -- f )
	  Return #t if key exists in lst, otherwise #f.
     list-ref (	lst idx	-- val )
	  Return value at position idx of lst.	Negative idx counts from back-
	  ward.	 Raise an out-of-range exception if idx	is not in lst's	range.
     list-reverse ( lst1 -- ary2 )
	  Return new list with elements	reversed.
     list-set! ( lst idx val --	)
	  Store	element	val at position	idx in lst.  Negative idx counts from
	  backward.  Raise an out-of-range exception if	idx is not in lst's
	  range.
     list-slice	( lst1 idx :key	count 1	-- lst2	)
	  Return new list without count	elements from idx on.  Raise an
	  out-of-range exception if idx	is not in lst1's range.
		#( 0 1 1 2 ) 1 :count 2	list-slice => #( 0 2 )
     list-slice! ( lst idx :key	count 1	-- lst'	)
	  Return lst without count elements from idx on.  Raise	an
	  out-of-range exception if idx	is not in lst's	range.
     list-tail ( lst1 idx -- lst2 )
	  Return idx'th	cdr of lst1 up to the last entry in a new list or nil.
     list= ( lst1 lst2 -- f )
	  Return #t if lst1 and	lst2 are list objects of same length and con-
	  tent,	otherwise #f.
     list? ( obj -- f )
	  Return #t if obj is a	list (nil or a cons pointer), otherwise	#f.
     make-list ( len :key initial-element nil -- lst )
	  Return list of length	len filled with	keyword	initial-element	val-
	  ues.	initial-element	defaults to nil	if not specified.  Raise an
	  out-of-range exception if len	< 0.
     nil? ( obj	-- f )
	  Return #t if obj is nil, otherwise #f.
     null? ( obj --f ) alias for nil?
     pair? ( obj -- f )
	  Return #t if obj is a	pair (a	cons pointer), otherwise #f.
     set-car! (	lst val	-- lst'	)
	  Set val to car of lst.
     set-cdr! (	lst val	-- lst'	)
	  Set val to cdr of lst.

     Assoc lists:
     >alist ( vals len -- alst )
	  Return assoc list object with	len / 2	key-value pairs	found on pa-
	  rameter stack. Raise an out-of-range exception if len	< 0 or not
	  even.
     acons ( key val alst1 -- alst2 )
	  Return new Lisp-like associated list from key-val pair and alst1.
     list-assoc	( alst key -- ret )
	  If key matches, return corresponding key-value pair, otherwise #f.
     list-assoc-ref ( alst key -- val )
	  If key matches, return corresponding value, otherwise	#f.
     list-assoc-remove!	( alst key -- alst' )
	  If key matches, remove key-value pair	from alst.  Return current as-
	  soc-list.
     list-assoc-set! ( alst key	val -- alst' )
	  If key matches, set key-value	pair, otherwise	add new	pair to	alst.
	  Return current assoc-list.

   File	Functions
     General functions:
     chdir ( path -- ) alias for file-chdir
     close-pipe	( fp --	ior )
	  Forth-like word.
		256 constant max-line
		create line-buffer max-line 2 +	allot
		s" pwd"	r/o open-pipe throw value FP
		line-buffer max-line FP	read-line throw	drop
		    line-buffer	swap type
		FP close-pipe throw
     file-atime	( name -- time )
	  If name is a file, return its	last access time, otherwise #f.	 One
	  can convert the number in a readable string with time->string.
     file-basename ( name ext -- base )
	  Return basename of file name depending on ext.  ext may be #f,
	  nil/undef, a string or a regexp.  If ext is #f, return filename
	  without pathname.  If	ext is nil or undef, discard the part from the
	  last dot to the end of basename name.	 If ext	is a string or a reg-
	  exp, discard found ext from basename name.
		"/home/mike/cage.snd" #f file-basename => "cage.snd"
		"/home/mike/cage.snd" nil file-basename	=> "cage"
		"/home/mike/cage.snd" "nd" file-basename => "cage.s"
		"/home/mike/cage.snd" /\.(snd|wave)$/ file-basename => "cage"
     file-chdir	( path -- )
	  Change working directory to path and,	if in a	repl, print result to
	  current standard output.  If path is nil, change working directory
	  to $HOME.  path may contain `~' as an	abbreviation for home direc-
	  tory.
     file-chmod	( name mode -- )
	  Change access	mode of	file name to mode.  You	can write mode with
	  octal	numbers: prepend the number with `0o', this is number zero `0'
	  and lower letter `o',	similar	to `0x'	for hexadecimal	numbers.
     file-chroot ( path	-- )
	  Change root directory	to path	and, if	in a repl, print result	to
	  current standard output.  This function is restricted	to the super-
	  user.
     file-copy ( src dst -- )
	  Copy file src	to dst.	 If dst	is a directory,	copy src to DST/SRC.
	  Raise	a system-error exception if fopen(3) fails on any of the two
	  files.
     file-ctime	( name -- time )
	  If name is a file, return its	status change time, otherwise #f.  One
	  can convert the number in a readable string with time->string.
     file-delete ( name	-- )
	  If file name exist, delete it, otherwise do nothing.
     file-dir (	dir -- files-ary )
	  Return an array of all filenames found in dir.
     file-dirname ( name -- path )
	  Return directory part	of file	name.
		"/home/mike/cage.snd" file-dirname => "/home/mike"
     file-eval ( name -- )
	  Load and eval	content	of file	name and add name to *loaded-files* if
	  it wasn't there.  It's similar to include except that	name must be
	  on stack (include is a parse word).  With file-eval one can load
	  files	from within word definitions.  Raise a load-error exception if
	  file-eval fails.
     file-fullpath ( name -- path )
	  Return current working directory prepended to	file name.  If name
	  starts with a	slash, return name unchanged.
     file-install ( src	dst mode -- f )
	  Install src to dst with access mode mode if dst doesn't exist	or if
	  modification time of src is greater than dst's.  If dst is a direc-
	  tory,	install	src to dst/src.	 Return	#t if src could	be installed,
	  otherwise #f.	 You can write mode with octal numbers:	prepend	the
	  number with `0o', this is number zero	`0' and	lower letter `o', sim-
	  ilar to `0x' for hexadecimal numbers.
		: install-lib {	src dst	mode --	}
			src dst	mode file-install if
				"%s -->	%04o %s" '( src	mode dst )
			else
				"%s is up-to-date" '( dst )
			then  fth-print	 cr
		;
		"libsndlib.so" "/usr/opt/lib/s7" 0o755 install-lib
     file-length ( name	-- len )
	  If name is a file, return its	length in bytes, otherwise #f.
     file-match-dir ( dir reg -- files-ary )
	  Return an array of filenames in dir matching regexp reg.
     file-mkdir	( name mode -- )
	  Create directory named name with access mode mode.  You can write
	  mode with octal numbers: prepend the number with `0o', this is num-
	  ber zero `0' and lower letter	`o', similar to	`0x' for hexadecimal
	  numbers.
     file-mkfifo ( name	mode --	)
	  Create fifo named name with access mode mode.	 You can write mode
	  with octal numbers: prepend the number with `0o', this is number
	  zero `0' and lower letter `o', similar to `0x' for hexadecimal num-
	  bers.
     file-mtime	( name -- time )
	  If name is a file, return its	last modification time,	otherwise #f.
	  One can convert the number in	a readable string with time->string.
     file-pwd (	-- path	)
	  Return current working directory.
     file-realpath ( name -- path )
	  If name starts with `~', replace it with content of environment
	  variable $HOME.  If realpath(3) function exists, return resolved
	  path,	otherwise return name with `~' replacement.
		"~" file-realpath => "/home/mike"
		"/usr/local" file-chdir	=> "/usr/local"
		file-pwd => "/usr/local"
		"../bin" file-realpath => "/usr/bin"
     file-rename ( src dst -- )
	  Rename src to	dst.
     file-rmdir	( name -- )
	  Remove empty directory name.
     file-shell	( cmd -- str )
	  Open pipe for	reading, feed it with cmd and collect string output as
	  long as pipe is open.	 Afterwards close pipe,	set read-only variable
	  exit-status and return collected string (with	trailing cr).
     file-split	( name -- ary )
	  Split	file name in dirname and basename and return result in array
	  of two strings.
		"/home/mike/cage.snd" file-split
		  => #(	"/home/mike" "cage.snd"	)
     file-symlink ( src	dst -- )
	  Create symlink from src named	dst.
     file-system ( cmd -- f )
	  Execute cmd as a shell command.  Set read-only variable exit-status
	  and return #t	for success, #f	otherwise.  In the latter case you can
	  check	exit-status.
     file-touch	( name time -- )
	  Change modification time of name to time.  If	time is	nil, use cur-
	  rent time.
     file-truncate ( name size -- )
	  Truncate or extend file name to size bytes.
     open-pipe ( addr u	fam -- fp ior )
	  Forth-like word.
		256 constant max-line
		create line-buffer max-line 2 +	allot
		s" pwd"	r/o open-pipe throw value FP
		line-buffer max-line FP	read-line throw	drop
		    line-buffer	swap type
		FP close-pipe throw
     shell ( cmd -- str	) alias	for file-shell

     File test functions:
     file-block? ( name	-- f )
	  Return #t if name is a block special file, otherwise #f.
     file-character? ( name -- f )
	  Return #t if name is a character special file, otherwise #f.
     file-directory? ( name -- f )
	  Return #t if name is a directory, otherwise #f.
     file-executable? (	name --	f )
	  Return #t if name is an executable file, otherwise #f.
     file-exists? ( name -- f )
	  Return #t if name is an existing file, otherwise #f.
     file-fifo?	( name -- f )
	  Return #t if name is a named pipe, otherwise #f.
     file-grpowned? ( name -- f	)
	  Return #t if name matches effective gid, otherwise #f.
     file-owned? ( name	-- f )
	  Return #t if name matches effective uid, otherwise #f.
     file-readable? ( name -- f	)
	  Return #t if name is a readable file,	otherwise #f.
     file-setgid? ( name -- f )
	  Return #t if name has	set gid	bit, otherwise #f.
     file-setuid? ( name -- f )
	  Return #t if name has	set uid	bit, otherwise #f.
     file-socket? ( name -- f )
	  Return #t if name is a socket, otherwise #f.
     file-sticky? ( name -- f )
	  Return #t if name has	set sticky bit,	otherwise #f.
     file-symlink? ( name -- f )
	  Return #t if name is a symbolic link,	otherwise #f.
     file-writable? ( name -- f	)
	  Return #t if name is a writable file,	otherwise #f.
     file-zero?	( name -- f )
	  Return #t if name length is zero, otherwise #f.

   Hashs
     #{} ( -- hash ) alias for make-hash
     .hash ( hash -- )
	  Print	hash object to current output.
     >hash ( vals len -- hash )
	  Take len / 2 key-value pairs from parameter stack and	return hash
	  object.  Raise an out-of-range exception if len < 0 or len is	not
	  even.
		'foo 0	'bar 1	4 >hash	=>  #{ 'foo => 0  'bar => 1 }
     hash->array ( hash	-- ass )
	  Return array with #( key value ) pairs of hash's content.
		#{ 'foo	0 'bar 1 } hash->array
		  => #(	#( 'foo	 0 ) #(	'bar  1	) )
     hash-clear	( hash -- )
	  Remove all entries from hash,	hash's length is zero.
     hash-copy ( hash1 -- hash2	)
	  Return copy of hash1 using object-copy for all elements.
     hash-delete! ( hash key --	ary )
	  Delete key-value pair	associated with	key and	return key-value array
	  or #f	if not found.
     hash-each ( hash proc -- )
	  Run proc for each key-value pair.  proc's stack effect must be ( key
	  value	-- ).
		#{ 'foo	0 'bar 1 } lambda: <{ key value	-- }>
			"%s=%s\n" #( key value ) fth-print
		; hash-each
     hash-find ( hash key -- ary )
	  Return key-value array if key	exist or #f if not found.
     hash-keys ( hash -- keys )
	  Return array of keys.
     hash-map (	hash1 proc -- hash2 )
	  Run proc for each key-value pair.  proc's stack effect must be ( key
	  value	-- val ) where val is the new value for	key.
		#{ 'foo	0 'bar 1 } lambda: <{ key val -- val }>
			val 10 +
		; hash-map => #{ 'foo => 10  'bar => 11	}
     hash-member? ( hash key --	f )
	  Return #t if key exists, otherwise #f.
     hash-ref (	hash key -- value )
	  Return associated value or #f	if not found.
     hash-set! ( hash key value	-- )
	  Set key-value	pair of	hash.  If key exists, overwrite	existing
	  value, otherwise create new key-value	entry.
     hash-values ( hash	-- values )
	  Return array of values.
     hash= ( obj1 obj2 -- f )
	  Return #t if obj1 and	obj2 are hash objects with same	length and
	  content, otherwise #f.
     hash? ( obj -- f )
	  Return #t if obj is a	hash object, otherwise #f.
     make-hash ( -- hash )
	  Return empty hash object.
     make-hash-with-len	( size -- hash )
	  Return hash object with size key-value pairs.	 Keys are 0, 1,	2, ...
	  and values are nil.

     Property functions:
     object-properties ( obj --	props )
	  Return obj's properties or #f	if empty.
     object-property-ref ( obj key -- val )
	  Return obj's property	val associated with key	or #f if not found.
     object-property-set! ( obj	key val	-- )
	  Set key-value	pair to	obj's property object.
     properties	( obj -- props )
	  Return obj's global properties or #f if empty.  If obj is #f,	return
	  entire global	property object.
     property-ref ( obj	key -- val )
	  Return obj's global property val associated with key or #f if	not
	  found.
     property-set! ( obj key val -- )
	  Set key-value	pair to	obj's global property object.
     word-properties ( xt -- props )
	  Return xt's properties or #f if empty.
     word-property-ref ( xt key	-- val )
	  Return xt's property val associated with key or #f if	not found.
     word-property-set!	( xt key val --	)
	  Set key-value	pair to	xt's property object.

   Hooks
     .hook ( hook -- )
	  Print	hook object hook to current output.
     add-hook! ( hook prc -- ) alias for hook-add
     create-hook ( arity help "name" --	)
	  Create hook variable name with arity and documentation help.	arity
	  can be an integer or an array	of length 3, #(	req opt	rest ).
		2 "A simple hook." create-hook my-new-hook
		#( 2 0 #f ) "A simple hook." create-hook my-new-hook
     hook->array ( hook	-- ary )
	  Return array of all hook procedures.
     hook->list	( hook -- proc-list ) alias for	hook-_array
     hook-add (	hook prc -- )
	  Add hook procedure prc to hook.  Raise a bad-arity exception if
	  prc's	arity doesn't match hook's arity.
     hook-apply	( hook args -- value-list )
	  Run all hook procedures with args, an	array of arguments.  args can
	  be an	array of arguments or a	single argument.  Raise	a bad-arity
	  exception if args's length doesn't match hook's arity.
		2 make-hook value hk1
		hk1  <'> + 2 make-proc	add-hook!
		hk1 #( 1 2 ) run-hook => #( 3 )
     hook-arity	( hook -- arity	)
	  Return arity array of	hook, #( req opt rest ).
		2 make-hook hook-arity => #( 2 0 #f )
     hook-clear	( hook -- )
	  Remove all hook procedures from hook.
     hook-delete ( hook	prc-or-name -- prc )
	  Remove hook procedure	prc-or-name from hook and return it.
	  prc-or-name can be a string, an xt or	a proc.
     hook-empty? ( hook	-- f )
	  Return #t if no hook procedure exist in hook,	otherwise #f.
     hook-member? ( hook prc-or-name --	f )
	  Return #t if procedure prc-or-name exist in hook, otherwise #f.
	  prc-or-name can be a string, an xt or	a proc.
     hook-name ( hook -- name )
	  Return name of hook as string	if hook	object,	otherwise #f.
     hook-names	( hook -- name-list )
	  Return array of hook procedure names (strings).
     hook-procs	( hook -- proc-list ) alias for	hook-_array
     hook= ( obj1 obj2 -- f )
	  Return #t if obj1 and	obj2 are hook objects of same arity and	proce-
	  dures, otherwise #f.
     hook? ( obj -- f )
	  Return #t if obj is a	hook object, otherwise #f.
     make-hook ( arity -- hook )
	  Return hook object for procs accepting arity arguments.  arity can
	  be an	integer	or an array of length 3, #( req	opt rest ).
		2 make-hook value my-new-hook
		#( 2 0 #f ) make-hook value my-new-hook
     remove-hook! ( hook prc-or-name --	prc ) alias for	hook-delete
     reset-hook! ( hook	-- ) alias for hook-clear
     run-hook (	hook args -- value-list	) alias	for hook-apply

   IO Functions
     Global variables:
     *stderr*
	  Return current standard error	output IO object.
     *stdin*
	  Return current standard input	IO object.
     *stdout*
	  Return current standard output IO object.
     set-*stderr* ( io -- old )
	  Set io to current standard error and return old IO object.
     set-*stdin* ( io -- old )
	  Set io to current standard input and return old IO object.
     set-*stdout* ( io -- old )
	  Set io to current standard output and	return old IO object.
     set-version-control ( val -- )
	  Set current version control style.  Accepted values:
	       #t     numbered backups
	       nil    numbered/simple backups
	       #f     simple backups
	       undef  no backups
     version-control ( -- val )
	  Return current version control style.

     General IO	functions:
     .io ( io -- )
	  Print	io object to current output.
     exit-status ( -- n	) alias	for io-exit-status
     io->string	( io --	str )
	  Return content of io object as string	if possible.
     io-close (	io -- )
	  If necessary,	flush io, close	io object and set closed? to #t.
     io-closed?	( io --	f )
	  Return #t if io object is closed, otherwise #f.
     io-eof? ( io -- f )
	  Return #t if EOF is reached, otherwise #f.
     io-exit-status ( -- n )
	  Return exit status of	last extern process called via file-shell,
	  file-system, etc.
     io-fdopen ( fd :key fam r/o -- io )
	  Connect file descriptor fd to	new IO object.	If keyword fam was not
	  given, open file read-only, otherwise	use fam.  See io-open for fam.
		2 :fam w/o io-fdopen value err-io
		err-io "our error log" io-write
		err-io io-flush	=> "our	error log" (on stderr)
     io-filename ( io -- fname )
	  Return filename of io	object or #f if	filename is not	available.
     io-fileno ( io -- fd )
	  Return file descriptor of io.
     io-flush (	io -- )
	  Flushe io object if possible.
     io-getc ( io -- c )
	  Return next character	from io	object or #f if	EOF.
     io-input? ( obj --	f )
	  Return #t if obj is an input IO object, otherwise #f.
     io-mode ( io -- mode )
	  Return access	mode of	io object.
     io-open ( name :key fam r/o if-exists overwrite --	io )
	  Open file name and return new	IO object.  If keyword fam was not
	  specified, open file read-only, otherwise take fam.  Possible	fam
	  values:
	       a/o  apend "a"
	       r/a  read/write-append "a+"
	       r/o  read-only "r"
	       r/w  read/write "w+"
	       w/o  write-only "w"
	  If keyword if-exists was not specified, overwrite possible existing
	  file before open it for writing or appending.	 Possible if-exists
	  values:
	       :error
		    raise an io-error exception	if name	already	exist
	       :overwrite
		    overwrite existing file (default)
	       :rename
		    depends on environment variable $VERSION_CONTROL and
		    global Fth variable	version-control	(see there)
		"in-test" io-open value	rd-io1
		"in-test" :fam r/o io-open value rd-io2
		"out-test" :fam	w/o io-open value ow-io1
		"out-test" :fam	w/o :if-exists :overwrite io-open value	ow-io2
		"out-test" :fam	r/w :if-exists :error io-open value rw-io1
		"out-test" :fam	r/w :if-exists :rename io-open value rn-io1
     io-open-read ( name -- io )
	  Open file name for reading and return	new IO object.
     io-open-write ( name :key if-exists overwrite -- io )
	  Open file name for writing and return	new IO object.	For keyword
	  if-exists see	io-open.
     io-output?	( obj -- f )
	  Return #t if obj is an output	IO object, otherwise #f.
     io-pos-ref	( io --	pos )
	  Return current io object position.
     io-pos-set! ( io pos -- )
	  Set io object	position to pos.
     io-putc ( io c -- )
	  Write	character c to io object.
     io-read ( io -- line )
	  Return next line from	io object or #f	if EOF.
     io-readlines ( io -- array-of-lines )
	  Return the entire io object content as an array of strings, line by
	  line.
     io-reopen ( io1 name :key fam io1-fam -- io2 )
	  Return new IO	object as copy of io1 and close	io1.  If name is not a
	  string, for example #f or nil, use filename from io1.	 If keyword
	  fam was not given, use mode from io1,	otherwise use fam.  All	re-
	  strictions on	reopen apply, for example, a file opened for reading
	  cannot reopened for writing etc.
		"1-test" io-open-write value io1
		io1 "hello" io-write
		io1 "2-test" io-reopen value io2
		io1 io-closed? => #t
		io2 "world" io-write
		io2 io-close
		io2 io-closed? => #t
		"1-test" readlines => #( "hello" )
		"2-test" readlines => #( "world" )
		*stderr* "error.log" io-reopen value err-io
     io-rewind ( io -- )
	  Rewind position to begin of io object.
     io-seek ( io offset :key whence io-seek-set -- pos	)
	  Add offset to	the file position in io	object and return new posi-
	  tion.	 Keyword whence	can have the following values:
		SEEK_SET
		     offset counts from	begin of file (default)
		SEEK_CUR
		     offset counts from	current	position
		SEEK_END
		     offset counts from	end of file.
     io-tell ( io -- pos ) alias for io-pos-ref
     io-write (	io line	-- )
	  Write	line to	io object.
     io-write-format ( io fmt args -- )
	  Write	string built from fmt and array	fmt-args to io object.
     io-writelines ( io	array-of-lines -- )
	  Write	array-of-lines to io object.
     io= ( obj1	obj2 --	f )
	  Return #t if obj1 and	obj2 are IO objects with equal filenames,
	  modes	and file positions, otherwise #f.
     io? ( obj -- f )
	  Return #t if obj is an IO object, otherwise #f.
     readlines ( name -- array-of-lines	)
	  Open file name, read its content in an array,	close file and return
	  the array.
     writelines	( name array-of-lines -- )
	  Open file name, write	the content of array-of-lines to it and	close
	  file.

     File functions:
     io-open-file ( :key fam r/o args -- io )
	  General IO open function.  Open and return any IO object for io-
	  read/io-write	etc.  Keyword argument :fam defaults to	r/o.  See
	  make-soft-port for keyword arguments.
		:filename "foo"	io-open-file value io1
		:filename "foo"	:fam r/o io-open-file value io2
		:filename "bar"	:fam r/w io-open-file value io3
		:command "ls -lF" io-open-file value io4
		:command #( "ls" "-lF" ) io-open-file value io5
		:string	"test string" io-open-file value io6
		:soft-port "test" io-open-file value io7
     io-open-input-file	( :key args -- io )
	  General IO open function.  Return IO object for reading.  See
	  make-soft-input-port for keyword arguments.
		:filename "foo"	io-open-input-file value io1
		:command "ls -lF" io-open-input-file value io2
		:command #( "ls" "-lF")	io-open-input-file value io3
		:string	"test string" io-open-input-file value io4
		:soft-port "input-test"	io-open-input-file value io5
     io-open-output-file ( :key	args --	io )
	  General IO open function.  Return IO object for writing.  See
	  make-soft-output-port	for keyword arguments.
		:filename "foo"	io-open-output-file value io1
		:command "cat" io-open-output-file value io2
		:command #( "cat" ) io-open-output-file	value io3
		(dq(dq value s1
		:string	s1 io-open-output-file value io4
     make-file-input-port ( name -- io ) alias for io-open-read
     make-file-output-port ( name :key args -- io ) alias for io-open-write
     make-file-port ( name :key	args --	io ) alias for io-open

     Pipe functions:
     io-popen (	cmd :key fam r/o -- io )
	  Open pipe for	command	cmd and	return new IO object.  cmd may be a
	  string (with shell expansion)	or an array of strings.	 If keyword
	  fam was not given, open pipe read-only, otherwise use	fam.  See
	  io-open for fam.
		"ls -lAF ~/" io-popen value read-io1
		#( "ls"	"-lAF" "~/") io-popen value read-io2
		read-io1 io->string => "..."
		read-io1 io-close
		"cat" :fam w/o io-popen-write value write-io1
		write-io1 "hello" io-write
		write-io1 io-close
     io-popen-read ( cmd -- io )
	  Open read-only pipe for command cmd and return new IO	object.	 cmd
	  may be a string (with	shell expansion) or an array of	strings.
     io-popen-write ( cmd -- io	)
	  Open write-only pipe for command cmd and return new IO object.  cmd
	  may be a string (with	shell expansion) or an array of	strings.
     make-pipe-input-port ( cmd	-- io )	alias for io-popen-read
     make-pipe-output-port ( cmd -- io ) alias for io-popen-write
     make-pipe-port ( cmd :key args -- io ) alias for io-popen

     String functions:
     io-sopen (	str :key fam r/o -- io )
	  Open string with content string and return new IO object.  If	key-
	  word fam was not given, opens	string read-only, otherwise takes fam.
	  See io-open for fam.
		"test-string" value s1
		s1 io-sopen value read-io1
		read-io1 io-read => "test-string"
		read-io1 io-close
		s1 :fam	r/a io-sopen value append-io1
		append-io1 " with append content" io-write
		append-io1 io-rewind
		append-io1 io-read => "test-string with	append content"
		append-io1 io-close
		s1 .string => "test-string with	append content"
     io-sopen-read ( str -- io )
	  Open read-only string	with content str and return new	IO object.
     io-sopen-write ( str -- io	)
	  Open str for writing and return new IO object.
     make-string-input-port ( cmd -- io	) alias	for io-sopen-read
     make-string-output-port ( cmd :key	args --	io ) alias for io-sopen-write
     make-string-port (	str :key fam r/o -- io ) alias for io-sopen

     Socket functions:
     io-nopen (host :key port 1024 domain AF_INET -- io)
	  Connect to an	already	established server and return new IO object.
	  Raise	an a socket-error exception if an error	occured.  host is a
	  host name (AF_INET) or a path	name (AF_UNIX).	 If host is not	a
	  string, "localhost" will be used.  port is the connection port (de-
	  fault	1024) if domain	is AF_INET, otherwise unused, and domain can
	  be one of AF_INET (default) or AF_UNIX.  The socket is opened	with
	  domain, hardcoded second argument SOCK_STREAM, and hardcoded third
	  argument of 0, see socket(2) and connect(2) for more information.
		"localhost" :port 25 io-nopen value io
		io io-read => "220 fth-devel.net ESMTP Sendmail	..."
		io "HELP\r\n" io-write
		io io-read => "... (sendmail help output)"
		io io-close
		"ftp.freebsd.org" :port	21 io-nopen to io
		io io-read => "220 ftp.beastie.tdk.net FTP server ..."
		io "HELP\r\n" io-write
		io io-read => "... (ftpd help output)"
		io io-close
     make-socket-port (	host :key args -- io ) alias for io-nopen
     net-accept	( fd host domain -- io )
	  Accept a connection on a socket and return an	IO object after	estab-
	  lished connection.  fd is the	socket descriptor, host	can be an ar-
	  bitrary name,	its only use is	the name for the IO object, domain is
	  one of AF_INET or AF_UNIX.  This is used on the server side of a
	  socket connection.  Raise a socket-error exception if	accept(2)
	  fails.
     net-bind (	fd host	port domain -- )
	  Assign a name	to a socket.  fd is the	socket descriptor, host	is a
	  host name (AF_INET) or a path	name (AF_UNIX),	port is	the port if
	  domain is AF_INET, otherwise unused, and domain is one of AF_INET or
	  AF_UNIX.  This is used on the	server side of a socket	connection.
	  Raise	a socket-error exception if bind(2) fails.
     net-connect ( fd host port	domain -- io )
	  Connect to a server and return IO object after an established	con-
	  nection.  fd is the socket descriptor, host is a host	name (AF_INET)
	  or a name (AF_UNIX), port is the port	if domain is AF_INET, other-
	  wise unused, and domain is one of AF_INET or AF_UNIX.	 This is used
	  on the client	side of	a socket connection.  Raise a socket-error ex-
	  ception if connect(2)	fails.
     net-listen	( fd --	)
	  Inform the operating system that connection requests should be de-
	  livered.  fd is the previously opened	socket descriptor.  This is
	  used on the server side of a socket connection.  Raise a
	  socket-error exception if listen(2) fails.
     net-recv (	fd flags -- msg	)
	  Receive data via a socket and	return it.  fd is the socket descrip-
	  tor and flags	can be 0, MSG_PEEK, or MSG_OOB.	 Raise a socket-error
	  exception if recv(2) fails.
     net-recvfrom ( fd flags host port domain -- msg )
	  Receive data via a socket and	return it.  fd is the socket descrip-
	  tor, flags can be 0, MSG_PEEK, or MSG_OOB.  host is a	host name
	  (AF_INET) or a path name (AF_UNIX), port is the port if is AF_INET,
	  otherwise unused, and	domain is one of AF_INET or AF_UNIX.  Raise a
	  socket-error exception if recvfrom(2)	fails.
     net-send (	fd msg flags --	)
	  Send data via	a socket.  fd is the socket descriptor,	msg is the
	  data to send and flags can be	0, MSG_PEEK or MSG_OOB.	 Raise a
	  socket-error exception if send(2) fails.
     net-sendto	( fd msg flags host port domain	-- )
	  Send data via	a socket.  fd is the socket descriptor,	msg is the
	  data to send,	flags can be 0,	MSG_PEEK, or MSG_OOB.  host is a host
	  name (AF_INET) or a name (AF_UNIX), port is the port if domain is
	  AF_INET, otherwise unused, and domain	is one of AF_INET or AF_UNIX.
	  Raise	a socket-error exception if sendto(2) fails.
     net-shutdown ( fd how -- )
	  Close	socket connection.  fd is the socket descriptor	and how	is one
	  of SHUT_RD, SHUT_WR or SHUT_RDWR.  Raise a socket-error exception if
	  shutdown(2) fails.
     net-socket	( domain type -- fd )
	  Return socket	descriptor.  domain can	be AF_INET or AF_UNIX, type
	  can be SOCK_STREAM or	SOCK_DGRAM.  The third argument	to socket(2)
	  is 0 and cannot be set by the	user.  Raise a socket-error exception
	  if socket(2) fails.
		AF_INET	SOCK_STREAM net-socket value fd
		fd "localhost" 1024 AF_INET net-bind
		fd net-listen
		fd "localhost" AF_INET net-accept value	io

   Miscellaneous
     Constants:
     FICL_VM_STATE_INTERPRET
     FICL_VM_STATE_COMPILE
     INTERPRET_STATE alias for FICL_VM_STATE_INTERPRET
     COMPILE_STATE alias for FICL_VM_STATE_COMPILE
	  Return compile or interpret state value for comparison with global
	  variable state.
		state @	COMPILE_STATE =	if
			\ compile state	here
		else
			\ interpret state here
		then
     cell
	  Return bytes of one cell.
     dfloat
	  Return bytes of one dfloat.
     ficl-version
	  Return Ficl version string.
     float
	  Return bytes of one float (same as dfloat).
     fth-date
	  Return version date string.
     fth-version
	  Return full Fth version string.
     sfloat
	  Return bytes of one sfloat (same as dfloat).

     Features and Source files:
     *features*
	  Return array of all features.
     add-feature ( str -- )
	  Add str, a string or symbol, to *features* list.
		'snd add-feature
     add-load-lib-path ( path -- )
	  Add string path to *load-lib-path* array if not already there.
		"/home/mike/lib/fth" add-load-lib-path
     add-load-path ( path -- )
	  Add string path to *load-path* array if not already there.
		"/home/mike/share/fth" add-load-path
     apropos ( obj -- ary )
	  Return array of dictionary entries matching regexpression or string
	  obj.
		/do/ apropos =>	#( "doLocal" ... )
     dl-load ( "lib" "func" -- )
	  Load dynamic library lib and call its	function func.
		dl-load	dbm Init_dbm
     include ( "name" -- )
	  Load Forth source file name and add name to *loaded-files* if	it
	  wasn't already there.	 If file extension wasn't specified, use
	  `.fs'.  If name doesn't exist, try each entry	of *load-path* with
	  name.	 With include one can load a file more than once.  Before
	  loading name,	run hook before-load-hook.  After loading name,	run
	  hook after-load-hook.	 Raise a no-such-file exception	if file
	  doesn't exist, raise a load-error if an error	occured	during load.
		include	hello
     install ( "file" -- )
	  Install file in first	writeable path found in	*load-path* (*.fs[m])
	  or *load-lib-path* (*.so).  In the last example the trailing -e is
	  necessary because the	last occurrence	of -e will be compiled.
	  install is a parse word and won't work in compile state.
		install	snd-test.fs
		install	sndlib.so
		% fth -ve "install sndlib.so" -e ""
     install-file ( file -- )
	  Install file in first	writeable path found in	*load-path* (*.fs[m])
	  or *load-lib-path* (*.so).  A	warning	is given if no writable	path
	  is found.
		"snd-test.fs" install-file
		"sndlib.so" install-file
     load-init-file ( file -- )
	  If Forth source file exists in current or $HOME dir, load it,	other-
	  wise do nothing.
		".my-fth-init" load-init-file
     provided? ( obj --	f )
	  Return #t if obj, a string or	symbol,	exists in *features* list,
	  otherwise #f.
		'fth provided? => #t
		'foo provided? => #f
     require ( "name" -- )
	  If Forth source file name doesn't exist in array *loaded-files*,
	  load it and add name to *loaded-files*.  If file extension wasn't
	  specified, use `.fs'.	 If name doesn't exist,	try each entry of
	  *load-path* with name.  With require one can load a file only	one
	  time.	 Before	loading	name, run hook before-load-hook.  After	load-
	  ing name, run	hook after-load-hook.  Raise a no-such-file exception
	  if file doesn't exist, raise a load-error if an error	occured	during
	  load.
		require	hello
     unshift-load-lib-path ( path -- )
	  Prepend string path to *load-lib-path* array if not already there.
		"/home/mike/lib/fth" unshift-load-lib-path
     unshift-load-path ( path -- )
	  Prepend string path to *load-path* array if not already there.
		"/home/mike/share/fth" unshift-load-path

     Catch errors:
     fth-catch ( ?? obj	exc arg	-- ?? res )
	  Run proc or xt obj in	save environment.  If obj fails	with an	excep-
	  tion,	data and return	stack environments are recovered to the	state
	  before execution.  If	obj is #f, finishs immediately and returns #f.
	  The second argument exc may be a symbol, an exception, or #t.	 If
	  it's a symbol	or an exception, this will be catched, if it's #t, all
	  exceptions will be catched.  The third argument arg may be nil or a
	  return value.	 If arg	is nil,	the catched exception or #f will be
	  returned, if arg is any other	than nil, arg will be returned instead
	  of the catched exception; if arg is a	proc or	xt, this will be exe-
	  cuted	instead	of simply returned.  The stack effect must be (	retval
	  -- val ).
		3 :initial-element 0.3 make-array value	ary
		ary .array => #( 0.3 0.3 0.3 )
		ary 2 <'> array-ref  #t	 nil  fth-catch	=> 0.3 #f
		ary 4 <'> array-ref  'out-of-range  #t	fth-catch
		  => #(	0.3 0.3	0.3 ) 4	#t
		: ary-handler {	retval -- val }
			"from handler: %S\n" #(	retval ) fth-print
			#t ( return value )
		;
		ary 4 0.4 <'> array-set!
		    'out-of-range <'> ary-handler fth-catch
		  prints: => from handler: \
			#( 'out-of-range "array-set! (ary_set) arg 2: \
			4 is out of range" )
		  => 0.4 #t
		ary 2 0.4 <'> array-set!
		    'out-of-range <'> ary-handler fth-catch => #f
     fth-raise ( exc fmt args -- )
	  Raise	exception exc with text	built from fmt and args.  If fmt is a
	  format string	with N %s-format signs,	args should have N elements
	  with corresponding values.  If exc is	#f, reraise last exception.
		'bad-arity "%s:	%s args	required, got %s"
		    #( proc 2 3	) fth-throw
		  => #<bad-arity in test-proc: 2 args required,	got 3>
		#f #f #f fth-raise
		  => reraise last exception
     fth-throw ( exc args -- )
	  Throw	exception exc with text	built from args.  If args is not an
	  array, its string representation is used. If args is NIL or an empty
	  array, a default string is used.  If args is an array	with one ele-
	  ment,	this string is used. If	args is	an array and its first element
	  is a format string with N %s-format signs, args should have N	more
	  elements with	corresponding values.
		\
		\ ARGS:	any object
		\
		'bad-arity proc	fth-throw
		  => #<bad-arity in test-proc>
		\
		\ ARGS:	nil or #()
		\
		'bad-arity nil fth-throw
		  => #<bad-arity: proc has bad arity>
		\
		\ ARGS:	#( string )
		\
		'bad-arity #( "test-proc" ) fth-throw
		  => #<bad-arity in test-proc>
		\
		\ ARGS:	#( fmt arg1 arg2 arg3 )
		\
		'bad-arity #( "%s: %s args required, got %s"
			      proc
			      2
			      3	) fth-throw
		  => #<bad-arity in test-proc: 2 args required,	got 3>
     stack-reset ( ?? -- )
	  Reset	the data stack to initial state.

     Time functions:
     current-time ( -- secs )
	  Return time in seconds since 1970/01/01 as ficl2Unsigned.  See
	  time(3) for more information.
     gmtime ( secs -- ary )
	  Return array of eleven elements with secs converted to Greenwich
	  Mean Time.
		sec
		    seconds after minute (0-60)
		min
		    minutes after the hour (0-59)
		hour
		    hours since	midnight (0-23)
		mday
		    day	of the month (1-31)
		mon
		    months since January (0-11)
		year
		    years since	1900
		wday
		    days since Sunday (0-6)
		yday
		    days since January 1 (0-365)
		isdst
		    Daylight Savings Time flag
		tm_gmtoff
		    offset from	UTC in seconds
		tm_zone
		    timezone abbreviation
     localtime ( secs -- ary )
	  Return array of eleven elements with secs converted to local time,
	  see gmtime.
     mktime ( ary -- secs )
	  Return time constructed from values of ary.  ary may be #f or	an ar-
	  ray of up to eleven elements where single elements may be #f,	see
	  gmtime for array elements.
		#( 28 40 2 14 0	112 6 13 #f 3600 "CET" ) mktime	=> 1326505228
     strftime (	fmt secs -- str	)
	  Convert ficl2Unsigned	secs in	a date string corresponding to fmt.
	  The fmt string will be interpreted by	strftime(3).
		"%a %b %d %H:%M:%S %Z %Y" current-time strftime
		  => "Sat Jan 14 02:40:28 CET 2012"
     strptime (	str fmt	-- secs	)
	  Parse	str according to fmt and return	seconds	as ficl2Unsigned.
		"2012 01 14" "%Y %m %d"	strptime time->string
		  => "Sat Jan 14 02:40:28 CET 2012"
     time ( -- r )
	  Return real time, a ficlFloat.
     time->string ( secs -- str	)
	  Convert ficl2Unsigned	secs in	a date string in current local time.
		current-time time->string => "Sat Jan 14 02:40:28 CET 2012"
     time-reset	( -- )
	  Set global timeval struct variable to	current	time.
     utime ( --	utime stime )
	  Return user and system time as ficlFloats.  Raise a not-implemented
	  exception if times(3)	is not available.
		utime => 0.171875 0.0234375

     System information:
     date ( -- str )
	  Return date in default UNIX format as	a string.
     environ ( -- ary )
	  Return hash of all shell environment variables and their values.
     exec ( cmd	-- )
	  Replace current process by running cmd as shell command.  If cmd is
	  a string, shell expansion takes place	and $SHELL -- or sh if $SHELL
	  is empty -- executes cmd.  If	cmd is an array	of strings, no shell
	  expansion takes place	and cmd	NO 0 array-ref should be a program
	  name.
		lambda:	<{}> #(	"ls" "-lAF" ) exec ; fork
		lambda:	<{}> "ls -lAF [A-Z]*" exec ; fork
     fork ( xt -- pid )
	  Create child process and execute xt in the child.  The child process
	  returns nothing, parent returns child's process id.
		lambda:	<{}> "ls -lAF" exec ; fork value pid
		pid SIGKILL kill
     getegid ( -- id )
	  Return effective group id of calling process.
     getenv ( name -- value )
	  Return content of shell environment variable name as string or #f if
	  variable is not defined.
     geteuid ( -- id )
	  Return effective user	id of calling process.
     getgid ( -- id )
	  Return real group id of calling process.
     gethostname ( -- str )
	  Return name of current host.
     getlogin (	-- str )
	  Return name of user associated with current session.
     getpid ( -- id )
	  Return process id.
     getppid ( -- id )
	  Return parent	process	id.
     getservbyname ( str -- ary	)
	  Return array containing the service, an array	of aliases, the	port
	  number and the protocol.  Raise a not-implemented exception if
	  getservbyname(3) is not available.
		"smtp" getservbyname =>	#( "smtp" #( "mail" ) 25 "tcp" )
     getservbyport ( port -- ary )
	  Return array containing the service, an array	of aliases, the	port
	  number and the protocol.  Raise a not-implemented exception if
	  getservbyport(3) is not available.
		25 getservbyport => #( "smtp" #( "mail"	) 25 "tcp" )
     getuid ( -- id )
	  Return real user id of calling process.
     hostname (	-- )
     kill ( pid	sig -- )
	  Send signal sig to process ID	pid.  If pid is	zero, send sig to cur-
	  rent process.	 sig is	a number or a constant like SIGKILL.
     putenv ( name value -- )
	  Set value to shell environment variable name.
     setegid ( id -- )
	  Set effective	user id.  This is only permitted if id is equal	real
	  UID or effective UID or the effective	UID is that of the super user.
     seteuid ( id -- )
	  Set effective	group id.  This	is only	permitted if id	is equal real
	  GID or effective GID or the effective	UID is that of the super user.
     setgid ( id -- )
	  Set real group id.  This is only permitted if	id is equal real GID
	  or effective GID or the effective UID	is that	of the super user.
     sethostname ( str -- )
	  Set name of current host to str.  This call is restricted to the su-
	  per-user.  Raise a not-implemented exception if sethostname(3) is
	  not available.
     setuid ( id -- )
	  Set real user	id.  This is only permitted if id is equal real	UID or
	  effective UID	or the effective UID is	that of	the super user.
     signal ( sig xt --	old-xt )
	  Install xt for signal	sig as an signal handler and return old	han-
	  dler.	 XT must take one value	from the stack,	the signal, and	must
	  not return any value;	its stack effect is ( sig -- ).	 The old xt
	  handler can be preserved for later use.
		SIGINT lambda: { sig --	}
			." SIGINT received" cr
		; signal value old-xt
     sleep ( secs -- )
	  Pause	for secs seconds.
     wait ( -- pid )
	  Wait for child process and return its	process	ID.  Set global	read
	  only variable	exit-status to wait status.
     waitpid ( pid flags -- )
	  Wait for child process pid.  Set global read only variable exit-sta-
	  tus to wait status.  flags may be 0 or WNOHANG and WUNTRACED ored.
		1234 0 waitpid
		1234 WNOHANG waitpid
		1234 WNOHANG WUNTRACED or waitpid

     Getopt variables:
     optarg
	  Getopt set this variable to the option string	of an argument which
	  accepts options, otherwise to	#f.
     opterr
	  If #t, the default, getopt print error message in case of an error,
	  if #f, no message will be printed.
     optind
	  Getopt set this variable to the index	of the next element of the
	  *argv* array.
     optopt
	  If getopt finds unknown options or getopt misses required arguments,
	  it stores that option	in this	variable.

     Getopt functions:
     getopt ( argv opts	-- c )
	  Return next option character from command line options.  See
	  EXAMPLES for an getopt example.
     getopt-long ( argv	opts longopts -- c )
	  Return next option character from command line options.
		: long-test
			#f #f {	bflag ffile }
			#f to opterr
			#( #( "flag" no-argument <char>	b )
			   #( "file" required-argument <char> f	) ) { opts }
			begin
				*argv* "bf:" opts getopt-long (	ch ) dup
			while (	ch )
				case
					<char> b of #t	   to bflag endof
					<char> f of optarg to ffile endof
					<char> ? of
						"-%c requires an argument"
						    #( optopt )	fth-warning
					endof
				endcase
			repeat drop ( ch )
			optind 0 ?do *argv* array-shift	drop loop
			*argv* array-length to *argc*
			"-b, --flag (default #f): %s\n"	#( bflag ) fth-print
			"-f, --file (default #f): %s\n"	#( ffile ) fth-print
		;

     Information and configuration:
     (bye) ( n -- )
	  The exit hook	fth_exit_hook will be called if	set, all procs regis-
	  tered	for at-exit will be executed and the current process will be
	  terminated with exit code n.
     .cflags ( -- )
	  Print	compiler flags to compile libfth.so to other applications.
     .libs ( --	)
	  Print	linker flags to	link libfth.so to other	applications.
     .long-version ( --	)
	  Print	long package version.
     .memory ( -- )
	  Print	used and free dictionary cells.
     .prefix ( -- )
	  Print	installation prefix path.
     .version (	-- )
	  Print	package	version	number.
     at-exit ( obj -- )
	  obj, an proc or xt, will be called by	Fth's exit function.  More
	  than one calls to at-exit are	possible, all procs or xts will	be
	  called in order.  The	stack effect of	obj must be ( -- ).
		lambda:	<{ -- }> "test.file" file-delete ; at-exit
     config-cflags ( --	str )
	  Return compiler flags	to compile libfth.so to	other applications.
     config-libs ( -- str )
	  Return linker	flags to link libfth.so	to other applications.
     config-prefix ( --	str )
	  Return installation prefix path.
     configure-args ( -- str )
	  Return configure arguments.
     ver ( -- addr len )
	  Return fth-version as	a Forth	string with addr len.
		ver type => "1.3.1 (19-Mar-2012) [i386-portbld-freebsd9.0]"

   Numbers
     Number predicates:
     bignum? ( obj -- f	)
     complex? (	obj -- f )
     even? ( obj -- f )
     exact? ( obj -- f )
     fixnum? ( obj -- f	)
     float? ( obj -- f )
     inexact? (	obj -- f )
     inf? ( obj	-- f )
     integer? (	obj -- f )
     long-long?	( obj -- f )
     nan? ( obj	-- f )
     number? ( obj -- f	)
     odd? ( obj	-- f )
     prime? ( obj -- f )
     ratio? ( obj -- f )
     rational? ( obj --	f ) alias for ratio?
     ulong-long? ( obj -- f )
     unsigned? ( obj --	f )
	  Return #t if a given object is of corresponding type,	otherwise #f.

     Miscellaneous math	functions:
     >bignum ( x -- b )	alias for s_b
	  Convert any number x to a bignum object.
     >c	( x -- c )
	  Convert any number x to a complex object.
     >complex (	r1 r2 -- c )
	  Return complex object	with real r1 and image r2.
     >llong ( x	-- d ) alias fo	s_d
	  Convert any number x to a llong object.
     >ratio ( x	-- q ) alias for s_q
	  Convert any number x to a ratio object.
     denominator ( x --	n )
	  Return denominator of	x or 1.
     exact->inexact ( x	-- r )
	  Convert x to an inexact number.
     imag-ref (	x -- r )
	  Return the image part	of Ar x	.
     image-ref ( x -- r	) alias	for imag-ref
     inexact->exact ( x	-- n )
	  Convert x to an exact	number.
     inf ( -- inf )
	  Return Infinity.
     make-bignum ( x --	b )
	  Return a new bignum object.
     make-long-long ( val -- d ) alias for s_d
	  Return new llong object (ficl2Integer) from val.
     make-polar	( real theta --	c )
	  Return polar complex object from real	and theta.
     make-ratio	( num den -- q )
	  Return a new ratio object with numerator num and denumerator den.
     make-rectangular (	r1 r2 -- c ) alias for _complex
     make-ulong-long ( val -- ud ) alias for s_ud
	  Return new ullong object (ficl2Unsigned) from	val.
     nan ( -- NaN )
	  Return Not-A-Number.
     numerator ( x -- n	)
	  Return numerator of x	or 0.
     rationalize ( x err -- y )
	  Return inexact number	within err of x.
     real-ref (	x -- r )
	  Return the real part of x.

     Pseudo randomize number functions:
     rand-seed-ref ( --	seed )
	  Return content of the	seed variable fth_randx.
     rand-seed-set! ( seed -- )
	  Set seed to the seed variable	fth_randx.
     frandom ( r -- -r...+r )
	  Return pseudo	randomized value between -r and	+r.
     random ( r	-- 0.0..r )
	  Return pseudo	randomized value between 0.0 and r.

     These formatted number output functions will by convention	add a space
     after the number:
     .r	( n1 n2	-- )
	  Print	integer	n1 in a	right-adjusted field of	n2 characters.
		17 3 .r	=> | 17	|
     c.	( c -- )
	  Print	complex	number c.
		17.0+1.0i c. =>	|17.000000+1.000000i |
     d.	( d -- )
	  Print	(Forth)	double d (ficl2Integer).
		17 d. => |17 |
     d.r ( d n -- )
	  Print	(Forth)	double d (ficl2Integer)	in a right-adjusted field of n
	  characters.
		17 3 d.r => | 17 |
     f.r ( r n -- )
	  Print	float r	with n digits after decimal point.
		17.0 3 f.r => |17.000 |
     bn. ( b --	)
	  Print	bignum number.
		17.0 bn. => |17	|
     q.	( q -- )
	  Print	rational number.
		17.0 q.	=> |17/1 |
     u.r ( u n -- )
	  Print	unsigned integer u in a	right-adjusted field of	n characters.
		17 3 u.r => | 17 |
     ud. ( ud -- )
	  Print	(Forth)	unsigned double	ud (ficl2Unsigned).
		17 ud. => |17 |
     ud.r ( ud n -- )
	  Print	(Forth)	unsigned double	ud (ficl2Unsigned) in a	right-adjusted
	  field	of n characters.
		17 3 ud.r => | 17 |
     uf.r ( r len-all len-after-comma -- )
	  Print	float r	in a right-adjusted field of len-all characters	with
	  len-after-comma digits.
		17.0 8 3 uf.r => | 17.000 |
		17.0 8 2 uf.r => |  17.00 |

     Comparison:
     0<	( n -- f )
     0<= ( n --	f )
     0<> ( n --	f )
     0=	( n -- f )
     0=> ( n --	f )
     0>	( n -- f )
     negative? ( n -- f	) alias	for 0_
     positive? < ( n --	f ) alias for 0_=
     zero? ( n -- f ) alias for	0=
	  Comparison between integer (ficlInteger) and zero.
     < ( n1 n2 -- f )
     <=	( n1 n2	-- f )
     <>	( n1 n2	-- f )
     = ( n1 n2 -- f )
     =>	( n1 n2	-- f )
     > ( n1 n2 -- f )
     negative? ( n -- f	) alias	for 0_
     positive? < ( n --	f ) alias for 0_=
     zero? ( n -- f ) alias for	0=
	  Comparison between two integers (ficlInteger).
     u<	( u1 u2	-- f )
     u<= ( u1 u2 -- f )
     u<> ( u1 u2 -- f )
     u=	( u1 u2	-- f )
     u=> ( u1 u2 -- f )
     u>	( u1 u2	-- f )
	  Comparison between two unsigned integers (ficlUnsigned).
     d0< ( d --	f )
     d0<= ( d -- f )
     d0<> ( d -- f )
     d0= ( d --	f )
     d0> ( d --	f )
     d0>= ( d -- f )
     dnegative?	( d -- f ) alias for d0_
     dpositive?	< ( d -- f ) alias for d0_=
     dzero? ( d	-- f ) alias for d0=
	  Comparison between long integer (ficl2Integer) and zero.  d can be
	  any type of number but should	fit in ficl2Integer.
		1 d0>= => #t
		1.0 d0<	=> #f
     d<	( d1 d2	-- f )
     d<= ( d1 d2 -- f )
     d<> ( d1 d2 -- f )
     d=	( d1 d2	-- f )
     d>	( d1 d2	-- f )
     d>= ( d1 d2 -- f )
	  Comparison between two long integers (ficl2Integer).	d1 and d2 can
	  be any type of number	but should fit in ficl2Integer.
		1 2.0 d< => #t
		1.0 2 d= => #f
     du< ( ud1 ud2 -- f	)
     du<= ( ud1	ud2 -- f )
     du<> ( ud1	ud2 -- f )
     du= ( ud1 ud2 -- f	)
     du> ( ud1 ud2 -- f	)
     du>= ( ud1	ud2 -- f )
	  Comparison between two long unsigned integers	(ficl2Unsigned).  ud1
	  and ud2 can be any type of number but	should fit in ficl2Unsigned.
		1 2.0 du< => #t
		1.0 2 du= => #f
     c0<> ( c -- f )
     c0= ( c --	f )
	  Comparison between a complex number and zero.	 c can be any type of
	  number but should fit	in ficlComplex.
		1.0+1.0i c0<> => #t
		0.0+0.0i c0= =>	#t
		1 c0= => #f
     c<> ( c1 c2 -- f )
     c=	( c1 c2	-- f )
	  Comparison between two numbers.  c1 and c2 can be any	type of	number
	  but should fit in ficlComplex.
		1.0+1.0i 1i c= => #t
		1+0i 2.0 c<> =>	#t
		1 1+0i c= => #t
     b0< ( b --	f )
     b0<= ( b -- f )
     b0<> ( b -- f )
     b0= ( b --	f )
     b0> ( b --	f )
     b0>= ( b -- f )
	  Comparison between an	arbitrary precision number and zero.  b	can be
	  any type of number.
     b<	( b1 b2	-- f )
     b<= ( b1 b2 -- f )
     b<> ( b1 b2 -- f )
     b=	( b1 b2	-- f )
     b>	( b1 b2	-- f )
     b>= ( b1 b2 -- f )
	  Comparison between two arbitrary precision big numbers.  b1 and b2
	  can be any type of number.
     q0< ( q --	f )
     q0<= ( q -- f )
     q0<> ( q -- f )
     q0= ( q --	f )
     q0> ( q --	f )
     q0>= ( q -- f )
	  Comparison between an	arbitrary precision rational number and	zero.
	  q can	be any type of number.
     q<	( q1 q2	-- f )
     q<= ( q1 q2 -- f )
     q<> ( q1 q2 -- f )
     q=	( q1 q2	-- f )
     q>	( q1 q2	-- f )
     q>= ( q1 q2 -- f )
	  Comparison between two arbitrary precision rational numbers.	q1 and
	  q2 can be any	type of	number.

     Convertion	between	number types:
     >bignum ( x -- b )
     f>b ( r --	b ) alias for _bignum
     s>b ( n --	b ) alias for _bignum
	  Convert any number to	a bignum object	(ficlBignum).
     >c	( x -- c )
     f>c ( r --	c ) alias for _c
     q>c ( q --	c ) alias for _c
     s>c ( n --	c ) alias for _c
	  Convert any number to	a complex object (ficlComplex).
     f>d ( r --	d ) alias for s_d
     s>d ( n --	d )
	  Convert any number to	a llong	object (ficl2Integer).
     f>ud ( r -- ud ) alias for	s_ud
     s>ud ( n -- ud )
	  Convert any number to	an ullong object (ficl2Unsigned).
     b>f ( b --	r ) alias for s_f
     c>f ( c --	r ) alias for s_f
     d>f ( d --	r ) alias for s_f
     q>f ( q --	r ) alias for s_f
     s>f ( n --	r )
	  Convert any number to	a float	object (ficlFloat).
     >ratio ( c	-- q ) alias for s_q
     c>q ( c --	q ) alias for s_q
     f>q ( r --	q ) alias for s_q
     s>q ( n --	q )
	  Convert any number to	a ratio	object (ficlRatio).
     b>s ( b --	n ) alias for f_s
     c>s ( c --	n ) alias for f_s
     d>s ( d --	n ) alias for f_s
     f>s ( r --	n )
     q>s ( q --	n ) alias for f_s
	  Convert any number to	Forth single word set number (ficlInteger).

     Math functions:
     1+	( n1 --	n2 )
     1-	( n1 --	n2 )
     2+	( n1 --	n2 )
     2-	( n1 --	n2 )
     2*	( n1 --	n2 )
     2/	( n1 --	n2 )
     abs ( n1 -- n2 )
     negate ( n1 -- n2 )
	  One argument integer (ficlInteger) operators.
     + ( n1 n2 -- n3 )
     - ( n1 n2 -- n3 )
     * ( n1 n2 -- n3 )
     / ( n1 n2 -- n3 )
     max ( n1 n2 -- n3 )
     min ( n1 n2 -- n3 )
	  Two argument integer (ficlInteger) operators.
     d2* ( d1 -- d2 )
     d2/ ( d1 -- d2 )
     dabs ( d1 -- d2 )
     dnegate ( d1 -- d2	)
	  One argument long integer (ficl2Integer) operators.  d1 can be any
	  type of number but should fit	in ficl2Integer.
     d+	( d1 d2	-- d3 )
     d-	( d1 d2	-- d3 )
     d*	( d1 d2	-- d3 )
     d/	( d1 d2	-- d3 )
     dmax ( d1 d2 -- d3	)
     dmin ( d1 d2 -- d3	)
	  Two argument long integer (ficl2Integer) operators.  d1 and d2 can
	  be any type of number	but should fit in ficl2Integer.
     1/f ( r1 -- r2 )
     f2* ( r1 -- r2 )
     f2/ ( r1 -- r2 )
     fabs ( r1 -- r2 )
     fnegate ( r1 -- r2	)
	  One argument real number (ficlFloat) operators.  r1 can be any type
	  of number but	should fit in ficlFloat.
     f+	( r1 r2	-- r3 )
     f-	( r1 r2	-- r3 )
     f*	( r1 r2	-- r3 )
     f/	( r1 r2	-- r3 )
     fmax ( r1 r2 -- r3	)
     fmin ( r1 r2 -- r3	)
	  Two argument real numbers (ficlFloat)	operators.  r1 and r2 can be
	  any type of number but should	fit in ficlFloat.
     f** ( r1 r2 -- r3 )
     fabs ( r1 -- r2 )
     facos ( r1	-- r2 )
     facosh ( r1 -- r2 )
     falog ( r1	-- r2 )
     fasin ( r1	-- r2 )
     fasinh ( r1 -- r2 )
     fatan ( r1	-- r2 )
     fatan2 ( r1 r2 -- r3 )
     fatanh ( r1 -- r2 )
     fceil ( r1	-- r2 )
     fcos ( r1 -- r2 )
     fcosh ( r1	-- r2 )
     fexp ( r1 -- r2 )
     fexpm1 ( r1 -- r2 )
     flog ( r1 -- r2 )
     flog10 ( r1 -- r2 )
     flog2 ( r1	-- r2 )
     flog1p ( r1 -- r2 )
     flogp1 ( r1 -- r2 ) alias for flog1p
     floor ( r1	-- r2 )
     fpow ( r1 r2 -- r3	) alias	for f**
     fround ( r1 -- r2 )
     fsin ( r1 -- r2 )
     fsincos ( r1 -- r2	r3 )
     fsinh ( r1	-- r2 )
     fsqrt ( r1	-- r2 )
     ftan ( r1 -- r2 )
     ftanh ( r1	-- r2 )
     ftrunc ( r1 -- r2 )
	  Math library functions for real numbers.  fsincos returns sin(r1)
	  and cos(r1).	r1 and probable	second argument	r2 can be any type of
	  number but should fit	in ficlFloat.
     1/c ( c1 -- c2 )
     c*	( c1 c2	-- c3 )
     c** ( c1 c2 -- c3 )
     c+	( c1 c2	-- c3 )
     c-	( c1 c2	-- c3 )
     c/	( c1 c2	-- c3 )
     cabs ( c1 -- c2 )
     cabs2 ( c1	-- c2 )
     cacos ( c1	-- c2 )
     cacosh ( c1 -- c2 )
     carg ( c1 -- c2 )
     casin ( c1	-- c2 )
     casinh ( c1 -- c2 )
     catan ( c1	-- c2 )
     catan2 ( c1 c2 -- c3 )
     catanh ( c1 -- c2 )
     ccos ( c1 -- c2 )
     ccosh ( c1	-- c2 )
     cexp ( c1 -- c2 )
     clog ( c1 -- c2 )
     clog10 ( c1 -- c2 )
     conj ( c1 -- c2 )
     conjugate ( c1 -- c2 ) alias for conj
     cpow ( c1 c2 -- c3	) alias	for c**
     csin ( c1 -- c2 )
     csinh ( c1	-- c2 )
     csqrt ( c1	-- c2 )
     ctan ( c1 -- c2 )
     ctanh ( c1	-- c2 )
     magnitude ( c1 -- c2 )
	  Math library functions for complex numbers.  c1 and probable second
	  argument c2 can be any type of number	but should fit in ficlComplex.
     b2* ( b1 -- b2 )
     b2/ ( b1 -- b2 )
     babs ( b1 -- b2 )
     bnegate ( b1 -- b2	)
	  One argument arbitrary precision bignum functions.  b1 can be	any
	  type of number.
     b+	( b1 b2	-- b3 )
     b-	( b1 b2	-- b3 )
     b*	( b1 b2	-- b3 )
     b/	( b1 b2	-- b3 )
     b** ( b1 b2 -- b3 )
     bmax ( b1 b2 -- b3	)
     bmin ( b1 b2 -- b3	)
     bpow ( b1 b2 -- b3	) alias	for b**
	  Two argument arbitrary precision bignum functions.  b1 and b2	can be
	  any type of number.
     bgcd ( x y	-- z )
	  Greatest common divisor.  x and y can	be any type of number, z is of
	  type bignum.
     blcm ( x y	-- z )
	  Least	common multiple.  x and	y can be any type of number, z is of
	  type bignum.
     broot ( b1	u -- b2	n )
	  Returns the integer part of the u th root of b1.  On top of stack 1
	  if result is exact, otherwise	0.
     bsqrt ( b1	-- b2 n	)
	  Returns the integer part of the square root of b1.  On top of	stack
	  1 if result is exact,	otherwise 0.
     bmod ( b1 b2 -- b3	n )
	  b3 becomes b1	modulo b2.
     b/mod ( b1	b2 -- b3 b4 n )
	  Divide b1 by b2 where	b3 becomes the remainder and b4	becomes	the
	  quotient.
     blshift ( b1 n -- b2 )
     brshift ( b1 n -- b2 )
	  Shifts arbitrary precision number b1 n bits to left resp. right.  b1
	  can be any type of number while n has	to be an integer (ficlInte-
	  ger).
     1/q ( q1 -- q2 )
     qabs ( q1 -- q2 )
     qceil ( q1	-- q2 )
     qfloor ( q1 -- q2 )
     qnegate ( q1 -- q2	)
	  One argument arbitrary precision rational functions.	q1 can be any
	  type of number.
     q+	( q1 q2	-- q3 )
     q-	( q1 q2	-- q3 )
     q*	( q1 q2	-- q3 )
     q/	( q1 q2	-- q3 )
     q** ( q1 q2 -- q3 )
     qpow ( q1 q2 -- q3	) alias	for q**
	  Two argument arbitrary precision rational functions.	q1 and q2 can
	  be any type of number.
     fegetround	( -- n )
     fesetround	( n -- )
	  Return or set	current	floating-point rounding	mode, one of:
	  FE_TONEARES
	  FE_DOWNWARD
	  FE_UPWARD
	  FE_TOWARDZERO
	  See fenv(3), fegetround(3) and fesetround(3).

     Constants:
     euler     e (~2.71828)
     half-pi   pi/2 (~1.5708)
     ln-ten    log(10) (~2.30259)
     ln-two    log(2) (~0.693147)
     pi	       pi (~3.14159)
     sqrt-two  sqrt(2) (~1.41421)
     two-pi    pi*2 (~6.28319)

   Object types
     backtrace ( -- )
	  Print	last word list from stack frame	to error output.
     bt	( -- ) alias for backtrace
     frame-depth ( -- n	)
	  Internal global variable.  Return the	current	frame depth.
     object-print-length ( -- n	)
	  Return the number of objects to print	for objects like array,	list,
	  hash.	 Default value is 12.
     set-object-print-length ( n -- )
	  Set number of	objects	to print for objects like array, list, hash to
	  n.  If n is negative,	print all elements of a	given object.
     stack-level ( -- n	) alias	for frame-depth

     Garbage collection	words:
     gc-mark ( obj -- obj )
	  Mark obj to protect it from garbage collection on next gc-run.
     gc-marked?	( obj -- f )
	  Return #t if obj is an instance and mark flag	is set.	 All new cre-
	  ated objects have mark flag set.
     gc-off ( -- )
	  Turn off garbage collection.	The return code	is meaningless in
	  Forth.
     gc-on ( --	)
	  Turn on garbage collection.  The return code is meaningless in
	  Forth.
     gc-permanent-objects ( -- ary )
	  Return array of all permanent	objects.
     gc-permanent? ( obj -- f )
	  Return #t if obj is an instance and permanent	flag is	set like con-
	  stants.
     gc-protect	( obj -- obj )
	  Protect obj from garbage collection until gc-unprotect.
     gc-protected-objects ( -- ary )
	  Return array of all protected	objects.
     gc-protected? ( obj -- f )
	  Return #t if obj is an instance and protected	flag is	set.
     gc-run ( -- )
	  Run garbage collection immediately.
     gc-stats (	-- )
	  Print	garbage	collection statistics.
		permanent
		     permanent protected objects like constants
		protected
		     temporary protected objects like gc-protected
		marked
		     marked to protect from next freeing
		freed
		     freed objects
		insts
		     all other nonfreed	objects
		buffer
		     size of entire allocated buffer-array
		gc stack
		     stack frame level
     gc-unmark ( obj --	obj )
	  Unmark obj to	unprotect it from garbage collection on	next gc-run.
     gc-unprotect ( obj	-- obj )
	  Unprotect obj	from garbage collection.

     Object type and instance words:
     instance-gen-ref (	obj -- gen )
	  Return GEN-struct of obj.
     instance-obj-ref (	obj -- gen )
	  Return object	type of	obj.
     instance-of? ( obj	type --	f )
	  Return #t if obj is an instance of type, otherwise #f.
     instance? ( obj --	f )
	  Return #t if obj is an instance, otherwise #f.
     make-instance ( gen obj --	instance )
	  Return new instance of Object	type obj with gen wrapped in.
     make-object-type (	name --	object-type )
	  Create new object type name.	Add name to feature environment	list,
	  create a constant fth-name of	object-type and	return new object-type
	  name.	 The new created object-type can be used to bind functions to
	  it.
     object-type-ref ( obj -- struct )
	  Return object	struct of object-type obj.
     object-type? ( obj	-- f )
	  Return #t if obj is an Object	type, otherwise	#f.
     object-types ( -- ary )
	  Return array of all object names known to the	system.

     Object set	words:
     set-object->array ( xt obj	-- )
	  Set xt as object->array function for obj type.
     set-object->string	( xt obj -- )
	  Set xt as object->string function for	obj type.
     set-object-apply (	xt obj arity --	)
	  Set xt as object-apply function for obj type.
     set-object-copy ( xt obj -- )
	  Set xt as object-copy	function for obj type.
     set-object-dump ( xt obj -- )
	  Set xt as object-dump	function for obj type.
     set-object-equal-p	( xt obj -- )
	  Set xt as object-equal? function for obj type.
     set-object-free ( xt obj -- )
	  Set xt as gc free function for obj type.
     set-object-inspect	( xt obj -- )
	  Set xt as object-inspect function for	obj type.
     set-object-length ( xt obj	-- )
	  Set xt as object-length function for obj type.
     set-object-mark ( xt obj -- )
	  Set xt as gc mark function for obj type.
     set-object-value-ref ( xt obj -- )
	  Set xt as object-ref function	for obj	type.
     set-object-value-set ( xt obj -- )
	  Set xt as object-set!	function for obj type.

     General object words
     .inspect (	obj -- )
	  Print	inspect	string of obj.
     .object-name ( obj	-- )
	  Print	object name of obj to current stdout.
     apply ( obj args -- result	) alias	for object-apply
     cycle-ref ( obj --	val )
	  Return value at current cycle-index of obj and increment cycle-in-
	  dex.	Cycle through content of obj from first	to last	entry and
	  start	again at the beginning etc.
     cycle-set!	( obj value -- )
	  Store	value at current cycle-index of	obj and	increment cycle-index.
	  Cycle	through	content	of obj from first to last entry	and start
	  again	at the beginning etc.
     cycle-start! ( obj	index -- )
	  Set cycle-index of obj to index.
     cycle-start0 ( obj	-- )
	  Set cycle-index of obj to zero.
     cycle-start@ ( obj	-- index )
	  Return current cycle-index of	obj.
     detect ( obj key -- value ) alias for object-find
     empty? ( obj -- f ) alias for object-empty?
     equal? ( obj1 obj2	-- f ) alias for object-equal?
     first-ref ( obj --	val )
	  Return first element of obj.	Raise an out-of-range exception	if
	  length of obj	is less	than 1.
     first-set!	( obj value -- )
	  Store	value to first element of obj.	Raise an out-of-range excep-
	  tion if length of obj	is less	than 1.
     hash-id ( obj -- id )
	  Return hash id computed from string representation of	obj.  Objects
	  with the same	content	have the same id.
     index ( obj key --	index )	alias for object-index
     last-ref (	obj -- val )
	  Return last element of obj.  Raise an	out-of-range exception if
	  length of obj	is less	than 1.
     last-set! ( obj value -- )
	  Store	value to last element of obj.  Raise an	out-of-range exception
	  if length of obj is less than	1.
     length ( obj -- len ) alias for object-length
     member? ( obj key -- f ) alias for	object-member?
     object->array ( obj -- ary	)
	  Return obj as	array.
     object->string ( obj -- str )
	  Return string	representation of obj.
     object-apply ( obj	args --	result )
	  Run apply on obj with	args as	arguments.  args can be	an array of
	  arguments or a single	argument.  The number of args must fit apply's
	  definition.  The next	two examples require each 1 argument:
		fth_set_object_apply(vct_tag, vct_ref, 1, 0, 0); /* C */
		<'> enved-ref fth-enved	1 set-object-apply \ Forth
     object-copy ( obj1	-- obj2	)
	  Return copy of obj1.	Copy any element if obj1 is an instance.
     object-debug-hook ( obj --	hook )
	  Return debug-hook member of obj if there is any, otherwise #f.  The
	  hook has the stack effect ( inspect-string obj -- new-str ).	Every
	  object can set this hook.  If	set, it	will be	called on inspecting
	  the object with the inspect string as	first argument.	 If there are
	  more than one	hook procedures, all of	them will be called feeded
	  with the new string previously returned.
		#( 0 1 ) value ary
		ary .inspect =>	#<array[2]:  #<fixnum: 0> #<fixnum: 1>>
		ary object-debug-hook lambda: <{ str obj -- new-str }>
			"debug-inspect:	%s" #( obj ) string-format
		; add-hook!
		ary .inspect =>	#<debug-inspect: #( 0 1	)>
		ary object-debug-hook hook-clear
		ary .inspect =>	#<array[2]:  #<fixnum: 0> #<fixnum: 1>>
     object-dump ( obj -- str )
	  Return dump string of	obj which one can eval to get the object back.
     object-empty? ( obj -- f )
	  Return #t if length of obj is	zero, otherwise	#f.
     object-equal? ( obj1 obj2 -- f )
	  Return #t if obj1 and	obj2 have equal	content, otherwise #f.
     object-find ( obj key -- value )
	  Search for key in obj	and return corresponding value or #f if	not
	  found.
     object-id ( obj --	id )
	  Return object	id of obj, a uniq number.
     object-index ( obj	key -- index )
	  Search for key in obj	and return index or -1 if not found.
     object-inspect ( obj -- str )
	  Return inspect string	of obj.
     object-length ( obj -- len	)
	  Return length	of obj.
     object-member? ( obj key -- f )
	  Return #t if key is present in obj, otherwise	#f.
     object-name ( obj -- name )
	  Return object	type name of OBJ as a string.
     object-range? ( obj index -- f )
	  Return #t if index is	in range of obj, otherwise #f.	If index is
	  negative, return #f.
     object-ref	( obj index -- val )
	  Return value at index	from obj.  If obj is of	a type which can have
	  multiple elements, an	array for example, return value	at index.  If
	  obj is of a type which consists of only one element, a fixnum	for
	  example, ignore index	and return obj itself.
     object-set! ( obj index value -- )
	  Set value at index to	obj.  If obj is	of a type which	can have mul-
	  tiple	elements, an array for example,	set value at position index.
	  If obj is of a type which consists of	only one element, a fixnum for
	  example, do nothing.
     object-set*! ( obj	index value -- )
	  Multiply value to value at index of obj.  Value may be any number
	  (ficlInteger,	ficlFloat, ficlRatio or	ficlComplex).
     object-set+! ( obj	index value -- )
	  Add value to value at	index of obj.  Value may be any	number (fi-
	  clInteger, ficlFloat,	ficlRatio or ficlComplex).
     object-set-! ( obj	index value -- )
	  Subtract value from value at index of	obj.  Value may	be any number
	  (ficlInteger,	ficlFloat, ficlRatio or	ficlComplex).
     object-set/! ( obj	index value -- )
	  Divide value at index	of obj by value.  Value	may be any number (fi-
	  clInteger, ficlFloat,	ficlRatio or ficlComplex).
     object-sort ( obj cmp-xt -- ary )
	  Convert obj to an array, sort	and return it.	cmp-xt compares	two
	  items	A and B	and should return a negative integer if	A < B, 0 if A
	  == B,	and a positive integer if A > B.
		: numb-sort { val1 val2	-- n }
			val1 val2 < if
				-1
			else
				val1 val2 > if
					1
				else
					0
				then
			then
		;
		#( 6 2 8 1 ) <'> numb-sort object-sort => #( 1 2 6 8 )
     range? ( obj index	-- f ) alias for object-range?
     second-ref	( obj -- val )
	  Return second	element	of obj.	 Raise an out-of-range exception if
	  length of obj	is less	than 2.
     second-set! ( obj value --	)
	  Store	value to second	element	of obj.	 Raise an out-of-range excep-
	  tion if length of obj	is less	than 2.
     sort ( obj	cmp-xt -- ary )	alias for object-sort
     third-ref ( obj --	val )
	  Return third element of obj.	Raise an out-of-range exception	if
	  length of obj	is less	than 3.
     third-set!	( obj value -- )
	  Store	value to third element of obj.	Raise an out-of-range excep-
	  tion if length of obj	is less	than 3.
     xmobj? ( obj -- f )
	  Return #t if obj is an XmObj (xm.c), otherwise #f.  It is a very
	  special Snd XM test.	See snd(1) for more information.

     Predicates:
     boolean? (	obj -- f )
	  Return #t if obj is #t or #f,	otherwise #f.
     false? ( obj -- f )
	  Return #t if obj is #f, otherwise #f.
     nil? ( obj	-- f )
	  Return #t if obj is nil, otherwise #f.
     true? ( obj -- f )
	  Return #t if obj is #t, otherwise #f.
     undef? ( obj -- f )
	  Return #t if obj is undef, otherwise #f.

   Ports
     make-soft-input-port ( :key args -- prt )
	  Return new input soft	port IO	object with corresponding procs.  Not
	  all procs are	required.  Recognized keyword options:
		:close ( -- )
		     Proc for closing soft port.
		:flush ( -- )
		     Proc for flushing port buffer.
		:port-name "soft-port"
		     Name for IO object, default is "soft-port".
		:read-char ( --	c )
		     Proc for reading one character.
		:read-line ( --	line )
		     Proc for reading one line.
	  Input	example, *stdin* IO object is preserved	for later use:
		:port-name "sndin"
		:read-char lambda: <{ -- c }> *stdin* io-getc ;
		:read-line lambda: <{ -- line }> *stdin* io-read ;
		make-soft-port set-*stdin* value stdin-io
     make-soft-output-port ( :key args -- prt )
	  Return new output soft port IO object	with corresponding procs.  Not
	  all procs are	required.  Recognized keyword options:
		:close ( -- )
		     Proc for closing soft port.
		:flush ( -- )
		     Proc for flushing port buffer.
		:port-name "soft-port"
		     Name for IO object, default is "soft-port".
		:write-char ( c	-- )
		     Proc for writing one character.
		:write-line ( line -- )
		     Proc for writing one line.
	  Output example, *stdout* IO object is	preserved for later use:
		:port-name "sndout"
		:write-char lambda: <{ c -- }> c snd-print .stdout ;
		:write-line lambda: <{ line -- }> line snd-print .stdout ;
		make-soft-port set-*stdout* value stdout-io
     make-soft-port ( :key args	-- prt )
	  Return new soft port IO object with corresponding procs.  Not	all
	  procs	are required.  Recognized keyword options:
		:close ( -- )
		     Proc for closing soft port.
		:fam r/o | w/o (default) | r/w
		     For read-only use constant	r/o, for write-only use	con-
		     stant w/o and for read-write use constant r/w.
		:flush ( -- )
		     Proc for flushing port buffer.
		:port-name "soft-port"
		     Name for IO object, default is "soft-port".
		:read-char ( --	c )
		     Proc for reading one character.
		:read-line ( --	line )
		     Proc for reading one line.
		:write-char ( c	-- )
		     Proc for writing one character.
		:write-line ( line -- )
		     Proc for writing one line.
	  Input	example, *stdin* IO object is preserved	for later use:
		:port-name "sndin"
		:read-char lambda: <{ -- c }> *stdin* io-getc ;
		:read-line lambda: <{ -- line }> *stdin* io-read ;
		make-soft-port set-*stdin* value stdin-io
	  Output example, *stdout* IO object is	preserved for later use:
		:port-name "sndout"
		:write-char lambda: <{ c -- }> c snd-print .stdout ;
		:write-line lambda: <{ line -- }> line snd-print .stdout ;
		make-soft-port set-*stdout* value stdout-io
     port->string ( prt	-- str )
	  Return content of prt	object as string if available, otherwise #f.
     port-close	( prt -- )
	  File and IO ports close their	streams, other kind of ports do	noth-
	  ing.
     port-closed? ( prt	-- f )
	  Return #t if io object is closed, otherwise #f.
     port-display ( prt	obj -- )
	  Write	the string representation of obj to prt	object.	 If prt	is #f,
	  write	to current output port (stout).
     port-flush	( prt -- )
	  File and IO ports flush their	streams, other kind of ports do	noth-
	  ing.
     port-getc ( prt --	c )
	  Return next character	from prt IO object.  If	prt is #f, read	from
	  current input	port (stdin).
     port-gets ( prt --	str )
	  Return one line from prt IO object.  If prt is #f, read from current
	  input	port (stdin).
     port-input? ( obj -- f )
	  Return #t if obj is an input IO object or #f,	otherwise #f.
     port-output? ( obj	-- f )
	  Return #t if obj is an output	IO object or #f, otherwise #f.
     port-putc ( prt c -- )
	  Write	character c to prt IO object.  If prt is #f, write to current
	  output port (stout).
     port-puts ( prt str -- )
	  Write	str to prt IO object.  If prt is #f, write to current output
	  port (stout).
     port-puts-format (	prt fmt	fmt-args -- )
	  Write	string built from fmt and array	fmt-args to prt	IO object.  If
	  prt is #f, write to current output port (stdout).  For example,
	  write	"hello,	world" to stdout (#f) port:
		#f "hello, %s" #( "world" ) port-puts-format
		  => hello, world
     port-read ( prt --	str ) alias for	port-gets
     port-write	( prt str -- ) alias for port-puts
     port-write-format ( prt fmt fmt-args -- ) alias for port-puts-format
     port? ( obj -- f )
	  Return #t if obj is an IO object or #f, otherwise #f.

     The following words recognize these options:
	   :filename string
		      :fam r/o | w/o (default) | r/w
			   For read-only use constant r/o, for write-only use
			   constant w/o	and for	read-write use constant	r/w.
	   :command string | array-of-strings
		      :fam r/o | w/o (default) | r/w
			   For read-only use constant r/o, for write-only use
			   constant w/o	and for	read-write use constant	r/w.
	   :socket string
		      :domain domain (AF_INET |	AF_UNIX)
		      :port port (default 1024)
	   :soft-port string
		      :close ( -- )
			   Proc	for closing soft port.
		      :fam r/o | w/o (default) | r/w
			   For read-only use constant r/o, for write-only use
			   constant w/o	and for	read-write use constant	r/w.
		      :flush ( -- )
			   Proc	for flushing port buffer.
		      :port-name "soft-port"
			   Name	for IO object, default is "soft-port".
		      :read-char ( -- c	)
			   Proc	for reading one	character.
		      :read-line ( -- line )
			   Proc	for reading one	line.
		      :write-char ( c -- )
			   Proc	for writing one	character.
		      :write-line ( line -- )
			   Proc	for writing one	line.
     with-error-to-port	( obj :key args	-- )
	  Open IO object for output and	point IO to *stderr*.  If obj is a
	  string, write	string to IO object, otherwise execute obj as proc or
	  xt with stack	effect ( -- ).	Close IO object.  *stderr* will	be re-
	  set to its previous value.
		lambda:	<{ -- }>
			"hello\n" .stderr
		; :filename "file.test"	with-error-to-port
		% cat test.file
		hello
		%
		"" value s
		lambda:	<{ -- }>
			*stderr* "hello" io-write
		; :string s with-error-to-port
		s => "hello"
		"file.test" file-delete
		"hello\n" :filename "file.test"	with-error-to-port
		% cat file.test
		hello
		%
     with-input-from-port ( obj	:key args -- str )
	  Open IO object for input and point IO	to *stdin*.  If	obj is nil,
	  read first line from IO object, otherwise execute obj	as proc	or xt
	  with stack effect ( -- str ).	 Close IO object and return resulting
	  string.  *stdin* will	be reset to its	previous value.
		% cat file.test
		hello
		%
		lambda:	<{ -- str }>
			*stdin*	io-read
		; :filename "file.test"	with-input-from-port =>	"hello\n"
		"hello"	value s
		lambda:	<{ -- str }>
			*stdin*	io-read
		; :string s with-input-from-port => "hello"
		nil :filename "file.test" with-input-from-port => "hello"
     with-input-port ( obj :key	args --	str )
	  Open IO object for input.  If	obj is nil, read first line from IO
	  object, otherwise execute obj	as a proc or xt	with stack effect ( io
	  -- str ).  Close IO object and return	resulting string.
		% cat file.test
		hello
		%
		lambda:	<{ io -- str }>
			io io-read
		; :filename "file.test"	with-input-port	=> "hello\n"
		"hello"	value s
		lambda:	<{ io -- str }>
			io io-read
		; :string s with-input-port => "hello"
		nil :filename "file.test" with-input-port => "hello\n"
     with-output-port (	obj :key args -- )
	  Open IO object for output.  If obj is	a string, write	string to IO
	  object, otherwise execute obj	as proc	or xt with stack effect	( io
	  -- ).	 Close IO object.
		lambda:	<{ io -- }>
			io "hello\n" io-write
		; :filename "file.test"	with-output-port
		% cat file.test
		hello
		%
		"" value s
		lambda:	<{ io -- }>
			io "hello" io-write
		; :string s with-output-port
		s => "hello"
		"file.test" file-delete
		"hello\n" :filename "file.test"	with-output-port
		% cat file.test
		hello
		%
     with-output-to-port ( obj :key args -- )
	  Open IO object for output and	point IO to *stdout*.  If obj is a
	  string, write	string to IO object, otherwise execute obj as proc or
	  xt with stack	effect ( -- ).	Close IO object.  *stdout* will	be re-
	  set to its previous value.
		lambda:	<{ -- }>
			." hello" cr
		; :filename "file.test"	with-output-to-port
		% cat test.file
		hello
		%
		"" value s
		lambda:	<{ -- }>
			*stdout* "hello" io-write
		; :string s with-output-to-port
		s => "hello"
		"file.test" file-delete
		"hello\n" :filename "file.test"	with-output-to-port
		% cat file.test
		hello
		%

   Procs and Xts
     *filename*
	  Current filename.
     *lineno*
	  Current line number.
     .proc ( prc -- )
	  Print	proc object prc	to current output.
     <'set> ( "name" --	set-name|#f )
	  Parse	name and search	for word set-name.  Return xt of set-name or
	  #f if	not found.
		<'set> object-print-length => set-object-print-length
     <{	( -- )
	  Turn current colon definition	in a proc object.  Takes tokens	up to
	  closing `}>' as local	variables, `--'	start a	comment	ignoring rest
	  to closing `}>'.  In addition	to other local variable	words like { }
	  and {{ }} this form handles two keywords, :key and :optional.	 Vari-
	  able names are taken from keyword and	optional names.	 This word can
	  span over more than one lines	but without empty lines	or comments in
	  between.  If :key and	:optional is used together, :key must come
	  first.  All keyword and optional variables must have default values.
	  This word is immediate and compile only and can only be used in word
	  definitions.
		: optkey-test <{ a b c
		  :key d 10 e 20 :optional f 30	g 40 --	ary }>
			#( a b c d e f g )
		;
		1 2 3 optkey-test => #(	1 2 3 10 20 30 40 )
		:d 11 1	:e 22 2	3 4 optkey-test	=> #( 1	2 3 11 22  4 40	)
     <{}> ( -- )
	  Turn current colon definition	in a proc object.  This	word is	imme-
	  diate	and compile only and can only be used in word definitions.
		: we-dont-need-args <{}> ;
		<'> we-dont-need-args proc? => #t
     defined? (	"name" -- f )
	  Return #t if name is defined in the dictionary, otherwise #f.
		defined?  10 =>	#f
		defined? nil =>	#t
		defined?   + =>	#t
     doc" ( <ccc>" -- )
	  Add input buffer to next double quote	character `"' to documentation
	  of current word.  Escape double quote	character with backslash if
	  required in documentation.  It is not	necessary to repeat the	stack
	  effect if it already exist in	the word definition.  This word	is im-
	  mediate and compile only and can only	be used	in word	definitions.
		: new-word ( --	)
			doc" our documentation may contain \
		\"double quotes\".  \
		Escape them with a backslash."
			\ we do	nothing
		;
		help new-word => new-word  ( --	)  our documentation may
		contain	qdouble	quotes".  Escape them with a backslash.
     documentation-ref ( obj --	str )
	  Return documentation string of obj (Forth word, object or topic) or
	  #f.
     documentation-set!	( obj str -- )
	  Set documentation of obj (Forth word,	object or topic) to str.
     get-func-name ( --	name )
	  Return name of current xt in word definition as string.  This	word
	  is immediate and compile only	and can	only be	used in	word defini-
	  tions.
		: new-word
			get-func-name .$
			space
			10
		;
		new-word => new-word 10
     get-optarg	( req def -- val )
	  Return either	default	value def or a value found on stack.  req is
	  the sum of required and following optional arguments.	 It simulates
	  the :optional	keyword	in Lisp/Scheme.
		: optarg-test (	a b c=33 d=44 e=55 -- ary )
			4 55 get-optarg	{ e }
			3 44 get-optarg	{ d }
			2 33 get-optarg	{ c }
			{ a b }
			#( a b c d e )
		;
		1 2 optarg-test	=> #( 1	2 33 44	55 )
		1 2 3 4	optarg-test => #( 1 2  3  4 55 )
		1 2 3 4	5 6 7 optarg-test => 1 2 #( 3 4	 5  6  7 )
     get-optargs ( lst req -- vals )
	  The plural form of get-optarg.  args is an array with	default	val-
	  ues, req is number of	required arguments.  Return req	+ args length
	  values on stack, either default ones or from stack.
		: optargs-test ( a b c=33 d=44 e=55 -- ary )
			#( 33 44 55 ) 2	get-optargs { a	b c d e	}
			#( a b c d e )
		;
		1 2 optargs-test => #( 1 2 33 44 55 )
		1 2 3 4	optargs-test =>	#( 1 2	3  4 55	)
		1 2 3 4	5 6 7 optargs-test => 1	2 #( 3 4  5  6	7 )
     get-optkey	( key def -- val )
	  Return either	default	value def or a value found on stack determined
	  by keyword key.  It simulates	the :key keyword in Lisp/Scheme.
		: optkey-test (	start dur keyword-args -- ary )
			:frequency 440.0 get-optkey { freq }
			:initial-phase pi get-optkey { phase }
			{ start	dur }
			#( start dur freq phase	)
		;
		0 1 optkey-test	=> #( 0.0 1.0 440.0 3.14159 )
		0 2 :frequency 330.0 optkey-test => #( 0.0 2.0 330.0 3.14159 )
     get-optkeys ( ary req -- vals )
	  The plural form of get-optkey.  ary is an array of key-value pairs,
	  req is number	of required arguments.	Return req + ary length	/ 2
	  values on stack, either default ones or from stack.
		: optkeys-test ( start dur keyword-args	-- ary )
			#( :frequency 440.0
			   :initial-phase pi )
			    2 get-optkeys { start dur freq phase }
			#( start dur freq phase	)
		;
		0 1 optkeys-test => #( 0.0 1.0 440.0 3.14159 )
		0 2 :frequency 330.0 optkeys-test => #(	0.0 2.0	330.0 3.14159 )
     help ( "name" -- )
	  Print	documentation of name (Forth word or topic) or "no documenta-
	  tion available".
		help make-array	\ Forth	word
		help array	\ topic
     help-add! ( obj str -- )
	  Append str to	documentation of obj.
     help-ref (	obj -- str )
	  Return documentation of obj (Forth word, object or topic) or "no
	  documentation	available".
     help-set! ( obj str -- )
	  Set documentation of obj (Forth word or object) to str.
		#( "behemoth" "pumpkin"	"mugli"	) value	hosts
		hosts "local-net hostnames" help-set!
		hosts help-ref => "local-net hostnames"
     lambda: ( -- xt )
	  Start	nameless word definition and set variable latestxt to word.
	  Stack-effect or normal comment immediately at	the beginning will be
	  used as documentation.  Return xt after closing semicolon `;'.
		lambda:	( a b -- c ) + ; value plus
		plus help-ref => lambda-009  ( a b -- c	)
		1 2 plus execute => 3
		1 2 lambda: ( a	b -- c ) * ; execute =>	2
     latestxt (	-- xt )
	  Return latest	defined	xt.
     local-variables ( -- vars )
	  Return a hash	of local variable name-value pairs up to the location
	  in definition.  This word is immediate and compile only and can only
	  be used in word definitions.
		: word-with-locals { foo -- }
			10 { bar }
			local-variables	each
				.$ space
			end-each
		;
		20 word-with-locals => #{ "bar"	=> 10  "foo" =>	20 }
     make-proc ( xt arity -- prc )
	  Return new proc object.  arity can be	an integer or an array of
	  length 3, #( req opt rest ).
		<'> +  2  make-proc => +
		lambda:	( a b -- c )
			+
		; #( 2 0 #f ) make-proc	=> lambda-009
     proc->xt (	prc -- xt )
	  Return the actual word (the execution	token xt) of prc.
     proc-apply	( prc args -- res )
	  Execute proc object prc with arguments args and return result	or #f.
	  args can be an array of arguments or a single	argument.  If execu-
	  tion fails, raise an eval-error exception, if	length of args is less
	  than required	arity of prc, raise a bad-arity	exception.
		<'> +  2  make-proc value plus
		plus #(	5 6 ) proc-apply => 11
     proc-arity	( prc -- arity )
	  Return arity array #(	req opt	rest ) of proc object prc, or #f if
	  not a	proc object.
     proc-create ( arity -- prc	)
	  Create nameless proc object with arity.  Like	create it goes with
	  does>.
		: input-fn ( gen -- proc; dir self -- r	)
			{ gen }
			1 proc-create	\ return proc with one argument
			gen ,		\ store	gen for	later use in DOES
		  does>	{ dir self -- r	 } \ dir (ignored here)	self (address)
			self @		\ return our gen
			readin		\ return readin	value
		;
		instrument: src-simp <{	start dur amp sr sr-env	fname -- }>
			:file fname find-file make-readin { f }
			:input	f INPUT-FN  :srate sr	make-src { sc }
			:envelope sr-env  :duration dur	make-env { en }
			start dur run
				i sc en	env #f src amp f* *output* outa	drop
			loop
			f mus-close drop
		;instrument
		0 1.5 0.5 0.2 #( 0 0 50	1 100 0	) "fyow.snd"
		    <'>	src-simp with-sound
     proc-name ( prc --	name )
	  Return name of proc object prc if found, otherwise an	empty string.
     proc-source-ref ( prc -- str )
	  Return source	string property	of prc,	or #f if not available.
     proc-source-set! (	prc str	-- )
	  Set source string property of	prc to str.
     proc? ( obj -- f )
	  Return #t if obj is a	proc object.
     run-proc (	prc args -- res	) alias	for proc-apply
     running-word ( -- xt )
	  Return current xt in word definition.	 This word is immediate	and
	  compile only and can only be used in word definitions.
		: new-word
			running-word xt->name .$
			space
			10
		; new-word => new-word 10
     see2 ( "name" -- )
	  Show word definition of name.
     set! ( "name" -- )
	  Parse	name and execute word set-name if found, otherwise raise an
	  undefined-word exception.  The following two lines do	the same:
		128 set! object-print-length
		128 set-object-print-length
     set-execute ( xt -- ?? )
	  Execute set-xt if found, otherwise raise an undefined-word excep-
	  tion.	 The following two lines do the	same:
		128 <'>	object-print-length set-execute
		128 set-object-print-length
     set-xt ( xt1 -- xt2 )
	  Return set-xt	if found, otherwise #f.
		<'> object-print-length	set-xt => set-object-print-length
     source-file ( xt -- file )
	  Return source	file where xt was created or #f	if xt is a primitive
	  or not defined.
     source-line ( xt -- line )
	  Return source	line number where xt was created or #f if xt is	a
	  primitive or not defined.
     source-ref	( obj -- str )
	  Return source	string of obj, a proc or xt, or	#f if not found.
     source-set! ( obj str -- )
	  Set source string of obj, a proc or xt, to str.
     thunk? ( obj -- f )
	  Return #t if obj is a	proc object with no required, optional and
	  rest arguments.  If its arity	is not #( 0 0 #f ), return #f.
     trace-var ( var proc-or-xt	-- )
	  Add proc-or-xt to global var hook which is utilized on every call of
	  to.  The stack effect	of proc-or-xt must be (	val -- res ).
		mus-array-print-length => 8
		8 value	*clm-array-print-length*
		<'> *clm-array-print-length* lambda: <{	val -- res }>
			val set-mus-array-print-length
		; trace-var
		24 to *clm-array-print-length*
		*clm-array-print-length* => 24
		mus-array-print-length => 24
		<'> *clm-array-print-length* untrace-var
     untrace-var ( var -- )
	  Remove previously installed hook from	var.
     word? ( obj -- f )
	  Return #t if obj is a	proc object or an xt (execution	token, address
	  of a Ficl word), otherwise #f.
     word-create ( name	-- )
	  Create word name in dictionary with does>-part as body.
		: make-setter (	name --	; hs val self -- )
			{ name }
			name "!" $+ word-create
			name ,
		  does>	{ hs val self -- }
			hs self	@ ( slot ) val hash-set!
		;
		"user-time" make-setter	' creates setter word user-time!
		#{} value hs
		hs 3.2 user-time!
		hs ' #{	"user-time" => 3.2 }
     xt->name (	xt -- str )
	  Return name of xt if found, otherwise	an empty string.
     xt->origin	( xt --	str )
	  Return name, source file and source line number where	xt was defined
	  (name:file:line).  If	xt is a	C-primitive, return (name:primitive),
	  if not defined, return an empty string.
     xt? ( obj -- f )
	  Return #t if obj is an xt (execution token, address of a Ficl	word),
	  otherwise #f.

   Regexp object type
     *re-syntax-options*
	  This regexp variable can be set with the following constants.	 If
	  more than one	constant is used, combine them with or,	see regex(3).
	       REG_EXTENDED  Compile modern regex, default.
	       REG_ICASE     Compile for matching ignore case.
	       REG_NEWLINE   Compile for newline-sensitive matching.
	       REG_NOSUB     Compile without creating subexpression.
	  For example, set matching to ignore case before creating a new reg-
	  exp
		REG_EXTENDED REG_ICASE or  to *re-syntax-options*
     / ( <ccc>/	-- reg )
	  Prefix character `/' start a regular expression object delimited by
	  a second `/'.
		/(B|b)+/ => /(B|b)+/
     make-regexp ( str -- reg )
	  Return new regexp object from	str which may contain regular expres-
	  sion.
		"(B|b)+" make-regexp value reg
     re-match (	reg str	start -- n )
	  Return count of matched characters or	-1 for no match.
		/a*/ "aaaaab" 2	re-match => 3
     re-search ( reg str start range --	n )
	  Return index of match	or -1 for no match.
		/a*/ "aaaaab" 2	4 re-search => 2
     re/ ( space<ccc>/ -- reg )
	  Parse	regexp ccc delimited by	`/' at compile time and	at interpret
	  time return parsed regexp.  See / for	an alternative.
		re/ (B|b)+/ => /(B|b)+/
     re= ( reg str -- len|#f ) alias for regexp-match
     regexp-match ( reg	str -- len|#f )
	  Return count of matched characters or	#f.  Possible matched group
	  results or #f	can be found in	regexp object reg, in read-only	vari-
	  ables	*re1* to *re9* and in read-only	array *re*.
		/.*(bar)/ value	reg
		reg "foobar" regexp-match => 6
		reg 0 apply => foobar
		reg 1 apply => bar
		reg 2 apply => #f
     regexp= ( reg str -- len|#f ) alias for regexp-match
     regexp-replace ( reg str1 replace -- str2 )
	  Replace 1st occurrence of reg	in str1	with replace if	found.	Refer-
	  ences	\1 to \9 in replace will be replaced by	corresponding subex-
	  pressions.  If no corresponding subexpression	exist, raise a
	  regexp-error exception.
		/(foo)/	"foo-bar" "***\\1***" regexp-replace
		  => ***foo***-bar
	  Note the double quotes on back reference characters .
     regexp-search ( reg str :key start	0 range	-1 -- pos|f )
	  Return index of match	or #f.	If index is zero, return #t to fool
	  Forth' if.  If keyword range is -1 (default),	the entire string will
	  be searched.	Possible matched group results or #f can be found in
	  regexp object	reg, in	read-only variables *re1* to *re9* and in
	  read-only array *re*.
		/foo/ "foobar" :start 0	:range 6 regexp-search => #t (pos 0)
		/(bar)/	value reg
		reg "foobar" :start 0 :range 2 regexp-search =>	#f
		reg "foobar" :start 3 :range 2 regexp-search =>	3
		reg 0 apply => bar
		reg 1 apply => bar
		reg 2 apply => #f
     regexp? ( obj -- f	)
	  Return #t if obj is a	regexp object, otherwise #f.
		/^s/ regexp? =>	#t

   String object type
     " ( <ccc>"	-- str )
	  Prefix character `"' start a string object delimited by a second
	  `"'.
		"pumpkin" => "pumpkin"
     ""	( -- str )
	  Return empty string object ("").
     $"	( space<ccc>" -- str )
	  Parse	string ccc delimited by	`"' at compile time and	at interpret
	  time return parsed string.  See " for	an alternative.
		$" pumpkin" => "pumpkin"
     $+	( str1 str2 -- str3 ) alias for	string-append
     $>string (	addr len -- str	)
	  Return Forth string addr len as string object.  Standard words like
	  type and evaluate require this kind of string.
     $cr ( -- str )
	  Return carriage return string	object ("\n").
     $space ( -- str )
	  Return string	of one space ("	").
     $spaces ( len -- str )
	  Return string	of len spaces.	Raise an out-of-range exception	if len
	  < 0.
     .$	( obj -- ) alias for .string
     .debug ( obj -- )
	  Print	string representation of obj to	stderr wrapped in #<DEBUG(F):
	  ...>.
     .error ( obj -- )
	  Print	string representation of obj to	current	error output.
     .g	( obj -- ) alias for .string
     .stderr ( obj -- )
	  Print	string representation of obj to	stderr.
     .stdout ( obj -- )
	  Print	string representation of obj to	stdout.
     .string ( obj -- )
	  Print	string representation of obj to	current	output.
     <<	( str val -- str'  ) alias for string-push
     >string ( chars len -- str	) alias	for string-concat
     char? ( obj -- )
	  Return #t if obj is a	character, otherwise #f.
     die ( str -- )
	  Print	str wrappen in #<die: ...> to current stderr and exit inter-
	  preter with return code 1.
     error ( str -- )
	  Print	str wrappen in #<error:	...> to	current	stderr and throw ex-
	  ception.
     format ( fmt args -- ) alias for string-format
     fth-die ( fmt :optional args -- )
	  Print	fmt string with	corresponding args array wrapped in #<die:
	  ...> to current stderr and exit interpreter with return code 1; args
	  is optional.	 See string-format for fmt description.
     fth-error ( fmt :optional args -- )
	  Print	fmt string with	corresponding args array wrapped in #<error:
	  ...> to current stderr and throw exception; args is optional.	  See
	  string-format	for fmt	description.
     fth-format	( fmt :optional	args --	str  )
	  Return string	object from printf(3) fmt string and args array	con-
	  taining corresponding	arguments; args	is optional.  See
	  string-format	for fmt	description.
     fth-print ( fmt :optional args -- )
	  Print	fmt string with	corresponding args array to current stdout;
	  args is optional.   See string-format	for fmt	description.
     fth-warning ( fmt :optional args -- )
	  Print	fmt string with	corresponding args array wrapped in #<warning:
	  ...> to current stderr; args is optional.   See string-format	for
	  fmt description.
     make-string ( len :key initial-element ' '	-- str )
	  Return a new string of length	len filled with	initial-element	char-
	  acters, default space.  Raise	an out-of-range	exception if len < 0.
		3 :initial-element <char> x make-string	=> "xxx"
     string->array ( str -- ary	)
	  Convert str to an array of characters.
		"foo" string->array => #( 102 111 111 )
     string-append ( str1 str2 -- str3 )
	  Return new string str1 + str2.
     string-capitalize ( str1 -- str2 )
	  Return new string with first character capitalized and remaining
	  characters in	lowercase.
     string-capitalize!	( str -- str' )
	  Return str changed to	first character	capitalized and	remaining
	  characters to	lowercase.
     string-chomp ( str1 -- str2 )
	  Return new string object with	possible trailing \n removed.
     string-chomp! ( str -- str' )
	  Return changed str with possible trailing \n removed.
     string-concat ( objs len -- str )
	  Return new string with len objects from stack	converted to their
	  string representation.
		0 1 2 "	foo " "b" "a" "r"  7 >string
		  => "012 foo bar"
     string-copy ( str1	-- str2	)
	  Return copy of str1.
     string-delete! ( str idx -- val )
	  Delete and return character at position idx from str;	negative index
	  counts from backward.	 Raise an out-of-range exception if index is
	  not in range of string.
     string-downcase ( str1 -- str2 )
	  Return new string with all characters	lowercase.
     string-downcase! (	str -- str' )
	  Return str changed to	all characters lowercase.
     string-eval ( str -- ?? )
	  Evaluate str;	values already on stack	can be accessed, resulting
	  values remain	on stack.
		7 "3 4 + +" string-eval	=> 14
     string-eval-with-status ( str -- ?? status	)
	  Evaluate str and return eval-status on top of	stack; values already
	  on stack can be accessed, resulting values remain on stack.  Eval-
	  status can be	one of the following constants:
	       BREAK	     Ficl Break.
	       ERROR_EXIT    Ficl Error	Exit.
	       INNER_EXIT    Ficl Inner	Exit.
	       OUT_OF_TEXT   Ficl Out of Text.
	       RESTART	     Ficl Restart.
	       USER_EXIT     Ficl User Exit.
     string-fill ( str char -- str' )
	  Fill str with	char and return	changed	string object.
     string-find ( str1	key -- str2|#f )
	  Return match if string or regexp key exist in	str, otherwise #f.
		"hello world" "l" string-find => "llo world"
		"hello world" /ell/ string-find	=> "lo world"
     string-format ( fmt args -- )
	  fmt is a printf(3) format string and args the	needed arguments which
	  may be an array, a single argument or	#f.
		"%04d %8.2f %b %X %o"  #( 128 pi 255 255 255 ) string-format
		  => "0128     3.14 11111111 FF	377"
	  The format string can	have zero or more of the following flags:
		`#'	  The value will be converted to an alternate form.
			  For b, B, o and O conversions	prepend	a zero before
			  output, for x	and X conversions prepend a `0x' re-
			  spective `0X'	before output.	For a, A, e, E,	f, F,
			  g and	G conversions the result will always have a
			  decimal point.
		`-'	  Flush	output left.
		`0' (zero)
			  Padding with `0' (zero) rather than blank.
	  The following	conversion specifiers are known:
		%	  A `%'	is written.
		aAeEfFgG  Floating point output	like printf 3.
		c	  Single character output.
		bdouxX	  Integer output in binary, decimal, octal, unsigned
			  and hexadecimal form.
		p	  Inspect string output	of any Forth object with
			  object-inspect.
		s	  String representation	of any Forth object with
			  object->string.
		S	  Dump string output of	any Forth object with
			  object-dump.
     string-index ( str	key -- idx )
	  Return index of string key in	str or -1 if not found.
		"hello world" "orl" string-index => 7
     string-insert! ( str idx val -- str' )
	  Insert string	representation of val to str at	position idx; negative
	  index	counts from backward.  Raise an	out-of-range exception if in-
	  dex is not in	range of string.
     string-length ( str -- len	)
	  If str is a string object, return its	length,	otherwise -1.
     string-member? ( str key -- f )
	  Return #t if string key exist	in str,	otherwise #f.
		"hello world" "ell" string-member? => #t
     string-pop	( str -- char )
	  Remove and return last character.  If	str is empty, return #f.
     string-push ( str val -- str' )
	  Append string	representation of val to str and return	changed	string
	  object.
     string-ref	( str idx -- val )
	  Return character at position idx; negative index counts from back-
	  ward.	 Raise an out-of-range exception if index is not in range of
	  string.
     string-replace ( str1 from	to -- str2 )
	  Return new string object with	string from replaced by	string to.  If
	  to is	the empty string, delete the from part from str1.
     string-replace! ( str from	to -- str' )
	  Return changed str with string from replaced by string to.  If to is
	  the empty string, delete the from part from str.
     string-reverse ( str1-- str2 )
	  Return str1 reversed as new string object.
     string-reverse! ( str -- str' )
	  Return the same string object	str reversed.
     string-set! ( str idx val -- )
	  Store	character char at index	idx; negative index counts from	back-
	  ward.	 Raise an out-of-range exception if index is not in range of
	  string.
     string-shift ( str	-- char	)
	  Remove and return first character.  If str is	empty, return #f.
     string-split ( str	sep -- ary )
	  Split	str using sep as delimiter and return result as	array of
	  strings.  If sep is not a string or regexp, delimiter	is space.
		"foo:bar:baz" ":" string-split
		  => #(	"foo" "bar" "baz" )
		"foo:bar:baz" "/:/" string-split
		  => #(	"foo" "bar" "baz" )
     string-substring (	str1 start end -- str2 )
	  Return new string from position start	to, but	excluding, position
	  end.	If end is not an integer, end will be set to length of str1;
	  negative index counts	from backward.	Raise an out-of-range excep-
	  tion if start	is not in range	of string.
		"hello world" 2	4 string-substring => "ll"
		"hello world" -4 -2 string-substring =>	"or"
		"hello world" -4 nil string-substring => "orld"
     string-unshift ( str val -- str' )
	  Prepend string representation	of val to str and return changed
	  string object.
     string-upcase ( str1 -- str2 )
	  Return new string with all characters	uppercase.
     string-upcase! ( str -- str' )
	  Return str changed to	all characters uppercase.
     string-cmp	( str1 str2 -- n )
	  Return -1 if str1 is less than str2, 1 if str1 is greater than str2,
	  and 0	if str1	is equal to str2.  It may be used with sort functions.
     string< ( str1 str2 -- f )
	  Return #t if str1 is lexicographically lesser	than str2, otherwise
	  #f.
     string<> (	str1 str2 -- f )
	  Return #t if strings are not equal, otherwise	#f.
     string= ( str1 str2 -- f )
	  Return #t if strings are equal, otherwise #f.
     string> ( str1 str2 -- f )
	  Return #t if str1 is lexicographically greater than str2, otherwise
	  #f.
     string>$ (	str -- addr len	)
	  Return string	object str converted to	a Forth	string with addr len.
	  Standard words like type and evaluate	require	this kind of string.
     string? ( obj -- f	)
	  Return #t if obj is a	string object, otherwise #f.
     warn ( str	-- ) alias for warning
     warning ( str -- )
	  Print	str wrappen in #<warning: ...> to current stderr.

   Symbols
     .symbol ( sym -- )
	  Print	symbol sym to current output.
     create-symbol ( "name" -- )
	  Create symbol	name prepended by `''.	Symbols	are actually values
	  (variables) named 'name.
		create-symbol new-symbol => create symbol 'new-symbol
     make-symbol ( name	-- sym )
	  Return symbol	name prepended by `''.	Symbols	are actually values
	  (variables) named 'name.
		"new-symbol" make-symbol => 'new-symbol
     symbol-name ( sym -- str )
	  Return name of symbol	sym.
		'new-symbol symbol-name	=> "new-symbol"
     symbol= ( obj1 obj2 -- f )
	  Return #t if obj1 and	obj2 are symbols with identical	name, other-
	  wise #f.
     symbol? ( obj -- f	)
	  Return #t if obj is a	symbol,	otherwise #f.

   Keywords
     .keyword (	kw -- )
	  Print	keyword	kw to current output.
     create-keyword ( "name" --	)
	  Create keyword name prepended	by `:'.	 Keywords are actually values
	  (variables) named :name.
		create-keyword new-keyword => create keyword :new-keyword
     keyword-name ( kw -- name )
	  Return name of keyword kw.
		:new-keyword keyword-name => "new-keyword"
     keyword= (	obj1 obj2 -- f )
	  Return #t if obj1 and	obj2 are keywords with identical name, other-
	  wise #f.
     keyword? (	obj -- f )
	  Return #t if obj is a	keyword, otherwise #f.
     make-keyword ( name -- kw )
	  Return keyword name prepended	by `:'.	 Keywords are actually values
	  (variables) named :name.
		"new-keyword" make-keyword => :new-keyword

   Exceptions
     *last-exception*
	  Hold last raised exception.
     .exception	( ex --	)
	  Print	exception ex to	current	output.
     create-exception (	msg "name" -- )
	  Create exception named name with message msg,	msg can	be #f.	The
	  exception has	a symbol name, that means it has prefix	`'' before
	  name.
		"New test exception" create-exception new-exception
		  => create 'new-exception
     exception-last-message-ref	( ex --	msg )
	  Return last message of exception ex.	Last message was set after an
	  exception was	thrown with e.g.  fth-throw or fth-raise.
     exception-last-message-set! ( ex msg -- )
	  Set msg, a string or #f, as last message of exception	ex.  This will
	  be set automatically after an	exception was thrown with e.g.
	  fth-throw or fth-raise.
     exception-message-ref ( ex	-- msg )
	  Return message of exception ex.
     exception-message-set! ( ex msg --	)
	  Set msg, a string or #f to exception ex.
     exception-name ( ex -- name )
	  Return name of exception ex.
		'new-exception exception-name => "new-exception"
     exception=	( obj1 obj2 -- f )
	  Return #t if obj1 and	obj2 are exeptions with	identical name,	other-
	  wise #f.
     exception?	( obj -- f )
	  Return #t if obj is a	exception, otherwise #f.
     make-exception ( name msg -- ex )
	  Return exception named name with message msg,	msg can	be #f.	The
	  exception has	a symbol name, that means it has prefix	`'' before
	  name.
		"New test exception" create-exception new-exception
		  => create 'new-exception
     symbol->exception ( sym --	ex )
	  Return symbol	sym as exception.

ENVIRONMENT
     FTH_DICTIONARY_SIZE
	  Overwrite default dictionary size (1024 * 1024).
     FTH_LOCALS_SIZE
	  Overwrite default number of locals (2048).
     FTH_RETURN_SIZE
	  Overwrite default size of return stack (1024).
     FTH_STACK_SIZE
	  Overwrite default size of parameter stack (8192).
     FTH_FTHPATH
	  A colon separated list of paths pointing to Forth script files.
	  These	paths will be prepended	to *load-path*.
     FTH_HISTORY
	  Overwrite default history filename ~/.fth-history.
     FTH_HISTORY_LENGTH
	  Overwrite default history file length	(100).
     FTH_INIT_FILE
	  Overwrite default initialization filename ~/.fthrc.
     FTH_LIBPATH
	  A colon separated list of paths pointing to C	extension libraries.
	  These	paths will be prepended	to *load-lib-path*.

FILES
     /usr/local/etc/fthrc
	  Global initialization	file for system	wide configuration.
     ~/.fthrc
	  Local	initialization file for	user configuration.  The name can be
	  changed with FTH_INIT_FILE.
     ~/.fth-history
	  Local	history	file.  The name	can be changed with FTH_HISTORY.

EXIT STATUS
     The fth utility exits 0 on	success, and >0	if an error occurs.

EXAMPLES
     The following are examples	of typical usage of the	fth command:

     Print 32 Fahrenheit as Celsius (0.0)

	   % fth -e "32	f2c . cr"

     Load C extension library libxm with initialization	function Init_libxm()
     and Forth source file motif-script.fs with	at least one word main defined
     in	it, execute word main and exit if finished

	   % fth -S "libxm Init_libxm" -e "main" motif-script.fs

     Prepend path ~/share/forth	to *load-path*,	load Forth source file
     sound-script.fs and start the repl	showing	a prompt.  Initialization
     files /usr/local/etc/fthrc	and ~/.fthrc are loaded	if they	exist

	   % fth -I ~/share/forth sound-script.fs

     Run Forth script check.fth	and provide options -ab	10 to the script which
     should handle at least these two; exit if finished

	   % fth -s check.fth -ab 10

     Rename config.h to	config.h.orig and read it line by line.	 If a line
     with
	   #define HAVE_COMPLEX_DOUBLE
     occures, replace it with
	   /* #undef HAVE_COMPLEX_DOUBLE */
     otherwise write original to config.h.  The	first -e set the global	Forth
     variable reg to a regexp object, the second -e uses this variable for
     testing.  The pattern of the first	-e is evaluated	in interpret state be-
     fore reading file while the pattern of the	second -e is evaluated in com-
     pile state	in a nameless lambda: <{}> pattern ; word during reading file
     line by line.

     % fth -ni.orig -e '/#define HAVE_COMPLEX_DOUBLE/ value reg' \
		    -e 'reg *line* re= if \
			  "/* #undef HAVE_COMPLEX_DOUBLE */\n" \
			else \
			  *line* \
			then' config.h

     Print name	and login time from the	who command:
	   who | fth -ane '.*1*	.*5* cr'

     The same with output file separator set to	" == ":
	   who | fth -ane '" ==	" to *ofs* .*1*	.*5* cr'

     Stand-alone executable Forth scripts have a first line of at least
	   #! /usr/local/bin/fth -s
     but may have more options;	adjust the path	to the interpreter.  Note the
     space after #!.  It's a Forth word	starting a comment and must be sepa-
     rated by at least one space.

     % cat hello-world.fth
     #!	/usr/local/bin/fth -s
     ."	Hello, World!" cr

     Add option	-v to turn on verbose mode.  Note: Option -s must be the last;
     fth doesn't process options after -s, they	are transfered to the script
     and can be	processed there	with Forth word	getopt,	see below.

     % cat hello-world.fth
     #!	/usr/local/bin/fth -Ds
     ."	Hello, World!" cr

     The getopt(3) example in Forth:

     % cat getopt-test.fth
     #!	/usr/local/bin/fth -Ds
     : main ( -- )
	     #f	#f { bflag ffile }
	     #t	to opterr    \ getopt prints error messages
	     begin
		     *argv* "bf:" getopt ( ch )	dup
	     while ( ch	)
		     case
			     <char> b of #t	to bflag endof
			     <char> f of optarg	to ffile endof
			     <char> ? of
				     "usage: [-b] [-f file]\n" #()
					 fth-print
				     1 (bye) \ exit with return	code 1
			     endof
		     endcase
	     repeat ( ch ) drop
	     optind 0 ?do *argv* array-shift drop loop
	     *argv* array-length to *argc*
	     "-b: %s, -f: %s\n"	#( bflag ffile ) fth-print
     ;
     main
     0 (bye)		     \ exit with return	code 0
     % ./getopt-test.fth
     -b: #f, -f: #f
     % ./getopt-test.fth -b
     -b: #t, -f: #f
     % ./getopt-test.fth -bf outfile
     -b: #t, -f: outfile
     % ./getopt-test.fth -f
     fth: option requires an argument -- f
     usage: [-b] [-f file]
     % ./getopt-test.fth -h
     fth: illegal option -- h
     usage: [-b] [-f file]

DIAGNOSTICS
     The command may fail for one of the following reasons:

     bad-arity	Arity doesn't match for	a given	proc object.

     bad-syntax	 Paren mismatch	for array, list	or hash	objects.

     bignum-error  Bignum error.

     catch-error  Catch-throw mismatch.

     eval-error	 Evaluation error.

     ficl-error	 Ficl evaluation error.

     forth-error  Forth	error.

     load-error	 Error while loading a Forth file.

     math-error	 Math error occured.

     null-string  Empty	string occured.

     no-memory-error  Memory exhausted.

     optkey-error  Error while evaluating option key functions.

     out-of-range  Argument is out of range.

     regexp-error  Regexp error	occured.

     signal-caught  Signal received.

     socket-error  Error while processing sockets.

     so-file-error  Dynamic library load error.

     system-error  General system function error occured.

     wrong-number-of-args  Wrong number	of arguments provided.

     wrong-type-arg  Wrong argument type provided.

SEE ALSO
     csh(1), snd(1), tcsh(1), vi(1), accept(2),	bind(2), connect(2),
     listen(2),	recv(2), recvfrom(2), send(2), sendto(2), shutdown(2),
     socket(2),	fegetround(3), fenv(3),	fesetround(3), fopen(3), getopt(3),
     getservbyname(3), getservbyport(3), gl_prompt_style(3), libfth(3),
     printf(3),	realpath(3), regex(3), sethostname(3), strftime(3), time(3),
     times(3), tecla(7).

HISTORY
     This manual page describes	version	1.4.1.	fth is based on	Ficl,
     Forth-inspired command language, version 4.0.31 written by	John Sadler.

AUTHORS
     fth and this manual page was written by Michael Scholz
     <mi-scholz@users.sourceforge.net>.

BUGS
     Please report bugs	to the author.

FreeBSD	13.0		       January 23, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | EXIT STATUS | EXAMPLES | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fth&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help