summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2011-05-19 06:49:20 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2011-05-19 06:49:20 (GMT)
commit304935a296997c9781688f08693ef70180dd24e4 (patch) (side-by-side diff)
tree7b7801f3a97a780af1719826b2b9ef471151a352 /doc
parent6ef143bd53c35635b6d7edc6410d45fa58f54da2 (diff)
downloadgrecs-304935a296997c9781688f08693ef70180dd24e4.tar.gz
grecs-304935a296997c9781688f08693ef70180dd24e4.tar.bz2
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.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/grecs_format_locus.350
-rw-r--r--doc/grecs_format_node.333
-rw-r--r--doc/grecs_format_node_path.323
-rw-r--r--doc/grecs_format_value.326
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" ", "
+.ti +17
+.BI "struct grecs_format_closure " "*clos" );
+.sp
+.BI "void grecs_print_value(struct grecs_value *" "val" ", int " \
"flags" ", FILE " "*fp" );
.SH DESCRIPTION
-\fBgrecs_format_value\fR formats and outputs to the file \fBfp\fR the
-value \fIval\fR. The \fIflags\fR argument describes how to format the
-value. See
+\fBgrecs_format_value\fR formats the value \fIval\fR and outputs it
+using the formatting closure \fIclos\fR. The \fIflags\fR argument
+describes how to format the value. See
.BR grecs_format_node (3),
for a discussion of available flags.
+.PP
+\fBgrecs_print_value\fR is an alternative interface that outputs the
+formatted data to a file.
.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).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"

Return to:

Send suggestions and report system problems to the System administrator.