File: states.man

package info (click to toggle)
enscript 1.6.5.90-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 7,264 kB
  • ctags: 4,824
  • sloc: ansic: 33,705; sh: 5,383; makefile: 649; yacc: 457; lex: 428; perl: 340; lisp: 109; sed: 16
file content (366 lines) | stat: -rw-r--r-- 11,884 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
.\"
.\" States manual page.
.\" Copyright (c) 1997-1998 Markku Rossi.
.\" Author: Markku Rossi <mtr@iki.fi>
.\"
.\" This file is part of GNU Enscript.
.\"
.\" Enscript 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 3 of the License, or
.\" (at your option) any later version.
.\"
.\" Enscript 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 Enscript.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH STATES 1 "Oct 23, 1998" "STATES" "STATES"

.SH NAME
states \- awk alike text processing tool

.SH SYNOPSIS
.B states
[\f3\-hvV\f1]
[\f3\-D \f2var\f3=\f2val\f1]
[\f3\-f \f2file\f1]
[\f3\-o \f2outputfile\f1]
[\f3\-p \f2path\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 \-p \f2path\f3, \-\-path=\f2path\f3
Set the load path to \f2path\f1.  The load path defaults to the
directory, from which the state definitions file is loaded.
.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, \-\-verbose
Increase the program verbosity.
.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 beginning 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 calln (\f2name\f3)
Like \f3call\f1 but the argument \f2name\f1 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.
.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 require_state (\f2symbol\f3)
Check that the state \f2symbol\f1 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.
.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\f1:th 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
@DATADIR@/enscript/hl/*.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/>