Provided by: enscript_1.6.5.90-1_amd64 bug

NAME

       states - awk alike text processing tool

SYNOPSIS

       states  [-hvV] [-D var=val] [-f file] [-o outputfile] [-p path] [-s startstate] [-W level]
       [filename ...]

DESCRIPTION

       States is an awk-alike text processing tool with some state  machine  extensions.   It  is
       designed for program source code highlighting and to similar tasks where state information
       helps input processing.

       At a single point of time, States is in one  state,  each  quite  similar  to  awk's  work
       environment,  they  have  regular expressions which are matched from the input and actions
       which are executed when a match is found.  From the  action  blocks,  states  can  perform
       state  transitions;  it  can move to another state from which the processing is continued.
       State transitions are recorded so states can return to the calling state once the  current
       state has finished.

       The  biggest  difference between states and awk, besides state machine extensions, is that
       states is not line-oriented.  It matches regular expression tokens from the input and once
       a  match  is  processed,  it  continues processing from the current position, not from the
       beginning of the next input line.

OPTIONS

       -D var=val, --define=var=val
               Define variable var to have string value val.  Command line definitions  overwrite
               variable definitions found from the config file.

       -f file, --file=file
               Read  state  definitions from file file.  As a default, states tries to read state
               definitions from file states.st in the current working directory.

       -h, --help
               Print short help message and exit.

       -o file, --output=file
               Save output to file file instead of printing it to stdout.

       -p path, --path=path
               Set the load path to path.  The load path defaults to the  directory,  from  which
               the state definitions file is loaded.

       -s state, --state=state
               Start execution from state state.  This definition overwrites start state resolved
               from the start block.

       -v, --verbose
               Increase the program verbosity.

       -V, --version
               Print states version and exit.

       -W level, --warning=level
               Set the warning level to level.  Possible values for level are:

               light   light warnings (default)

               all     all warnings

STATES PROGRAM FILES

       States program files can contain on  start  block,  startrules  and  namerules  blocks  to
       specify the initial state, state definitions and expressions.

       The  start block is the main() of the states program, it is executed on script startup for
       each input file and it can perform any initialization the script needs.  It normally  also
       calls  the  check_startrules()  and check_namerules() primitives which resolve the initial
       state from the input file name or the data found from the beginning  of  the  input  file.
       Here  is  a sample start block which initializes two variables and does the standard start
       state resolving:

              start
              {
                a = 1;
                msg = "Hello, world!";
                check_startrules ();
                check_namerules ();
              }

       Once the start block is processed, the input processing  is  continued  from  the  initial
       state.

       The  initial  state is resolved by the information found from the startrules and namerules
       blocks.  Both  blocks  contain  regular  expression  -  symbol  pairs,  when  the  regular
       expression  is  matched from the name of from the beginning of the input file, the initial
       state is named by the corresponding symbol.  For example, the  following  start  and  name
       rules can distinguish C and Fortran files:

              namerules
              {
                /\.(c|h)$/    c;
                /\.[fF]$/     fortran;
              }

              startrules
              {
                /-\*- [cC] -\*-/      c;
                /-\*- fortran -\*-/   fortran;
              }

       If  these  rules  are  used  with the previously shown start block, states first check the
       beginning of input file.  If it has string -*- c -*-, the file is  assumed  to  contain  C
       code  and  the  processing  is started from state called c.  If the beginning of the input
       file has string -*- fortran -*-, the initial state is fortran.  If none of the start rules
       matched,  the  name  of the input file is matched with the namerules.  If the name ends to
       suffix c or C, we go to state c.  If the suffix is f or F, the initial state is fortran.

       If both start and name rules failed to resolve the start state,  states  just  copies  its
       input to output unmodified.

       The start state can also be specified from the command line with option -s, --state.

       State definitions have the following syntax:

       state { expr {statements} ... }

       where expr is: a regular expression, special expression or symbol and statements is a list
       of statements.  When the expression expr is matched from the input, the statement block is
       executed.  The statement block can call states' primitives, user-defined subroutines, call
       other states, etc.  Once the block is executed, the input processing is continued from the
       current intput position (which might have been changed if the statement block called other
       states).

       Special expressions BEGIN and END can be used in the  place  of  expr.   Expression  BEGIN
       matches  the  beginning  of  the  state,  its  block  is called when the state is entered.
       Expression END matches the end of the state, its block is executed when states leaves  the
       state.

       If  expr  is  a  symbol, its value is looked up from the global environment and if it is a
       regular expression, it is matched to the input, otherwise that rule is ignored.

       The states program file can also have top-level expressions, they are evaluated after  the
       program  file  is  parsed  but  before any input files are processed or the start block is
       evaluated.

PRIMITIVE FUNCTIONS

       call (symbol)
               Move to state symbol and continue input file processing from that state.  Function
               returns whatever the symbol state's terminating return statement returned.

       calln (name)
               Like  call  but  the argument name is evaluated and its value must be string.  For
               example, this function can be used to call a state  which  name  is  stored  to  a
               variable.

       check_namerules ()
               Try  to  resolve  start  state  from namerules rules.  Function returns 1 if start
               state was resolved or 0 otherwise.

       check_startrules ()
               Try to resolve start state from startrules rules.  Function  returns  1  if  start
               state was resolved or 0 otherwise.

       concat (str, ...)
               Concanate argument strings and return result as a new string.

       float (any)
               Convert argument to a floating point number.

       getenv (str)
               Get value of environment variable str.  Returns an empty string if variable var is
               undefined.

       int (any)
               Convert argument to an integer number.

       length (item, ...)
               Count the length of argument strings or lists.

       list (any, ...)
               Create a new list which contains items any, ...

       panic (any, ...)
               Report a non-recoverable error and exit with status 1.  Function never returns.

       print (any, ...)
               Convert arguments to strings and print them to the output.

       range (source, start, end)
               Return a sub-range of source starting from position  start  (inclusively)  to  end
               (exclusively).  Argument source can be string or list.

       regexp (string)
               Convert string string to a new regular expression.

       regexp_syntax (char, syntax)
               Modify  regular  expression  character syntaxes by assigning new syntax syntax for
               character char.  Possible values for syntax are:

               'w'     character is a word constituent

               ' '     character isn't a word constituent

       regmatch (string, regexp)
               Check if string string matches regular expression  regexp.   Functions  returns  a
               boolean success status and sets sub-expression registers $n.

       regsub (string, regexp, subst)
               Search  regular  expression  regexp  from  string  string and replace the matching
               substring with string subst.  Returns  the  resulting  string.   The  substitution
               string subst can contain $n references to the n:th parenthesized sup-expression.

       regsuball (string, regexp, subst)
               Like  regsub  but  replace  all  matches  of regular expression regexp from string
               string with string subst.

       require_state (symbol)
               Check that the state symbol is defined.  If the required state is  undefined,  the
               function  tries  to autoload it.  If the loading fails, the program will terminate
               with an error message.

       split (regexp, string)
               Split string string to list considering matches of regular rexpression  regexp  as
               item separator.

       sprintf (fmt, ...)
               Format arguments according to fmt and return result as a string.

       strcmp (str1, str2)
               Perform  a case-sensitive comparision for strings str1 and str2.  Function returns
               a value that is:

               -1      string str1 is less than str2

               0       strings are equal

               1       string str1 is greater than str2

       string (any)
               Convert argument to string.

       strncmp (str1, str2, num)
               Perform a case-sensitive comparision  for  strings  str1  and  str2  comparing  at
               maximum num characters.

       substring (str, start, end)
               Return a substring of string str starting from position start (inclusively) to end
               (exclusively).

BUILTIN VARIABLES

       $.      current input line number

       $n      the n:th parenthesized regular expression sub-expression  from  the  latest  state
               regular expression or from the regmatch primitive

       $`      everything  before the matched regular rexpression.  This is usable when used with
               the regmatch primitive; the contents of this variable is undefined  when  used  in
               action blocks to refer the data before the block's regular expression.

       $B      an alias for $`

       argv    list of input file names

       filename
               name of the current input file

       program name of the program (usually states)

       version program version string

FILES

       /usr/share/enscript/hl/*.st             enscript's states definitions

SEE ALSO

       awk(1), enscript(1)

AUTHOR

       Markku Rossi <mtr@iki.fi> <http://www.iki.fi/~mtr/>

       GNU Enscript WWW home page: <http://www.iki.fi/~mtr/genscript/>