path: root/doc/grecs_parse.3
diff options
Diffstat (limited to 'doc/grecs_parse.3')
1 files changed, 185 insertions, 0 deletions
diff --git a/doc/grecs_parse.3 b/doc/grecs_parse.3
new file mode 100644
index 0000000..357889f
--- /dev/null
+++ b/doc/grecs_parse.3
@@ -0,0 +1,185 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 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
+.\" 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/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.TH GRECS_PARSE 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+grecs_parse \- parse a configuration file.
+.B #include <grecs.h>
+.BI "struct grecs_node *grecs_parse(const char *" "name" );
+.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).
+The syntax tree consists of \fInodes\fR, linked together so as to
+represent the file structure. A node is described by the following
+.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;
+ struct grecs_value value;
+} grecs_node_t;
+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 \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.
+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.
+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.
+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:
+.in +5
+node->up->down == node
+node->down->up == node
+provided that \fBnode->up\fR and \fBnode->down\fR are not NULL.
+The \fBident\fR member points to the keyword of that node. For
+example, a node corresponding to the input line:
+.in +5
+pidfile "/var/run/mypid";
+will have \fBident\fR pointing to the string \fB/var/run/mypid\fR.
+Finally, the \fBvalue\fR member keeps the value associated with this
+statement. It is defined as:
+.in +5
+typedef struct grecs_value {
+ int type;
+ union {
+ struct grecs_list *list;
+ const char *string;
+ struct {
+ size_t c;
+ struct grecs_value *v;
+ } arg;
+ } v;
+} grecs_value_t;
+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:
+Actual string value is pointed to by \fBv.string\fR.
+The list value is pointed to by \fBv.list\fR.
+The array itself is stored in \fBv.arg.v\fR. The \fBv.arg.c\fR member
+contains the number of elements in the array.
+On success, a pointer to the root node. On error, \fBNULL\fR.
+The following program parses the file and prints its contents on
+.in +5
+main(int argc, char **argv)
+ struct grecs_node *tree, *node;
+ tree = grecs_parse(argv[1]);
+ for (node = tree; node; node = node->next) {
+ grecs_format_node(node, GRECS_NODE_FLAG_DEFAULT, stdout);
+ fputc('\n', stdout);
+ }
+ grecs_tree_free(tree);
+ exit(0);
+.BR grecs_config (5),
+.BR grecs_error (3),
+.BR grecs_format_node (3),
+.BR grecs_tree_free (3).
+Sergey Poznyakoff
+Report bugs to <gray+grecs@gnu.org.ua>.
+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>.
+Copyright \(co 2011 Sergey Poznyakoff
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+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.