states man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

STATES(1)			    STATES			     STATES(1)

NAME
       states - awk alike text processing tool

SYNOPSIS
       states [-hV] [-D var=val] [-f file] [-o outputfile] [-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 con‐
       tinues  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 con‐
	       fig 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 cur‐
	       rent 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.

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

       -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  initializa‐
       tion  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 begining 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 expres‐
       sion - 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  con‐
       tinued  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,	other‐
       wise 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  ter‐
	       minating return statement returned.

       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.	 Func‐
	       tion 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-expres‐
	       sion registers $n.

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

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

       split (regexp, string)
	       Split string string to list considering matches of regular rex‐
	       pression 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 nth parenthesized regular  expression  sub-expression  from
	       the latest state regular expression or from the regmatch primi‐
	       tive

       $`      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/enscript.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/>

STATES				  Jun 6, 1997			     STATES(1)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net