Manual Pages for UNIX Darwin command on man states

STATES(1) STATES STATES(1)

NAME

states - awk alike text processing tool

SYNOPSIS

ssttaatteess [-hhvvVV] [-DD var==val] [-ff file] [-oo outputfile] [-pp path] [-ss

startstate] [-WW level] [filename ...]

DESCRIPTION

SSttaatteess 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, SSttaatteess 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, ssttaatteess can perform state transitions; it can move to another state from which the processing is continued. State transitions are recorded so ssttaatteess can return to the calling state once the current state has finished. The biggest difference between ssttaatteess and awk, besides state machine

extensions, is that ssttaatteess 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. OOPPTTIIOONNSS

-DD var==val,, --ddeeffiinnee==var==val

Define variable var to have string value val. Command line

definitions overwrite variable definitions found from the con-

fig file.

-ff file,, --ffiillee==file

Read state definitions from file file. As a default, ssttaatteess

tries to read state definitions from file ssttaatteess..sstt in the cur-

rent working directory.

-hh,, --hheellpp

Print short help message and exit.

-oo file,, --oouuttppuutt==file

Save output to file file instead of printing it to ssttddoouutt.

-pp path,, --ppaatthh==path

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

-ss state,, --ssttaattee==state

Start execution from state ssttaattee. This definition overwrites start state resolved from the ssttaarrtt block.

-vv,, --vveerrbboossee

Increase the program verbosity.

-VV,, --vveerrssiioonn

Print ssttaatteess version and exit.

-WW level,, --wwaarrnniinngg==level

Set the warning level to level. Possible values for level are: lliigghhtt light warnings (default) aallll all warnings STATES PROGRAM FILES SSttaatteess 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 ssttaatteess 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 cchheecckkssttaarrttrruulleess(()) and cchheecckknnaammeerruulleess(()) 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!"; checkstartrules (); checknamerules (); } 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, ssttaatteess

first check the beginning of input file. If it has string -**- cc -**-,

the file is assumed to contain C code and the processing is started

from state called cc. If the beginning of the input file has string -**-

ffoorrttrraann -**-, the initial state is ffoorrttrraann. If none of the start rules

matched, the name of the input file is matched with the namerules. If the name ends to suffix cc or CC, we go to state cc. If the suffix is ff or FF, the initial state is fortran. If both start and name rules failed to resolve the start state, ssttaatteess just copies its input to output unmodified. The start state can also be specified from the command line with option

-ss, --ssttaattee.

State definitions have the following syntax: ssttaattee {{ 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 ssttaatteess' 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 BBEEGGIINN and EENNDD can be used in the place of expr. Expression BBEEGGIINN matches the beginning of the state, its block is called when the state is entered. Expression EENNDD matches the end of the state, its block is executed when ssttaatteess 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 ssttaatteess 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. PPRRIIMMIITTIIVVEE FFUUNNCCTTIIOONNSS ccaallll ((symbol)) Move to state symbol and continue input file processing from

that state. Function returns whatever the ssyymmbbooll state's ter-

minating rreettuurrnn statement returned. ccaallllnn ((name)) Like ccaallll 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. cchheecckknnaammeerruulleess (()) Try to resolve start state from nnaammeerruulleess rules. Function returns 11 if start state was resolved or 00 otherwise. cchheecckkssttaarrttrruulleess (()) Try to resolve start state from ssttaarrttrruulleess rules. Function returns 11 if start state was resolved or 00 otherwise. ccoonnccaatt ((str,, ......)) Concanate argument strings and return result as a new string. ffllooaatt ((any)) Convert argument to a floating point number. ggeetteennvv ((str)) Get value of environment variable str. Returns an empty string if variable var is undefined. iinntt ((any)) Convert argument to an integer number. lleennggtthh ((item,, ......)) Count the length of argument strings or lists. lliisstt ((any,, ......)) Create a new list which contains items any, ... ppaanniicc ((any,, ......))

Report a non-recoverable error and exit with status 11. Func-

tion never returns. pprriinntt ((any,, ......)) Convert arguments to strings and print them to the output. rraannggee ((source,, start,, end))

Return a sub-range of source starting from position start

(inclusively) to end (exclusively). Argument source can be string or list. rreeggeexxpp ((string)) Convert string string to a new regular expression. rreeggeexxppssyynnttaaxx ((char,, syntax)) Modify regular expression character syntaxes by assigning new syntax syntax for character char. Possible values for syntax are: ''ww'' character is a word constituent '' '' character isn't a word constituent rreeggmmaattcchh ((string,, regexp)) Check if string string matches regular expression regexp.

Functions returns a boolean success status and sets sub-expres-

sion registers $$n.

rreeggssuubb ((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.

rreeggssuubbaallll ((string, regexp,, subst))

Like rreeggssuubb but replace all matches of regular expression reg-

exp from string string with string subst. rreeqquuiirreessttaattee ((symbol)) Check that the state symbol is defined. If the required state

is undefined, the function tries to autoload it. If the load-

ing fails, the program will terminate with an error message. sspplliitt ((regexp,, string))

Split string string to list considering matches of regular rex-

pression regexp as item separator. sspprriinnttff ((fmt, ...) Format arguments according to fmt and return result as a string. ssttrrccmmpp ((str1,, str2))

Perform a case-sensitive comparision for strings str1 and str2.

Function returns a value that is:

-11 string str1 is less than str2

00 strings are equal 11 string str1 is greater than str2 ssttrriinngg ((any)) Convert argument to string. ssttrrnnccmmpp ((str1,, str2,, num))

Perform a case-sensitive comparision for strings str1 and str2

comparing at maximum num cchhaarraacctteerrss.. ssuubbssttrriinngg ((str,, start,, end)) Return a substring of string str starting from position start (inclusively) to end (exclusively). BBUUIILLTTIINN VVAARRIIAABBLLEESS

$$.. current input line number

$$n the n:th parenthesized regular expression sub-expression from

the latest state regular expression or from the rreeggmmaattcchh primi-

tive

$$`` everything before the matched regular rexpression. This is

usable when used with the rreeggmmaattcchh primitive; the contents of this variable is undefined when used in action blocks to refer the data before the block's regular expression.

$$BB an alias for $$``

aarrggvv list of input file names ffiilleennaammee name of the current input file pprrooggrraamm name of the program (usually ssttaatteess) vveerrssiioonn program version string FILES