GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
FTH(1) FreeBSD General Commands Manual FTH(1)

fth —
Forth script and extension language

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]

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

Split every line to array *farray* before evaluation. The split string is field separator *fs*. Used with -n or -p option.
path
Prepend path to *load‐lib‐path*, multiple calls possible.
Show backtrace and exit with return code 1 if an exception was found evaluating the initialization file, running a script, loading additional source files, or evaluating strings from the command line.
Set global variable *fth‐debug* to #t.
pattern
 
pattern
Evaluate pattern. After evaluation, if options -e was specified, exit, if option -E was specified, start read‐eval‐print‐loop. Multiple calls possible. If -D was given and evaluation was not successful, 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.
fs
Set global variable *fs* to field separator fs.
file
Take initialization file file instead of ~/.fthrc. Use -Q to prevent loading initialization files.
path
Prepend path to *load‐path*, multiple calls possible.
[suffix]
The -e pattern will be applied to files or stdin. If suffix is specified, a backup file will be created with that suffix.
Remove line ending \n when used with -n or -p option.
Suppress output of current *line*. If not in‐place -i, start an implicit loop.
Print current *line* to stdout. If not in‐place -i, start an implicit loop.
Neither load the system wide nor the local initialization file.
Do not print banner and set global variable *fth‐verbose* to #f.
Start a conventional Forth‐like session with data stack left untouched 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 return code 1, otherwise exit with return code 0.
“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.
file
Evaluate file as a Forth script and exit. It doesn't read the initialization file. The global Forth variables *argc* and *argv* are set and filled with the count and command line options appearing after -s file. This must be the last option given to the fth interpreter. 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.
Display version info and exit.
Set global variable *fth‐verbose* to #t (default).

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

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.
( 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!
( filename -- )
Called after loading filename and updating global variable *loaded-files*. 
after-load-hook lambda: <{ fname -- }>
	"\\ %s loaded\n" #( fname ) fth-print
; add-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!
( history-file -- )
Called after leaving the repl and writing the history file but before leaving the program. Its only argument is the history filename. You may manipulate the history data entries. One history entry 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!
( 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!

Command-line editing similar to tcsh(1) is handled by the tecla(7) library 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 completed 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 substitution similar to csh(1).

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

If set to gl-all, only unique history events are entered in the history 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.
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.
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 undef.
If true, save history events, otherwise not. Default is #t.
If true, enable special formatting directives within the prompt, see gl_prompt_style(3). Default is #f.

( :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
( :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

Forth has loop constructs for compile state and interpret state. In addition to the usual do—loop, fth provides each—end-each and map—end-map loops for objects.
( limit start -- ) compile-only
 
( limit start -- ) compile-only
 
( -- ) 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
( obj -- val ) compile-only
 
( -- ) 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
( obj -- ) compile-only
 
( obj -- ) compile-only
 
( -- 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.
( limit start -- )
 
( -- )
3 0 [do]  i .  [loop] ⇒ 0 1 2
( obj -- val )
 
( -- )
#( 0 1 2 ) [each]  .  [end-each] ⇒ 0 1 2
( obj -- )
 
( obj -- )
 
( -- 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:
( -- ary )
Return array of length 0 for array-append, array-push etc.
( ary -- )
Print array object ary to current output.
( vals len -- ary )
Return array object with len objects found on parameter stack. Raise an out-of-range exception if len < 0.
( 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 )
( 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 )
( ary1 ary2 -- ary1+ary2 )
Append two arrays and return new one. If ary2 is not an array, append 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 )
( ary -- )
Clear array and set all elements to #f.
( ary1 prc args -- ary2 )
Return new array object with nil elements removed.
( ary prc args -- ary' )
Remove all nil elements from ary and return changed array object.
( vals len -- ary ) alias for >array
 
( 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 )
( 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.
( ary key -- val )
Delete and return key from ary if found, otherwise return #f.
( ary val -- )
Set all elements of ary to val.
( ary key -- key )
Return key if key exists in ary, otherwise #f.
( ary key -- idx )
Return index of key in ary or -1 if not found.
( 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.
( 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.
( 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"
( obj -- len )
If obj is an array object, return its length, otherwise -1.
( ary key -- f )
Return #t if key exists in ary, otherwise #f.
( ary -- val )
Remove and return last element from ary. If ary is empty, return #f.
( ary val -- ary' )
Append val to ary. 
#( 0 1 2 ) 10 array-push ⇒ #( 0 1 2 10 )
( 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.
( ary1 prc args -- ary2 )
prc will be called with args, an array of zero or more proc arguments, 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 )
( ary prc args -- ary' )
prc will be called with args, an array of zero or more proc arguments, 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 example n1 corresponds to the current array element and n2 comes from args, here 2.
( ary1 -- ary2 )
Return new array with elements reversed.
( ary -- ary' )
Return ary with elements reversed.
( 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.
( ary -- val )
Remove and return first element from ary. If ary is empty, return #f.
( 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 positive 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 )
( 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 integer if A > B. Raise a bad-arity exception if prc doesn't take two arguments.
( ary start end -- subary )
Return array built from ary beginning with index start up to but excluding index end. If end is nil, up to end of array will be returned. 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 )
( ary1 -- ary2 )
Return new array without duplicated elements of ary1.
( ary -- ary' )
Return ary without duplicated elements.
( ary val -- ary' )
Prepend val to ary. 
#( 0 1 2 ) 10 array-unshift ⇒ #( 10 0 1 2 )
( ary1 ary2 -- f )
Return #t if ary1 and ary2 are array objects of same length and content, otherwise #f.
( obj -- f )
Return #t if obj is an array object, otherwise #f.
( len :key initial-element -- ary )
Return array of length len filled with keyword INITIAL-ELEMENT values. initial-element defaults to nil if not specified. Raise an out-of-range exception if len < 0.

Assoc arrays:

( vals len -- ary )
Return assoc array object with len / 2 key-value pairs found on parameter stack. Raise an out-of-range exception if len < 0 or not even.
( ass key -- ret )
If key matches, return corresponding key-value pair, otherwise #f.
( ass key -- val )
If key matches, return corresponding value, otherwise #f.
( ass key -- 'ass )
If key matches, remove key-value pair from ass.
( ass key val -- 'ass )
If key matches, set key-value pair, otherwise add new pair.
( 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 ) )
( obj -- f )
Return #t if obj is an assoc array object, otherwise #f.

Lists:

( -- lst )
Return empty list.
( lst -- )
Print list object lst to current output.
( vals len -- lst )
Return list object with len objects found on parameter stack. Raise an out-of-range exception if len < 0.
( lst -- val )
Return fourth entry, the cadddr, of list or nil.
( lst -- val )
Return third entry, the caddr, of list or nil.
( lst -- val )
Return second entry, the cadr, of list or nil.
( lst -- val )
Return first entry, the car, of list or nil.
( lst -- val )
Return rest, the cddr, of list without its first and second entries.
( lst -- val )
Return rest, the cdr, of list without its first entry.
( val lst1 -- lst2 )
Return Lisp-like cons pointer with val as car and list as cdr.
( val1 val2 lst1 -- lst2 )
Return Lisp-like cons pointer with val1 as car, val2 as cadr and list as cddr.
( obj -- f )
Return #t if obj is a cons pointer, otherwise #f.
( lst -- lp )
Return last pair of lst. 
'( 0 1 2 3 ) last-pair ⇒ '( 3 )
( 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 )
( arg0 arg1 ... argn n -- lst )
Return list object with n objects found on parameter stack. Raise an out-of-range exception if n < 0.
( 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 )
( lst1 key -- lst2 )
Return new list without all elements equal key.
( lst key -- lst' )
Return lst without all elements equal key.
( lst val -- lst' )
Set all elements of lst to val.
( lst1 idx -- lst2 )
Return first idx entries of lst1 in a new list or nil.
( lst key -- idx )
Return index of key in lst or -1 if not found.
( 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.
( obj -- len )
If obj is a list (or array), return length of list, if obj is nil, return 0 otherwise -1.
( lst key -- f )
Return #t if key exists in lst, otherwise #f.
( lst idx -- val )
Return value at position idx of lst. Negative idx counts from backward. Raise an out-of-range exception if idx is not in lst's range.
( lst1 -- ary2 )
Return new list with elements reversed.
( 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.
( 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 )
( 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.
( lst1 idx -- lst2 )
Return idx'th cdr of lst1 up to the last entry in a new list or nil.
( lst1 lst2 -- f )
Return #t if lst1 and lst2 are list objects of same length and content, otherwise #f.
( obj -- f )
Return #t if obj is a list (nil or a cons pointer), otherwise #f.
( len :key initial-element nil -- lst )
Return list of length len filled with keyword initial-element values. initial-element defaults to nil if not specified. Raise an out-of-range exception if len < 0.
( obj -- f )
Return #t if obj is nil, otherwise #f.
( obj --f ) alias for nil?
 
( obj -- f )
Return #t if obj is a pair (a cons pointer), otherwise #f.
( lst val -- lst' )
Set val to car of lst.
( lst val -- lst' )
Set val to cdr of lst.

Assoc lists:

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

General functions:
( path -- ) alias for file-chdir
 
( 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
( 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.
( 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 regexp, 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"
( 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 directory.
( 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.
( 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.
( 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.
( 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.
( name -- )
If file name exist, delete it, otherwise do nothing.
( dir -- files-ary )
Return an array of all filenames found in dir.
( name -- path )
Return directory part of file name. 
"/home/mike/cage.snd" file-dirname ⇒ "/home/mike"
( 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.
( name -- path )
Return current working directory prepended to file name. If name starts with a slash, return name unchanged.
( 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 directory, 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’, similar 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
( name -- len )
If name is a file, return its length in bytes, otherwise #f.
( dir reg -- files-ary )
Return an array of filenames in dir matching regexp reg.
( name mode -- )
Create directory 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 numbers.
( 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 numbers.
( 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.
( -- path )
Return current working directory.
( 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"
( src dst -- )
Rename src to dst.
( name -- )
Remove empty directory name.
( 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).
( 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" )
( src dst -- )
Create symlink from src named dst.
( 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.
( name time -- )
Change modification time of name to time. If time is nil, use current time.
( name size -- )
Truncate or extend file name to size bytes.
( 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
( cmd -- str ) alias for file-shell
 

File test functions:

( name -- f )
Return #t if name is a block special file, otherwise #f.
( name -- f )
Return #t if name is a character special file, otherwise #f.
( name -- f )
Return #t if name is a directory, otherwise #f.
( name -- f )
Return #t if name is an executable file, otherwise #f.
( name -- f )
Return #t if name is an existing file, otherwise #f.
( name -- f )
Return #t if name is a named pipe, otherwise #f.
( name -- f )
Return #t if name matches effective gid, otherwise #f.
( name -- f )
Return #t if name matches effective uid, otherwise #f.
( name -- f )
Return #t if name is a readable file, otherwise #f.
( name -- f )
Return #t if name has set gid bit, otherwise #f.
( name -- f )
Return #t if name has set uid bit, otherwise #f.
( name -- f )
Return #t if name is a socket, otherwise #f.
( name -- f )
Return #t if name has set sticky bit, otherwise #f.
( name -- f )
Return #t if name is a symbolic link, otherwise #f.
( name -- f )
Return #t if name is a writable file, otherwise #f.
( name -- f )
Return #t if name length is zero, otherwise #f.

( -- hash ) alias for make-hash
 
( hash -- )
Print hash object to current output.
( 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 -- ass )
Return array with #( key value ) pairs of hash's content. 
#{ 'foo 0 'bar 1 } hash->array
  ⇒ #( #( 'foo  0 ) #( 'bar  1 ) )
( hash -- )
Remove all entries from hash, hash's length is zero.
( hash1 -- hash2 )
Return copy of hash1 using object-copy for all elements.
( hash key -- ary )
Delete key-value pair associated with key and return key-value array or #f if not found.
( 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 key -- ary )
Return key-value array if key exist or #f if not found.
( hash -- keys )
Return array of keys.
( 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 key -- f )
Return #t if key exists, otherwise #f.
( hash key -- value )
Return associated value or #f if not found.
( hash key value -- )
Set key-value pair of hash. If key exists, overwrite existing value, otherwise create new key-value entry.
( hash -- values )
Return array of values.
( obj1 obj2 -- f )
Return #t if obj1 and obj2 are hash objects with same length and content, otherwise #f.
( obj -- f )
Return #t if obj is a hash object, otherwise #f.
( -- hash )
Return empty hash object.
( size -- hash )
Return hash object with size key-value pairs. Keys are 0, 1, 2, ... and values are nil.

Property functions:

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

( hook -- )
Print hook object hook to current output.
( hook prc -- ) alias for hook-add
 
( 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 -- ary )
Return array of all hook procedures.
( hook -- proc-list ) alias for hook->array
 
( hook prc -- )
Add hook procedure prc to hook. Raise a bad-arity exception if prc's arity doesn't match hook's arity.
( 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 )
Return arity array of hook, #( req opt rest ). 
2 make-hook hook-arity ⇒ #( 2 0 #f )
( hook -- )
Remove all hook procedures from hook.
( 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 -- f )
Return #t if no hook procedure exist in hook, otherwise #f.
( 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 )
Return name of hook as string if hook object, otherwise #f.
( hook -- name-list )
Return array of hook procedure names (strings).
( hook -- proc-list ) alias for hook->array
 
( obj1 obj2 -- f )
Return #t if obj1 and obj2 are hook objects of same arity and procedures, otherwise #f.
( obj -- f )
Return #t if obj is a hook object, otherwise #f.
( 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
( hook prc-or-name -- prc ) alias for hook-delete
 
( hook -- ) alias for hook-clear
 
( hook args -- value-list ) alias for hook-apply
 

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

General IO functions:

( io -- )
Print io object to current output.
( -- n ) alias for io-exit-status
 
( io -- str )
Return content of io object as string if possible.
( io -- )
If necessary, flush io, close io object and set closed? to #t.
( io -- f )
Return #t if io object is closed, otherwise #f.
( io -- f )
Return #t if EOF is reached, otherwise #f.
( -- n )
Return exit status of last extern process called via file-shell, file-system, etc.
( 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 -- fname )
Return filename of io object or #f if filename is not available.
( io -- fd )
Return file descriptor of io.
( io -- )
Flushe io object if possible.
( io -- c )
Return next character from io object or #f if EOF.
( obj -- f )
Return #t if obj is an input IO object, otherwise #f.
( io -- mode )
Return access mode of io object.
( 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
( name -- io )
Open file name for reading and return new IO object.
( name :key if-exists overwrite -- io )
Open file name for writing and return new IO object. For keyword if-exists see io-open.
( obj -- f )
Return #t if obj is an output IO object, otherwise #f.
( io -- pos )
Return current io object position.
( io pos -- )
Set io object position to pos.
( io c -- )
Write character c to io object.
( io -- line )
Return next line from io object or #f if EOF.
( io -- array-of-lines )
Return the entire io object content as an array of strings, line by line.
( 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 restrictions 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 position to begin of io object.
( io offset :key whence io-seek-set -- pos )
Add offset to the file position in io object and return new position. Keyword whence can have the following values:
offset counts from begin of file (default)
offset counts from current position
offset counts from end of file.
( io -- pos ) alias for io-pos-ref
 
( io line -- )
Write line to io object.
( io fmt args -- )
Write string built from fmt and array fmt-args to io object.
( io array-of-lines -- )
Write array-of-lines to io object.
( obj1 obj2 -- f )
Return #t if obj1 and obj2 are IO objects with equal filenames, modes and file positions, otherwise #f.
( obj -- f )
Return #t if obj is an IO object, otherwise #f.
( name -- array-of-lines )
Open file name, read its content in an array, close file and return the array.
( name array-of-lines -- )
Open file name, write the content of array-of-lines to it and close file.

File functions:

( :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
( :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
( :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
( name -- io ) alias for io-open-read
 
( name :key args -- io ) alias for io-open-write
 
( name :key args -- io ) alias for io-open
 

Pipe functions:

( 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
( 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.
( 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.
( cmd -- io ) alias for io-popen-read
 
( cmd -- io ) alias for io-popen-write
 
( cmd :key args -- io ) alias for io-popen
 

String functions:

( str :key fam r/o -- io )
Open string with content string and return new IO object. If keyword 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"
( str -- io )
Open read-only string with content str and return new IO object.
( str -- io )
Open str for writing and return new IO object.
( cmd -- io ) alias for io-sopen-read
 
( cmd :key args -- io ) alias for io-sopen-write
 
( str :key fam r/o -- io ) alias for io-sopen
 

Socket functions:

(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 (default 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
( host :key args -- io ) alias for io-nopen
 
( fd host domain -- io )
Accept a connection on a socket and return an IO object after established connection. fd is the socket descriptor, host can be an arbitrary 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.
( 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.
( fd host port domain -- io )
Connect to a server and return IO object after an established connection. 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, otherwise 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 exception if connect(2) fails.
( fd -- )
Inform the operating system that connection requests should be delivered. 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.
( fd flags -- msg )
Receive data via a socket and return it. fd is the socket descriptor and flags can be 0, MSG_PEEK, or MSG_OOB. Raise a socket-error exception if recv(2) fails.
( fd flags host port domain -- msg )
Receive data via a socket and return it. fd is the socket descriptor, 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.
( 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.
( 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.
( 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.
( 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

Constants:
 
 
FICL_VM_STATE_INTERPRET
 
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
Return bytes of one cell.
Return bytes of one dfloat.
Return Ficl version string.
Return bytes of one float (same as dfloat).
Return version date string.
Return full Fth version string.
Return bytes of one sfloat (same as dfloat).

Features and Source files:

Return array of all features.
( str -- )
Add str, a string or symbol, to *features* list. 
'snd add-feature
( path -- )
Add string path to *load-lib-path* array if not already there. 
"/home/mike/lib/fth" add-load-lib-path
( path -- )
Add string path to *load-path* array if not already there. 
"/home/mike/share/fth" add-load-path
Return array of dictionary entries matching regexpression or string obj. 
/do/ apropos ⇒ #( "doLocal" ... )
( "lib" "func" -- )
Load dynamic library lib and call its function func. 
dl-load dbm Init_dbm
( "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
( "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 ""
( 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
( file -- )
If Forth source file exists in current or $HOME dir, load it, otherwise do nothing. 
".my-fth-init" load-init-file
( obj -- f )
Return #t if obj, a string or symbol, exists in *features* list, otherwise #f. 
'fth provided? ⇒ #t
'foo provided? ⇒ #f
( "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 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. 
require hello
( path -- )
Prepend string path to *load-lib-path* array if not already there. 
"/home/mike/lib/fth" unshift-load-lib-path
( path -- )
Prepend string path to *load-path* array if not already there. 
"/home/mike/share/fth" unshift-load-path

Catch errors:

( ?? obj exc arg -- ?? res )
Run proc or xt obj in save environment. If obj fails with an exception, 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 executed 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
( 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
( 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 element, 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>
( ?? -- )
Reset the data stack to initial state.

Time functions:

( -- secs )
Return time in seconds since 1970/01/01 as ficl2Unsigned. See time(3) for more information.
( 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
( secs -- ary )
Return array of eleven elements with secs converted to local time, see gmtime.
( ary -- secs )
Return time constructed from values of ary. ary may be #f or an array 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
( 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"
( 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"
( -- r )
Return real time, a ficlFloat.
( 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"
( -- )
Set global timeval struct variable to current time.
( -- 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:

( -- str )
Return date in default UNIX format as a string.
( -- ary )
Return hash of all shell environment variables and their values.
( 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
( 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
( -- id )
Return effective group id of calling process.
( name -- value )
Return content of shell environment variable name as string or #f if variable is not defined.
( -- id )
Return effective user id of calling process.
( -- id )
Return real group id of calling process.
( -- str )
Return name of current host.
( -- str )
Return name of user associated with current session.
( -- id )
Return process id.
( -- id )
Return parent process id.
( 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" )
( 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" )
( -- id )
Return real user id of calling process.
( -- )
 
( pid sig -- )
Send signal sig to process ID pid. If pid is zero, send sig to current process. sig is a number or a constant like SIGKILL.
( name value -- )
Set value to shell environment variable name.
( 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.
( 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.
( 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.
( str -- )
Set name of current host to str. This call is restricted to the super-user. Raise a not-implemented exception if sethostname(3) is not available.
( 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.
( sig xt -- old-xt )
Install xt for signal sig as an signal handler and return old handler. 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
( secs -- )
Pause for secs seconds.
( -- pid )
Wait for child process and return its process ID. Set global read only variable exit-status to wait status.
( pid flags -- )
Wait for child process pid. Set global read only variable exit-status 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:

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

Getopt functions:

( argv opts -- c )
Return next option character from command line options. See EXAMPLES for an getopt example.
( 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:

( n -- )
The exit hook fth_exit_hook will be called if set, all procs registered for at-exit will be executed and the current process will be terminated with exit code n.
( -- )
Print compiler flags to compile libfth.so to other applications.
( -- )
Print linker flags to link libfth.so to other applications.
( -- )
Print long package version.
( -- )
Print used and free dictionary cells.
( -- )
Print installation prefix path.
( -- )
Print package version number.
( 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
( -- str )
Return compiler flags to compile libfth.so to other applications.
( -- str )
Return linker flags to link libfth.so to other applications.
( -- str )
Return installation prefix path.
( -- str )
Return configure arguments.
( -- addr len )
Return fth-version as a Forth string with addr len. 
ver type ⇒ "1.3.1 (19-Mar-2012) [i386-portbld-freebsd9.0]"

Number predicates:
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f )
 
( obj -- f ) alias for ratio?
 
( obj -- f )
 
( obj -- f )
Return #t if a given object is of corresponding type, otherwise #f.

Miscellaneous math functions:

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

Pseudo randomize number functions:

( -- seed )
Return content of the seed variable fth_randx.
( seed -- )
Set seed to the seed variable fth_randx.
( r -- -r...+r )
Return pseudo randomized value between -r and +r.
( 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:

( n1 n2 -- )
Print integer n1 in a right-adjusted field of n2 characters. 
17 3 .r ⇒ | 17 |
( c -- )
Print complex number c. 
17.0+1.0i c. ⇒ |17.000000+1.000000i |
( d -- )
Print (Forth) double d (ficl2Integer). 
17 d. ⇒ |17 |
( d n -- )
Print (Forth) double d (ficl2Integer) in a right-adjusted field of n characters. 
17 3 d.r ⇒ | 17 |
( r n -- )
Print float r with n digits after decimal point. 
17.0 3 f.r ⇒ |17.000 |
( b -- )
Print bignum number. 
17.0 bn. ⇒ |17 |
( q -- )
Print rational number. 
17.0 q. ⇒ |17/1 |
( u n -- )
Print unsigned integer u in a right-adjusted field of n characters. 
17 3 u.r ⇒ | 17 |
( ud -- )
Print (Forth) unsigned double ud (ficl2Unsigned). 
17 ud. ⇒ |17 |
( ud n -- )
Print (Forth) unsigned double ud (ficl2Unsigned) in a right-adjusted field of n characters. 
17 3 ud.r ⇒ | 17 |
( 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:

( n -- f )
 
( n -- f )
 
( n -- f )
 
( n -- f )
 
( n -- f )
 
( n -- f )
 
( n -- f ) alias for 0<
 
( n -- f ) alias for 0>=
 
( 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 )
 
( n -- f ) alias for 0<
 
( n -- f ) alias for 0>=
 
( n -- f ) alias for 0=
Comparison between two integers (ficlInteger).
( u1 u2 -- f )
 
( u1 u2 -- f )
 
( u1 u2 -- f )
 
( u1 u2 -- f )
 
( u1 u2 -- f )
 
( u1 u2 -- f )
Comparison between two unsigned integers (ficlUnsigned).
( d -- f )
 
( d -- f )
 
( d -- f )
 
( d -- f )
 
( d -- f )
 
( d -- f )
 
( d -- f ) alias for d0<
 
( d -- f ) alias for d0>=
 
( 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
( d1 d2 -- f )
 
( d1 d2 -- f )
 
( d1 d2 -- f )
 
( d1 d2 -- f )
 
( d1 d2 -- f )
 
( 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
( ud1 ud2 -- f )
 
( ud1 ud2 -- f )
 
( ud1 ud2 -- f )
 
( ud1 ud2 -- f )
 
( ud1 ud2 -- f )
 
( 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
( c -- f )
 
( 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
( c1 c2 -- f )
 
( 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
( b -- f )
 
( b -- f )
 
( b -- f )
 
( b -- f )
 
( b -- f )
 
( b -- f )
Comparison between an arbitrary precision number and zero. b can be any type of number.
( b1 b2 -- f )
 
( b1 b2 -- f )
 
( b1 b2 -- f )
 
( b1 b2 -- f )
 
( b1 b2 -- f )
 
( b1 b2 -- f )
Comparison between two arbitrary precision big numbers. b1 and b2 can be any type of number.
( q -- f )
 
( q -- f )
 
( q -- f )
 
( q -- f )
 
( q -- f )
 
( q -- f )
Comparison between an arbitrary precision rational number and zero. q can be any type of number.
( q1 q2 -- f )
 
( q1 q2 -- f )
 
( q1 q2 -- f )
 
( q1 q2 -- f )
 
( q1 q2 -- f )
 
( q1 q2 -- f )
Comparison between two arbitrary precision rational numbers. q1 and q2 can be any type of number.

Convertion between number types:

( x -- b )
 
( r -- b ) alias for >bignum
 
( n -- b ) alias for >bignum
Convert any number to a bignum object (ficlBignum).
( x -- c )
 
( r -- c ) alias for >c
 
( q -- c ) alias for >c
 
( n -- c ) alias for >c
Convert any number to a complex object (ficlComplex).
( r -- d ) alias for s>d
 
( n -- d )
Convert any number to a llong object (ficl2Integer).
( r -- ud ) alias for s>ud
 
( n -- ud )
Convert any number to an ullong object (ficl2Unsigned).
( b -- r ) alias for s>f
 
( c -- r ) alias for s>f
 
( d -- r ) alias for s>f
 
( q -- r ) alias for s>f
 
( n -- r )
Convert any number to a float object (ficlFloat).
s>q
 
( c -- q ) alias for s>q
 
( r -- q ) alias for s>q
 
( n -- q )
Convert any number to a ratio object (ficlRatio).
( b -- n ) alias for f>s
 
( c -- n ) alias for f>s
 
( d -- n ) alias for f>s
 
( r -- n )
 
( q -- n ) alias for f>s
Convert any number to Forth single word set number (ficlInteger).

Math functions:

( n1 -- n2 )
 
( n1 -- n2 )
 
( n1 -- n2 )
 
( n1 -- n2 )
 
( n1 -- n2 )
 
( n1 -- n2 )
 
( n1 -- n2 )
 
( n1 -- n2 )
One argument integer (ficlInteger) operators.
( n1 n2 -- n3 )
 
( n1 n2 -- n3 )
 
( n1 n2 -- n3 )
 
( n1 n2 -- n3 )
 
( n1 n2 -- n3 )
 
( n1 n2 -- n3 )
Two argument integer (ficlInteger) operators.
( d1 -- d2 )
 
( d1 -- d2 )
 
( d1 -- d2 )
 
( d1 -- d2 )
One argument long integer (ficl2Integer) operators. d1 can be any type of number but should fit in ficl2Integer.
( d1 d2 -- d3 )
 
( d1 d2 -- d3 )
 
( d1 d2 -- d3 )
 
( d1 d2 -- d3 )
 
( d1 d2 -- d3 )
 
( d1 d2 -- d3 )
Two argument long integer (ficl2Integer) operators. d1 and d2 can be any type of number but should fit in ficl2Integer.
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
One argument real number (ficlFloat) operators. r1 can be any type of number but should fit in ficlFloat.
( r1 r2 -- r3 )
 
( r1 r2 -- r3 )
 
( r1 r2 -- r3 )
 
( r1 r2 -- r3 )
 
( r1 r2 -- r3 )
 
( r1 r2 -- r3 )
Two argument real numbers (ficlFloat) operators. r1 and r2 can be any type of number but should fit in ficlFloat.
( r1 r2 -- r3 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 r2 -- r3 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 ) alias for flog1p
 
( r1 -- r2 )
 
( r1 r2 -- r3 ) alias for f**
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 r3 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( r1 -- r2 )
 
( 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.
( c1 -- c2 )
 
( c1 c2 -- c3 )
 
( c1 c2 -- c3 )
 
( c1 c2 -- c3 )
 
( c1 c2 -- c3 )
 
( c1 c2 -- c3 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 c2 -- c3 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 ) alias for conj
 
( c1 c2 -- c3 ) alias for c**
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( c1 -- c2 )
 
( 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.
( b1 -- b2 )
 
( b1 -- b2 )
 
( b1 -- b2 )
 
( b1 -- b2 )
One argument arbitrary precision bignum functions. b1 can be any type of number.
( b1 b2 -- b3 )
 
( b1 b2 -- b3 )
 
( b1 b2 -- b3 )
 
( b1 b2 -- b3 )
 
( b1 b2 -- b3 )
 
( b1 b2 -- b3 )
 
( b1 b2 -- b3 )
 
( b1 b2 -- b3 ) alias for b**
Two argument arbitrary precision bignum functions. b1 and b2 can be any type of number.
( x y -- z )
Greatest common divisor. x and y can be any type of number, z is of type bignum.
( x y -- z )
Least common multiple. x and y can be any type of number, z is of type bignum.
( 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.
( b1 -- b2 n )
Returns the integer part of the square root of b1. On top of stack 1 if result is exact, otherwise 0.
( b1 b2 -- b3 n )
b3 becomes b1 modulo b2.
( b1 b2 -- b3 b4 n )
Divide b1 by b2 where b3 becomes the remainder and b4 becomes the quotient.
( b1 n -- b2 )
 
( 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 (ficlInteger).
( q1 -- q2 )
 
( q1 -- q2 )
 
( q1 -- q2 )
 
( q1 -- q2 )
 
( q1 -- q2 )
One argument arbitrary precision rational functions. q1 can be any type of number.
( q1 q2 -- q3 )
 
( q1 q2 -- q3 )
 
( q1 q2 -- q3 )
 
( q1 q2 -- q3 )
 
( q1 q2 -- q3 )
 
( q1 q2 -- q3 ) alias for q**
Two argument arbitrary precision rational functions. q1 and q2 can be any type of number.
 
Return or set current floating-point rounding mode, one of:
 
 
 
 
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)

( -- )
Print last word list from stack frame to error output.
( -- ) alias for backtrace
 
( -- n )
Internal global variable. Return the current frame depth.
( -- n )
Return the number of objects to print for objects like array, list, hash. Default value is 12.
( 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.
( -- n ) alias for frame-depth
 

Garbage collection words:

( obj -- obj )
Mark obj to protect it from garbage collection on next gc-run.
( obj -- f )
Return #t if obj is an instance and mark flag is set. All new created objects have mark flag set.
( -- )
Turn off garbage collection. The return code is meaningless in Forth.
( -- )
Turn on garbage collection. The return code is meaningless in Forth.
( -- ary )
Return array of all permanent objects.
( obj -- f )
Return #t if obj is an instance and permanent flag is set like constants.
( obj -- obj )
Protect obj from garbage collection until gc-unprotect.
( -- ary )
Return array of all protected objects.
( obj -- f )
Return #t if obj is an instance and protected flag is set.
( -- )
Run garbage collection immediately.
( -- )
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
( obj -- obj )
Unmark obj to unprotect it from garbage collection on next gc-run.
( obj -- obj )
Unprotect obj from garbage collection.

Object type and instance words:

( obj -- gen )
Return GEN-struct of obj.
( obj -- gen )
Return object type of obj.
( obj type -- f )
Return #t if obj is an instance of type, otherwise #f.
( obj -- f )
Return #t if obj is an instance, otherwise #f.
( gen obj -- instance )
Return new instance of Object type obj with gen wrapped in.
( 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.
( obj -- struct )
Return object struct of object-type obj.
( obj -- f )
Return #t if obj is an Object type, otherwise #f.
( -- ary )
Return array of all object names known to the system.

Object set words:

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

General object words

( obj -- )
Print inspect string of obj.
( obj -- )
Print object name of obj to current stdout.
( obj args -- result ) alias for object-apply
 
( obj -- val )
Return 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.
( 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.
( obj index -- )
Set cycle-index of obj to index.
( obj -- )
Set cycle-index of obj to zero.
( obj -- index )
Return current cycle-index of obj.
( obj key -- value ) alias for object-find
 
( obj -- f ) alias for object-empty?
 
( obj1 obj2 -- f ) alias for object-equal?
 
( obj -- val )
Return first element of obj. Raise an out-of-range exception if length of obj is less than 1.
( obj value -- )
Store value to first element of obj. Raise an out-of-range exception if length of obj is less than 1.
( obj -- id )
Return hash id computed from string representation of obj. Objects with the same content have the same id.
( obj key -- index ) alias for object-index
 
( obj -- val )
Return last element of obj. Raise an out-of-range exception if length of obj is less than 1.
( obj value -- )
Store value to last element of obj. Raise an out-of-range exception if length of obj is less than 1.
( obj -- len ) alias for object-length
 
( obj key -- f ) alias for object-member?
 
( obj -- ary )
Return obj as array.
( obj -- str )
Return string representation of obj.
( 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
( obj1 -- obj2 )
Return copy of obj1. Copy any element if obj1 is an instance.
( 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>>
( obj -- str )
Return dump string of obj which one can eval to get the object back.
( obj -- f )
Return #t if length of obj is zero, otherwise #f.
( obj1 obj2 -- f )
Return #t if obj1 and obj2 have equal content, otherwise #f.
( obj key -- value )
Search for key in obj and return corresponding value or #f if not found.
( obj -- id )
Return object id of obj, a uniq number.
( obj key -- index )
Search for key in obj and return index or -1 if not found.
( obj -- str )
Return inspect string of obj.
( obj -- len )
Return length of obj.
( obj key -- f )
Return #t if key is present in obj, otherwise #f.
( obj -- name )
Return object type name of OBJ as a string.
( obj index -- f )
Return #t if index is in range of obj, otherwise #f. If index is negative, return #f.
( 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.
( obj index value -- )
Set value at index to obj. If obj is of a type which can have multiple 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.
( obj index value -- )
Multiply value to value at index of obj. Value may be any number (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
( obj index value -- )
Add value to value at index of obj. Value may be any number (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
( obj index value -- )
Subtract value from value at index of obj. Value may be any number (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
( obj index value -- )
Divide value at index of obj by value. Value may be any number (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
( 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 )
( obj index -- f ) alias for object-range?
 
( obj -- val )
Return second element of obj. Raise an out-of-range exception if length of obj is less than 2.
( obj value -- )
Store value to second element of obj. Raise an out-of-range exception if length of obj is less than 2.
( obj cmp-xt -- ary ) alias for object-sort
 
( obj -- val )
Return third element of obj. Raise an out-of-range exception if length of obj is less than 3.
( obj value -- )
Store value to third element of obj. Raise an out-of-range exception if length of obj is less than 3.
( 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:

( obj -- f )
Return #t if obj is #t or #f, otherwise #f.
( obj -- f )
Return #t if obj is #f, otherwise #f.
( obj -- f )
Return #t if obj is nil, otherwise #f.
( obj -- f )
Return #t if obj is #t, otherwise #f.
( obj -- f )
Return #t if obj is undef, otherwise #f.

( :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
( :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
( :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 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.
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
( prt -- str )
Return content of prt object as string if available, otherwise #f.
( prt -- )
File and IO ports close their streams, other kind of ports do nothing.
( prt -- f )
Return #t if io object is closed, otherwise #f.
( prt obj -- )
Write the string representation of obj to prt object. If prt is #f, write to current output port (stout).
( prt -- )
File and IO ports flush their streams, other kind of ports do nothing.
( prt -- c )
Return next character from prt IO object. If prt is #f, read from current input port (stdin).
( prt -- str )
Return one line from prt IO object. If prt is #f, read from current input port (stdin).
( obj -- f )
Return #t if obj is an input IO object or #f, otherwise #f.
( obj -- f )
Return #t if obj is an output IO object or #f, otherwise #f.
( prt c -- )
Write character c to prt IO object. If prt is #f, write to current output port (stout).
( prt str -- )
Write str to prt IO object. If prt is #f, write to current output port (stout).
( 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
( prt -- str ) alias for port-gets
 
( prt str -- ) alias for port-puts
 
( prt fmt fmt-args -- ) alias for port-puts-format
 
( 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.
( 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 reset 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
%
( 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"
( 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"
( 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
%
( 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 reset 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
%

Current filename.
Current line number.
( prc -- )
Print proc object prc to current output.
( "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. Variable 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 immediate and compile only and can only be used in word definitions. 
: we-dont-need-args <{}> ;
<'> we-dont-need-args proc? ⇒ #t
( "name" -- f )
Return #t if name is defined in the dictionary, otherwise #f. 
defined?  10 ⇒ #f
defined? nil ⇒ #t
defined?   + ⇒ #t
( <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 immediate 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.
( obj -- str )
Return documentation string of obj (Forth word, object or topic) or #f.
( obj str -- )
Set documentation of obj (Forth word, object or topic) to str.
( -- 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 definitions. 
: new-word
	get-func-name .$
	space
	10
;
new-word ⇒ new-word 10
( 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 )
( lst req -- vals )
The plural form of get-optarg. args is an array with default values, 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 )
( 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 )
( 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 )
( "name" -- )
Print documentation of name (Forth word or topic) or "no documentation available". 
help make-array \ Forth word
help array      \ topic
( obj str -- )
Append str to documentation of obj.
( obj -- str )
Return documentation of obj (Forth word, object or topic) or "no documentation available".
( 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"
( -- 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
( -- xt )
Return latest defined xt.
( -- 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 }
( 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
( prc -- xt )
Return the actual word (the execution token xt) of prc.
( 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 execution 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
( prc -- arity )
Return arity array #( req opt rest ) of proc object prc, or #f if not a proc object.
( 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
( prc -- name )
Return name of proc object prc if found, otherwise an empty string.
( prc -- str )
Return source string property of prc, or #f if not available.
( prc str -- )
Set source string property of prc to str.
( obj -- f )
Return #t if obj is a proc object.
( prc args -- res ) alias for proc-apply
 
( -- 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
( "name" -- )
Show word definition of name.
( "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
( xt -- ?? )
Execute set-xt if found, otherwise raise an undefined-word exception. The following two lines do the same: 
128 <'> object-print-length set-execute
128 set-object-print-length
( xt1 -- xt2 )
Return set-xt if found, otherwise #f. 
<'> object-print-length set-xt ⇒ set-object-print-length
( xt -- file )
Return source file where xt was created or #f if xt is a primitive or not defined.
( xt -- line )
Return source line number where xt was created or #f if xt is a primitive or not defined.
( obj -- str )
Return source string of obj, a proc or xt, or #f if not found.
( obj str -- )
Set source string of obj, a proc or xt, to str.
( 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.
( 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
( var -- )
Remove previously installed hook from var.
( obj -- f )
Return #t if obj is a proc object or an xt (execution token, address of a Ficl word), otherwise #f.
( 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 -- str )
Return name of xt if found, otherwise an empty string.
( 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.
( obj -- f )
Return #t if obj is an xt (execution token, address of a Ficl word), otherwise #f.

This regexp variable can be set with the following constants. If more than one constant is used, combine them with or, see regex(3).
Compile modern regex, default.
Compile for matching ignore case.
Compile for newline-sensitive matching.
Compile without creating subexpression.
For example, set matching to ignore case before creating a new regexp 
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)+/
( str -- reg )
Return new regexp object from str which may contain regular expression. 
"(B|b)+" make-regexp value reg
( reg str start -- n )
Return count of matched characters or -1 for no match. 
/a*/ "aaaaab" 2 re-match ⇒ 3
( reg str start range -- n )
Return index of match or -1 for no match. 
/a*/ "aaaaab" 2 4 re-search ⇒ 2
( 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)+/
( reg str -- len|#f ) alias for 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 variables *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
( reg str -- len|#f ) alias for regexp-match
 
( reg str1 replace -- str2 )
Replace 1st occurrence of reg in str1 with replace if found. References \1 to \9 in replace will be replaced by corresponding subexpressions. 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 .
( 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
( obj -- f )
Return #t if obj is a regexp object, otherwise #f. 
/^s/ regexp? ⇒ #t

( <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
 
( addr len -- str )
Return Forth string addr len as string object. Standard words like type and evaluate require this kind of string.
( -- str )
Return carriage return string object ("\n").
( -- str )
Return string of one space (" ").
( len -- str )
Return string of len spaces. Raise an out-of-range exception if len < 0.
( obj -- ) alias for .string
 
( obj -- )
Print string representation of obj to stderr wrapped in #<DEBUG(F): ...>.
( obj -- )
Print string representation of obj to current error output.
( obj -- ) alias for .string
 
( obj -- )
Print string representation of obj to stderr.
( obj -- )
Print string representation of obj to stdout.
( obj -- )
Print string representation of obj to current output.
( str val -- str'  ) alias for string-push
 
( chars len -- str ) alias for string-concat
 
( obj -- )
Return #t if obj is a character, otherwise #f.
( str -- )
Print str wrappen in #<die: ...> to current stderr and exit interpreter with return code 1.
( str -- )
Print str wrappen in #<error: ...> to current stderr and throw exception.
( fmt args -- ) alias for string-format
 
( 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.
( 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.
( fmt :optional args -- str  )
Return string object from printf(3) fmt string and args array containing corresponding arguments; args is optional. See string-format for fmt description.
( fmt :optional args -- )
Print fmt string with corresponding args array to current stdout; args is optional. See string-format for fmt description.
( 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.
( len :key initial-element ' ' -- str )
Return a new string of length len filled with initial-element characters, default space. Raise an out-of-range exception if len < 0. 
3 :initial-element <char> x make-string ⇒ "xxx"
( str -- ary )
Convert str to an array of characters. 
"foo" string->array ⇒ #( 102 111 111 )
( str1 str2 -- str3 )
Return new string str1 + str2.
( str1 -- str2 )
Return new string with first character capitalized and remaining characters in lowercase.
( str -- str' )
Return str changed to first character capitalized and remaining characters to lowercase.
( str1 -- str2 )
Return new string object with possible trailing \n removed.
( str -- str' )
Return changed str with possible trailing \n removed.
( 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"
( str1 -- str2 )
Return copy of str1.
( 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.
( str1 -- str2 )
Return new string with all characters lowercase.
( str -- str' )
Return str changed to all characters lowercase.
( str -- ?? )
Evaluate str; values already on stack can be accessed, resulting values remain on stack. 
7 "3 4 + +" string-eval ⇒ 14
( 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.
( str char -- str' )
Fill str with char and return changed string object.
( 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"
( 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’ respective ‘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.
Floating point output like printf 3.
Single character output.
Integer output in binary, decimal, octal, unsigned and hexadecimal form.
Inspect string output of any Forth object with object-inspect.
String representation of any Forth object with object->string.
Dump string output of any Forth object with object-dump.
( str key -- idx )
Return index of string key in str or -1 if not found. 
"hello world" "orl" string-index ⇒ 7
( 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 index is not in range of string.
( str -- len )
If str is a string object, return its length, otherwise -1.
( str key -- f )
Return #t if string key exist in str, otherwise #f. 
"hello world" "ell" string-member? ⇒ #t
( str -- char )
Remove and return last character. If str is empty, return #f.
( str val -- str' )
Append string representation of val to str and return changed string object.
( str idx -- val )
Return character at position idx; negative index counts from backward. Raise an out-of-range exception if index is not in range of string.
( 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.
( 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.
( str1-- str2 )
Return str1 reversed as new string object.
( str -- str' )
Return the same string object str reversed.
( str idx val -- )
Store character char at index idx; negative index counts from backward. Raise an out-of-range exception if index is not in range of string.
( str -- char )
Remove and return first character. If str is empty, return #f.
( 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" )
( 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 exception 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"
( str val -- str' )
Prepend string representation of val to str and return changed string object.
( str1 -- str2 )
Return new string with all characters uppercase.
( str -- str' )
Return str changed to all characters uppercase.
( 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.
( str1 str2 -- f )
Return #t if str1 is lexicographically lesser than str2, otherwise #f.
( str1 str2 -- f )
Return #t if strings are not equal, otherwise #f.
( str1 str2 -- f )
Return #t if strings are equal, otherwise #f.
( str1 str2 -- f )
Return #t if str1 is lexicographically greater than str2, otherwise #f.
( 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.
( obj -- f )
Return #t if obj is a string object, otherwise #f.
( str -- ) alias for warning
 
( str -- )
Print str wrappen in #<warning: ...> to current stderr.

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

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

Hold last raised exception.
( ex -- )
Print exception ex to current output.
( 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
( 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.
( 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.
( ex -- msg )
Return message of exception ex.
( ex msg -- )
Set msg, a string or #f to exception ex.
( ex -- name )
Return name of exception ex. 
'new-exception exception-name ⇒ "new-exception"
( obj1 obj2 -- f )
Return #t if obj1 and obj2 are exeptions with identical name, otherwise #f.
( obj -- f )
Return #t if obj is a exception, otherwise #f.
( 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
( sym -- ex )
Return symbol sym as exception.

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

/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.

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

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 before reading file while the pattern of the second -e is evaluated in compile 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 separated 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]

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.

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).

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.

fth and this manual page was written by Michael Scholz ⟨mi-scholz@users.sourceforge.net⟩.

Please report bugs to the author.
2019/11/25 FreeBSD 13.1-RELEASE
Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.