aboutsummaryrefslogtreecommitdiff
path: root/doc/argot_parse.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/argot_parse.3')
-rw-r--r--doc/argot_parse.3199
1 files changed, 199 insertions, 0 deletions
diff --git a/doc/argot_parse.3 b/doc/argot_parse.3
new file mode 100644
index 0000000..4db155c
--- /dev/null
+++ b/doc/argot_parse.3
@@ -0,0 +1,199 @@
+.\" This file is part of argot -*- nroff -*-
+.\" Copyright (C) 2007-2016 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 ARGOT_PARSE 3 "July 1, 2011" "ARGOT" "Grecs User Reference"
+.SH NAME
+argot_parse \- parse a configuration file.
+.SH SYNOPSIS
+.nf
+.B #include <argot.h>
+.sp
+.BI "struct argot_node *argot_parse(const char *" "name" );
+.SH DESCRIPTION
+The
+.BR argot_parse ()
+function reads the file \fBname\fR, which must be formatted
+according to
+.BR argot_config (5)
+and returns the parsed-out syntax tree. On errors, \fBNULL\fR is
+returned and appropriate diagnostic messages are printed using
+.BR argot_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 argot_node {
+ enum argot_node_type type;
+ argot_locus_t locus;
+ struct argot_node *up;
+ struct argot_node *down;
+ struct argot_node *next;
+ struct argot_node *prev;
+ char *ident;
+ argot_locus_t idloc;
+ union {
+ struct argot_value *value;
+ struct argot_symtab *texttab;
+ } v;
+} argot_node_t;
+.in
+.fi
+.PP
+The \fItype\fR member describes the type of this node. Its value is
+\fBargot_node_stmt\fR for simple statements and
+\fBargot_node_block\fR, for block statements. The topmost node (the
+one returned by \fBargot_tree_parse\fR) has type \fBargot_node_root\fR.
+.PP
+The \fIlocus\fR describes the location in the input file, which this
+node described. See
+.BR argot_error (3),
+for a description of \fBargot_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 \fBargot_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
+\fBargot_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 argot_value {
+ int type;
+ argot_locus_t locus;
+ union {
+ struct argot_list *list;
+ char *string;
+ struct {
+ size_t c;
+ struct argot_value **v;
+ } arg;
+ } v;
+} argot_value_t;
+.in
+.fi
+.PP
+The \fBtype\fR will be \fBARGOT_TYPE_STRING\fR, for string values,
+\fBARGOT_TYPE_LIST\fR, for list values, and \fBARGOT_TYPE_ARRAY\fR,
+for arrays of values. Depending on its value, the following members
+of the union are used:
+.TP
+.B ARGOT_TYPE_STRING
+Actual string value is pointed to by \fBv.string\fR.
+.TP
+.B ARGOT_TYPE_LIST
+The list value is pointed to by \fBv.list\fR.
+.TP
+.B ARGOT_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 argot_node *tree;
+
+ tree = argot_parse(argv[1]);
+ argot_format_node(tree, ARGOT_NODE_FLAG_DEFAULT, stdout);
+ fputc('\\n', stdout);
+ argot_tree_free(tree);
+ exit(0);
+}
+.in
+.fi
+.SH "SEE ALSO"
+.BR argot_config (5),
+.BR argot_error (3),
+.BR argot_format_node (3),
+.BR argot_tree_free (3).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+argot@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/argot>.
+.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.