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
|
.\" placed in the public domain by Will Naylor -*- nroff -*-
.\" 1998-08-21 formatting added by Jim Van Zandt <jrv@vanzandt.mv.com>
.TH WNCSTR 3 "August 23, 1998" "WNLIB" ""
.SH NAME
wn_make_cstream, wn_free_cstream, wn_current_mark, wn_set_current_mark, wn_flush_to_mark, wn_cstream_debug \- general parsing and writing package
.SH SYNOPSIS
.nf
.B #include <wn/wncstr.h>
.sp
.B WN_PARSE
.B WN_WRITE
.sp
.B wn_make_cstream(&\fIstream\fP,\fIpmove_block\fP,\fImove_block_ptr\fP,
.B \fIblock_size\fP,\fIparse_or_write\fP)
.B wn_cstream \fIstream\fP;
.B void (*\fIpmove_block\fP)(/* \fIblock\fP,&\fIactually_moved\fP,\fIrequest_moved\fP,
.B \fImove_block_ptr\fP */);
.B ptr \fImove_block_ptr\fP;
.B int \fIblock_size\fP,\fIparse_or_write\fP;
.sp
.B wn_free_cstream(\fIstream\fP)
.B wn_cstream \fIstream\fP;
.sp
.B int wn_current_mark(\fIstream\fP)
.B wn_cstream \fIstream\fP;
.sp
.B bool wn_set_current_mark(\fIstream\fP,\fImark\fP)
.B wn_cstream \fIstream\fP;
.B int \fImark\fP;
.sp
.B wn_flush_to_mark(\fIstream\fP,\fImark\fP)
.B wn_cstream \fIstream\fP;
.B int \fImark\fP;
.sp
.B bool wn_cstream_debug(\fIstream\fP)
.B wn_cstream \fIstream\fP;
.SH DESCRIPTION
wncstr, wncstl, wnptok, wnwtok, wnwtokp, and wncinf comprise
an integrated package designed to parse and write complicated
files and strings. Parsing is accomplished using a generalized
recursive-descent methodology [1]; writing is accomplished
using a recursive-descent like methodology. Identical or very similar
grammars work for parsing and for writing a language. The C code
is also very similar. Very complicated grammars
can be parsed efficiently using this package, including context-free
grammars with long lookahead and many context-sensitive grammars.
No distinction is made between lexical analysis and parsing proper;
the lexical analysis is handled in the same way as the parsing.
The object to be parsed or written must first
be converted to a logical character array (a cstream).
\fBwn_make_cstream\fP accomplishes this in general; for files and
strings see wncstl for shortcuts. A cstream is logically an array of
characters (that is, bytes), together with a cursor or
"current mark". The current mark points to the character
currently being looked at. Thus, during parsing or writing,
the current mark moves from 0 (beginning of \fIstream\fP) to
larger and larger values and eventually reaches end of \fIstream\fP.
Parsing is accomplished using a generalized recursive-descent
methodology. Generally, you need a C subroutine for each non-terminal in
the grammar. The subroutine generally has 2 or more arguments
and returns a boolean. The first argument is the cstream to
parse; the other arguments are parse trees and other data constructed
if the parse succeeds; the return value says whether the parse
succeeded. When called, the subroutine attempts to parse the
non-terminal from the cstream, starting at the current mark.
If it fails, it returns \fBFALSE\fP and sets the current mark back
to its start value (using \fBwn_set_current_mark\fP and
\fBwn_current_mark\fP). If its succeeds, it returns \fBTRUE\fP,
usually generates some data (such as a parse tree), and
leaves the current mark after the parsed non-terminal in
the cstream. These subroutines are built from other
non-terminal parsing subroutines. The hierarchy bottoms out
with the subroutines in wnptok. Subroutines are often combined
in logical expressions.
All characters earlier in the cstream than the current mark
take up dynamic memory unless flushed using \fBwn_flush_to_mark\fP.
Use \fBwn_flush_to_mark\fP when it is clear that characters before
\fImark\fP will never be examined again.
\fBwn_cstream_debug\fP prints the characters from \fIstream\fP in the
neighborhood of the current mark. This information is very useful
for debugging parsers. \fBwn_cstream_debug\fP always returns \fBTRUE\fP, so
it can be inserted into logical expressions.
Writing is also accomplished with a recursive-descent like
methodology, with a subroutine for each non-terminal in the
grammar. The subroutine generally has 2 or more arguments;
no value is returned. The first argument is the cstream to
write into; the other arguments contain the information to write.
These subroutines are built from other non-terminal writing subroutines.
The hierarchy bottoms out with the subroutines in wnwtok and wnwtokp.
Generally, the same or similar subroutine hierarchies works for
parsing and writing a language.
Routines in wncinf assist in printing error messages with
line numbers.
Routines in wnscan scan a cstream for patterns.
.SH BUGS
Too many subroutine names to remember.
This package may be slower than less general parsing packages.
.SH "SEE ALSO"
wncstl, wnptok, wnscan, wnwtok, wnwtokp, wncinf
.SH REFERENCES
[1] Alfred V. Aho, Jeffrey D. Ullman: Principles of Compiler Design,
April 1979, Addison-Wesley Publishing, Reading Massachusetts.
.SH AUTHOR
Will Naylor
|
