.\" .\" States manual page. .\" Copyright (c) 1997 Markku Rossi. .\" Author: Markku Rossi <mtr@iki.fi> .\" .\" This file is part of GNU enscript. .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2, or (at your option) .\" any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; see the file COPYING. If not, write to .\" the Free Software Foundation, 59 Temple Place - Suite 330, .\" Boston, MA 02111-1307, USA. .\" .TH STATES 1 "Jun 6, 1997" "STATES" "STATES" .SH NAME states \- awk alike text processing tool .SH SYNOPSIS .B states [\f3\-hV\f1] [\f3\-D \f2var\f3=\f2val\f1] [\f3\-f \f2file\f1] [\f3\-o \f2outputfile\f1] [\f3\-s \f2startstate\f1] [\f3\-W \f2level\f1] [\f2filename\f1 ...] .SH DESCRIPTION \f3States\f1 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, \f3States\f1 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, \f3states\f1 can perform state transitions; it can move to another state from which the processing is continued. State transitions are recorded so \f3states\f1 can return to the calling state once the current state has finished. The biggest difference between \f3states\f1 and awk, besides state machine extensions, is that \f3states\f1 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. .SH OPTIONS .TP 8 .B \-D \f2var\f3=\f2val\f3, \-\-define=\f2var\f3=\f2val\f3 Define variable \f2var\f1 to have string value \f2val\f1. Command line definitions overwrite variable definitions found from the config file. .TP 8 .B \-f \f2file\f3, \-\-file=\f2file\f3 Read state definitions from file \f2file\f1. As a default, \f3states\f1 tries to read state definitions from file \f3states.st\f1 in the current working directory. .TP 8 .B \-h, \-\-help Print short help message and exit. .TP 8 .B \-o \f2file\f3, \-\-output=\f2file\f3 Save output to file \f2file\f1 instead of printing it to \f3stdout\f1. .TP 8 .B \-s \f2state\f3, \-\-state=\f2state\f3 Start execution from state \f3state\f1. This definition overwrites start state resolved from the \f3start\f1 block. .TP 8 .B \-V, \-\-version Print \f3states\f1 version and exit. .TP 8 .B \-W \f2level\f3, \-\-warning=\f2level\f3 Set the warning level to \f2level\f1. Possible values for \f2level\f1 are: .RS 8 .TP 8 .B light light warnings (default) .TP 8 .B all all warnings .RE .SH STATES PROGRAM FILES \f3States\f1 program files can contain on \f2start\f1 block, \f2startrules\f1 and \f2namerules\f1 blocks to specify the initial state, \f2state\f1 definitions and \f2expressions\f1. The \f2start\f1 block is the main() of the \f3states\f1 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 \f3check_startrules()\f1 and \f3check_namerules()\f1 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: .PP .RS .nf start { a = 1; msg = "Hello, world!"; check_startrules (); check_namerules (); } .fi .RE .PP 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 \f2startrules\f1 and \f2namerules\f1 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: .PP .RS .nf namerules { /\.(c|h)$/ c; /\.[fF]$/ fortran; } startrules { /-\*- [cC] -\*-/ c; /-\*- fortran -\*-/ fortran; } .fi .RE .PP If these rules are used with the previously shown start block, \f3states\f1 first check the beginning of input file. If it has string \f3-*- c -*-\f1, the file is assumed to contain C code and the processing is started from state called \f3c\f1. If the beginning of the input file has string \f3-*- fortran -*-\f1, the initial state is \f3fortran\f1. If none of the start rules matched, the name of the input file is matched with the namerules. If the name ends to suffix \f3c\f1 or \f3C\f1, we go to state \f3c\f1. If the suffix is \f3f\f1 or \f3F\f1, the initial state is fortran. If both start and name rules failed to resolve the start state, \f3states\f1 just copies its input to output unmodified. The start state can also be specified from the command line with option \f3\-s\f1, \f3\-\-state\f1. State definitions have the following syntax: .B state { \f2expr\f1 {\f2statements\f1} ... } where \f2expr\f1 is: a regular expression, special expression or symbol and \f2statements\f1 is a list of statements. When the expression \f2expr\f1 is matched from the input, the statement block is executed. The statement block can call \f3states\f1' 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 \f3BEGIN\f1 and \f3END\f1 can be used in the place of \f2expr\f1. Expression \f3BEGIN\f1 matches the beginning of the state, its block is called when the state is entered. Expression \f3END\f1 matches the end of the state, its block is executed when \f3states\f1 leaves the state. If \f2expr\f1 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 \f3states\f1 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 \f2start\f1 block is evaluated. .SH PRIMITIVE FUNCTIONS .TP 8 .B call (\f2symbol\f3) Move to state \f2symbol\f1 and continue input file processing from that state. Function returns whatever the \f3symbol\f1 state's terminating \f3return\f1 statement returned. .TP 8 .B check_namerules () Try to resolve start state from \f3namerules\f1 rules. Function returns \f31\f1 if start state was resolved or \f30\f1 otherwise. .TP 8 .B check_startrules () Try to resolve start state from \f3startrules\f1 rules. Function returns \f31\f1 if start state was resolved or \f30\f1 otherwise. .TP 8 .B concat (\f2str\f3, ...) Concanate argument strings and return result as a new string. .TP 8 .B float (\f2any\f3) Convert argument to a floating point number. .TP 8 .B getenv (\f2str\f3) Get value of environment variable \f2str\f1. Returns an empty string if variable \f2var\f1 is undefined. .TP 8 .B int (\f2any\f3) Convert argument to an integer number. .TP 8 .B length (\f2item\f3, ...) Count the length of argument strings or lists. .TP 8 .B list (\f2any\f3, ...) Create a new list which contains items \f2any\f1, ... .TP 8 .B panic (\f2any\f3, ...) Report a non-recoverable error and exit with status \f31\f1. Function never returns. .TP 8 .B print (\f2any\f3, ...) Convert arguments to strings and print them to the output. .TP 8 .B range (\f2source\f3, \f2start\f3, \f2end\f3) Return a sub\-range of \f2source\f1 starting from position \f2start\f1 (inclusively) to \f2end\f1 (exclusively). Argument \f2source\f1 can be string or list. .TP 8 .B regexp (\f2string\f3) Convert string \f2string\f1 to a new regular expression. .TP 8 .B regexp_syntax (\f2char\f3, \f2syntax\f3) Modify regular expression character syntaxes by assigning new syntax \f2syntax\f1 for character \f2char\f1. Possible values for \f2syntax\f1 are: .RS 8 .TP 8 .B 'w' character is a word constituent .TP 8 .B ' ' character isn't a word constituent .RE .TP 8 .B regmatch (\f2string\f3, \f2regexp\f3) Check if string \f2string\f1 matches regular expression \f2regexp\f1. Functions returns a boolean success status and sets sub-expression registers \f3$\f2n\f1. .TP 8 .B regsub (\f2string\f1, \f2regexp\f3, \f2subst\f3) Search regular expression \f2regexp\f1 from string \f2string\f1 and replace the matching substring with string \f2subst\f1. Returns the resulting string. The substitution string \f2subst\f1 can contain \f3$\f2n\f1 references to the \f2n\f1:th parenthesized sup-expression. .TP 8 .B regsuball (\f2string\f1, \f2regexp\f3, \f2subst\f3) Like \f3regsub\f1 but replace all matches of regular expression \f2regexp\f1 from string \f2string\f1 with string \f2subst\f1. .TP 8 .B split (\f2regexp\f3, \f2string\f3) Split string \f2string\f1 to list considering matches of regular rexpression \f2regexp\f1 as item separator. .TP 8 .B sprintf (\f2fmt\f1, ...) Format arguments according to \f2fmt\f1 and return result as a string. .TP 8 .B strcmp (\f2str1\f3, \f2str2\f3) Perform a case\-sensitive comparision for strings \f2str1\f1 and \f2str2\f1. Function returns a value that is: .RS 8 .TP 8 .B -1 string \f2str1\f1 is less than \f2str2\f1 .TP 8 .B 0 strings are equal .TP 8 .B 1 string \f2str1\f1 is greater than \f2str2\f1 .RE .TP 8 .B string (\f2any\f3) Convert argument to string. .TP 8 .B strncmp (\f2str1\f3, \f2str2\f3, \f2num\f3) Perform a case\-sensitive comparision for strings \f2str1\f1 and \f2str2\f1 comparing at maximum \f2num\f3 characters. .TP 8 .B substring (\f2str\f3, \f2start\f3, \f2end\f3) Return a substring of string \f2str\f1 starting from position \f2start\f1 (inclusively) to \f2end\f1 (exclusively). .RE .SH BUILTIN VARIABLES .TP 8 .B $. current input line number .TP 8 .B $\f2n\f3 the \f2n\f1th parenthesized regular expression sub-expression from the latest state regular expression or from the \f3regmatch\f1 primitive .TP 8 .B $` everything before the matched regular rexpression. This is usable when used with the \f3regmatch\f1 primitive; the contents of this variable is undefined when used in action blocks to refer the data before the block's regular expression. .TP 8 .B $B an alias for \f3$`\f1 .TP 8 .B argv list of input file names .TP 8 .B filename name of the current input file .TP 8 .B program name of the program (usually \f3states\f1) .TP 8 .B version program version string .RE .SH FILES .nf .ta 4i @prefix@/share/enscript/enscript.st enscript's states definitions .fi .SH SEE ALSO awk(1), enscript(1) .SH AUTHOR Markku Rossi <mtr@iki.fi> <http://www.iki.fi/~mtr/> GNU Enscript WWW home page: <http://www.iki.fi/~mtr/genscript/>