diff options
Diffstat (limited to 'doc/argot_parse.3')
-rw-r--r-- | doc/argot_parse.3 | 199 |
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: + |