Man Linux: Main Page and Category List

NAME

       toke - OpenBIOS tokenizer

SYNOPSIS

       toke [options] forth-file

DESCRIPTION

       toke is an open-source FCode Tokenizer from the OpenBIOS project.

OPTIONS

       -h, -? Print a brief help message and then exit.

       -i, --ignore-errors
              Generate a Binary Output even if errors were reported.

       -l, --load-list
              Collect  the names of floaded files into an FLoad-List file. The
              names collected are in the same form as they were  presented  in
              the fload statements.
              The  name of the FLoad-List File is derived from the name of the
              binary output file, by replacing its extension with .fl , or, if
              the  binary  output file name had no extension, merely appending
              the extension .fl.
              The binary output file name used for this purpose is either  the
              one  specified  on  the  command  line,  or  the  one created by
              default.

       -o, --output-name OutputFileName,
              Direct the binary output (FCode result of Tokenization)  to  the
              named  file instead of to the default-named file. This option is
              not valid when multiple input files are named.

       -P, --dependencies
              Collect the fully-resolved  pathnames  of  floaded  and  ENCODEd
              files  into  a dependency-list file.  The names collected are in
              the form that is presented to the host operating  system:  shell
              environment  Variables  and  related  expressions  will be fully
              expanded, and the directory within the include-list in which the
              file was found will be attached.
              The name of the dependency-list file will be the same as that of
              the FLoad-list file,  except  that  its  extension  will  be  .P
              instead of .fl.

       -v, --verbose
              Print   additional   messages   (including   advisories)  during
              tokenization.

       -I, --Include directory
              This tokenizer supports the notion of an include-list. The  user
              creates  the include-list by specifying a number of -I directory
              pairs on the command-line. All file-reads, whether for an  fload
              command  or  an encode-file directive, will involve a search for
              the named file through the directories of the  include-list,  in
              the order they were supplied on the command-line.
              If  no  include-list  is created, file-reads are relative to the
              current working Directory. If an include-list is created,  file-
              reads  are  restricted  to  the  directories within it.  For the
              current working directory to be included in the file-search,  it
              must  be  specified explicitly.  -I.  will accomplish that quite
              effectively.

       -T, --Trace symbol
              This tokenizer supports the notion of  a  trace-list.  The  User
              creates the trace-list by specifying a number of -T symbol pairs
              on the command-line.
              When a name is defined, whether as an FCode, an alias,  a  Macro
              or   anything  else,  either  in  normal  tokenization  mode  or
              "Tokenizer Escape"-mode, if it matches a symbol  that  has  been
              added  to  the  trace  list, a trace note message will be issued
              indicating that a definition of  that  name  has  been  created.
              Subsequent   trace   note  Messages  will  be  issued  when  the
              definition of that name is invoked.
              This trace-symbols feature can be helpful during maintenance  of
              legacy  code, for instance, when multiple symbols carry the same
              name.

       -d, --define Symbol[=Value]
              Define a command-line symbol and optionally, assign a  value  to
              it.  If  you wish the value to contain spaces or quotes, you can
              accomplish  that  using  the  shell  escape  conventions.   This
              sequence  may  be  repeated.  Once  a  Symbol  is defined on the
              command-line, it stays in effect for the duration of the  entire
              batch  of tokenizations (i.e., if there are multiple input files
              named on the command line). Command-line Symbols can  be  tested
              for  purposes  of  conditional  tokenization,  or their assigned
              values can be evaluated.

       -f, --flag [no]<FlagName>
              The tokenizer recognizes a specific set of special-feature flag-
              names;  each  is associated with a specific non-standard variant
              behavior. Pass the flag-name as an argument to the -f switch  to
              enable  the  behavior; to disable it, precede the flag-name with
              the optional string no.
              The settings of the special-feature flags can also be changed or
              displayed from within the source input file.
              The  special-feature  flags are all initially set to be enabled,
              except where noted.
              The flag-names and  their  associated  special-features  are  as
              follows:

              Local-Values
                     Support   IBM-style   Local   Values  ("LV"s).  Initially
                     disabled.

              LV-Legacy-Separator
                     Allow Semicolon for Local Values Separator ("Legacy").

              LV-Legacy-Message
                     Display a Warning Message when Semicolon is used  as  the
                     Local Values Separator.

              ABORT-Quote
                     Allow ABORT" macro.

              Sun-ABORT-Quote
                     ABORT" with implicit IF ... THEN

              Abort-Quote-Throw
                     Use -2 THROW, rather than ABORT, in an Abort" phrase

              String-remark-escape
                     Allow "\ (Quote-Backslash) to interrupt string parsing.

              Hex-remark-escape
                     Allow  \  (Backslash)  to  interrupt hex-sequence parsing
                     within a string.

              C-Style-string-escape
                     Allow the C-style String-Escape pairs \n \t and  \xx\  to
                     be treated as special characters in string parsing.

              Always-Headers
                     Override occurrences of the standard directive headerless
                     in the source with -- effectively -- headers to make  all
                     definitions  have  a header. Occurrences of the directive
                     external will continue to behave in the standard  manner.
                     Initially disabled.

              Always-External
                     All definitions will be made as though under the external
                     directive;  occurrences  of  either  Standard   directive
                     headerless  or  headers in the source will be overridden.
                     This  special-feature  flag  will   also   override   the
                     Always-Headers  special-feature  flag  in  the event that
                     both have been specified. Initially disabled.

              Warn-if-Duplicate
                     Display a WARNING message whenever a definition  is  made
                     whose  name  duplicates  that  of an existing definition.
                     Disabling this flag will suspend the duplicate-names test
                     globally,   until   it  is  re-enabled.  A  Directive  is
                     supported that will suspend the test for the duration  of
                     only   a  single  definition,  without  affecting  global
                     behavior.

              Obsolete-FCode-Warning
                     Display a WARNING message whenever an FCode  function  is
                     invoked that the Standard identifies as obsolete.

              Trace-Conditionals
                     Issue  advisory  messages  about the state of conditional
                     tokenization.  (Remember  that  advisory   messages   are
                     displayed   only  if  the  verbose  option  -v  is  set.)
                     Initially disabled.

              Upper-Case-Token-Names
                     Lower-Case-Token-Names  When  outputting  the  names   of
                     headered  functions  (token-names)  to  the binary output
                     file, override the  character-case  in  which  the  names
                     appeared  in  the  source,  and convert them to Upper- or
                     Lower- -Case, respectively. (These flags  do  not  affect
                     text  string  sequences,  whose  character-case is always
                     preserved.)  Initially disabled.

              Big-End-PCI-Rev-Level
                     Save the Revision Level of the Vendor’s ROM field of  the
                     PCI  Header in big-endian byte-order, rather than little-
                     endian as per the general PCI Standard convention.  (This
                     flag does not affect any other field
                      of the PCI Header). Initially disabled.

              Ret-Stk-Interp
                     Allow   return-stack  operations  during  interpretation.
                     While the standard specifies that usage of the  operators
                     >r,  r@,  and  r>  while  interpreting is allowed, actual
                     practice in the industry is inconsistent.  Developers who
                     wish  to  take  a more cautious approach to this question
                     can disable this flag so that  any  attempt  to  use  the
                     operators  >r,  r@, and r> in the interpreting state will
                     generate an ERROR Message.

       Also, the pseudo-flag-name help will cause a list of the flag-names and
       their associated special-features to be printed.

SEE ALSO

       detok(1).

AUTHORS

       Stefan Reinauer <stepan@openbios.org>
       David L. Paktor <dlpaktor@us.ibm.com>

       This manual page was written by Aurelien Jarno <aurel32@debian.org> for
       the Debian GNU/Linux system (but may be used by others).

                                 May 15, 2007