Reimplement grecs_format_ familiy as output-independent functions.

* src/format.c (grecs_format_docstring): Rename to grecs_print_docstring.
(grecs_format_simple_statement): Rename to grecs_print_simple_statement.
(grecs_format_block_statement): Rename to grecs_print_block_statement.
(grecs_format_statement_array): Rename to grecs_print_statement_array.
(grecs_format_locus): Rename to grecs_print_locus.
(grecs_format_node_path): Rename to grecs_print_node_path.
(grecs_format_value): Rename to grecs_print_value.
(grecs_format_node): Rename to grecs_print_node.
(grecs_format_locus,grecs_format_node_path)
(grecs_format_value,grecs_format_node): Reimplement as
output-independent functions.
All uses changed.
* src/grecs.h: Update prototypes.
* doc/grecs_format_locus.3: Update.
* doc/grecs_format_node.3: Update.
* doc/grecs_format_node_path.3: Update.
* doc/grecs_format_value.3: Update.

4 files changed, 104 insertions, 28 deletions

diff --git a/doc/grecs_format_locus.3 b/doc/grecs_format_locus.3
index a7743f1..83c9c0b 100644
--- a/doc/grecs_format_locus.3
+++ b/doc/grecs_format_locus.3
@@ -14,31 +14,59 @@
 .\" 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_LOCUS 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.TH GRECS_FORMAT_LOCUS 3 "May 19, 2011" "GRECS" "Grecs User Reference"
 .SH NAME
 grecs_format_locus \- format and output source file location
 .SH SYNOPSIS
 .nf
 .B #include <grecs.h>
 .sp
-.BI "void grecs_format_locus(grecs_locus_t " "*locus" ", FILE " "*fp" );
+.BI "void grecs_format_locus(grecs_locus_t " "*locus" ","
+.ti +17
+.BI  "struct grecs_format_closure " "*clos" );
+.sp
+.BI "void grecs_print_locus(grecs_locus_t " "*locus" ", FILE " "*fp" );
+
 .SH DESCRIPTION
-\fBgrecs_format_locus\fR formats the location from \fIlocus\fR in the
-human-readable form and outputs it to file \fBfp\fR.
+\fBgrecs_print_locus\fR formats the location from \fIlocus\fR in the
+human-readable form and outputs it using the format closure
+\fIclos\fR. The closure is defined as:
+.sp
+.nf
+.in +5
+struct grecs_format_closure
+{
+        int (*fmtfun)(const char *str, void *data);
+        void *data;
+};
+.in
+.fi
 .PP
-The location is output as follows: the file name, followed by a
-semicolon, followed by the line number.
+While formatting the location, 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.
 .PP
-If \fIlocus\fR is \fBNULL\fR, \fBgrecs_format_locus\fR returns without
+\fBgrecs_print_locus\fR is an alternative interface, which formats the
+location from \fIlocus\fR in the human-readable form and outputs it to
+file \fBfp\fR.
+.PP
+In both cases, the location is formatted as follows: the file name,
+followed by a semicolon, followed by the line number.
+.PP
+If \fIlocus\fR is \fBNULL\fR, both functions return without
 doing anything.
 .SH "RETURN VALUE"
 None.
 .SH NOTES
-This is an auxiliary function used by
-.BR grecs_format_node (3).
-It is seldom needed in user programs.
-.SH "SEE ALSO"
+This are auxiliary functions used by
 .BR grecs_format_node (3)
+and
+.BR grecs_print_node (3),
+correspondingly. They are is seldom needed in user programs.
+.SH "SEE ALSO"
+.BR grecs_format_node (3),
+.BR grecs_print_node (3).
 .SH AUTHORS
 Sergey Poznyakoff
 .SH "BUG REPORTS"
diff --git a/doc/grecs_format_node.3 b/doc/grecs_format_node.3
index 095a494..dd87ca7 100644
--- a/doc/grecs_format_node.3
+++ b/doc/grecs_format_node.3
@@ -14,7 +14,7 @@
 .\" 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 4, 2011" "GRECS" "Grecs User Reference"
+.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
@@ -22,11 +22,19 @@ grecs_format_node \- format and print a single node from a syntax tree
 .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 prints to the output file \fBfp\fR the
-contents of a parse tree node \fBnode\fR, according to formatting
-options, given by \fBflags\fR.
+\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:
@@ -72,6 +80,23 @@ Same as
 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"
diff --git a/doc/grecs_format_node_path.3 b/doc/grecs_format_node_path.3
index bf119e7..ed687db 100644
--- a/doc/grecs_format_node_path.3
+++ b/doc/grecs_format_node_path.3
@@ -14,7 +14,7 @@
 .\" 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_PATH 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.TH GRECS_FORMAT_NODE_PATH 3 "May 19, 2011" "GRECS" "Grecs User Reference"
 .SH NAME
 grecs_format_node_path \- format and output statement pathname for the
 node
@@ -23,10 +23,21 @@ node
 .B #include <grecs.h>
 .sp
 .BI "void grecs_format_node_path(struct grecs_node " "*node" ", int " \
+  "flag" ", "
+.ti +17
+.BI  "struct grecs_format_closure " "*clos" );
+.sp
+.BI "void grecs_print_node_path(struct grecs_node " "*node" ", int " \
   "flag" ", FILE " "*fp" );
 .SH DESCRIPTION
 \fBgrecs_format_node_path\fR computes the \fIstatement pathname\fR for
-the \fInode\fR, and outputs it to the file \fBfp\fR.
+the \fInode\fR, and outputs it using the closure \fIclos\fR.  See
+section \fBCLOSURE\fR in
+.BR grecs_format_node (3),
+for a description of struct grecs_format_closure.
+.PP
+\fBgrecs_print_node_path\fR is an alternative interface that outputs
+the formatted data to the file.
 .PP
 The \fIflags\fR argument describes what character to use as a pathname
 component separator and how to format the statement tag, if \fInode\fR
@@ -36,9 +47,11 @@ for a discussion of available flags.
 .SH "RETURN VALUE"
 None.
 .SH NOTES
-This is an auxiliary function used by
-.BR grecs_format_node (3).
-It is seldom needed in user programs.
+This are auxiliary functions used by
+.BR grecs_format_node (3)
+and
+.BR grecs_print_node (3),
+correspondingly. They are is seldom needed in user programs.
 .SH "SEE ALSO"
 .BR grecs_format_node (3),
 .BR grecs_stmt_path (5).
diff --git a/doc/grecs_format_value.3 b/doc/grecs_format_value.3
index e4b45fa..918e972 100644
--- a/doc/grecs_format_value.3
+++ b/doc/grecs_format_value.3
@@ -14,7 +14,7 @@
 .\" 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_VALUE 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.TH GRECS_FORMAT_VALUE 3 "May 19, 2011" "GRECS" "Grecs User Reference"
 .SH NAME
 grecs_format_value \- format and output a configuration value
 .SH SYNOPSIS
@@ -22,21 +22,31 @@ grecs_format_value \- format and output a configuration value
 .B #include <grecs.h>
 .sp
 .BI "void grecs_format_value(struct grecs_value *" "val" ", int " \
+  "flags" ", "