1 rizwank 1.1 .\"
2 .\" States manual page.
3 .\" Copyright (c) 1997-1998 Markku Rossi.
4 .\" Author: Markku Rossi <mtr@iki.fi>
5 .\"
6 .\" This file is part of GNU enscript.
7 .\"
8 .\" This program is free software; you can redistribute it and/or modify
9 .\" it under the terms of the GNU General Public License as published by
10 .\" the Free Software Foundation; either version 2, or (at your option)
11 .\" any later version.
12 .\"
13 .\" This program is distributed in the hope that it will be useful,
14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 .\" GNU General Public License for more details.
17 .\"
18 .\" You should have received a copy of the GNU General Public License
19 .\" along with this program; see the file COPYING. If not, write to
20 .\" the Free Software Foundation, 59 Temple Place - Suite 330,
21 .\" Boston, MA 02111-1307, USA.
22 rizwank 1.1 .\"
23 .TH STATES 1 "Oct 23, 1998" "STATES" "STATES"
24
25 .SH NAME
26 states \- awk alike text processing tool
27
28 .SH SYNOPSIS
29 .B states
30 [\f3\-hvV\f1]
31 [\f3\-D \f2var\f3=\f2val\f1]
32 [\f3\-f \f2file\f1]
33 [\f3\-o \f2outputfile\f1]
34 [\f3\-p \f2path\f1]
35 [\f3\-s \f2startstate\f1]
36 [\f3\-W \f2level\f1]
37 [\f2filename\f1 ...]
38
39 .SH DESCRIPTION
40
41 \f3States\f1 is an awk-alike text processing tool with some state
42 machine extensions. It is designed for program source code
43 rizwank 1.1 highlighting and to similar tasks where state information helps input
44 processing.
45
46 At a single point of time, \f3States\f1 is in one state, each quite
47 similar to awk's work environment, they have regular expressions which
48 are matched from the input and actions which are executed when a match
49 is found. From the action blocks, \f3states\f1 can perform state
50 transitions; it can move to another state from which the processing is
51 continued. State transitions are recorded so \f3states\f1 can return
52 to the calling state once the current state has finished.
53
54 The biggest difference between \f3states\f1 and awk, besides state
55 machine extensions, is that \f3states\f1 is not line-oriented. It
56 matches regular expression tokens from the input and once a match is
57 processed, it continues processing from the current position, not from
58 the beginning of the next input line.
59
60 .SH OPTIONS
61 .TP 8
62 .B \-D \f2var\f3=\f2val\f3, \-\-define=\f2var\f3=\f2val\f3
63 Define variable \f2var\f1 to have string value \f2val\f1. Command
64 rizwank 1.1 line definitions overwrite variable definitions found from the config
65 file.
66 .TP 8
67 .B \-f \f2file\f3, \-\-file=\f2file\f3
68 Read state definitions from file \f2file\f1. As a default,
69 \f3states\f1 tries to read state definitions from file \f3states.st\f1
70 in the current working directory.
71 .TP 8
72 .B \-h, \-\-help
73 Print short help message and exit.
74 .TP 8
75 .B \-o \f2file\f3, \-\-output=\f2file\f3
76 Save output to file \f2file\f1 instead of printing it to
77 \f3stdout\f1.
78 .TP 8
79 .B \-p \f2path\f3, \-\-path=\f2path\f3
80 Set the load path to \f2path\f1. The load path defaults to the
81 directory, from which the state definitions file is loaded.
82 .TP 8
83 .B \-s \f2state\f3, \-\-state=\f2state\f3
84 Start execution from state \f3state\f1. This definition overwrites
85 rizwank 1.1 start state resolved from the \f3start\f1 block.
86 .TP 8
87 .B \-v, \-\-verbose
88 Increase the program verbosity.
89 .TP 8
90 .B \-V, \-\-version
91 Print \f3states\f1 version and exit.
92 .TP 8
93 .B \-W \f2level\f3, \-\-warning=\f2level\f3
94 Set the warning level to \f2level\f1. Possible values for \f2level\f1
95 are:
96 .RS 8
97 .TP 8
98 .B light
99 light warnings (default)
100 .TP 8
101 .B all
102 all warnings
103 .RE
104
105 .SH STATES PROGRAM FILES
106 rizwank 1.1
107 \f3States\f1 program files can contain on \f2start\f1 block,
108 \f2startrules\f1 and \f2namerules\f1 blocks to specify the initial
109 state, \f2state\f1 definitions and \f2expressions\f1.
110
111 The \f2start\f1 block is the main() of the \f3states\f1 program, it is
112 executed on script startup for each input file and it can perform any
113 initialization the script needs. It normally also calls the
114 \f3check_startrules()\f1 and \f3check_namerules()\f1 primitives which
115 resolve the initial state from the input file name or the data found
116 from the begining of the input file. Here is a sample start block
117 which initializes two variables and does the standard start state
118 resolving:
119 .PP
120 .RS
121 .nf
122 start
123 {
124 a = 1;
125 msg = "Hello, world!";
126 check_startrules ();
127 rizwank 1.1 check_namerules ();
128 }
129 .fi
130 .RE
131 .PP
132 Once the start block is processed, the input processing is continued
133 from the initial state.
134
135 The initial state is resolved by the information found from the
136 \f2startrules\f1 and \f2namerules\f1 blocks. Both blocks contain
137 regular expression - symbol pairs, when the regular expression is
138 matched from the name of from the beginning of the input file, the
139 initial state is named by the corresponding symbol. For example, the
140 following start and name rules can distinguish C and Fortran files:
141 .PP
142 .RS
143 .nf
144 namerules
145 {
146 /\.(c|h)$/ c;
147 /\.[fF]$/ fortran;
148 rizwank 1.1 }
149
150 startrules
151 {
152 /-\*- [cC] -\*-/ c;
153 /-\*- fortran -\*-/ fortran;
154 }
155 .fi
156 .RE
157 .PP
158 If these rules are used with the previously shown start block,
159 \f3states\f1 first check the beginning of input file. If it has
160 string \f3-*- c -*-\f1, the file is assumed to contain C code and the
161 processing is started from state called \f3c\f1. If the beginning of
162 the input file has string \f3-*- fortran -*-\f1, the initial state is
163 \f3fortran\f1. If none of the start rules matched, the name of the
164 input file is matched with the namerules. If the name ends to suffix
165 \f3c\f1 or \f3C\f1, we go to state \f3c\f1. If the suffix is
166 \f3f\f1 or \f3F\f1, the initial state is fortran.
167
168 If both start and name rules failed to resolve the start state,
169 rizwank 1.1 \f3states\f1 just copies its input to output unmodified.
170
171 The start state can also be specified from the command line with
172 option \f3\-s\f1, \f3\-\-state\f1.
173
174 State definitions have the following syntax:
175
176 .B state { \f2expr\f1 {\f2statements\f1} ... }
177
178 where \f2expr\f1 is: a regular expression, special expression or
179 symbol and \f2statements\f1 is a list of statements. When the
180 expression \f2expr\f1 is matched from the input, the statement block
181 is executed. The statement block can call \f3states\f1' primitives,
182 user-defined subroutines, call other states, etc. Once the block is
183 executed, the input processing is continued from the current intput
184 position (which might have been changed if the statement block called
185 other states).
186
187 Special expressions \f3BEGIN\f1 and \f3END\f1 can be used in the place
188 of \f2expr\f1. Expression \f3BEGIN\f1 matches the beginning of the
189 state, its block is called when the state is entered. Expression
190 rizwank 1.1 \f3END\f1 matches the end of the state, its block is executed when
191 \f3states\f1 leaves the state.
192
193 If \f2expr\f1 is a symbol, its value is looked up from the global
194 environment and if it is a regular expression, it is matched to the
195 input, otherwise that rule is ignored.
196
197 The \f3states\f1 program file can also have top-level expressions,
198 they are evaluated after the program file is parsed but before any
199 input files are processed or the \f2start\f1 block is evaluated.
200
201 .SH PRIMITIVE FUNCTIONS
202
203 .TP 8
204 .B call (\f2symbol\f3)
205 Move to state \f2symbol\f1 and continue input file processing from
206 that state. Function returns whatever the \f3symbol\f1 state's
207 terminating \f3return\f1 statement returned.
208 .TP 8
209 .B calln (\f2name\f3)
210 Like \f3call\f1 but the argument \f2name\f1 is evaluated and its value
211 rizwank 1.1 must be string. For example, this function can be used to call a
212 state which name is stored to a variable.
213 .TP 8
214 .B check_namerules ()
215 Try to resolve start state from \f3namerules\f1 rules. Function
216 returns \f31\f1 if start state was resolved or \f30\f1 otherwise.
217 .TP 8
218 .B check_startrules ()
219 Try to resolve start state from \f3startrules\f1 rules. Function
220 returns \f31\f1 if start state was resolved or \f30\f1 otherwise.
221 .TP 8
222 .B concat (\f2str\f3, ...)
223 Concanate argument strings and return result as a new string.
224 .TP 8
225 .B float (\f2any\f3)
226 Convert argument to a floating point number.
227 .TP 8
228 .B getenv (\f2str\f3)
229 Get value of environment variable \f2str\f1. Returns an empty string
230 if variable \f2var\f1 is undefined.
231 .TP 8
232 rizwank 1.1 .B int (\f2any\f3)
233 Convert argument to an integer number.
234 .TP 8
235 .B length (\f2item\f3, ...)
236 Count the length of argument strings or lists.
237 .TP 8
238 .B list (\f2any\f3, ...)
239 Create a new list which contains items \f2any\f1, ...
240 .TP 8
241 .B panic (\f2any\f3, ...)
242 Report a non-recoverable error and exit with status \f31\f1. Function
243 never returns.
244 .TP 8
245 .B print (\f2any\f3, ...)
246 Convert arguments to strings and print them to the output.
247 .TP 8
248 .B range (\f2source\f3, \f2start\f3, \f2end\f3)
249 Return a sub\-range of \f2source\f1 starting from position \f2start\f1
250 (inclusively) to \f2end\f1 (exclusively). Argument \f2source\f1 can
251 be string or list.
252 .TP 8
253 rizwank 1.1 .B regexp (\f2string\f3)
254 Convert string \f2string\f1 to a new regular expression.
255 .TP 8
256 .B regexp_syntax (\f2char\f3, \f2syntax\f3)
257 Modify regular expression character syntaxes by assigning new
258 syntax \f2syntax\f1 for character \f2char\f1. Possible values for
259 \f2syntax\f1 are:
260 .RS 8
261 .TP 8
262 .B 'w'
263 character is a word constituent
264 .TP 8
265 .B ' '
266 character isn't a word constituent
267 .RE
268 .TP 8
269 .B regmatch (\f2string\f3, \f2regexp\f3)
270 Check if string \f2string\f1 matches regular expression \f2regexp\f1.
271 Functions returns a boolean success status and sets sub-expression
272 registers \f3$\f2n\f1.
273 .TP 8
274 rizwank 1.1 .B regsub (\f2string\f1, \f2regexp\f3, \f2subst\f3)
275 Search regular expression \f2regexp\f1 from string \f2string\f1 and
276 replace the matching substring with string \f2subst\f1. Returns the
277 resulting string. The substitution string \f2subst\f1 can contain
278 \f3$\f2n\f1 references to the \f2n\f1:th parenthesized
279 sup-expression.
280 .TP 8
281 .B regsuball (\f2string\f1, \f2regexp\f3, \f2subst\f3)
282 Like \f3regsub\f1 but replace all matches of regular expression
283 \f2regexp\f1 from string \f2string\f1 with string \f2subst\f1.
284 .TP 8
285 .B require_state (\f2symbol\f3)
286 Check that the state \f2symbol\f1 is defined. If the required state
287 is undefined, the function tries to autoload it. If the loading
288 fails, the program will terminate with an error message.
289 .TP 8
290 .B split (\f2regexp\f3, \f2string\f3)
291 Split string \f2string\f1 to list considering matches of regular
292 rexpression \f2regexp\f1 as item separator.
293 .TP 8
294 .B sprintf (\f2fmt\f1, ...)
295 rizwank 1.1 Format arguments according to \f2fmt\f1 and return result as a
296 string.
297 .TP 8
298 .B strcmp (\f2str1\f3, \f2str2\f3)
299 Perform a case\-sensitive comparision for strings \f2str1\f1 and
300 \f2str2\f1. Function returns a value that is:
301 .RS 8
302 .TP 8
303 .B -1
304 string \f2str1\f1 is less than \f2str2\f1
305 .TP 8
306 .B 0
307 strings are equal
308 .TP 8
309 .B 1
310 string \f2str1\f1 is greater than \f2str2\f1
311 .RE
312 .TP 8
313 .B string (\f2any\f3)
314 Convert argument to string.
315 .TP 8
316 rizwank 1.1 .B strncmp (\f2str1\f3, \f2str2\f3, \f2num\f3)
317 Perform a case\-sensitive comparision for strings \f2str1\f1 and
318 \f2str2\f1 comparing at maximum \f2num\f3 characters.
319 .TP 8
320 .B substring (\f2str\f3, \f2start\f3, \f2end\f3)
321 Return a substring of string \f2str\f1 starting from position
322 \f2start\f1 (inclusively) to \f2end\f1 (exclusively).
323 .RE
324
325 .SH BUILTIN VARIABLES
326 .TP 8
327 .B $.
328 current input line number
329 .TP 8
330 .B $\f2n\f3
331 the \f2n\f1:th parenthesized regular expression sub-expression from the
332 latest state regular expression or from the \f3regmatch\f1 primitive
333 .TP 8
334 .B $`
335 everything before the matched regular rexpression. This is usable
336 when used with the \f3regmatch\f1 primitive; the contents of this
337 rizwank 1.1 variable is undefined when used in action blocks to refer the data
338 before the block's regular expression.
339 .TP 8
340 .B $B
341 an alias for \f3$`\f1
342 .TP 8
343 .B argv
344 list of input file names
345 .TP 8
346 .B filename
347 name of the current input file
348 .TP 8
349 .B program
350 name of the program (usually \f3states\f1)
351 .TP 8
352 .B version
353 program version string
354 .RE
355
356 .SH FILES
357 .nf
358 rizwank 1.1 .ta 4i
359 @DATADIR@/enscript/hl/*.st enscript's states definitions
360 .fi
361
362 .SH SEE ALSO
363 awk(1), enscript(1)
364
365 .SH AUTHOR
366 Markku Rossi <mtr@iki.fi> <http://www.iki.fi/~mtr/>
367
368 GNU Enscript WWW home page: <http://www.iki.fi/~mtr/genscript/>
|
Return to
states.man
CVS log
Up to [RizwankCVS] / testProject / docs