FTH(1)                      General Commands Manual                     FTH(1)

NNAAMMEE
     fftthh - Forth script and extension language

SSYYNNOOPPSSIISS
     fftthh [--DDddQQqqrrvv] [--CC _s_o_-_l_i_b_-_p_a_t_h] [--EEee _p_a_t_t_e_r_n] [--FF _f_s] [--ff _i_n_i_t_-_f_i_l_e]
         [--II _f_s_-_p_a_t_h] [--SS "_l_i_b _i_n_i_t"] [--ss _f_i_l_e] [_f_i_l_e _._._.]
     fftthh [--aall] [--ii [_s_u_f_f_i_x]] [--nn | --pp] --ee _p_a_t_t_e_r_n [_f_i_l_e | _-]
     fftthh [--VV]

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

   AArrgguummeenntt lliisstt pprroocceessssiinngg
     --aa   Split every line to array *farray* before evaluation.  The split
          string is field separator *fs*.  Used with --nn or --pp option.
     --CC _p_a_t_h
          Prepend _p_a_t_h to *load-lib-path*, multiple calls possible.
     --DD   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.
     --dd   Set global variable *fth-debug* to #t.
     --EE _p_a_t_t_e_r_n
     --ee _p_a_t_t_e_r_n
          Evaluate _p_a_t_t_e_r_n.  After evaluation, if options --ee was specified,
          exit, if option --EE was specified, start read-eval-print-loop.
          Multiple calls possible.  If --DD 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 --ee _p_a_t_t_e_r_n can be
          considered between
                lambda: <{}> pattern ;
          and is in compile state!  If multiple --ee _p_a_t_t_e_r_n appear, all but the
          last are in interpret state.
     --FF _f_s
          Set global variable *fs* to field separator _f_s.
     --ff _f_i_l_e
          Take initialization file _f_i_l_e instead of _~_/_._f_t_h_r_c.  Use --QQ to
          prevent loading initialization files.
     --II _p_a_t_h
          Prepend _p_a_t_h to *load-path*, multiple calls possible.
     --ii [_s_u_f_f_i_x]
          The --ee _p_a_t_t_e_r_n will be applied to files or stdin.  If _s_u_f_f_i_x is
          specified, a backup file will be created with that suffix.
     --ll   Remove line ending \n when used with --nn or --pp option.
     --nn   Suppress output of current *line*.  If not in-place --ii, start an
          implicit loop.
     --pp   Print current *line* to stdout.  If not in-place --ii, start an
          implicit loop.
     --QQ   Neither load the system wide nor the local initialization file.
     --qq   Do not print banner and set global variable *fth-verbose* to #f.
     --rr   Start a conventional Forth-like session with data stack left
          untouched after pressing <Return>.  Normally the data stack is
          printed and cleared but --rr changes this behavior to something like a
          _r_e_a_d_-_e_v_a_l_-_l_o_o_p instead of a _r_e_a_d_-_e_v_a_l_-_p_r_i_n_t_-_l_o_o_p.  If --DD was given
          and evaluation was not successful, show backtrace and exit with
          return code 1, otherwise exit with return code 0.
     --SS "_l_i_b _i_n_i_t"
          Load C extension library _l_i_b and call the initialization function
          _i_n_i_t.  _l_i_b and _i_n_i_t must be enclosed in quotations
                -S "dbm Init_dbm"
          Multiple calls possible.
     --ss _f_i_l_e
          Evaluate _f_i_l_e 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 --ss _f_i_l_e.  This must be the last option given to the fftthh
          interpreter.  Options after that are taken as script options.  If --DD
          was given and evaluation was not successful, show a backtrace and
          exit with return code 1, otherwise exit with return code 0.
     --VV   Display version info and exit.
     --vv   Set global variable *fth-verbose* to #t (default).

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

   HHooookk vvaarriiaabblleess
     fftthh 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.
     bbeeffoorree--llooaadd--hhooookk ( filename -- f )
          Called before loading _f_i_l_e_n_a_m_e.  If hook returns #f, _f_i_l_e_n_a_m_e won't
          be loaded.
                before-load-hook lambda: <{ fname -- f }>
                        "\\ loading %s\n" #( fname ) fth-print
                        #t
                ; add-hook!
     aafftteerr--llooaadd--hhooookk ( filename -- )
          Called after loading _f_i_l_e_n_a_m_e and updating global variable
          *loaded-files*.
                after-load-hook lambda: <{ fname -- }>
                        "\\ %s loaded\n" #( fname ) fth-print
                ; add-hook!
     bbeeffoorree--rreeppll--hhooookk ( -- )
          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!
     aafftteerr--rreeppll--hhooookk ( 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!
     bbeeffoorree--pprroommpptt--hhooookk ( prompt pos -- new-prompt )
          Called before printing a new prompt to customize the output of it.
          _p_r_o_m_p_t is the old prompt and _p_o_s the current history position.  The
          return value, preferable a string, is the _p_r_o_m_p_t 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
          _*_p_r_o_m_p_t_s_t_y_l_e_* below:
                #t to *promptstyle*
                before-prompt-hook lambda: <{ prompt pos -- new-prompt }>
                        "%%Sfth (%d)%%s %%Bok%%b " #( pos ) string-format
                ; add-hook!

   TThhee ccoommmmaanndd--lliinnee eeddiittoorr
     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 MM--^^VV and from vi-mode to emacs-mode
     via MM--^^EE.  To start in vi-mode, put a line like
           edit-mode vi
     in your _~_/_._t_e_c_l_a_r_c file.  A history of the last command-lines can be
     listed with ^^XXhh, the last 10 history entries can be listed with MM--1100^^XXhh.
     The Tab-key or ^^II 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 _s_t_r_; the last ?? is optional
     !str    repeat last event starting with _s_t_r

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

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

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

   TTeeccllaa wwoorrddss
     bbiinnddkkeeyy ( :optional key action -- )
          Key bindings and others can be set in _~_/_._f_t_h_r_c to control libtecla
          and getline.
          no argument
                  Show user-defined key-bindings set for example in _~_/_._f_t_h_r_c.
          one argument
                  If _k_e_y is a string, take it as configure string.  If _k_e_y 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 _k_e_y and _a_c_t_i_o_n are strings, bind _a_c_t_i_o_n to _k_e_y.  If _k_e_y
                  is a string and _a_c_t_i_o_n is anything else, unbind _k_e_y from
                  last bind.  See tecla(7) for key-bindings and actions.
                        "^G" "user-interrupt" bindkey
                        "^G" #f bindkey
     hhiissttoorryy ( :optional action arg -- )
          History events can be displayed, loaded, saved, and cleared where
          _a_c_t_i_o_n can be one of
          gl-show
                  show _a_r_g or all history events
          gl-load
                  load history events from _a_r_g or *histfile*
          gl-save
                  save history events to _a_r_g 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

   LLooooppss
     Forth has loop constructs for compile state and interpret state.  In
     addition to the usual do--loop, fftthh provides each--end-each and map--end-
     map loops for objects.
     ddoo ( limit start -- ) compile-only
     ??ddoo ( limit start -- ) compile-only
     lloooopp ( -- ) compile-only
          Run loop from _s_t_a_r_t up to but not including _l_i_m_i_t.  ??ddoo starts only
          if _l_i_m_i_t is greater than _s_t_a_r_t.
                3 0 do  i .  loop => 0 1 2
     eeaacchh ( obj -- val ) compile-only
     eenndd--eeaacchh ( -- ) compile-only
          Push each element of _o_b_j in order on stack and repeat execution of
          body.
                #( 0 1 2 ) each  .  end-each => 0 1 2
     mmaapp ( obj -- ) compile-only
     mmaapp!! ( obj -- ) compile-only
     eenndd--mmaapp ( -- obj ) compile-only
          Set each element of _o_b_j in order to global variable *key* and repeat
          execution of body.  The current element of _o_b_j with mmaapp!! or a copy
          of _o_b_j with mmaapp is set to top of stack before eenndd--mmaapp.
                #( 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 ii, jj, kk and lleeaavvee etc can be used like in
     colon definitions.
     [[ddoo]] ( limit start -- )
     [[lloooopp]] ( -- )
                3 0 [do]  i .  [loop] => 0 1 2
     [[eeaacchh]] ( obj -- val )
     [[eenndd--eeaacchh]] ( -- )
                #( 0 1 2 ) [each]  .  [end-each] => 0 1 2
     [[mmaapp]] ( obj -- )
     [[mmaapp!!]] ( obj -- )
     [[eenndd--mmaapp]] ( -- 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 )

   AArrrraayyss aanndd LLiissttss
     Arrays:
     ##(()) ( -- ary )
          Return array of length 0 for array-append, array-push etc.
     ..aarrrraayy ( ary -- )
          Print array object _a_r_y to current output.
     >>aarrrraayy ( vals len -- ary )
          Return array object with _l_e_n objects found on parameter stack.
          Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0.
     aarrrraayy-->>aarrrraayy ( ary1 -- ary2 )
          Return copy of _a_r_y_1 only with references of each element in contrary
          to _a_r_r_a_y_-_c_o_p_y.  If _a_r_y_1 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 )
     aarrrraayy-->>lliisstt ( ary -- lst )
          Return copy of _a_r_y as list only with references of each elements in
          contrary to _a_r_r_a_y_-_c_o_p_y.  If _a_r_y 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 )
     aarrrraayy--aappppeenndd ( ary1 ary2 -- ary1+ary2 )
          Append two arrays and return new one.  If _a_r_y_2 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 )
     aarrrraayy--cclleeaarr ( ary -- )
          Clear array and set all elements to #f.
     aarrrraayy--ccoommppaacctt ( ary1 prc args -- ary2 )
          Return new array object with nil elements removed.
     aarrrraayy--ccoommppaacctt!! ( ary prc args -- ary' )
          Remove all nil elements from _a_r_y and return changed array object.
     aarrrraayy--ccoonnccaatt ( vals len -- ary ) alias for _>_a_r_r_a_y
     aarrrraayy--ccooppyy ( ary1 -- ary2 )
          Return copy of _a_r_y_1 with all elements new created in contrary to
          _a_r_r_a_y_-_>_a_r_r_a_y.
                #( 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 )
     aarrrraayy--ddeelleettee!! ( ary idx -- val )
          Delete and return one element from _a_r_y at position _i_d_x.  Negative
          index counts from backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x
          is not in _a_r_y_'_s range.
     aarrrraayy--ddeelleettee--kkeeyy ( ary key -- val )
          Delete and return _k_e_y from _a_r_y if found, otherwise return #f.
     aarrrraayy--ffiillll ( ary val -- )
          Set all elements of _a_r_y to _v_a_l.
     aarrrraayy--ffiinndd ( ary key -- key )
          Return key if _k_e_y exists in _a_r_y, otherwise #f.
     aarrrraayy--iinnddeexx ( ary key -- idx )
          Return index of _k_e_y in _a_r_y or -1 if not found.
     aarrrraayy--iinnsseerrtt ( ary1 idx val -- ary2 )
          Insert _v_a_l to _a_r_y_1 at position _i_d_x and return new array.  _v_a_l can be
          an array or any other object.  Negative _i_d_x counts from backward.
          Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _a_r_y_1_'_s range.
     aarrrraayy--iinnsseerrtt!! ( ary idx val -- ary' )
          Insert _v_a_l to _a_r_y at position _i_d_x and return changed array.  _v_a_l can
          be a single object or an array.  Negative _i_d_x counts from backward.
          Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _a_r_y_'_s range.
     aarrrraayy--jjooiinn ( ary sep -- str )
          Return string with all elements of _a_r_y converted to their string
          representation and joined together separated by the string _s_e_p.  If
          _s_e_p 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"
     aarrrraayy--lleennggtthh ( obj -- len )
          If _o_b_j is an array object, return its length, otherwise -1.
     aarrrraayy--mmeemmbbeerr?? ( ary key -- f )
          Return #t if _k_e_y exists in _a_r_y, otherwise #f.
     aarrrraayy--ppoopp ( ary -- val )
          Remove and return last element from _a_r_y.  If _a_r_y is empty, return
          #f.
     aarrrraayy--ppuusshh ( ary val -- ary' )
          Append _v_a_l to _a_r_y.
                #( 0 1 2 ) 10 array-push => #( 0 1 2 10 )
     aarrrraayy--rreeff ( ary idx -- val )
          Return value at position _i_d_x.  Negative index counts from backward.
          Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in _a_r_y_'_s range.
     aarrrraayy--rreejjeecctt ( ary1 prc args -- ary2 )
          _p_r_c will be called with _a_r_g_s, an array of zero or more proc
          arguments, and the current array element set as first arg in _a_r_g_s
          array.  The length of _a_r_g_s + 1 is the required arity of _p_r_c.  If _p_r_c
          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 )
     aarrrraayy--rreejjeecctt!! ( ary prc args -- ary' )
          _p_r_c will be called with _a_r_g_s, an array of zero or more proc
          arguments, and the current array element set as first arg in _a_r_g_s
          array.  The length of _a_r_g_s + 1 is the required arity of _p_r_c.  If _p_r_c
          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.
     aarrrraayy--rreevveerrssee ( ary1 -- ary2 )
          Return new array with elements reversed.
     aarrrraayy--rreevveerrssee!! ( ary -- ary' )
          Return _a_r_y with elements reversed.
     aarrrraayy--sseett!! ( ary idx val -- )
          Store _v_a_l at position _i_d_x.  Negative index counts from backward.
          Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in _a_r_y_'_s range.
     aarrrraayy--sshhiifftt ( ary -- val )
          Remove and return first element from _a_r_y.  If _a_r_y is empty, return
          #f.
     aarrrraayy--ssoorrtt ( ary1 prc -- ary2 )
          Return new sorted array.  _p_r_c 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 _b_a_d_-_a_r_i_t_y exception if _p_r_c
          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 )
     aarrrraayy--ssoorrtt!! ( ary prc -- ary' )
          Return the sorted _a_r_y.  _p_r_c 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 _b_a_d_-_a_r_i_t_y exception if _p_r_c doesn't take
          two arguments.
     aarrrraayy--ssuubbaarrrraayy ( ary start end -- subary )
          Return array built from _a_r_y beginning with index _s_t_a_r_t up to but
          excluding index _e_n_d.  If _e_n_d is nil, up to end of array will be
          returned.  Negative index counts from backward.  Raise an
          _o_u_t_-_o_f_-_r_a_n_g_e exception if _s_t_a_r_t is not in _a_r_y_'_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 )
     aarrrraayy--uunniiqq ( ary1 -- ary2 )
          Return new array without duplicated elements of _a_r_y_1.
     aarrrraayy--uunniiqq!! ( ary -- ary' )
          Return _a_r_y without duplicated elements.
     aarrrraayy--uunnsshhiifftt ( ary val -- ary' )
          Prepend _v_a_l to _a_r_y.
                #( 0 1 2 ) 10 array-unshift => #( 10 0 1 2 )
     aarrrraayy== ( ary1 ary2 -- f )
          Return #t if _a_r_y_1 and _a_r_y_2 are array objects of same length and
          content, otherwise #f.
     aarrrraayy?? ( obj -- f )
          Return #t if _o_b_j is an array object, otherwise #f.
     mmaakkee--aarrrraayy ( len :key initial-element -- ary )
          Return array of length _l_e_n filled with keyword INITIAL-ELEMENT
          values.  _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t defaults to nil if not specified.  Raise an
          _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0.

     Assoc arrays:
     >>aassssoocc ( vals len -- ary )
          Return assoc array object with _l_e_n / 2 key-value pairs found on
          parameter stack.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0 or not
          even.
     aarrrraayy--aassssoocc ( ass key -- ret )
          If _k_e_y matches, return corresponding key-value pair, otherwise #f.
     aarrrraayy--aassssoocc--rreeff ( ass key -- val )
          If _k_e_y matches, return corresponding value, otherwise #f.
     aarrrraayy--aassssoocc--rreemmoovvee!! ( ass key -- 'ass )
          If _k_e_y matches, remove key-value pair from _a_s_s.
     aarrrraayy--aassssoocc--sseett!! ( ass key val -- 'ass )
          If _k_e_y matches, set key-value pair, otherwise add new pair.
     aassssoocc ( ass key val -- 'ass )
          Build sorted assoc array.  _a_s_s 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 ) )
     aassssoocc?? ( obj -- f )
          Return #t if _o_b_j is an assoc array object, otherwise #f.

     Lists:
     ''(()) ( -- lst )
          Return empty list.
     ..lliisstt ( lst -- )
          Print list object _l_s_t to current output.
     >>lliisstt ( vals len -- lst )
          Return list object with _l_e_n objects found on parameter stack.  Raise
          an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0.
     ccaaddddddrr ( lst -- val )
          Return fourth entry, the cadddr, of _l_i_s_t or nil.
     ccaaddddrr ( lst -- val )
          Return third entry, the caddr, of _l_i_s_t or nil.
     ccaaddrr ( lst -- val )
          Return second entry, the cadr, of _l_i_s_t or nil.
     ccaarr ( lst -- val )
          Return first entry, the car, of _l_i_s_t or nil.
     ccddddrr ( lst -- val )
          Return rest, the cddr, of _l_i_s_t without its first and second entries.
     ccddrr ( lst -- val )
          Return rest, the cdr, of _l_i_s_t without its first entry.
     ccoonnss ( val lst1 -- lst2 )
          Return Lisp-like cons pointer with _v_a_l as car and _l_i_s_t as cdr.
     ccoonnss22 ( val1 val2 lst1 -- lst2 )
          Return Lisp-like cons pointer with _v_a_l_1 as car, _v_a_l_2 as cadr and
          _l_i_s_t as cddr.
     ccoonnss?? ( obj -- f )
          Return #t if _o_b_j is a cons pointer, otherwise #f.
     llaasstt--ppaaiirr ( lst -- lp )
          Return last pair of _l_s_t.
                '( 0 1 2 3 ) last-pair => '( 3 )
     lliisstt-->>aarrrraayy ( lst -- ary )
          Return copy of _l_s_t as array only with references of each element in
          contrary to _l_i_s_t_-_c_o_p_y.  _l_s_t 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 )
     lliisstt--aappppeenndd ( arg0 arg1 ... argn n -- lst )
          Return list object with _n objects found on parameter stack.  Raise
          an _o_u_t_-_o_f_-_r_a_n_g_e exception if _n < 0.
     lliisstt--ccooppyy ( lst1 -- ary2 )
          Return copy of _l_s_t_1 with all elements new created in contrary to
          _l_i_s_t_-_>_a_r_r_a_y.
                '( 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 )
     lliisstt--ddeelleettee ( lst1 key -- lst2 )
          Return new list without all elements equal _k_e_y.
     lliisstt--ddeelleettee!! ( lst key -- lst' )
          Return _l_s_t without all elements equal _k_e_y.
     lliisstt--ffiillll ( lst val -- lst' )
          Set all elements of _l_s_t to _v_a_l.
     lliisstt--hheeaadd ( lst1 idx -- lst2 )
          Return first _i_d_x entries of _l_s_t_1 in a new list or nil.
     lliisstt--iinnddeexx ( lst key -- idx )
          Return index of _k_e_y in _l_s_t or -1 if not found.
     lliisstt--iinnsseerrtt ( lst1 idx val -- lst2 )
          Insert _v_a_l to _l_s_t_1 at position _i_d_x and return new list.  _v_a_l can be
          a list or any other object.  Negative _i_d_x counts from backward.
          Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_1_'_s range.
     lliisstt--lleennggtthh ( obj -- len )
          If _o_b_j is a list (or array), return length of list, if _o_b_j is nil,
          return 0 otherwise -1.
     lliisstt--mmeemmbbeerr?? ( lst key -- f )
          Return #t if _k_e_y exists in _l_s_t, otherwise #f.
     lliisstt--rreeff ( lst idx -- val )
          Return value at position _i_d_x of _l_s_t.  Negative _i_d_x counts from
          backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_'_s
          range.
     lliisstt--rreevveerrssee ( lst1 -- ary2 )
          Return new list with elements reversed.
     lliisstt--sseett!! ( lst idx val -- )
          Store element _v_a_l at position _i_d_x in _l_s_t.  Negative _i_d_x counts from
          backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_'_s
          range.
     lliisstt--sslliiccee ( lst1 idx :key count 1 -- lst2 )
          Return new list without _c_o_u_n_t elements from _i_d_x on.  Raise an
          _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_1_'_s range.
                #( 0 1 1 2 ) 1 :count 2 list-slice => #( 0 2 )
     lliisstt--sslliiccee!! ( lst idx :key count 1 -- lst' )
          Return _l_s_t without _c_o_u_n_t elements from _i_d_x on.  Raise an
          _o_u_t_-_o_f_-_r_a_n_g_e exception if _i_d_x is not in _l_s_t_'_s range.
     lliisstt--ttaaiill ( lst1 idx -- lst2 )
          Return _i_d_x_'_t_h cdr of _l_s_t_1 up to the last entry in a new list or nil.
     lliisstt== ( lst1 lst2 -- f )
          Return #t if _l_s_t_1 and _l_s_t_2 are list objects of same length and
          content, otherwise #f.
     lliisstt?? ( obj -- f )
          Return #t if _o_b_j is a list (nil or a cons pointer), otherwise #f.
     mmaakkee--lliisstt ( len :key initial-element nil -- lst )
          Return list of length _l_e_n filled with keyword _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t
          values.  _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t defaults to nil if not specified.  Raise an
          _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0.
     nniill?? ( obj -- f )
          Return #t if _o_b_j is nil, otherwise #f.
     nnuullll?? ( obj --f ) alias for _n_i_l_?
     ppaaiirr?? ( obj -- f )
          Return #t if _o_b_j is a pair (a cons pointer), otherwise #f.
     sseett--ccaarr!! ( lst val -- lst' )
          Set _v_a_l to car of _l_s_t.
     sseett--ccddrr!! ( lst val -- lst' )
          Set _v_a_l to cdr of _l_s_t.

     Assoc lists:
     >>aalliisstt ( vals len -- alst )
          Return assoc list object with _l_e_n / 2 key-value pairs found on
          parameter stack. Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0 or not
          even.
     aaccoonnss ( key val alst1 -- alst2 )
          Return new Lisp-like associated list from _k_e_y_-_v_a_l pair and _a_l_s_t_1.
     lliisstt--aassssoocc ( alst key -- ret )
          If _k_e_y matches, return corresponding key-value pair, otherwise #f.
     lliisstt--aassssoocc--rreeff ( alst key -- val )
          If _k_e_y matches, return corresponding value, otherwise #f.
     lliisstt--aassssoocc--rreemmoovvee!! ( alst key -- alst' )
          If _k_e_y matches, remove key-value pair from _a_l_s_t.  Return current
          assoc-list.
     lliisstt--aassssoocc--sseett!! ( alst key val -- alst' )
          If _k_e_y matches, set key-value pair, otherwise add new pair to _a_l_s_t.
          Return current assoc-list.

   FFiillee FFuunnccttiioonnss
     General functions:
     cchhddiirr ( path -- ) alias for _f_i_l_e_-_c_h_d_i_r
     cclloossee--ppiippee ( 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
     ffiillee--aattiimmee ( name -- time )
          If _n_a_m_e is a file, return its last access time, otherwise #f.  One
          can convert the number in a readable string with ttiimmee-->>ssttrriinngg.
     ffiillee--bbaasseennaammee ( name ext -- base )
          Return basename of file _n_a_m_e depending on _e_x_t.  _e_x_t may be #f,
          nil/undef, a string or a regexp.  If _e_x_t is #f, return filename
          without pathname.  If _e_x_t is nil or undef, discard the part from the
          last dot to the end of basename _n_a_m_e.  If _e_x_t is a string or a
          regexp, discard found _e_x_t from basename _n_a_m_e.
                "/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"
     ffiillee--cchhddiirr ( path -- )
          Change working directory to _p_a_t_h and, if in a repl, print result to
          current standard output.  If _p_a_t_h is nil, change working directory
          to $HOME.  _p_a_t_h may contain `~' as an abbreviation for home
          directory.
     ffiillee--cchhmmoodd ( name mode -- )
          Change access mode of file _n_a_m_e to _m_o_d_e.  You can write _m_o_d_e with
          octal numbers: prepend the number with `0o', this is number zero `0'
          and lower letter `o', similar to `0x' for hexadecimal numbers.
     ffiillee--cchhrroooott ( path -- )
          Change root directory to _p_a_t_h and, if in a repl, print result to
          current standard output.  This function is restricted to the super-
          user.
     ffiillee--ccooppyy ( src dst -- )
          Copy file _s_r_c to _d_s_t.  If _d_s_t is a directory, copy _s_r_c to _D_S_T_/_S_R_C.
          Raise a _s_y_s_t_e_m_-_e_r_r_o_r exception if fopen(3) fails on any of the two
          files.
     ffiillee--ccttiimmee ( name -- time )
          If _n_a_m_e is a file, return its status change time, otherwise #f.  One
          can convert the number in a readable string with ttiimmee-->>ssttrriinngg.
     ffiillee--ddeelleettee ( name -- )
          If file _n_a_m_e exist, delete it, otherwise do nothing.
     ffiillee--ddiirr ( dir -- files-ary )
          Return an array of all filenames found in _d_i_r.
     ffiillee--ddiirrnnaammee ( name -- path )
          Return directory part of file _n_a_m_e.
                "/home/mike/cage.snd" file-dirname => "/home/mike"
     ffiillee--eevvaall ( name -- )
          Load and eval content of file _n_a_m_e and add _n_a_m_e to *loaded-files* if
          it wasn't there.  It's similar to iinncclluuddee except that _n_a_m_e must be
          on stack (include is a parse word).  With ffiillee--eevvaall one can load
          files from within word definitions.  Raise a _l_o_a_d_-_e_r_r_o_r exception if
          ffiillee--eevvaall fails.
     ffiillee--ffuullllppaatthh ( name -- path )
          Return current working directory prepended to file _n_a_m_e.  If name
          starts with a slash, return _n_a_m_e unchanged.
     ffiillee--iinnssttaallll ( src dst mode -- f )
          Install _s_r_c to _d_s_t with access mode _m_o_d_e if _d_s_t doesn't exist or if
          modification time of _s_r_c is greater than _d_s_t_'_s.  If _d_s_t is a
          directory, install _s_r_c to _d_s_t_/_s_r_c.  Return #t if _s_r_c could be
          installed, otherwise #f.  You can write _m_o_d_e 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
     ffiillee--lleennggtthh ( name -- len )
          If _n_a_m_e is a file, return its length in bytes, otherwise #f.
     ffiillee--mmaattcchh--ddiirr ( dir reg -- files-ary )
          Return an array of filenames in _d_i_r matching regexp _r_e_g.
     ffiillee--mmkkddiirr ( name mode -- )
          Create directory named _n_a_m_e with access mode _m_o_d_e.  You can write
          _m_o_d_e with octal numbers: prepend the number with `0o', this is
          number zero `0' and lower letter `o', similar to `0x' for
          hexadecimal numbers.
     ffiillee--mmkkffiiffoo ( name mode -- )
          Create fifo named _n_a_m_e with access mode _m_o_d_e.  You can write _m_o_d_e
          with octal numbers: prepend the number with `0o', this is number
          zero `0' and lower letter `o', similar to `0x' for hexadecimal
          numbers.
     ffiillee--mmttiimmee ( name -- time )
          If _n_a_m_e is a file, return its last modification time, otherwise #f.
          One can convert the number in a readable string with ttiimmee-->>ssttrriinngg.
     ffiillee--ppwwdd ( -- path )
          Return current working directory.
     ffiillee--rreeaallppaatthh ( name -- path )
          If _n_a_m_e starts with `~', replace it with content of environment
          variable $HOME.  If realpath(3) function exists, return resolved
          path, otherwise return _n_a_m_e with `~' replacement.
                "~" file-realpath => "/home/mike"
                "/usr/local" file-chdir => "/usr/local"
                file-pwd => "/usr/local"
                "../bin" file-realpath => "/usr/bin"
     ffiillee--rreennaammee ( src dst -- )
          Rename _s_r_c to _d_s_t.
     ffiillee--rrmmddiirr ( name -- )
          Remove empty directory _n_a_m_e.
     ffiillee--sshheellll ( cmd -- str )
          Open pipe for reading, feed it with _c_m_d 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).
     ffiillee--sspplliitt ( name -- ary )
          Split file _n_a_m_e in dirname and basename and return result in array
          of two strings.
                "/home/mike/cage.snd" file-split
                  => #( "/home/mike" "cage.snd" )
     ffiillee--ssyymmlliinnkk ( src dst -- )
          Create symlink from _s_r_c named _d_s_t.
     ffiillee--ssyysstteemm ( cmd -- f )
          Execute _c_m_d 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.
     ffiillee--ttoouucchh ( name time -- )
          Change modification time of _n_a_m_e to _t_i_m_e.  If _t_i_m_e is nil, use
          current time.
     ffiillee--ttrruunnccaattee ( name size -- )
          Truncate or extend file _n_a_m_e to _s_i_z_e bytes.
     ooppeenn--ppiippee ( 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
     sshheellll ( cmd -- str ) alias for _f_i_l_e_-_s_h_e_l_l

     File test functions:
     ffiillee--bblloocckk?? ( name -- f )
          Return #t if _n_a_m_e is a block special file, otherwise #f.
     ffiillee--cchhaarraacctteerr?? ( name -- f )
          Return #t if _n_a_m_e is a character special file, otherwise #f.
     ffiillee--ddiirreeccttoorryy?? ( name -- f )
          Return #t if _n_a_m_e is a directory, otherwise #f.
     ffiillee--eexxeeccuuttaabbllee?? ( name -- f )
          Return #t if _n_a_m_e is an executable file, otherwise #f.
     ffiillee--eexxiissttss?? ( name -- f )
          Return #t if _n_a_m_e is an existing file, otherwise #f.
     ffiillee--ffiiffoo?? ( name -- f )
          Return #t if _n_a_m_e is a named pipe, otherwise #f.
     ffiillee--ggrrppoowwnneedd?? ( name -- f )
          Return #t if _n_a_m_e matches effective gid, otherwise #f.
     ffiillee--oowwnneedd?? ( name -- f )
          Return #t if _n_a_m_e matches effective uid, otherwise #f.
     ffiillee--rreeaaddaabbllee?? ( name -- f )
          Return #t if _n_a_m_e is a readable file, otherwise #f.
     ffiillee--sseettggiidd?? ( name -- f )
          Return #t if _n_a_m_e has set gid bit, otherwise #f.
     ffiillee--sseettuuiidd?? ( name -- f )
          Return #t if _n_a_m_e has set uid bit, otherwise #f.
     ffiillee--ssoocckkeett?? ( name -- f )
          Return #t if _n_a_m_e is a socket, otherwise #f.
     ffiillee--ssttiicckkyy?? ( name -- f )
          Return #t if _n_a_m_e has set sticky bit, otherwise #f.
     ffiillee--ssyymmlliinnkk?? ( name -- f )
          Return #t if _n_a_m_e is a symbolic link, otherwise #f.
     ffiillee--wwrriittaabbllee?? ( name -- f )
          Return #t if _n_a_m_e is a writable file, otherwise #f.
     ffiillee--zzeerroo?? ( name -- f )
          Return #t if _n_a_m_e length is zero, otherwise #f.

   HHaasshhss
     ##{{}} ( -- hash ) alias for _m_a_k_e_-_h_a_s_h
     ..hhaasshh ( hash -- )
          Print _h_a_s_h object to current output.
     >>hhaasshh ( vals len -- hash )
          Take _l_e_n / 2 key-value pairs from parameter stack and return hash
          object.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n < 0 or _l_e_n is not
          even.
                'foo 0  'bar 1  4 >hash =>  #{ 'foo => 0  'bar => 1 }
     hhaasshh-->>aarrrraayy ( hash -- ass )
          Return array with #( key value ) pairs of _h_a_s_h_'_s content.
                #{ 'foo 0 'bar 1 } hash->array
                  => #( #( 'foo  0 ) #( 'bar  1 ) )
     hhaasshh--cclleeaarr ( hash -- )
          Remove all entries from _h_a_s_h, _h_a_s_h_'_s length is zero.
     hhaasshh--ccooppyy ( hash1 -- hash2 )
          Return copy of _h_a_s_h_1 using object-copy for all elements.
     hhaasshh--ddeelleettee!! ( hash key -- ary )
          Delete key-value pair associated with _k_e_y and return key-value array
          or #f if not found.
     hhaasshh--eeaacchh ( hash proc -- )
          Run _p_r_o_c for each key-value pair.  _p_r_o_c_'_s stack effect must be ( key
          value -- ).
                #{ 'foo 0 'bar 1 } lambda: <{ key value -- }>
                        "%s=%s\n" #( key value ) fth-print
                ; hash-each
     hhaasshh--ffiinndd ( hash key -- ary )
          Return key-value array if _k_e_y exist or #f if not found.
     hhaasshh--kkeeyyss ( hash -- keys )
          Return array of keys.
     hhaasshh--mmaapp ( hash1 proc -- hash2 )
          Run _p_r_o_c for each key-value pair.  _p_r_o_c_'_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 }
     hhaasshh--mmeemmbbeerr?? ( hash key -- f )
          Return #t if _k_e_y exists, otherwise #f.
     hhaasshh--rreeff ( hash key -- value )
          Return associated value or #f if not found.
     hhaasshh--sseett!! ( hash key value -- )
          Set _k_e_y_-_v_a_l_u_e pair of _h_a_s_h.  If key exists, overwrite existing
          value, otherwise create new key-value entry.
     hhaasshh--vvaalluueess ( hash -- values )
          Return array of values.
     hhaasshh== ( obj1 obj2 -- f )
          Return #t if _o_b_j_1 and _o_b_j_2 are hash objects with same length and
          content, otherwise #f.
     hhaasshh?? ( obj -- f )
          Return #t if _o_b_j is a hash object, otherwise #f.
     mmaakkee--hhaasshh ( -- hash )
          Return empty hash object.
     mmaakkee--hhaasshh--wwiitthh--lleenn ( size -- hash )
          Return hash object with _s_i_z_e key-value pairs.  Keys are 0, 1, 2, ...
          and values are nil.

     Property functions:
     oobbjjeecctt--pprrooppeerrttiieess ( obj -- props )
          Return _o_b_j_'_s properties or #f if empty.
     oobbjjeecctt--pprrooppeerrttyy--rreeff ( obj key -- val )
          Return _o_b_j_'_s property val associated with _k_e_y or #f if not found.
     oobbjjeecctt--pprrooppeerrttyy--sseett!! ( obj key val -- )
          Set _k_e_y_-_v_a_l_u_e pair to _o_b_j_'_s property object.
     pprrooppeerrttiieess ( obj -- props )
          Return _o_b_j_'_s global properties or #f if empty.  If _o_b_j is #f, return
          entire global property object.
     pprrooppeerrttyy--rreeff ( obj key -- val )
          Return _o_b_j_'_s global property val associated with _k_e_y or #f if not
          found.
     pprrooppeerrttyy--sseett!! ( obj key val -- )
          Set _k_e_y_-_v_a_l_u_e pair to _o_b_j_'_s global property object.
     wwoorrdd--pprrooppeerrttiieess ( xt -- props )
          Return _x_t_'_s properties or #f if empty.
     wwoorrdd--pprrooppeerrttyy--rreeff ( xt key -- val )
          Return _x_t_'_s property val associated with _k_e_y or #f if not found.
     wwoorrdd--pprrooppeerrttyy--sseett!! ( xt key val -- )
          Set _k_e_y_-_v_a_l_u_e pair to _x_t_'_s property object.

   HHooookkss
     ..hhooookk ( hook -- )
          Print hook object _h_o_o_k to current output.
     aadddd--hhooookk!! ( hook prc -- ) alias for _h_o_o_k_-_a_d_d
     ccrreeaattee--hhooookk ( arity help "name" -- )
          Create hook variable _n_a_m_e with _a_r_i_t_y and documentation _h_e_l_p.  _a_r_i_t_y
          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
     hhooookk-->>aarrrraayy ( hook -- ary )
          Return array of all _h_o_o_k procedures.
     hhooookk-->>lliisstt ( hook -- proc-list ) alias for _h_o_o_k_-_>_a_r_r_a_y
     hhooookk--aadddd ( hook prc -- )
          Add hook procedure _p_r_c to _h_o_o_k.  Raise a _b_a_d_-_a_r_i_t_y exception if
          _p_r_c_'_s arity doesn't match _h_o_o_k_'_s arity.
     hhooookk--aappppllyy ( hook args -- value-list )
          Run all hook procedures with _a_r_g_s, an array of arguments.  _a_r_g_s can
          be an array of arguments or a single argument.  Raise a _b_a_d_-_a_r_i_t_y
          exception if _a_r_g_s_'_s length doesn't match _h_o_o_k_'_s arity.
                2 make-hook value hk1
                hk1  <'> + 2 make-proc  add-hook!
                hk1 #( 1 2 ) run-hook => #( 3 )
     hhooookk--aarriittyy ( hook -- arity )
          Return arity array of _h_o_o_k, #( req opt rest ).
                2 make-hook hook-arity => #( 2 0 #f )
     hhooookk--cclleeaarr ( hook -- )
          Remove all hook procedures from _h_o_o_k.
     hhooookk--ddeelleettee ( hook prc-or-name -- prc )
          Remove hook procedure _p_r_c_-_o_r_-_n_a_m_e from _h_o_o_k and return it.
          _p_r_c_-_o_r_-_n_a_m_e can be a string, an xt or a proc.
     hhooookk--eemmppttyy?? ( hook -- f )
          Return #t if no hook procedure exist in _h_o_o_k, otherwise #f.
     hhooookk--mmeemmbbeerr?? ( hook prc-or-name -- f )
          Return #t if procedure _p_r_c_-_o_r_-_n_a_m_e exist in _h_o_o_k, otherwise #f.
          _p_r_c_-_o_r_-_n_a_m_e can be a string, an xt or a proc.
     hhooookk--nnaammee ( hook -- name )
          Return name of _h_o_o_k as string if hook object, otherwise #f.
     hhooookk--nnaammeess ( hook -- name-list )
          Return array of hook procedure names (strings).
     hhooookk--pprrooccss ( hook -- proc-list ) alias for _h_o_o_k_-_>_a_r_r_a_y
     hhooookk== ( obj1 obj2 -- f )
          Return #t if _o_b_j_1 and _o_b_j_2 are hook objects of same arity and
          procedures, otherwise #f.
     hhooookk?? ( obj -- f )
          Return #t if _o_b_j is a hook object, otherwise #f.
     mmaakkee--hhooookk ( arity -- hook )
          Return hook object for procs accepting _a_r_i_t_y arguments.  _a_r_i_t_y 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
     rreemmoovvee--hhooookk!! ( hook prc-or-name -- prc ) alias for _h_o_o_k_-_d_e_l_e_t_e
     rreesseett--hhooookk!! ( hook -- ) alias for _h_o_o_k_-_c_l_e_a_r
     rruunn--hhooookk ( hook args -- value-list ) alias for _h_o_o_k_-_a_p_p_l_y

   IIOO FFuunnccttiioonnss
     Global variables:
     *stderr*
          Return current standard error output IO object.
     *stdin*
          Return current standard input IO object.
     *stdout*
          Return current standard output IO object.
     sseett--**ssttddeerrrr** ( io -- old )
          Set _i_o to current standard error and return old IO object.
     sseett--**ssttddiinn** ( io -- old )
          Set _i_o to current standard input and return old IO object.
     sseett--**ssttddoouutt** ( io -- old )
          Set _i_o to current standard output and return old IO object.
     sseett--vveerrssiioonn--ccoonnttrrooll ( val -- )
          Set current version control style.  Accepted values:
               #t     numbered backups
               nil    numbered/simple backups
               #f     simple backups
               undef  no backups
     vveerrssiioonn--ccoonnttrrooll ( -- val )
          Return current version control style.

     General IO functions:
     ..iioo ( io -- )
          Print _i_o object to current output.
     eexxiitt--ssttaattuuss ( -- n ) alias for _i_o_-_e_x_i_t_-_s_t_a_t_u_s
     iioo-->>ssttrriinngg ( io -- str )
          Return content of _i_o object as string if possible.
     iioo--cclloossee ( io -- )
          If necessary, flush _i_o, close _i_o object and set closed? to #t.
     iioo--cclloosseedd?? ( io -- f )
          Return #t if _i_o object is closed, otherwise #f.
     iioo--eeooff?? ( io -- f )
          Return #t if EOF is reached, otherwise #f.
     iioo--eexxiitt--ssttaattuuss ( -- n )
          Return exit status of last extern process called via file-shell,
          file-system, etc.
     iioo--ffddooppeenn ( fd :key fam r/o -- io )
          Connect file descriptor _f_d to new IO object.  If keyword _f_a_m was not
          given, open file read-only, otherwise use _f_a_m.  See _i_o_-_o_p_e_n 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)
     iioo--ffiilleennaammee ( io -- fname )
          Return filename of _i_o object or #f if filename is not available.
     iioo--ffiilleennoo ( io -- fd )
          Return file descriptor of _i_o.
     iioo--fflluusshh ( io -- )
          Flushe _i_o object if possible.
     iioo--ggeettcc ( io -- c )
          Return next character from _i_o object or #f if EOF.
     iioo--iinnppuutt?? ( obj -- f )
          Return #t if _o_b_j is an input IO object, otherwise #f.
     iioo--mmooddee ( io -- mode )
          Return access mode of _i_o object.
     iioo--ooppeenn ( name :key fam r/o if-exists overwrite -- io )
          Open file _n_a_m_e and return new IO object.  If keyword _f_a_m was not
          specified, open file read-only, otherwise take _f_a_m.  Possible _f_a_m
          values:
               aa//oo  apend "a"
               rr//aa  read/write-append "a+"
               rr//oo  read-only "r"
               rr//ww  read/write "w+"
               ww//oo  write-only "w"
          If keyword iiff--eexxiissttss was not specified, overwrite possible existing
          file before open it for writing or appending.  Possible iiff--eexxiissttss
          values:
               ::eerrrroorr
                    raise an _i_o_-_e_r_r_o_r exception if _n_a_m_e already exist
               ::oovveerrwwrriittee
                    overwrite existing file (default)
               ::rreennaammee
                    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
     iioo--ooppeenn--rreeaadd ( name -- io )
          Open file _n_a_m_e for reading and return new IO object.
     iioo--ooppeenn--wwrriittee ( name :key if-exists overwrite -- io )
          Open file _n_a_m_e for writing and return new IO object.  For keyword
          if-exists see _i_o_-_o_p_e_n.
     iioo--oouuttppuutt?? ( obj -- f )
          Return #t if _o_b_j is an output IO object, otherwise #f.
     iioo--ppooss--rreeff ( io -- pos )
          Return current _i_o object position.
     iioo--ppooss--sseett!! ( io pos -- )
          Set _i_o object position to _p_o_s.
     iioo--ppuuttcc ( io c -- )
          Write character _c to _i_o object.
     iioo--rreeaadd ( io -- line )
          Return next line from _i_o object or #f if EOF.
     iioo--rreeaaddlliinneess ( io -- array-of-lines )
          Return the entire _i_o object content as an array of strings, line by
          line.
     iioo--rreeooppeenn ( io1 name :key fam io1-fam -- io2 )
          Return new IO object as copy of _i_o_1 and close _i_o_1.  If _n_a_m_e is not a
          string, for example #f or nil, use filename from _i_o_1.  If keyword
          _f_a_m was not given, use mode from _i_o_1, otherwise use _f_a_m.  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
     iioo--rreewwiinndd ( io -- )
          Rewind position to begin of _i_o object.
     iioo--sseeeekk ( io offset :key whence io-seek-set -- pos )
          Add _o_f_f_s_e_t to the file position in _i_o object and return new
          position.  Keyword _w_h_e_n_c_e can have the following values:
                SEEK_SET
                     offset counts from begin of file (default)
                SEEK_CUR
                     offset counts from current position
                SEEK_END
                     offset counts from end of file.
     iioo--tteellll ( io -- pos ) alias for _i_o_-_p_o_s_-_r_e_f
     iioo--wwrriittee ( io line -- )
          Write _l_i_n_e to _i_o object.
     iioo--wwrriittee--ffoorrmmaatt ( io fmt args -- )
          Write string built from _f_m_t and array _f_m_t_-_a_r_g_s to _i_o object.
     iioo--wwrriitteelliinneess ( io array-of-lines -- )
          Write _a_r_r_a_y_-_o_f_-_l_i_n_e_s to _i_o object.
     iioo== ( obj1 obj2 -- f )
          Return #t if _o_b_j_1 and _o_b_j_2 are IO objects with equal filenames,
          modes and file positions, otherwise #f.
     iioo?? ( obj -- f )
          Return #t if _o_b_j is an IO object, otherwise #f.
     rreeaaddlliinneess ( name -- array-of-lines )
          Open file _n_a_m_e, read its content in an array, close file and return
          the array.
     wwrriitteelliinneess ( name array-of-lines -- )
          Open file _n_a_m_e, write the content of _a_r_r_a_y_-_o_f_-_l_i_n_e_s to it and close
          file.

     File functions:
     iioo--ooppeenn--ffiillee ( :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
          _m_a_k_e_-_s_o_f_t_-_p_o_r_t 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
     iioo--ooppeenn--iinnppuutt--ffiillee ( :key args -- io )
          General IO open function.  Return IO object for reading.  See _m_a_k_e_-
          _s_o_f_t_-_i_n_p_u_t_-_p_o_r_t 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
     iioo--ooppeenn--oouuttppuutt--ffiillee ( :key args -- io )
          General IO open function.  Return IO object for writing.  See _m_a_k_e_-
          _s_o_f_t_-_o_u_t_p_u_t_-_p_o_r_t 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
     mmaakkee--ffiillee--iinnppuutt--ppoorrtt ( name -- io ) alias for _i_o_-_o_p_e_n_-_r_e_a_d
     mmaakkee--ffiillee--oouuttppuutt--ppoorrtt ( name :key args -- io ) alias for _i_o_-_o_p_e_n_-_w_r_i_t_e
     mmaakkee--ffiillee--ppoorrtt ( name :key args -- io ) alias for _i_o_-_o_p_e_n

     Pipe functions:
     iioo--ppooppeenn ( cmd :key fam r/o -- io )
          Open pipe for command _c_m_d and return new IO object.  _c_m_d may be a
          string (with shell expansion) or an array of strings.  If keyword
          _f_a_m was not given, open pipe read-only, otherwise use _f_a_m.  See _i_o_-
          _o_p_e_n 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
     iioo--ppooppeenn--rreeaadd ( cmd -- io )
          Open read-only pipe for command _c_m_d and return new IO object.  _c_m_d
          may be a string (with shell expansion) or an array of strings.
     iioo--ppooppeenn--wwrriittee ( cmd -- io )
          Open write-only pipe for command _c_m_d and return new IO object.  _c_m_d
          may be a string (with shell expansion) or an array of strings.
     mmaakkee--ppiippee--iinnppuutt--ppoorrtt ( cmd -- io ) alias for _i_o_-_p_o_p_e_n_-_r_e_a_d
     mmaakkee--ppiippee--oouuttppuutt--ppoorrtt ( cmd -- io ) alias for _i_o_-_p_o_p_e_n_-_w_r_i_t_e
     mmaakkee--ppiippee--ppoorrtt ( cmd :key args -- io ) alias for _i_o_-_p_o_p_e_n

     String functions:
     iioo--ssooppeenn ( str :key fam r/o -- io )
          Open string with content _s_t_r_i_n_g and return new IO object.  If
          keyword _f_a_m was not given, opens string read-only, otherwise takes
          _f_a_m.  See _i_o_-_o_p_e_n 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"
     iioo--ssooppeenn--rreeaadd ( str -- io )
          Open read-only string with content _s_t_r and return new IO object.
     iioo--ssooppeenn--wwrriittee ( str -- io )
          Open _s_t_r for writing and return new IO object.
     mmaakkee--ssttrriinngg--iinnppuutt--ppoorrtt ( cmd -- io ) alias for _i_o_-_s_o_p_e_n_-_r_e_a_d
     mmaakkee--ssttrriinngg--oouuttppuutt--ppoorrtt ( cmd :key args -- io ) alias for _i_o_-_s_o_p_e_n_-_w_r_i_t_e
     mmaakkee--ssttrriinngg--ppoorrtt ( str :key fam r/o -- io ) alias for _i_o_-_s_o_p_e_n

     Socket functions:
     iioo--nnooppeenn (host :key port 1024 domain AF_INET -- io)
          Connect to an already established server and return new IO object.
          Raise an a _s_o_c_k_e_t_-_e_r_r_o_r exception if an error occured.  _h_o_s_t is a
          host name (AF_INET) or a path name (AF_UNIX).  If _h_o_s_t is not a
          string, "localhost" will be used.  _p_o_r_t is the connection port
          (default 1024) if _d_o_m_a_i_n is AF_INET, otherwise unused, and _d_o_m_a_i_n
          can be one of AF_INET (default) or AF_UNIX.  The socket is opened
          with _d_o_m_a_i_n, 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
     mmaakkee--ssoocckkeett--ppoorrtt ( host :key args -- io ) alias for _i_o_-_n_o_p_e_n
     nneett--aacccceepptt ( fd host domain -- io )
          Accept a connection on a socket and return an IO object after
          established connection.  _f_d is the socket descriptor, _h_o_s_t can be an
          arbitrary name, its only use is the name for the IO object, _d_o_m_a_i_n
          is one of AF_INET or AF_UNIX.  This is used on the server side of a
          socket connection.  Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if accept(2)
          fails.
     nneett--bbiinndd ( fd host port domain -- )
          Assign a name to a socket.  _f_d is the socket descriptor, _h_o_s_t is a
          host name (AF_INET) or a path name (AF_UNIX), _p_o_r_t is the port if
          _d_o_m_a_i_n is AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or
          AF_UNIX.  This is used on the server side of a socket connection.
          Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if bind(2) fails.
     nneett--ccoonnnneecctt ( fd host port domain -- io )
          Connect to a server and return IO object after an established
          connection.  _f_d is the socket descriptor, _h_o_s_t is a host name
          (AF_INET) or a name (AF_UNIX), _p_o_r_t is the port if _d_o_m_a_i_n is
          AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or AF_UNIX.
          This is used on the client side of a socket connection.  Raise a
          _s_o_c_k_e_t_-_e_r_r_o_r exception if connect(2) fails.
     nneett--lliisstteenn ( fd -- )
          Inform the operating system that connection requests should be
          delivered.  _f_d is the previously opened socket descriptor.  This is
          used on the server side of a socket connection.  Raise a
          _s_o_c_k_e_t_-_e_r_r_o_r exception if listen(2) fails.
     nneett--rreeccvv ( fd flags -- msg )
          Receive data via a socket and return it.  _f_d is the socket
          descriptor and _f_l_a_g_s can be 0, MSG_PEEK, or MSG_OOB.  Raise a
          _s_o_c_k_e_t_-_e_r_r_o_r exception if recv(2) fails.
     nneett--rreeccvvffrroomm ( fd flags host port domain -- msg )
          Receive data via a socket and return it.  _f_d is the socket
          descriptor, _f_l_a_g_s can be 0, MSG_PEEK, or MSG_OOB.  _h_o_s_t is a host
          name (AF_INET) or a path name (AF_UNIX), _p_o_r_t is the port if is
          AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or AF_UNIX.
          Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if recvfrom(2) fails.
     nneett--sseenndd ( fd msg flags -- )
          Send data via a socket.  _f_d is the socket descriptor, _m_s_g is the
          data to send and _f_l_a_g_s can be 0, MSG_PEEK or MSG_OOB.  Raise a
          _s_o_c_k_e_t_-_e_r_r_o_r exception if send(2) fails.
     nneett--sseennddttoo ( fd msg flags host port domain -- )
          Send data via a socket.  _f_d is the socket descriptor, _m_s_g is the
          data to send, _f_l_a_g_s can be 0, MSG_PEEK, or MSG_OOB.  _h_o_s_t is a host
          name (AF_INET) or a name (AF_UNIX), _p_o_r_t is the port if _d_o_m_a_i_n is
          AF_INET, otherwise unused, and _d_o_m_a_i_n is one of AF_INET or AF_UNIX.
          Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if sendto(2) fails.
     nneett--sshhuuttddoowwnn ( fd how -- )
          Close socket connection.  _f_d is the socket descriptor and _h_o_w is one
          of SHUT_RD, SHUT_WR or SHUT_RDWR.  Raise a _s_o_c_k_e_t_-_e_r_r_o_r exception if
          shutdown(2) fails.
     nneett--ssoocckkeett ( domain type -- fd )
          Return socket descriptor.  _d_o_m_a_i_n can be AF_INET or AF_UNIX, _t_y_p_e
          can be SOCK_STREAM or SOCK_DGRAM.  The third argument to socket(2)
          is 0 and cannot be set by the user.  Raise a _s_o_c_k_e_t_-_e_r_r_o_r 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

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

     Features and Source files:
     *features*
          Return array of all features.
     aadddd--ffeeaattuurree ( str -- )
          Add _s_t_r, a string or symbol, to *features* list.
                'snd add-feature
     aadddd--llooaadd--lliibb--ppaatthh ( path -- )
          Add string _p_a_t_h to *load-lib-path* array if not already there.
                "/home/mike/lib/fth" add-load-lib-path
     aadddd--llooaadd--ppaatthh ( path -- )
          Add string _p_a_t_h to *load-path* array if not already there.
                "/home/mike/share/fth" add-load-path
     aapprrooppooss (( oobbjj ---- aarryy ))
          Return array of dictionary entries matching regexpression or string
          _o_b_j.
                /do/ apropos => #( "doLocal" ... )
     ddll--llooaadd ( "lib" "func" -- )
          Load dynamic library _l_i_b and call its function _f_u_n_c.
                dl-load dbm Init_dbm
     iinncclluuddee ( "name" -- )
          Load Forth source file _n_a_m_e and add _n_a_m_e to *loaded-files* if it
          wasn't already there.  If file extension wasn't specified, use
          `.fs'.  If _n_a_m_e doesn't exist, try each entry of *load-path* with
          _n_a_m_e.  With iinncclluuddee one can load a file more than once.  Before
          loading _n_a_m_e, run hook _b_e_f_o_r_e_-_l_o_a_d_-_h_o_o_k.  After loading _n_a_m_e, run
          hook _a_f_t_e_r_-_l_o_a_d_-_h_o_o_k.  Raise a _n_o_-_s_u_c_h_-_f_i_l_e exception if file
          doesn't exist, raise a _l_o_a_d_-_e_r_r_o_r if an error occured during load.
                include hello
     iinnssttaallll ( "file" -- )
          Install _f_i_l_e in first writeable path found in *load-path* (*.fs[m])
          or *load-lib-path* (*.so).  In the last example the trailing --ee is
          necessary because the last occurrence of --ee will be compiled.
          iinnssttaallll is a parse word and won't work in compile state.
                install snd-test.fs
                install sndlib.so
                % fth -ve "install sndlib.so" -e ""
     iinnssttaallll--ffiillee ( file -- )
          Install _f_i_l_e 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
     llooaadd--iinniitt--ffiillee ( file -- )
          If Forth source _f_i_l_e exists in current or $HOME dir, load it,
          otherwise do nothing.
                ".my-fth-init" load-init-file
     pprroovviiddeedd?? ( obj -- f )
          Return #t if _o_b_j, a string or symbol, exists in *features* list,
          otherwise #f.
                'fth provided? => #t
                'foo provided? => #f
     rreeqquuiirree ( "name" -- )
          If Forth source file _n_a_m_e doesn't exist in array *loaded-files*,
          load it and add _n_a_m_e to *loaded-files*.  If file extension wasn't
          specified, use `.fs'.  If _n_a_m_e doesn't exist, try each entry of
          *load-path* with _n_a_m_e.  With rreeqquuiirree one can load a file only one
          time.  Before loading _n_a_m_e, run hook _b_e_f_o_r_e_-_l_o_a_d_-_h_o_o_k.  After
          loading _n_a_m_e, run hook _a_f_t_e_r_-_l_o_a_d_-_h_o_o_k.  Raise a _n_o_-_s_u_c_h_-_f_i_l_e
          exception if file doesn't exist, raise a _l_o_a_d_-_e_r_r_o_r if an error
          occured during load.
                require hello
     uunnsshhiifftt--llooaadd--lliibb--ppaatthh ( path -- )
          Prepend string _p_a_t_h to *load-lib-path* array if not already there.
                "/home/mike/lib/fth" unshift-load-lib-path
     uunnsshhiifftt--llooaadd--ppaatthh ( path -- )
          Prepend string _p_a_t_h to *load-path* array if not already there.
                "/home/mike/share/fth" unshift-load-path

     Catch errors:
     fftthh--ccaattcchh ( ?? obj exc arg -- ?? res )
          Run proc or xt _o_b_j in save environment.  If _o_b_j fails with an
          exception, data and return stack environments are recovered to the
          state before execution.  If _o_b_j is #f, finishs immediately and
          returns #f.  The second argument _e_x_c 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 _a_r_g may
          be nil or a return value.  If _a_r_g is nil, the catched exception or
          #f will be returned, if _a_r_g is any other than nil, _a_r_g will be
          returned instead of the catched exception; if _a_r_g 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
     fftthh--rraaiissee ( exc fmt args -- )
          Raise exception _e_x_c with text built from _f_m_t and _a_r_g_s.  If _f_m_t is a
          format string with N %s-format signs, _a_r_g_s should have N elements
          with corresponding values.  If _e_x_c 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
     fftthh--tthhrrooww ( exc args -- )
          Throw exception _e_x_c with text built from _a_r_g_s.  If _a_r_g_s is not an
          array, its string representation is used. If _a_r_g_s is NIL or an empty
          array, a default string is used.  If _a_r_g_s is an array with one
          element, this string is used. If _a_r_g_s is an array and its first
          element is a format string with N %s-format signs, _a_r_g_s 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>
     ssttaacckk--rreesseett ( ?? -- )
          Reset the data stack to initial state.

     Time functions:
     ccuurrrreenntt--ttiimmee ( -- secs )
          Return time in seconds since 1970/01/01 as ficl2Unsigned.  See
          time(3) for more information.
     ggmmttiimmee ( secs -- ary )
          Return array of eleven elements with _s_e_c_s 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
     llooccaallttiimmee ( secs -- ary )
          Return array of eleven elements with _s_e_c_s converted to local time,
          see gmtime.
     mmkkttiimmee ( ary -- secs )
          Return time constructed from values of _a_r_y.  _a_r_y 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
     ssttrrffttiimmee ( fmt secs -- str )
          Convert ficl2Unsigned _s_e_c_s in a date string corresponding to _f_m_t.
          The _f_m_t 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"
     ssttrrppttiimmee ( str fmt -- secs )
          Parse _s_t_r according to _f_m_t and return seconds as ficl2Unsigned.
                "2012 01 14" "%Y %m %d" strptime time->string
                  => "Sat Jan 14 02:40:28 CET 2012"
     ttiimmee ( -- r )
          Return real time, a ficlFloat.
     ttiimmee-->>ssttrriinngg ( secs -- str )
          Convert ficl2Unsigned _s_e_c_s in a date string in current local time.
                current-time time->string => "Sat Jan 14 02:40:28 CET 2012"
     ttiimmee--rreesseett ( -- )
          Set global timeval struct variable to current time.
     uuttiimmee ( -- utime stime )
          Return user and system time as ficlFloats.  Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d
          exception if times(3) is not available.
                utime => 0.171875 0.0234375

     System information:
     ddaattee ( -- str )
          Return date in default UNIX format as a string.
     eennvviirroonn ( -- ary )
          Return hash of all shell environment variables and their values.
     eexxeecc ( cmd -- )
          Replace current process by running _c_m_d as shell command.  If _c_m_d is
          a string, shell expansion takes place and $SHELL -- or sshh if $SHELL
          is empty -- executes _c_m_d.  If _c_m_d is an array of strings, no shell
          expansion takes place and _c_m_d _N_O _0 _a_r_r_a_y_-_r_e_f should be a program
          name.
                lambda: <{}> #( "ls" "-lAF" ) exec ; fork
                lambda: <{}> "ls -lAF [A-Z]*" exec ; fork
     ffoorrkk ( xt -- pid )
          Create child process and execute _x_t in the child.  The child process
          returns nothing, parent returns child's process id.
                lambda: <{}> "ls -lAF" exec ; fork value pid
                pid SIGKILL kill
     ggeetteeggiidd ( -- id )
          Return effective group id of calling process.
     ggeetteennvv ( name -- value )
          Return content of shell environment variable _n_a_m_e as string or #f if
          variable is not defined.
     ggeetteeuuiidd ( -- id )
          Return effective user id of calling process.
     ggeettggiidd ( -- id )
          Return real group id of calling process.
     ggeetthhoossttnnaammee ( -- str )
          Return name of current host.
     ggeettllooggiinn ( -- str )
          Return name of user associated with current session.
     ggeettppiidd ( -- id )
          Return process id.
     ggeettppppiidd ( -- id )
          Return parent process id.
     ggeettsseerrvvbbyynnaammee ( str -- ary )
          Return array containing the service, an array of aliases, the port
          number and the protocol.  Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d exception if
          getservbyname(3) is not available.
                "smtp" getservbyname => #( "smtp" #( "mail" ) 25 "tcp" )
     ggeettsseerrvvbbyyppoorrtt ( port -- ary )
          Return array containing the service, an array of aliases, the port
          number and the protocol.  Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d exception if
          getservbyport(3) is not available.
                25 getservbyport => #( "smtp" #( "mail" ) 25 "tcp" )
     ggeettuuiidd ( -- id )
          Return real user id of calling process.
     hhoossttnnaammee ( -- )
     kkiillll ( pid sig -- )
          Send signal _s_i_g to process ID _p_i_d.  If _p_i_d is zero, send _s_i_g to
          current process.  _s_i_g is a number or a constant like SIGKILL.
     ppuutteennvv ( name value -- )
          Set _v_a_l_u_e to shell environment variable _n_a_m_e.
     sseetteeggiidd ( id -- )
          Set effective user _i_d.  This is only permitted if _i_d is equal real
          UID or effective UID or the effective UID is that of the super user.
     sseetteeuuiidd ( id -- )
          Set effective group _i_d.  This is only permitted if _i_d is equal real
          GID or effective GID or the effective UID is that of the super user.
     sseettggiidd ( id -- )
          Set real group _i_d.  This is only permitted if _i_d is equal real GID
          or effective GID or the effective UID is that of the super user.
     sseetthhoossttnnaammee ( str -- )
          Set name of current host to _s_t_r.  This call is restricted to the
          super-user.  Raise a _n_o_t_-_i_m_p_l_e_m_e_n_t_e_d exception if sethostname(3) is
          not available.
     sseettuuiidd ( id -- )
          Set real user _i_d.  This is only permitted if _i_d is equal real UID or
          effective UID or the effective UID is that of the super user.
     ssiiggnnaall ( sig xt -- old-xt )
          Install _x_t for signal _s_i_g as an signal handler and return old
          handler.  _X_T 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
     sslleeeepp ( secs -- )
          Pause for _s_e_c_s seconds.
     wwaaiitt ( -- pid )
          Wait for child process and return its process ID.  Set global read
          only variable exit-status to wait status.
     wwaaiittppiidd ( pid flags -- )
          Wait for child process _p_i_d.  Set global read only variable exit-
          status to wait status.  _f_l_a_g_s may be 0 or WNOHANG and WUNTRACED
          ored.
                1234 0 waitpid
                1234 WNOHANG waitpid
                1234 WNOHANG WUNTRACED or waitpid

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

     Getopt functions:
     ggeettoopptt ( argv opts -- c )
          Return next option character from command line options.  See
          _E_X_A_M_P_L_E_S for an getopt example.
     ggeettoopptt--lloonngg ( 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:
     ((bbyyee)) ( 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.
     ..ccffllaaggss ( -- )
          Print compiler flags to compile libfth.so to other applications.
     ..lliibbss ( -- )
          Print linker flags to link libfth.so to other applications.
     ..lloonngg--vveerrssiioonn ( -- )
          Print long package version.
     ..mmeemmoorryy ( -- )
          Print used and free dictionary cells.
     ..pprreeffiixx ( -- )
          Print installation prefix path.
     ..vveerrssiioonn ( -- )
          Print package version number.
     aatt--eexxiitt ( obj -- )
          _o_b_j, 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 _o_b_j must be ( -- ).
                lambda: <{ -- }> "test.file" file-delete ; at-exit
     ccoonnffiigg--ccffllaaggss ( -- str )
          Return compiler flags to compile libfth.so to other applications.
     ccoonnffiigg--lliibbss ( -- str )
          Return linker flags to link libfth.so to other applications.
     ccoonnffiigg--pprreeffiixx ( -- str )
          Return installation prefix path.
     ccoonnffiigguurree--aarrggss ( -- str )
          Return configure arguments.
     vveerr ( -- addr len )
          Return fth-version as a Forth string with addr len.
                ver type => "1.3.1 (19-Mar-2012) [i386-portbld-freebsd9.0]"

   NNuummbbeerrss
     Number predicates:
     bbiiggnnuumm?? ( obj -- f )
     ccoommpplleexx?? ( obj -- f )
     eevveenn?? ( obj -- f )
     eexxaacctt?? ( obj -- f )
     ffiixxnnuumm?? ( obj -- f )
     ffllooaatt?? ( obj -- f )
     iinneexxaacctt?? ( obj -- f )
     iinnff?? ( obj -- f )
     iinntteeggeerr?? ( obj -- f )
     lloonngg--lloonngg?? ( obj -- f )
     nnaann?? ( obj -- f )
     nnuummbbeerr?? ( obj -- f )
     oodddd?? ( obj -- f )
     pprriimmee?? ( obj -- f )
     rraattiioo?? ( obj -- f )
     rraattiioonnaall?? ( obj -- f ) alias for _r_a_t_i_o_?
     uulloonngg--lloonngg?? ( obj -- f )
     uunnssiiggnneedd?? ( obj -- f )
          Return #t if a given object is of corresponding type, otherwise #f.

     Miscellaneous math functions:
     >>bbiiggnnuumm ( x -- b ) alias for _s_>_b
          Convert any number _x to a bignum object.
     >>cc ( x -- c )
          Convert any number _x to a complex object.
     >>ccoommpplleexx ( r1 r2 -- c )
          Return complex object with real _r_1 and image _r_2.
     >>lllloonngg ( x -- d ) alias fo _s_>_d
          Convert any number _x to a llong object.
     >>rraattiioo ( x -- q ) alias for _s_>_q
          Convert any number _x to a ratio object.
     ddeennoommiinnaattoorr ( x -- n )
          Return denominator of _x or 1.
     eexxaacctt-->>iinneexxaacctt ( x -- r )
          Convert _x to an inexact number.
     iimmaagg--rreeff ( x -- r )
          Return the image part of Ar x .
     iimmaaggee--rreeff ( x -- r ) alias for _i_m_a_g_-_r_e_f
     iinneexxaacctt-->>eexxaacctt ( x -- n )
          Convert _x to an exact number.
     iinnff ( -- inf )
          Return Infinity.
     mmaakkee--bbiiggnnuumm ( x -- b )
          Return a new bignum object.
     mmaakkee--lloonngg--lloonngg ( val -- d ) alias for _s_>_d
          Return new llong object (ficl2Integer) from _v_a_l.
     mmaakkee--ppoollaarr ( real theta -- c )
          Return polar complex object from _r_e_a_l and _t_h_e_t_a.
     mmaakkee--rraattiioo ( num den -- q )
          Return a new ratio object with numerator _n_u_m and denumerator _d_e_n.
     mmaakkee--rreeccttaanngguullaarr ( r1 r2 -- c ) alias for _>_c_o_m_p_l_e_x
     mmaakkee--uulloonngg--lloonngg ( val -- ud ) alias for _s_>_u_d
          Return new ullong object (ficl2Unsigned) from _v_a_l.
     nnaann ( -- NaN )
          Return Not-A-Number.
     nnuummeerraattoorr ( x -- n )
          Return numerator of _x or 0.
     rraattiioonnaalliizzee ( x err -- y )
          Return inexact number within _e_r_r of _x.
     rreeaall--rreeff ( x -- r )
          Return the real part of _x.

     Pseudo randomize number functions:
     rraanndd--sseeeedd--rreeff ( -- seed )
          Return content of the seed variable fth_randx.
     rraanndd--sseeeedd--sseett!! ( seed -- )
          Set _s_e_e_d to the seed variable fth_randx.
     ffrraannddoomm ( r -- -r...+r )
          Return pseudo randomized value between _-_r and _+_r.
     rraannddoomm ( 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:
     ..rr ( n1 n2 -- )
          Print integer _n_1 in a right-adjusted field of _n_2 characters.
                17 3 .r => | 17 |
     cc.. ( c -- )
          Print complex number _c.
                17.0+1.0i c. => |17.000000+1.000000i |
     dd.. ( d -- )
          Print (Forth) double _d (ficl2Integer).
                17 d. => |17 |
     dd..rr ( d n -- )
          Print (Forth) double _d (ficl2Integer) in a right-adjusted field of _n
          characters.
                17 3 d.r => | 17 |
     ff..rr ( r n -- )
          Print float _r with _n digits after decimal point.
                17.0 3 f.r => |17.000 |
     bbnn.. ( b -- )
          Print bignum number.
                17.0 bn. => |17 |
     qq.. ( q -- )
          Print rational number.
                17.0 q. => |17/1 |
     uu..rr ( u n -- )
          Print unsigned integer _u in a right-adjusted field of _n characters.
                17 3 u.r => | 17 |
     uudd.. ( ud -- )
          Print (Forth) unsigned double _u_d (ficl2Unsigned).
                17 ud. => |17 |
     uudd..rr ( ud n -- )
          Print (Forth) unsigned double _u_d (ficl2Unsigned) in a right-adjusted
          field of _n characters.
                17 3 ud.r => | 17 |
     uuff..rr ( r len-all len-after-comma -- )
          Print float _r in a right-adjusted field of _l_e_n_-_a_l_l characters with
          _l_e_n_-_a_f_t_e_r_-_c_o_m_m_a digits.
                17.0 8 3 uf.r => | 17.000 |
                17.0 8 2 uf.r => |  17.00 |

     Comparison:
     00<< ( n -- f )
     00<<== ( n -- f )
     00<<>> ( n -- f )
     00== ( n -- f )
     00==>> ( n -- f )
     00>> ( n -- f )
     nneeggaattiivvee?? ( n -- f ) alias for _0_<
     ppoossiittiivvee?? << ( n -- f ) alias for _0_>_=
     zzeerroo?? ( 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 )
     nneeggaattiivvee?? ( n -- f ) alias for _0_<
     ppoossiittiivvee?? << ( n -- f ) alias for _0_>_=
     zzeerroo?? ( n -- f ) alias for _0_=
          Comparison between two integers (ficlInteger).
     uu<< ( u1 u2 -- f )
     uu<<== ( u1 u2 -- f )
     uu<<>> ( u1 u2 -- f )
     uu== ( u1 u2 -- f )
     uu==>> ( u1 u2 -- f )
     uu>> ( u1 u2 -- f )
          Comparison between two unsigned integers (ficlUnsigned).
     dd00<< ( d -- f )
     dd00<<== ( d -- f )
     dd00<<>> ( d -- f )
     dd00== ( d -- f )
     dd00>> ( d -- f )
     dd00>>== ( d -- f )
     ddnneeggaattiivvee?? ( d -- f ) alias for _d_0_<
     ddppoossiittiivvee?? << ( d -- f ) alias for _d_0_>_=
     ddzzeerroo?? ( d -- f ) alias for _d_0_=
          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
     dd<< ( d1 d2 -- f )
     dd<<== ( d1 d2 -- f )
     dd<<>> ( d1 d2 -- f )
     dd== ( d1 d2 -- f )
     dd>> ( d1 d2 -- f )
     dd>>== ( d1 d2 -- f )
          Comparison between two long integers (ficl2Integer).  _d_1 and _d_2 can
          be any type of number but should fit in ficl2Integer.
                1 2.0 d< => #t
                1.0 2 d= => #f
     dduu<< ( ud1 ud2 -- f )
     dduu<<== ( ud1 ud2 -- f )
     dduu<<>> ( ud1 ud2 -- f )
     dduu== ( ud1 ud2 -- f )
     dduu>> ( ud1 ud2 -- f )
     dduu>>== ( ud1 ud2 -- f )
          Comparison between two long unsigned integers (ficl2Unsigned).  _u_d_1
          and _u_d_2 can be any type of number but should fit in ficl2Unsigned.
                1 2.0 du< => #t
                1.0 2 du= => #f
     cc00<<>> ( c -- f )
     cc00== ( 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
     cc<<>> ( c1 c2 -- f )
     cc== ( c1 c2 -- f )
          Comparison between two numbers.  _c_1 and _c_2 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
     bb00<< ( b -- f )
     bb00<<== ( b -- f )
     bb00<<>> ( b -- f )
     bb00== ( b -- f )
     bb00>> ( b -- f )
     bb00>>== ( b -- f )
          Comparison between an arbitrary precision number and zero.  _b can be
          any type of number.
     bb<< ( b1 b2 -- f )
     bb<<== ( b1 b2 -- f )
     bb<<>> ( b1 b2 -- f )
     bb== ( b1 b2 -- f )
     bb>> ( b1 b2 -- f )
     bb>>== ( b1 b2 -- f )
          Comparison between two arbitrary precision big numbers.  _b_1 and _b_2
          can be any type of number.
     qq00<< ( q -- f )
     qq00<<== ( q -- f )
     qq00<<>> ( q -- f )
     qq00== ( q -- f )
     qq00>> ( q -- f )
     qq00>>== ( q -- f )
          Comparison between an arbitrary precision rational number and zero.
          _q can be any type of number.
     qq<< ( q1 q2 -- f )
     qq<<== ( q1 q2 -- f )
     qq<<>> ( q1 q2 -- f )
     qq== ( q1 q2 -- f )
     qq>> ( q1 q2 -- f )
     qq>>== ( q1 q2 -- f )
          Comparison between two arbitrary precision rational numbers.  _q_1 and
          _q_2 can be any type of number.

     Convertion between number types:
     >>bbiiggnnuumm ( x -- b )
     ff>>bb ( r -- b ) alias for _>_b_i_g_n_u_m
     ss>>bb ( n -- b ) alias for _>_b_i_g_n_u_m
          Convert any number to a bignum object (ficlBignum).
     >>cc ( x -- c )
     ff>>cc ( r -- c ) alias for _>_c
     qq>>cc ( q -- c ) alias for _>_c
     ss>>cc ( n -- c ) alias for _>_c
          Convert any number to a complex object (ficlComplex).
     ff>>dd ( r -- d ) alias for _s_>_d
     ss>>dd ( n -- d )
          Convert any number to a llong object (ficl2Integer).
     ff>>uudd ( r -- ud ) alias for _s_>_u_d
     ss>>uudd ( n -- ud )
          Convert any number to an ullong object (ficl2Unsigned).
     bb>>ff ( b -- r ) alias for _s_>_f
     cc>>ff ( c -- r ) alias for _s_>_f
     dd>>ff ( d -- r ) alias for _s_>_f
     qq>>ff ( q -- r ) alias for _s_>_f
     ss>>ff ( n -- r )
          Convert any number to a float object (ficlFloat).
     >>rraattiioo (( cc ---- qq )) aalliiaass ffoorr _s_>_q
     cc>>qq ( c -- q ) alias for _s_>_q
     ff>>qq ( r -- q ) alias for _s_>_q
     ss>>qq ( n -- q )
          Convert any number to a ratio object (ficlRatio).
     bb>>ss ( b -- n ) alias for _f_>_s
     cc>>ss ( c -- n ) alias for _f_>_s
     dd>>ss ( d -- n ) alias for _f_>_s
     ff>>ss ( r -- n )
     qq>>ss ( q -- n ) alias for _f_>_s
          Convert any number to Forth single word set number (ficlInteger).

     Math functions:
     11++ ( n1 -- n2 )
     11-- ( n1 -- n2 )
     22++ ( n1 -- n2 )
     22-- ( n1 -- n2 )
     22** ( n1 -- n2 )
     22// ( n1 -- n2 )
     aabbss ( n1 -- n2 )
     nneeggaattee ( n1 -- n2 )
          One argument integer (ficlInteger) operators.
     ++ ( n1 n2 -- n3 )
     -- ( n1 n2 -- n3 )
     ** ( n1 n2 -- n3 )
     // ( n1 n2 -- n3 )
     mmaaxx ( n1 n2 -- n3 )
     mmiinn ( n1 n2 -- n3 )
          Two argument integer (ficlInteger) operators.
     dd22** ( d1 -- d2 )
     dd22// ( d1 -- d2 )
     ddaabbss ( d1 -- d2 )
     ddnneeggaattee ( d1 -- d2 )
          One argument long integer (ficl2Integer) operators.  _d_1 can be any
          type of number but should fit in ficl2Integer.
     dd++ ( d1 d2 -- d3 )
     dd-- ( d1 d2 -- d3 )
     dd** ( d1 d2 -- d3 )
     dd// ( d1 d2 -- d3 )
     ddmmaaxx ( d1 d2 -- d3 )
     ddmmiinn ( d1 d2 -- d3 )
          Two argument long integer (ficl2Integer) operators.  _d_1 and _d_2 can
          be any type of number but should fit in ficl2Integer.
     11//ff ( r1 -- r2 )
     ff22** ( r1 -- r2 )
     ff22// ( r1 -- r2 )
     ffaabbss ( r1 -- r2 )
     ffnneeggaattee ( r1 -- r2 )
          One argument real number (ficlFloat) operators.  _r_1 can be any type
          of number but should fit in ficlFloat.
     ff++ ( r1 r2 -- r3 )
     ff-- ( r1 r2 -- r3 )
     ff** ( r1 r2 -- r3 )
     ff// ( r1 r2 -- r3 )
     ffmmaaxx ( r1 r2 -- r3 )
     ffmmiinn ( r1 r2 -- r3 )
          Two argument real numbers (ficlFloat) operators.  _r_1 and _r_2 can be
          any type of number but should fit in ficlFloat.
     ff**** ( r1 r2 -- r3 )
     ffaabbss ( r1 -- r2 )
     ffaaccooss ( r1 -- r2 )
     ffaaccoosshh ( r1 -- r2 )
     ffaalloogg ( r1 -- r2 )
     ffaassiinn ( r1 -- r2 )
     ffaassiinnhh ( r1 -- r2 )
     ffaattaann ( r1 -- r2 )
     ffaattaann22 ( r1 r2 -- r3 )
     ffaattaannhh ( r1 -- r2 )
     ffcceeiill ( r1 -- r2 )
     ffccooss ( r1 -- r2 )
     ffccoosshh ( r1 -- r2 )
     ffeexxpp ( r1 -- r2 )
     ffeexxppmm11 ( r1 -- r2 )
     fflloogg ( r1 -- r2 )
     fflloogg1100 ( r1 -- r2 )
     fflloogg22 ( r1 -- r2 )
     fflloogg11pp ( r1 -- r2 )
     ffllooggpp11 ( r1 -- r2 ) alias for _f_l_o_g_1_p
     fflloooorr ( r1 -- r2 )
     ffppooww ( r1 r2 -- r3 ) alias for _f_*_*
     ffrroouunndd ( r1 -- r2 )
     ffssiinn ( r1 -- r2 )
     ffssiinnccooss ( r1 -- r2 r3 )
     ffssiinnhh ( r1 -- r2 )
     ffssqqrrtt ( r1 -- r2 )
     ffttaann ( r1 -- r2 )
     ffttaannhh ( r1 -- r2 )
     ffttrruunncc ( r1 -- r2 )
          Math library functions for real numbers.  ffssiinnccooss returns sin(r1)
          and cos(r1).  _r_1 and probable second argument _r_2 can be any type of
          number but should fit in ficlFloat.
     11//cc ( c1 -- c2 )
     cc** ( c1 c2 -- c3 )
     cc**** ( c1 c2 -- c3 )
     cc++ ( c1 c2 -- c3 )
     cc-- ( c1 c2 -- c3 )
     cc// ( c1 c2 -- c3 )
     ccaabbss ( c1 -- c2 )
     ccaabbss22 ( c1 -- c2 )
     ccaaccooss ( c1 -- c2 )
     ccaaccoosshh ( c1 -- c2 )
     ccaarrgg ( c1 -- c2 )
     ccaassiinn ( c1 -- c2 )
     ccaassiinnhh ( c1 -- c2 )
     ccaattaann ( c1 -- c2 )
     ccaattaann22 ( c1 c2 -- c3 )
     ccaattaannhh ( c1 -- c2 )
     ccccooss ( c1 -- c2 )
     ccccoosshh ( c1 -- c2 )
     cceexxpp ( c1 -- c2 )
     cclloogg ( c1 -- c2 )
     cclloogg1100 ( c1 -- c2 )
     ccoonnjj ( c1 -- c2 )
     ccoonnjjuuggaattee ( c1 -- c2 ) alias for _c_o_n_j
     ccppooww ( c1 c2 -- c3 ) alias for _c_*_*
     ccssiinn ( c1 -- c2 )
     ccssiinnhh ( c1 -- c2 )
     ccssqqrrtt ( c1 -- c2 )
     ccttaann ( c1 -- c2 )
     ccttaannhh ( c1 -- c2 )
     mmaaggnniittuuddee ( c1 -- c2 )
          Math library functions for complex numbers.  _c_1 and probable second
          argument _c_2 can be any type of number but should fit in ficlComplex.
     bb22** ( b1 -- b2 )
     bb22// ( b1 -- b2 )
     bbaabbss ( b1 -- b2 )
     bbnneeggaattee ( b1 -- b2 )
          One argument arbitrary precision bignum functions.  _b_1 can be any
          type of number.
     bb++ ( b1 b2 -- b3 )
     bb-- ( b1 b2 -- b3 )
     bb** ( b1 b2 -- b3 )
     bb// ( b1 b2 -- b3 )
     bb**** ( b1 b2 -- b3 )
     bbmmaaxx ( b1 b2 -- b3 )
     bbmmiinn ( b1 b2 -- b3 )
     bbppooww ( b1 b2 -- b3 ) alias for _b_*_*
          Two argument arbitrary precision bignum functions.  _b_1 and _b_2 can be
          any type of number.
     bbggccdd ( x y -- z )
          Greatest common divisor.  _x and _y can be any type of number, _z is of
          type bignum.
     bbllccmm ( x y -- z )
          Least common multiple.  _x and _y can be any type of number, _z is of
          type bignum.
     bbrroooott ( b1 u -- b2 n )
          Returns the integer part of the _u _t_h root of _b_1.  On top of stack 1
          if result is exact, otherwise 0.
     bbssqqrrtt ( b1 -- b2 n )
          Returns the integer part of the square root of _b_1.  On top of stack
          1 if result is exact, otherwise 0.
     bbmmoodd ( b1 b2 -- b3 n )
          _b_3 becomes _b_1 modulo _b_2.
     bb//mmoodd ( b1 b2 -- b3 b4 n )
          Divide _b_1 by _b_2 where _b_3 becomes the remainder and _b_4 becomes the
          quotient.
     bbllsshhiifftt ( b1 n -- b2 )
     bbrrsshhiifftt ( b1 n -- b2 )
          Shifts arbitrary precision number _b_1 _n bits to left resp. right.  _b_1
          can be any type of number while _n has to be an integer
          (ficlInteger).
     11//qq ( q1 -- q2 )
     qqaabbss ( q1 -- q2 )
     qqcceeiill ( q1 -- q2 )
     qqfflloooorr ( q1 -- q2 )
     qqnneeggaattee ( q1 -- q2 )
          One argument arbitrary precision rational functions.  _q_1 can be any
          type of number.
     qq++ ( q1 q2 -- q3 )
     qq-- ( q1 q2 -- q3 )
     qq** ( q1 q2 -- q3 )
     qq// ( q1 q2 -- q3 )
     qq**** ( q1 q2 -- q3 )
     qqppooww ( q1 q2 -- q3 ) alias for _q_*_*
          Two argument arbitrary precision rational functions.  _q_1 and _q_2 can
          be any type of number.
     ffeeggeettrroouunndd (( ---- nn ))
     ffeesseettrroouunndd (( nn ---- ))
          Return or set current floating-point rounding mode, one of:
          FFEE__TTOONNEEAARREESS
          FFEE__DDOOWWNNWWAARRDD
          FFEE__UUPPWWAARRDD
          FFEE__TTOOWWAARRDDZZEERROO
          See fenv(3), fegetround(3) and fesetround(3).

     Constants:
     eeuulleerr     e (~2.71828)
     hhaallff--ppii   pi/2 (~1.5708)
     llnn--tteenn    log(10) (~2.30259)
     llnn--ttwwoo    log(2) (~0.693147)
     ppii        pi (~3.14159)
     ssqqrrtt--ttwwoo  sqrt(2) (~1.41421)
     ttwwoo--ppii    pi*2 (~6.28319)

   OObbjjeecctt ttyyppeess
     bbaacckkttrraaccee ( -- )
          Print last word list from stack frame to error output.
     bbtt ( -- ) alias for _b_a_c_k_t_r_a_c_e
     ffrraammee--ddeepptthh ( -- n )
          Internal global variable.  Return the current frame depth.
     oobbjjeecctt--pprriinntt--lleennggtthh ( -- n )
          Return the number of objects to print for objects like array, list,
          hash.  Default value is 12.
     sseett--oobbjjeecctt--pprriinntt--lleennggtthh ( 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.
     ssttaacckk--lleevveell ( -- n ) alias for _f_r_a_m_e_-_d_e_p_t_h

     Garbage collection words:
     ggcc--mmaarrkk ( obj -- obj )
          Mark _o_b_j to protect it from garbage collection on next gc-run.
     ggcc--mmaarrkkeedd?? ( obj -- f )
          Return #t if _o_b_j is an instance and mark flag is set.  All new
          created objects have mark flag set.
     ggcc--ooffff ( -- )
          Turn off garbage collection.  The return code is meaningless in
          Forth.
     ggcc--oonn ( -- )
          Turn on garbage collection.  The return code is meaningless in
          Forth.
     ggcc--ppeerrmmaanneenntt--oobbjjeeccttss ( -- ary )
          Return array of all permanent objects.
     ggcc--ppeerrmmaanneenntt?? ( obj -- f )
          Return #t if _o_b_j is an instance and permanent flag is set like
          constants.
     ggcc--pprrootteecctt ( obj -- obj )
          Protect _o_b_j from garbage collection until gc-unprotect.
     ggcc--pprrootteecctteedd--oobbjjeeccttss ( -- ary )
          Return array of all protected objects.
     ggcc--pprrootteecctteedd?? ( obj -- f )
          Return #t if _o_b_j is an instance and protected flag is set.
     ggcc--rruunn ( -- )
          Run garbage collection immediately.
     ggcc--ssttaattss ( -- )
          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
     ggcc--uunnmmaarrkk ( obj -- obj )
          Unmark _o_b_j to unprotect it from garbage collection on next gc-run.
     ggcc--uunnpprrootteecctt ( obj -- obj )
          Unprotect _o_b_j from garbage collection.

     Object type and instance words:
     iinnssttaannccee--ggeenn--rreeff ( obj -- gen )
          Return GEN-struct of _o_b_j.
     iinnssttaannccee--oobbjj--rreeff ( obj -- gen )
          Return object type of _o_b_j.
     iinnssttaannccee--ooff?? ( obj type -- f )
          Return #t if _o_b_j is an instance of _t_y_p_e, otherwise #f.
     iinnssttaannccee?? ( obj -- f )
          Return #t if _o_b_j is an instance, otherwise #f.
     mmaakkee--iinnssttaannccee ( gen obj -- instance )
          Return new instance of Object type _o_b_j with _g_e_n wrapped in.
     mmaakkee--oobbjjeecctt--ttyyppee ( name -- object-type )
          Create new object type _n_a_m_e.  Add _n_a_m_e to feature environment list,
          create a constant fth-_n_a_m_e of object-type and return new object-type
          _n_a_m_e.  The new created object-type can be used to bind functions to
          it.
     oobbjjeecctt--ttyyppee--rreeff ( obj -- struct )
          Return object struct of object-type _o_b_j.
     oobbjjeecctt--ttyyppee?? ( obj -- f )
          Return #t if _o_b_j is an Object type, otherwise #f.
     oobbjjeecctt--ttyyppeess ( -- ary )
          Return array of all object names known to the system.

     Object set words:
     sseett--oobbjjeecctt-->>aarrrraayy ( xt obj -- )
          Set _x_t as oobbjjeecctt-->>aarrrraayy function for _o_b_j type.
     sseett--oobbjjeecctt-->>ssttrriinngg ( xt obj -- )
          Set _x_t as oobbjjeecctt-->>ssttrriinngg function for _o_b_j type.
     sseett--oobbjjeecctt--aappppllyy ( xt obj arity -- )
          Set _x_t as oobbjjeecctt--aappppllyy function for _o_b_j type.
     sseett--oobbjjeecctt--ccooppyy ( xt obj -- )
          Set _x_t as oobbjjeecctt--ccooppyy function for _o_b_j type.
     sseett--oobbjjeecctt--dduummpp ( xt obj -- )
          Set _x_t as oobbjjeecctt--dduummpp function for _o_b_j type.
     sseett--oobbjjeecctt--eeqquuaall--pp ( xt obj -- )
          Set _x_t as oobbjjeecctt--eeqquuaall?? function for _o_b_j type.
     sseett--oobbjjeecctt--ffrreeee ( xt obj -- )
          Set _x_t as gc free function for _o_b_j type.
     sseett--oobbjjeecctt--iinnssppeecctt ( xt obj -- )
          Set _x_t as oobbjjeecctt--iinnssppeecctt function for _o_b_j type.
     sseett--oobbjjeecctt--lleennggtthh ( xt obj -- )
          Set _x_t as oobbjjeecctt--lleennggtthh function for _o_b_j type.
     sseett--oobbjjeecctt--mmaarrkk ( xt obj -- )
          Set _x_t as gc mark function for _o_b_j type.
     sseett--oobbjjeecctt--vvaalluuee--rreeff ( xt obj -- )
          Set _x_t as oobbjjeecctt--rreeff function for _o_b_j type.
     sseett--oobbjjeecctt--vvaalluuee--sseett ( xt obj -- )
          Set _x_t as oobbjjeecctt--sseett!! function for _o_b_j type.

     General object words
     ..iinnssppeecctt ( obj -- )
          Print inspect string of _o_b_j.
     ..oobbjjeecctt--nnaammee ( obj -- )
          Print object name of _o_b_j to current stdout.
     aappppllyy ( obj args -- result ) alias for _o_b_j_e_c_t_-_a_p_p_l_y
     ccyyccllee--rreeff ( obj -- val )
          Return value at current cycle-index of _o_b_j and increment cycle-
          index.  Cycle through content of _o_b_j from first to last entry and
          start again at the beginning etc.
     ccyyccllee--sseett!! ( obj value -- )
          Store _v_a_l_u_e at current cycle-index of _o_b_j and increment cycle-index.
          Cycle through content of _o_b_j from first to last entry and start
          again at the beginning etc.
     ccyyccllee--ssttaarrtt!! ( obj index -- )
          Set cycle-index of _o_b_j to _i_n_d_e_x.
     ccyyccllee--ssttaarrtt00 ( obj -- )
          Set cycle-index of _o_b_j to zero.
     ccyyccllee--ssttaarrtt@@ ( obj -- index )
          Return current cycle-index of _o_b_j.
     ddeetteecctt ( obj key -- value ) alias for _o_b_j_e_c_t_-_f_i_n_d
     eemmppttyy?? ( obj -- f ) alias for _o_b_j_e_c_t_-_e_m_p_t_y_?
     eeqquuaall?? ( obj1 obj2 -- f ) alias for _o_b_j_e_c_t_-_e_q_u_a_l_?
     ffiirrsstt--rreeff ( obj -- val )
          Return first element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if
          length of _o_b_j is less than 1.
     ffiirrsstt--sseett!! ( obj value -- )
          Store _v_a_l_u_e to first element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e
          exception if length of _o_b_j is less than 1.
     hhaasshh--iidd ( obj -- id )
          Return hash id computed from string representation of _o_b_j.  Objects
          with the same content have the same id.
     iinnddeexx ( obj key -- index ) alias for _o_b_j_e_c_t_-_i_n_d_e_x
     llaasstt--rreeff ( obj -- val )
          Return last element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if
          length of _o_b_j is less than 1.
     llaasstt--sseett!! ( obj value -- )
          Store _v_a_l_u_e to last element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception
          if length of _o_b_j is less than 1.
     lleennggtthh ( obj -- len ) alias for _o_b_j_e_c_t_-_l_e_n_g_t_h
     mmeemmbbeerr?? ( obj key -- f ) alias for _o_b_j_e_c_t_-_m_e_m_b_e_r_?
     oobbjjeecctt-->>aarrrraayy ( obj -- ary )
          Return _o_b_j as array.
     oobbjjeecctt-->>ssttrriinngg ( obj -- str )
          Return string representation of _o_b_j.
     oobbjjeecctt--aappppllyy ( obj args -- result )
          Run apply on _o_b_j with _a_r_g_s as arguments.  _a_r_g_s can be an array of
          arguments or a single argument.  The number of _a_r_g_s 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
     oobbjjeecctt--ccooppyy ( obj1 -- obj2 )
          Return copy of _o_b_j_1.  Copy any element if _o_b_j_1 is an instance.
     oobbjjeecctt--ddeebbuugg--hhooookk ( obj -- hook )
          Return debug-hook member of _o_b_j 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>>
     oobbjjeecctt--dduummpp ( obj -- str )
          Return dump string of _o_b_j which one can eval to get the object back.
     oobbjjeecctt--eemmppttyy?? ( obj -- f )
          Return #t if length of _o_b_j is zero, otherwise #f.
     oobbjjeecctt--eeqquuaall?? ( obj1 obj2 -- f )
          Return #t if _o_b_j_1 and _o_b_j_2 have equal content, otherwise #f.
     oobbjjeecctt--ffiinndd ( obj key -- value )
          Search for _k_e_y in _o_b_j and return corresponding value or #f if not
          found.
     oobbjjeecctt--iidd ( obj -- id )
          Return object id of _o_b_j, a uniq number.
     oobbjjeecctt--iinnddeexx ( obj key -- index )
          Search for _k_e_y in _o_b_j and return index or -1 if not found.
     oobbjjeecctt--iinnssppeecctt ( obj -- str )
          Return inspect string of _o_b_j.
     oobbjjeecctt--lleennggtthh ( obj -- len )
          Return length of _o_b_j.
     oobbjjeecctt--mmeemmbbeerr?? ( obj key -- f )
          Return #t if _k_e_y is present in _o_b_j, otherwise #f.
     oobbjjeecctt--nnaammee ( obj -- name )
          Return object type name of OBJ as a string.
     oobbjjeecctt--rraannggee?? ( obj index -- f )
          Return #t if _i_n_d_e_x is in range of _o_b_j, otherwise #f.  If _i_n_d_e_x is
          negative, return #f.
     oobbjjeecctt--rreeff ( obj index -- val )
          Return value at _i_n_d_e_x from _o_b_j.  If _o_b_j is of a type which can have
          multiple elements, an array for example, return value at _i_n_d_e_x.  If
          _o_b_j is of a type which consists of only one element, a fixnum for
          example, ignore _i_n_d_e_x and return _o_b_j itself.
     oobbjjeecctt--sseett!! ( obj index value -- )
          Set _v_a_l_u_e at _i_n_d_e_x to _o_b_j.  If _o_b_j is of a type which can have
          multiple elements, an array for example, set _v_a_l_u_e at position
          _i_n_d_e_x.  If _o_b_j is of a type which consists of only one element, a
          fixnum for example, do nothing.
     oobbjjeecctt--sseett**!! ( obj index value -- )
          Multiply _v_a_l_u_e to value at _i_n_d_e_x of _o_b_j.  Value may be any number
          (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
     oobbjjeecctt--sseett++!! ( obj index value -- )
          Add _v_a_l_u_e to value at _i_n_d_e_x of _o_b_j.  Value may be any number
          (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
     oobbjjeecctt--sseett--!! ( obj index value -- )
          Subtract _v_a_l_u_e from value at _i_n_d_e_x of _o_b_j.  Value may be any number
          (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
     oobbjjeecctt--sseett//!! ( obj index value -- )
          Divide value at _i_n_d_e_x of _o_b_j by _v_a_l_u_e.  Value may be any number
          (ficlInteger, ficlFloat, ficlRatio or ficlComplex).
     oobbjjeecctt--ssoorrtt ( obj cmp-xt -- ary )
          Convert _o_b_j to an array, sort and return it.  _c_m_p_-_x_t 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 )
     rraannggee?? ( obj index -- f ) alias for _o_b_j_e_c_t_-_r_a_n_g_e_?
     sseeccoonndd--rreeff ( obj -- val )
          Return second element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if
          length of _o_b_j is less than 2.
     sseeccoonndd--sseett!! ( obj value -- )
          Store _v_a_l_u_e to second element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e
          exception if length of _o_b_j is less than 2.
     ssoorrtt ( obj cmp-xt -- ary ) alias for _o_b_j_e_c_t_-_s_o_r_t
     tthhiirrdd--rreeff ( obj -- val )
          Return third element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if
          length of _o_b_j is less than 3.
     tthhiirrdd--sseett!! ( obj value -- )
          Store _v_a_l_u_e to third element of _o_b_j.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e
          exception if length of _o_b_j is less than 3.
     xxmmoobbjj?? ( obj -- f )
          Return #t if _o_b_j is an XmObj (xm.c), otherwise #f.  It is a very
          special Snd XM test.  See snd(1) for more information.

     Predicates:
     bboooolleeaann?? ( obj -- f )
          Return #t if _o_b_j is #t or #f, otherwise #f.
     ffaallssee?? ( obj -- f )
          Return #t if _o_b_j is #f, otherwise #f.
     nniill?? ( obj -- f )
          Return #t if _o_b_j is nil, otherwise #f.
     ttrruuee?? ( obj -- f )
          Return #t if _o_b_j is #t, otherwise #f.
     uunnddeeff?? ( obj -- f )
          Return #t if _o_b_j is undef, otherwise #f.

   PPoorrttss
     mmaakkee--ssoofftt--iinnppuutt--ppoorrtt ( :key args -- prt )
          Return new input soft port IO object with corresponding procs.  Not
          all procs are required.  Recognized keyword options:
                ::cclloossee ( -- )
                     Proc for closing soft port.
                ::fflluusshh ( -- )
                     Proc for flushing port buffer.
                ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_"
                     Name for IO object, default is "soft-port".
                ::rreeaadd--cchhaarr ( -- c )
                     Proc for reading one character.
                ::rreeaadd--lliinnee ( -- 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
     mmaakkee--ssoofftt--oouuttppuutt--ppoorrtt ( :key args -- prt )
          Return new output soft port IO object with corresponding procs.  Not
          all procs are required.  Recognized keyword options:
                ::cclloossee ( -- )
                     Proc for closing soft port.
                ::fflluusshh ( -- )
                     Proc for flushing port buffer.
                ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_"
                     Name for IO object, default is "soft-port".
                ::wwrriittee--cchhaarr ( c -- )
                     Proc for writing one character.
                ::wwrriittee--lliinnee ( 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
     mmaakkee--ssoofftt--ppoorrtt ( :key args -- prt )
          Return new soft port IO object with corresponding procs.  Not all
          procs are required.  Recognized keyword options:
                ::cclloossee ( -- )
                     Proc for closing soft port.
                ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w
                     For read-only use constant rr//oo, for write-only use
                     constant ww//oo and for read-write use constant rr//ww.
                ::fflluusshh ( -- )
                     Proc for flushing port buffer.
                ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_"
                     Name for IO object, default is "soft-port".
                ::rreeaadd--cchhaarr ( -- c )
                     Proc for reading one character.
                ::rreeaadd--lliinnee ( -- line )
                     Proc for reading one line.
                ::wwrriittee--cchhaarr ( c -- )
                     Proc for writing one character.
                ::wwrriittee--lliinnee ( 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
     ppoorrtt-->>ssttrriinngg ( prt -- str )
          Return content of _p_r_t object as string if available, otherwise #f.
     ppoorrtt--cclloossee ( prt -- )
          File and IO ports close their streams, other kind of ports do
          nothing.
     ppoorrtt--cclloosseedd?? ( prt -- f )
          Return #t if _i_o object is closed, otherwise #f.
     ppoorrtt--ddiissppllaayy ( prt obj -- )
          Write the string representation of _o_b_j to _p_r_t object.  If _p_r_t is #f,
          write to current output port (stout).
     ppoorrtt--fflluusshh ( prt -- )
          File and IO ports flush their streams, other kind of ports do
          nothing.
     ppoorrtt--ggeettcc ( prt -- c )
          Return next character from _p_r_t IO object.  If _p_r_t is #f, read from
          current input port (stdin).
     ppoorrtt--ggeettss ( prt -- str )
          Return one line from _p_r_t IO object.  If _p_r_t is #f, read from current
          input port (stdin).
     ppoorrtt--iinnppuutt?? ( obj -- f )
          Return #t if _o_b_j is an input IO object or #f, otherwise #f.
     ppoorrtt--oouuttppuutt?? ( obj -- f )
          Return #t if _o_b_j is an output IO object or #f, otherwise #f.
     ppoorrtt--ppuuttcc ( prt c -- )
          Write character _c to _p_r_t IO object.  If _p_r_t is #f, write to current
          output port (stout).
     ppoorrtt--ppuuttss ( prt str -- )
          Write _s_t_r to _p_r_t IO object.  If _p_r_t is #f, write to current output
          port (stout).
     ppoorrtt--ppuuttss--ffoorrmmaatt ( prt fmt fmt-args -- )
          Write string built from _f_m_t and array _f_m_t_-_a_r_g_s to _p_r_t IO object.  If
          _p_r_t 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
     ppoorrtt--rreeaadd ( prt -- str ) alias for _p_o_r_t_-_g_e_t_s
     ppoorrtt--wwrriittee ( prt str -- ) alias for _p_o_r_t_-_p_u_t_s
     ppoorrtt--wwrriittee--ffoorrmmaatt ( prt fmt fmt-args -- ) alias for _p_o_r_t_-_p_u_t_s_-_f_o_r_m_a_t
     ppoorrtt?? ( obj -- f )
          Return #t if _o_b_j is an IO object or #f, otherwise #f.

     The following words recognize these options:
           ::ffiilleennaammee _s_t_r_i_n_g
                      ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w
                           For read-only use constant rr//oo, for write-only use
                           constant ww//oo and for read-write use constant rr//ww.
           ::ccoommmmaanndd _s_t_r_i_n_g _| _a_r_r_a_y_-_o_f_-_s_t_r_i_n_g_s
                      ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w
                           For read-only use constant rr//oo, for write-only use
                           constant ww//oo and for read-write use constant rr//ww.
           ::ssoocckkeett _s_t_r_i_n_g
                      ::ddoommaaiinn _d_o_m_a_i_n (AF_INET | AF_UNIX)
                      ::ppoorrtt _p_o_r_t (default 1024)
           ::ssoofftt--ppoorrtt _s_t_r_i_n_g
                      ::cclloossee ( -- )
                           Proc for closing soft port.
                      ::ffaamm _r_/_o | _w_/_o (default) | _r_/_w
                           For read-only use constant rr//oo, for write-only use
                           constant ww//oo and for read-write use constant rr//ww.
                      ::fflluusshh ( -- )
                           Proc for flushing port buffer.
                      ::ppoorrtt--nnaammee _"_s_o_f_t_-_p_o_r_t_"
                           Name for IO object, default is "soft-port".
                      ::rreeaadd--cchhaarr ( -- c )
                           Proc for reading one character.
                      ::rreeaadd--lliinnee ( -- line )
                           Proc for reading one line.
                      ::wwrriittee--cchhaarr ( c -- )
                           Proc for writing one character.
                      ::wwrriittee--lliinnee ( line -- )
                           Proc for writing one line.
     wwiitthh--eerrrroorr--ttoo--ppoorrtt ( obj :key args -- )
          Open IO object for output and point IO to _*_s_t_d_e_r_r_*.  If _o_b_j is a
          string, write string to IO object, otherwise execute _o_b_j as proc or
          xt with stack effect ( -- ).  Close IO object.  _*_s_t_d_e_r_r_* 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
                %
     wwiitthh--iinnppuutt--ffrroomm--ppoorrtt ( obj :key args -- str )
          Open IO object for input and point IO to _*_s_t_d_i_n_*.  If _o_b_j is _n_i_l,
          read first line from IO object, otherwise execute _o_b_j as proc or xt
          with stack effect ( -- str ).  Close IO object and return resulting
          string.  _*_s_t_d_i_n_* 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"
     wwiitthh--iinnppuutt--ppoorrtt ( obj :key args -- str )
          Open IO object for input.  If _o_b_j _i_s _n_i_l, read first line from IO
          object, otherwise execute _o_b_j 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"
     wwiitthh--oouuttppuutt--ppoorrtt ( obj :key args -- )
          Open IO object for output.  If _o_b_j is a string, write string to IO
          object, otherwise execute _o_b_j 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
                %
     wwiitthh--oouuttppuutt--ttoo--ppoorrtt ( obj :key args -- )
          Open IO object for output and point IO to _*_s_t_d_o_u_t_*.  If _o_b_j is a
          string, write string to IO object, otherwise execute _o_b_j as proc or
          xt with stack effect ( -- ).  Close IO object.  _*_s_t_d_o_u_t_* 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
                %

   PPrrooccss aanndd XXttss
     *filename*
          Current filename.
     *lineno*
          Current line number.
     ..pprroocc ( prc -- )
          Print proc object _p_r_c to current output.
     <<''sseett>> ( "name" -- set-name|#f )
          Parse _n_a_m_e and search for word _s_e_t_-_n_a_m_e.  Return xt of _s_e_t_-_n_a_m_e 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, ::kkeeyy and ::ooppttiioonnaall.
          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
     ddeeffiinneedd?? ( "name" -- f )
          Return #t if _n_a_m_e is defined in the dictionary, otherwise #f.
                defined?  10 => #f
                defined? nil => #t
                defined?   + => #t
     ddoocc"" ( <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.
     ddooccuummeennttaattiioonn--rreeff ( obj -- str )
          Return documentation string of _o_b_j (Forth word, object or topic) or
          #f.
     ddooccuummeennttaattiioonn--sseett!! ( obj str -- )
          Set documentation of _o_b_j (Forth word, object or topic) to _s_t_r.
     ggeett--ffuunncc--nnaammee ( -- 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
     ggeett--ooppttaarrgg ( req def -- val )
          Return either default value _d_e_f or a value found on stack.  _r_e_q 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 )
     ggeett--ooppttaarrggss ( lst req -- vals )
          The plural form of get-optarg.  _a_r_g_s is an array with default
          values, _r_e_q is number of required arguments.  Return _r_e_q + _a_r_g_s
          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 )
     ggeett--ooppttkkeeyy ( key def -- val )
          Return either default value _d_e_f or a value found on stack determined
          by keyword _k_e_y.  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 )
     ggeett--ooppttkkeeyyss ( ary req -- vals )
          The plural form of get-optkey.  _a_r_y is an array of key-value pairs,
          _r_e_q is number of required arguments.  Return _r_e_q + _a_r_y 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 )
     hheellpp ( "name" -- )
          Print documentation of _n_a_m_e (Forth word or topic) or "no
          documentation available".
                help make-array \ Forth word
                help array      \ topic
     hheellpp--aadddd!! ( obj str -- )
          Append _s_t_r to documentation of _o_b_j.
     hheellpp--rreeff ( obj -- str )
          Return documentation of _o_b_j (Forth word, object or topic) or "no
          documentation available".
     hheellpp--sseett!! ( obj str -- )
          Set documentation of _o_b_j (Forth word or object) to _s_t_r.
                #( "behemoth" "pumpkin" "mugli" ) value hosts
                hosts "local-net hostnames" help-set!
                hosts help-ref => "local-net hostnames"
     llaammbbddaa:: ( -- 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
     llaatteessttxxtt ( -- xt )
          Return latest defined xt.
     llooccaall--vvaarriiaabblleess ( -- 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 }
     mmaakkee--pprroocc ( xt arity -- prc )
          Return new proc object.  _a_r_i_t_y 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
     pprroocc-->>xxtt ( prc -- xt )
          Return the actual word (the execution token xt) of _p_r_c.
     pprroocc--aappppllyy ( prc args -- res )
          Execute proc object _p_r_c with arguments _a_r_g_s and return result or #f.
          _a_r_g_s can be an array of arguments or a single argument.  If
          execution fails, raise an _e_v_a_l_-_e_r_r_o_r exception, if length of _a_r_g_s is
          less than required arity of _p_r_c, raise a _b_a_d_-_a_r_i_t_y exception.
                <'> +  2  make-proc value plus
                plus #( 5 6 ) proc-apply => 11
     pprroocc--aarriittyy ( prc -- arity )
          Return arity array #( req opt rest ) of proc object _p_r_c, or #f if
          not a proc object.
     pprroocc--ccrreeaattee ( arity -- prc )
          Create nameless proc object with _a_r_i_t_y.  Like ccrreeaattee it goes with
          ddooeess>>.
                : 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
     pprroocc--nnaammee ( prc -- name )
          Return name of proc object _p_r_c if found, otherwise an empty string.
     pprroocc--ssoouurrccee--rreeff ( prc -- str )
          Return source string property of _p_r_c, or #f if not available.
     pprroocc--ssoouurrccee--sseett!! ( prc str -- )
          Set source string property of _p_r_c to _s_t_r.
     pprroocc?? ( obj -- f )
          Return #t if _o_b_j is a proc object.
     rruunn--pprroocc ( prc args -- res ) alias for _p_r_o_c_-_a_p_p_l_y
     rruunnnniinngg--wwoorrdd ( -- 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
     sseeee22 ( "name" -- )
          Show word definition of _n_a_m_e.
     sseett!! ( "name" -- )
          Parse _n_a_m_e and execute word _s_e_t_-_n_a_m_e if found, otherwise raise an
          _u_n_d_e_f_i_n_e_d_-_w_o_r_d exception.  The following two lines do the same:
                128 set! object-print-length
                128 set-object-print-length
     sseett--eexxeeccuuttee ( xt -- ?? )
          Execute _s_e_t_-_x_t if found, otherwise raise an _u_n_d_e_f_i_n_e_d_-_w_o_r_d
          exception.  The following two lines do the same:
                128 <'> object-print-length set-execute
                128 set-object-print-length
     sseett--xxtt ( xt1 -- xt2 )
          Return _s_e_t_-_x_t if found, otherwise #f.
                <'> object-print-length set-xt => set-object-print-length
     ssoouurrccee--ffiillee ( xt -- file )
          Return source file where _x_t was created or #f if _x_t is a primitive
          or not defined.
     ssoouurrccee--lliinnee ( xt -- line )
          Return source line number where _x_t was created or #f if _x_t is a
          primitive or not defined.
     ssoouurrccee--rreeff ( obj -- str )
          Return source string of _o_b_j, a proc or xt, or #f if not found.
     ssoouurrccee--sseett!! ( obj str -- )
          Set source string of _o_b_j, a proc or xt, to _s_t_r.
     tthhuunnkk?? ( obj -- f )
          Return #t if _o_b_j is a proc object with no required, optional and
          rest arguments.  If its arity is not #( 0 0 #f ), return #f.
     ttrraaccee--vvaarr ( var proc-or-xt -- )
          Add _p_r_o_c_-_o_r_-_x_t to global _v_a_r hook which is utilized on every call of
          ttoo.  The stack effect of _p_r_o_c_-_o_r_-_x_t 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
     uunnttrraaccee--vvaarr ( var -- )
          Remove previously installed hook from _v_a_r.
     wwoorrdd?? ( obj -- f )
          Return #t if _o_b_j is a proc object or an xt (execution token, address
          of a Ficl word), otherwise #f.
     wwoorrdd--ccrreeaattee ( name -- )
          Create word _n_a_m_e 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 }
     xxtt-->>nnaammee ( xt -- str )
          Return name of _x_t if found, otherwise an empty string.
     xxtt-->>oorriiggiinn ( xt -- str )
          Return name, source file and source line number where _x_t was defined
          (name:file:line).  If _x_t is a C-primitive, return (name:primitive),
          if not defined, return an empty string.
     xxtt?? ( obj -- f )
          Return #t if _o_b_j is an xt (execution token, address of a Ficl word),
          otherwise #f.

   RReeggeexxpp oobbjjeecctt ttyyppee
     *re-syntax-options*
          This regexp variable can be set with the following constants.  If
          more than one constant is used, combine them with oorr, see regex(3).
               REG_EXTENDED  Compile modern regex, default.
               REG_ICASE     Compile for matching ignore case.
               REG_NEWLINE   Compile for newline-sensitive matching.
               REG_NOSUB     Compile without creating subexpression.
          For example, set matching to ignore case before creating a new
          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)+/
     mmaakkee--rreeggeexxpp ( str -- reg )
          Return new regexp object from _s_t_r which may contain regular
          expression.
                "(B|b)+" make-regexp value reg
     rree--mmaattcchh ( reg str start -- n )
          Return count of matched characters or -1 for no match.
                /a*/ "aaaaab" 2 re-match => 3
     rree--sseeaarrcchh ( reg str start range -- n )
          Return index of match or -1 for no match.
                /a*/ "aaaaab" 2 4 re-search => 2
     rree// ( space<ccc>/ -- reg )
          Parse regexp _c_c_c delimited by `/' at compile time and at interpret
          time return parsed regexp.  See _/ for an alternative.
                re/ (B|b)+/ => /(B|b)+/
     rree== ( reg str -- len|#f ) alias for _r_e_g_e_x_p_-_m_a_t_c_h
     rreeggeexxpp--mmaattcchh ( reg str -- len|#f )
          Return count of matched characters or #f.  Possible matched group
          results or #f can be found in regexp object _r_e_g, 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
     rreeggeexxpp== ( reg str -- len|#f ) alias for _r_e_g_e_x_p_-_m_a_t_c_h
     rreeggeexxpp--rreeppllaaccee ( reg str1 replace -- str2 )
          Replace 1st occurrence of _r_e_g in _s_t_r_1 with _r_e_p_l_a_c_e if found.
          References \1 to \9 in _r_e_p_l_a_c_e will be replaced by corresponding
          subexpressions.  If no corresponding subexpression exist, raise a
          _r_e_g_e_x_p_-_e_r_r_o_r exception.
                /(foo)/ "foo-bar" "***\\1***" regexp-replace
                  => ***foo***-bar
          Note the double quotes on back reference characters .
     rreeggeexxpp--sseeaarrcchh ( reg str :key start 0 range -1 -- pos|f )
          Return index of match or #f.  If index is zero, return #t to fool
          Forth' iiff.  If keyword _r_a_n_g_e is -1 (default), the entire string will
          be searched.  Possible matched group results or #f can be found in
          regexp object _r_e_g, 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
     rreeggeexxpp?? ( obj -- f )
          Return #t if _o_b_j is a regexp object, otherwise #f.
                /^s/ regexp? => #t

   SSttrriinngg oobbjjeecctt ttyyppee
     "" ( <ccc>" -- str )
          Prefix character `"' start a string object delimited by a second
          `"'.
                "pumpkin" => "pumpkin"
     """" ( -- str )
          Return empty string object ("").
     $$"" ( space<ccc>" -- str )
          Parse string _c_c_c delimited by `"' at compile time and at interpret
          time return parsed string.  See _" for an alternative.
                $" pumpkin" => "pumpkin"
     $$++ ( str1 str2 -- str3 ) alias for _s_t_r_i_n_g_-_a_p_p_e_n_d
     $$>>ssttrriinngg ( addr len -- str )
          Return Forth string _a_d_d_r _l_e_n as string object.  Standard words like
          ttyyppee and eevvaalluuaattee require this kind of string.
     $$ccrr ( -- str )
          Return carriage return string object ("\n").
     $$ssppaaccee ( -- str )
          Return string of one space (" ").
     $$ssppaacceess ( len -- str )
          Return string of _l_e_n spaces.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n
          < 0.
     ..$$ ( obj -- ) alias for _._s_t_r_i_n_g
     ..ddeebbuugg ( obj -- )
          Print string representation of _o_b_j to stderr wrapped in ##<<DDEEBBUUGG((FF))::
          ......>>.
     ..eerrrroorr ( obj -- )
          Print string representation of _o_b_j to current error output.
     ..gg ( obj -- ) alias for _._s_t_r_i_n_g
     ..ssttddeerrrr ( obj -- )
          Print string representation of _o_b_j to stderr.
     ..ssttddoouutt ( obj -- )
          Print string representation of _o_b_j to stdout.
     ..ssttrriinngg ( obj -- )
          Print string representation of _o_b_j to current output.
     <<<< ( str val -- str'  ) alias for _s_t_r_i_n_g_-_p_u_s_h
     >>ssttrriinngg ( chars len -- str ) alias for _s_t_r_i_n_g_-_c_o_n_c_a_t
     cchhaarr?? ( obj -- )
          Return #t if _o_b_j is a character, otherwise #f.
     ddiiee ( str -- )
          Print _s_t_r wrappen in ##<<ddiiee:: ......>> to current stderr and exit
          interpreter with return code 1.
     eerrrroorr ( str -- )
          Print _s_t_r wrappen in ##<<eerrrroorr:: ......>> to current stderr and throw
          exception.
     ffoorrmmaatt ( fmt args -- ) alias for _s_t_r_i_n_g_-_f_o_r_m_a_t
     fftthh--ddiiee ( fmt :optional args -- )
          Print _f_m_t string with corresponding _a_r_g_s array wrapped in ##<<ddiiee::
          ......>> to current stderr and exit interpreter with return code 1; _a_r_g_s
          is optional.   See _s_t_r_i_n_g_-_f_o_r_m_a_t for _f_m_t description.
     fftthh--eerrrroorr ( fmt :optional args -- )
          Print _f_m_t string with corresponding _a_r_g_s array wrapped in ##<<eerrrroorr::
          ......>> to current stderr and throw exception; _a_r_g_s is optional.   See
          _s_t_r_i_n_g_-_f_o_r_m_a_t for _f_m_t description.
     fftthh--ffoorrmmaatt ( fmt :optional args -- str  )
          Return string object from printf(3) _f_m_t string and _a_r_g_s array
          containing corresponding arguments; _a_r_g_s is optional.  See _s_t_r_i_n_g_-
          _f_o_r_m_a_t for _f_m_t description.
     fftthh--pprriinntt ( fmt :optional args -- )
          Print _f_m_t string with corresponding _a_r_g_s array to current stdout;
          _a_r_g_s is optional.   See _s_t_r_i_n_g_-_f_o_r_m_a_t for _f_m_t description.
     fftthh--wwaarrnniinngg ( fmt :optional args -- )
          Print _f_m_t string with corresponding _a_r_g_s array wrapped in ##<<wwaarrnniinngg::
          ......>> to current stderr; _a_r_g_s is optional.   See _s_t_r_i_n_g_-_f_o_r_m_a_t for
          _f_m_t description.
     mmaakkee--ssttrriinngg ( len :key initial-element ' ' -- str )
          Return a new string of length _l_e_n filled with _i_n_i_t_i_a_l_-_e_l_e_m_e_n_t
          characters, default space.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if _l_e_n <
          0.
                3 :initial-element <char> x make-string => "xxx"
     ssttrriinngg-->>aarrrraayy ( str -- ary )
          Convert _s_t_r to an array of characters.
                "foo" string->array => #( 102 111 111 )
     ssttrriinngg--aappppeenndd ( str1 str2 -- str3 )
          Return new string _s_t_r_1 + _s_t_r_2.
     ssttrriinngg--ccaappiittaalliizzee ( str1 -- str2 )
          Return new string with first character capitalized and remaining
          characters in lowercase.
     ssttrriinngg--ccaappiittaalliizzee!! ( str -- str' )
          Return _s_t_r changed to first character capitalized and remaining
          characters to lowercase.
     ssttrriinngg--cchhoommpp ( str1 -- str2 )
          Return new string object with possible trailing \n removed.
     ssttrriinngg--cchhoommpp!! ( str -- str' )
          Return changed _s_t_r with possible trailing \n removed.
     ssttrriinngg--ccoonnccaatt ( objs len -- str )
          Return new string with _l_e_n objects from stack converted to their
          string representation.
                0 1 2 " foo " "b" "a" "r"  7 >string
                  => "012 foo bar"
     ssttrriinngg--ccooppyy ( str1 -- str2 )
          Return copy of _s_t_r_1.
     ssttrriinngg--ddeelleettee!! ( str idx -- val )
          Delete and return character at position _i_d_x from _s_t_r; negative index
          counts from backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is
          not in range of string.
     ssttrriinngg--ddoowwnnccaassee ( str1 -- str2 )
          Return new string with all characters lowercase.
     ssttrriinngg--ddoowwnnccaassee!! ( str -- str' )
          Return _s_t_r changed to all characters lowercase.
     ssttrriinngg--eevvaall ( str -- ?? )
          Evaluate _s_t_r; values already on stack can be accessed, resulting
          values remain on stack.
                7 "3 4 + +" string-eval => 14
     ssttrriinngg--eevvaall--wwiitthh--ssttaattuuss ( str -- ?? status )
          Evaluate _s_t_r 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.
     ssttrriinngg--ffiillll ( str char -- str' )
          Fill _s_t_r with _c_h_a_r and return changed string object.
     ssttrriinngg--ffiinndd ( str1 key -- str2|#f )
          Return match if string or regexp _k_e_y exist in _s_t_r, otherwise #f.
                "hello world" "l" string-find => "llo world"
                "hello world" /ell/ string-find => "lo world"
     ssttrriinngg--ffoorrmmaatt ( fmt args -- )
          _f_m_t is a printf(3) format string and _a_r_g_s 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 bb, BB, oo and OO conversions prepend a zero before
                          output, for xx and XX conversions prepend a `0x'
                          respective `0X' before output.  For aa, AA, ee, EE, ff,
                          FF, gg and GG conversions the result will always have a
                          decimal point.
                `--'       Flush output left.
                `00' (zero)
                          Padding with `0' (zero) rather than blank.
          The following conversion specifiers are known:
                %%         A `%' is written.
                aaAAeeEEffFFggGG  Floating point output like _p_r_i_n_t_f _3.
                cc         Single character output.
                bbddoouuxxXX    Integer output in binary, decimal, octal, unsigned
                          and hexadecimal form.
                pp         Inspect string output of any Forth object with
                          oobbjjeecctt--iinnssppeecctt.
                ss         String representation of any Forth object with
                          oobbjjeecctt-->>ssttrriinngg.
                SS         Dump string output of any Forth object with
                          oobbjjeecctt--dduummpp.
     ssttrriinngg--iinnddeexx ( str key -- idx )
          Return index of string _k_e_y in _s_t_r or -1 if not found.
                "hello world" "orl" string-index => 7
     ssttrriinngg--iinnsseerrtt!! ( str idx val -- str' )
          Insert string representation of _v_a_l to _s_t_r at position _i_d_x; negative
          index counts from backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if
          index is not in range of string.
     ssttrriinngg--lleennggtthh ( str -- len )
          If _s_t_r is a string object, return its length, otherwise -1.
     ssttrriinngg--mmeemmbbeerr?? ( str key -- f )
          Return #t if string _k_e_y exist in _s_t_r, otherwise #f.
                "hello world" "ell" string-member? => #t
     ssttrriinngg--ppoopp ( str -- char )
          Remove and return last character.  If _s_t_r is empty, return #f.
     ssttrriinngg--ppuusshh ( str val -- str' )
          Append string representation of _v_a_l to _s_t_r and return changed string
          object.
     ssttrriinngg--rreeff ( str idx -- val )
          Return character at position _i_d_x; negative index counts from
          backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in range
          of string.
     ssttrriinngg--rreeppllaaccee ( str1 from to -- str2 )
          Return new string object with string _f_r_o_m replaced by string _t_o.  If
          _t_o is the empty string, delete the _f_r_o_m part from _s_t_r_1.
     ssttrriinngg--rreeppllaaccee!! ( str from to -- str' )
          Return changed _s_t_r with string _f_r_o_m replaced by string _t_o.  If _t_o is
          the empty string, delete the _f_r_o_m part from _s_t_r.
     ssttrriinngg--rreevveerrssee ( str1-- str2 )
          Return _s_t_r_1 reversed as new string object.
     ssttrriinngg--rreevveerrssee!! ( str -- str' )
          Return the same string object _s_t_r reversed.
     ssttrriinngg--sseett!! ( str idx val -- )
          Store character _c_h_a_r at index _i_d_x; negative index counts from
          backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e exception if index is not in range
          of string.
     ssttrriinngg--sshhiifftt ( str -- char )
          Remove and return first character.  If _s_t_r is empty, return #f.
     ssttrriinngg--sspplliitt ( str sep -- ary )
          Split _s_t_r using _s_e_p as delimiter and return result as array of
          strings.  If _s_e_p 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" )
     ssttrriinngg--ssuubbssttrriinngg ( str1 start end -- str2 )
          Return new string from position _s_t_a_r_t to, but excluding, position
          _e_n_d.  If _e_n_d is not an integer, _e_n_d will be set to length of _s_t_r_1;
          negative index counts from backward.  Raise an _o_u_t_-_o_f_-_r_a_n_g_e
          exception if _s_t_a_r_t 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"
     ssttrriinngg--uunnsshhiifftt ( str val -- str' )
          Prepend string representation of _v_a_l to _s_t_r and return changed
          string object.
     ssttrriinngg--uuppccaassee ( str1 -- str2 )
          Return new string with all characters uppercase.
     ssttrriinngg--uuppccaassee!! ( str -- str' )
          Return _s_t_r changed to all characters uppercase.
     ssttrriinngg--ccmmpp ( str1 str2 -- n )
          Return -1 if _s_t_r_1 is less than _s_t_r_2, 1 if _s_t_r_1 is greater than _s_t_r_2,
          and 0 if _s_t_r_1 is equal to _s_t_r_2.  It may be used with sort functions.
     ssttrriinngg<< ( str1 str2 -- f )
          Return #t if _s_t_r_1 is lexicographically lesser than _s_t_r_2, otherwise
          #f.
     ssttrriinngg<<>> ( str1 str2 -- f )
          Return #t if strings are not equal, otherwise #f.
     ssttrriinngg== ( str1 str2 -- f )
          Return #t if strings are equal, otherwise #f.
     ssttrriinngg>> ( str1 str2 -- f )
          Return #t if _s_t_r_1 is lexicographically greater than _s_t_r_2, otherwise
          #f.
     ssttrriinngg>>$$ ( str -- addr len )
          Return string object _s_t_r converted to a Forth string with _a_d_d_r _l_e_n.
          Standard words like ttyyppee and eevvaalluuaattee require this kind of string.
     ssttrriinngg?? ( obj -- f )
          Return #t if _o_b_j is a string object, otherwise #f.
     wwaarrnn ( str -- ) alias for _w_a_r_n_i_n_g
     wwaarrnniinngg ( str -- )
          Print _s_t_r wrappen in ##<<wwaarrnniinngg:: ......>> to current stderr.

   SSyymmbboollss
     ..ssyymmbbooll ( sym -- )
          Print symbol _s_y_m to current output.
     ccrreeaattee--ssyymmbbooll ( "name" -- )
          Create symbol _n_a_m_e prepended by `''.  Symbols are actually values
          (variables) named _'_n_a_m_e.
                create-symbol new-symbol => create symbol 'new-symbol
     mmaakkee--ssyymmbbooll ( name -- sym )
          Return symbol _n_a_m_e prepended by `''.  Symbols are actually values
          (variables) named _'_n_a_m_e.
                "new-symbol" make-symbol => 'new-symbol
     ssyymmbbooll--nnaammee ( sym -- str )
          Return name of symbol _s_y_m.
                'new-symbol symbol-name => "new-symbol"
     ssyymmbbooll== ( obj1 obj2 -- f )
          Return #t if _o_b_j_1 and _o_b_j_2 are symbols with identical name,
          otherwise #f.
     ssyymmbbooll?? ( obj -- f )
          Return #t if _o_b_j is a symbol, otherwise #f.

   KKeeyywwoorrddss
     ..kkeeyywwoorrdd ( kw -- )
          Print keyword _k_w to current output.
     ccrreeaattee--kkeeyywwoorrdd ( "name" -- )
          Create keyword _n_a_m_e prepended by `:'.  Keywords are actually values
          (variables) named _:_n_a_m_e.
                create-keyword new-keyword => create keyword :new-keyword
     kkeeyywwoorrdd--nnaammee ( kw -- name )
          Return name of keyword _k_w.
                :new-keyword keyword-name => "new-keyword"
     kkeeyywwoorrdd== ( obj1 obj2 -- f )
          Return #t if _o_b_j_1 and _o_b_j_2 are keywords with identical name,
          otherwise #f.
     kkeeyywwoorrdd?? ( obj -- f )
          Return #t if _o_b_j is a keyword, otherwise #f.
     mmaakkee--kkeeyywwoorrdd ( name -- kw )
          Return keyword _n_a_m_e prepended by `:'.  Keywords are actually values
          (variables) named _:_n_a_m_e.
                "new-keyword" make-keyword => :new-keyword

   EExxcceeppttiioonnss
     *last-exception*
          Hold last raised exception.
     ..eexxcceeppttiioonn ( ex -- )
          Print exception _e_x to current output.
     ccrreeaattee--eexxcceeppttiioonn ( msg "name" -- )
          Create exception named _n_a_m_e with message _m_s_g, _m_s_g can be #f.  The
          exception has a symbol name, that means it has prefix `'' before
          _n_a_m_e.
                "New test exception" create-exception new-exception
                  => create 'new-exception
     eexxcceeppttiioonn--llaasstt--mmeessssaaggee--rreeff ( ex -- msg )
          Return last message of exception _e_x.  Last message was set after an
          exception was thrown with e.g.  fftthh--tthhrrooww or fftthh--rraaiissee.
     eexxcceeppttiioonn--llaasstt--mmeessssaaggee--sseett!! ( ex msg -- )
          Set _m_s_g, a string or #f, as last message of exception _e_x.  This will
          be set automatically after an exception was thrown with e.g.
          fftthh--tthhrrooww or fftthh--rraaiissee.
     eexxcceeppttiioonn--mmeessssaaggee--rreeff ( ex -- msg )
          Return message of exception _e_x.
     eexxcceeppttiioonn--mmeessssaaggee--sseett!! ( ex msg -- )
          Set _m_s_g, a string or #f to exception _e_x.
     eexxcceeppttiioonn--nnaammee ( ex -- name )
          Return name of exception _e_x.
                'new-exception exception-name => "new-exception"
     eexxcceeppttiioonn== ( obj1 obj2 -- f )
          Return #t if _o_b_j_1 and _o_b_j_2 are exeptions with identical name,
          otherwise #f.
     eexxcceeppttiioonn?? ( obj -- f )
          Return #t if _o_b_j is a exception, otherwise #f.
     mmaakkee--eexxcceeppttiioonn ( name msg -- ex )
          Return exception named _n_a_m_e with message _m_s_g, _m_s_g can be #f.  The
          exception has a symbol name, that means it has prefix `'' before
          _n_a_m_e.
                "New test exception" create-exception new-exception
                  => create 'new-exception
     ssyymmbbooll-->>eexxcceeppttiioonn ( sym -- ex )
          Return symbol _s_y_m as exception.

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

FFIILLEESS
     _/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_f_t_h_r_c
          Global initialization file for system wide configuration.
     _~_/_._f_t_h_r_c
          Local initialization file for user configuration.  The name can be
          changed with FTH_INIT_FILE.
     _~_/_._f_t_h_-_h_i_s_t_o_r_y
          Local history file.  The name can be changed with FTH_HISTORY.

EEXXIITT SSTTAATTUUSS
     The fftthh utility exits 0 on success, and >0 if an error occurs.

EEXXAAMMPPLLEESS
     The following are examples of typical usage of the fftthh command:

     Print 32 Fahrenheit as Celsius (0.0)

           % fth -e "32 f2c . cr"

     Load C extension library _l_i_b_x_m with initialization function IInniitt__lliibbxxmm()
     and Forth source file _m_o_t_i_f_-_s_c_r_i_p_t_._f_s with at least one word mmaaiinn defined
     in it, execute word mmaaiinn and exit if finished

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

     Prepend path _~_/_s_h_a_r_e_/_f_o_r_t_h to *load-path*, load Forth source file
     _s_o_u_n_d_-_s_c_r_i_p_t_._f_s and start the repl showing a prompt.  Initialization
     files _/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_f_t_h_r_c and _~_/_._f_t_h_r_c are loaded if they exist

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

     Run Forth script _c_h_e_c_k_._f_t_h and provide options --aabb _1_0 to the script which
     should handle at least these two; exit if finished

           % fth -s check.fth -ab 10

     Rename _c_o_n_f_i_g_._h to _c_o_n_f_i_g_._h_._o_r_i_g 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 _c_o_n_f_i_g_._h.  The first --ee set the global Forth
     variable reg to a regexp object, the second --ee uses this variable for
     testing.  The _p_a_t_t_e_r_n of the first --ee is evaluated in interpret state
     before reading file while the _p_a_t_t_e_r_n of the second --ee is evaluated in
     compile state in a nameless llaammbbddaa:: <<{{}}>> ppaatttteerrnn ;; 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 --vv to turn on verbose mode.  _N_o_t_e_: Option --ss must be the last;
     fftthh doesn't process options after --ss, they are transfered to the script
     and can be processed there with Forth word ggeettoopptt, 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]

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

     bbaadd--aarriittyy  Arity doesn't match for a given proc object.

     bbaadd--ssyynnttaaxx  Paren mismatch for array, list or hash objects.

     bbiiggnnuumm--eerrrroorr  Bignum error.

     ccaattcchh--eerrrroorr  Catch-throw mismatch.

     eevvaall--eerrrroorr  Evaluation error.

     ffiiccll--eerrrroorr  Ficl evaluation error.

     ffoorrtthh--eerrrroorr  Forth error.

     llooaadd--eerrrroorr  Error while loading a Forth file.

     mmaatthh--eerrrroorr  Math error occured.

     nnuullll--ssttrriinngg  Empty string occured.

     nnoo--mmeemmoorryy--eerrrroorr  Memory exhausted.

     ooppttkkeeyy--eerrrroorr  Error while evaluating option key functions.

     oouutt--ooff--rraannggee  Argument is out of range.

     rreeggeexxpp--eerrrroorr  Regexp error occured.

     ssiiggnnaall--ccaauugghhtt  Signal received.

     ssoocckkeett--eerrrroorr  Error while processing sockets.

     ssoo--ffiillee--eerrrroorr  Dynamic library load error.

     ssyysstteemm--eerrrroorr  General system function error occured.

     wwrroonngg--nnuummbbeerr--ooff--aarrggss  Wrong number of arguments provided.

     wwrroonngg--ttyyppee--aarrgg  Wrong argument type provided.

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

HHIISSTTOORRYY
     This manual page describes version 1.4.1.  fftthh is based on _F_i_c_l,
     _F_o_r_t_h_-_i_n_s_p_i_r_e_d _c_o_m_m_a_n_d _l_a_n_g_u_a_g_e, version 4.0.31 written by John Sadler.

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

BBUUGGSS
     Please report bugs to the author.

NetBSD 9.99.18                    2019/11/25                    NetBSD 9.99.18