summaryrefslogtreecommitdiffabout
path: root/doc/grecs_parse.3
blob: 6493a15ad669158871755fb889978bbd9f58c7e9 (plain)
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
.\" This file is part of grecs -*- nroff -*-
.\" Copyright (C) 2007, 2009-2012, 2015 Sergey Poznyakoff
.\"
.\" Grecs 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, or (at your option)
.\" any later version.
.\"
.\" Grecs 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 Grecs.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH GRECS_PARSE 3 "July 1, 2011" "GRECS" "Grecs User Reference"
.SH NAME
grecs_parse \- parse a configuration file.
.SH SYNOPSIS
.nf
.B #include <grecs.h>
.sp
.BI "struct grecs_node *grecs_parse(const char *" "name" );
.SH DESCRIPTION
The
.BR grecs_parse ()
function reads the file \fBname\fR, which must be formatted
according to
.BR grecs_config (5)
and returns the parsed-out syntax tree.  On errors, \fBNULL\fR is
returned and appropriate diagnostic messages are printed using
.BR grecs_error (3).
.PP
The syntax tree consists of \fInodes\fR, linked together so as to
represent the file structure. A node is described by the following
object:
.sp
.nf
.in +5
typedef struct grecs_node {
     enum grecs_node_type type;
     grecs_locus_t locus;
     struct grecs_node *up;
     struct grecs_node *down;
     struct grecs_node *next;
     struct grecs_node *prev;
     char *ident;
     grecs_locus_t idloc;
     union {
          struct grecs_value *value;
          struct grecs_symtab *texttab;
     } v;
} grecs_node_t;
.in
.fi
.PP
The \fItype\fR member describes the type of this node.  Its value is
\fBgrecs_node_stmt\fR for simple statements and
\fBgrecs_node_block\fR, for block statements.  The topmost node (the
one returned by \fBgrecs_tree_parse\fR) has type \fBgrecs_node_root\fR.
.PP
The \fIlocus\fR describes the location in the input file, which this
node described.  See
.BR grecs_error (3),
for a description of \fBgrecs_locus_t\fR.
.PP
Adjacent nodes form a doubly-linked list using the \fBnext\fR and
\fBprev\fR pointers.  Thus, the node pointed to by \fBnext\fR
describes the statement that appears immediately after the one
described by the current node, whereas \fBprev\fR points to the node
describing a preceding statement.
.PP
If \fItype\fR is \fBgrecs_node_block\fR, the \fBdown\fR member points
to the first \fBsub-statement\fR in this block.  \fBdown->next\fR
will point to the second statement (if any), and so on.
.PP
Whatever the node type is, its \fBup\fR member will point to the node
corresponding to the upper-level block statement, if any.  In other
words, \fBdown\fR and \fBup\fR pointers reflect the hierarchical
structure of the file, so that the following holds true:
.sp
.nf
.in +5
node->up->down == node
node->down->up == node
.in
.fi
.sp
provided that \fBnode->up\fR and \fBnode->down\fR are not NULL.
.PP
The \fBident\fR member points to the keyword of that node.  For
example, a node corresponding to the input line:
.sp
.nf
.in +5
pidfile "/var/run/mypid";
.in
.fi
.sp
will have \fBident\fR pointing to the string \fB/var/run/mypid\fR.
.PP
The \fIidloc\fR contains the location of the identifier portion in the
input file. Notice, that it differs from \fBlocus\fR described above.
.PP
The \fBv\fR union keeps data which depend on the type of this node.
The \fBv.texttab\fR member is defined only for the root node (type
\fBgrecs_node_root\fR). It points to a symbol table which holds shared
strings for this tree. In particular, this table holds file names
referenced by \fBlocus\fR members of all underlying nodes.
.PP
For non-root nodes,the \fBv.value\fR member is defined.  It points to
the value associated with this statement.  A value is defined as:
.sp
.nf
.in +5
typedef struct grecs_value {
     int type;
     grecs_locus_t locus;
     union {
          struct grecs_list *list;
          char *string;
          struct {
               size_t c;
               struct grecs_value **v;
          } arg;
     } v;
} grecs_value_t;
.in
.fi
.PP
The \fBtype\fR will be \fBGRECS_TYPE_STRING\fR, for string values,
\fBGRECS_TYPE_LIST\fR, for list values, and \fBGRECS_TYPE_ARRAY\fR,
for arrays of values.  Depending on its value, the following members
of the union are used:
.TP
.B GRECS_TYPE_STRING
Actual string value is pointed to by \fBv.string\fR.
.TP
.B GRECS_TYPE_LIST
The list value is pointed to by \fBv.list\fR.
.TP
.B GRECS_TYPE_ARRAY
The array itself is stored in \fBv.arg.v\fR.  The \fBv.arg.c\fR member
contains the number of elements in the array.
.PP
The \fBlocus\fR member contains the location of this value in the
input file.
.SH RETURN VALUE
On success, a pointer to the root node.  On error, \fBNULL\fR.
.SH EXAMPLE
The following program parses the file and prints its contents on
screen:
.sp
.nf
.in +5
int
main(int argc, char **argv)
{
     struct grecs_node *tree;

     tree = grecs_parse(argv[1]);
     grecs_format_node(tree, GRECS_NODE_FLAG_DEFAULT, stdout);
     fputc('\\n', stdout);
     grecs_tree_free(tree);
     exit(0);
}
.in
.fi
.SH "SEE ALSO"
.BR grecs_config (5),
.BR grecs_error (3),
.BR grecs_format_node (3),
.BR grecs_tree_free (3).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray+grecs@gnu.org.ua>.
.SH COLOPHON
The \fBGrecs\fR library is constantly changing, so this manual page
may be incorrect or out-of-date.  For the latest copy of \fBGrecs\fR
documentation, visit <http://www.gnu.org.ua/software/grecs>.
.SH COPYRIGHT
Copyright \(co 2011 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.