diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-05-04 20:10:36 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-05-04 21:41:39 +0300 |
commit | a60eb4b18345626a84e23784d77ca231812e1dff (patch) | |
tree | 80192afeadd44b073958c2762491cc7dfea778a1 /doc/grecs_parse.3 | |
parent | b65bfa7564f564f85d3c595c6c1030af2acf5056 (diff) | |
download | grecs-a60eb4b18345626a84e23784d77ca231812e1dff.tar.gz grecs-a60eb4b18345626a84e23784d77ca231812e1dff.tar.bz2 |
Improve docs. Add an option to create installable distribution.
Diffstat (limited to 'doc/grecs_parse.3')
-rw-r--r-- | doc/grecs_parse.3 | 185 |
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 +.\" 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/>. +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_PARSE 3 "May 4, 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; + struct grecs_value value; +} 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. +.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 +Finally, the \fBvalue\fR member keeps the value associated with this +statement. It is defined as: +.sp +.nf +.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; +.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. +.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, *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); +} +.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: + |