.\" This file is part of grecs -*- nroff -*-
.\" Copyright (C) 2007-2022 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_FORMAT_NODE 3 "May 19, 2011" "GRECS" "Grecs User Reference"
.SH NAME
grecs_format_node \- format and print a single node from a syntax tree
.SH SYNOPSIS
.nf
.B #include <grecs.h>
.sp
.BI "void grecs_format_node(struct grecs_node *" "node" ", int " \
 "flags" ","
.ti +17
.BI  "struct grecs_format_closure " "*clos" );
.sp
.BI "void grecs_print_node(struct grecs_node *" "node" ", int " \
 "flags" ", FILE " "*fp" );
.SH DESCRIPTION
\fBgrecs_format_node\fR formats the contents of a parse tree node
\fInode\fR, according to formatting options, given by \fIflags\fR. The
formatter closure \fIclos\fR is used for actual output.
.PP
\fBgrecs_print_node\fR is an alternative entry point, which formats
the node to the given file.
.PP
The \fBflags\fR argument is a bitwise \fBOR\fR of one or more of the
following options:
.TP
.I (a punctuation character)
This character will be used as pathname component separator, instead
of the default dot.
.TP
.B GRECS_NODE_FLAG_LOCUS
Print the source location. The location is printed as the file name,
followed by a semicolon, followed by the line number and another
semicolon. Locations are separated from the rest of output by a single
space character.
.TP
.B GRECS_NODE_FLAG_PATH
Print the \fInode path\fR.  See
.BR grecs_stmt_path (5),
for a description.  If printed, the path is separated from the
remaining output on its right by a semicolon and a space.
.TP
.B GRECS_NODE_FLAG_VALUE
Print the node value.
.TP
.B GRECS_NODE_FLAG_QUOTE
Always quote the value.  By default, the value will be quoted only
when necessary, i.e. if it contains white space, quotes or special
characters.  This option is useful only together with
\fBGRECS_NODE_FLAG_VALUE\fR.
.TP
.B GRECS_NODE_FLAG_NOQUOTE
Never quote values. If both \fBGRECS_NODE_FLAG_QUOTE\fR and
\fBGRECS_NODE_FLAG_NOQUOTE\fR are given, the former takes precedence
over the latter.
.TP
.B GRECS_NODE_FLAG_QUOTE_HEX
Print non-printable characters as C hex escapets.  This option is
ignored if \fBGRECS_NODE_FLAG_NOQUOTE\fR is set.
.TP
.B GRECS_NODE_FLAG_DEFAULT
Same as
.sp
.nf
GRECS_NODE_FLAG_PATH|GRECS_NODE_FLAG_VALUE|GRECS_NODE_FLAG_QUOTE
.PP
If \fBflag\fR is 0, \fBGRECS_NODE_FLAG_DEFAULT\fR is assumed.
.SH CLOSURE
The format closure is defined as:
.sp
.nf
.in +5
struct grecs_format_closure
{
	int (*fmtfun)(const char *str, void *data);
	void *data;
};
.in
.fi
.PP
While formatting the node, the formatter function \fBfmtfun\fR can
be called one or more times. On each invocation, it is supplied with
the string to be output as its first argument, and pointer to
\fBdata\fR as the second one.
.SH "RETURN VALUE"
None.
.SH "SEE ALSO"
.BR grecs_config (5),
.BR grecs_stmt_path (5).
.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: