From 9816160ca4462ccd6c1d4cd00f4f6c7f4c2d2831 Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@kth.se>
Date: Sun, 18 Apr 2021 07:29:45 +0200
Subject: Add libparser_parse_file.3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <maandree@kth.se>
---
 Makefile               |   3 ++
 libparser_parse_file.3 | 116 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 libparser_parse_file.3

diff --git a/Makefile b/Makefile
index 35b94e2..b3b672e 100644
--- a/Makefile
+++ b/Makefile
@@ -48,6 +48,7 @@ install: libparser.a libparser.$(LIBEXT) libparser-generate
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/lib"
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/include"
 	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man1/"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3/"
 	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7/"
 	cp -- libparser-generate "$(DESTDIR)$(PREFIX)/bin"
 	cp -- libparser.a "$(DESTDIR)$(PREFIX)/lib"
@@ -56,6 +57,7 @@ install: libparser.a libparser.$(LIBEXT) libparser-generate
 	ln -sf -- libparser.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libparser.$(LIBEXT)"
 	cp -- libparser.h "$(DESTDIR)$(PREFIX)/include"
 	cp -- libparser-generate.1 "$(DESTDIR)$(MANPREFIX)/man1/"
+	cp -- libparser_parse_file.3 "$(DESTDIR)$(MANPREFIX)/man3/"
 	cp -- libparser.7 "$(DESTDIR)$(MANPREFIX)/man7/"
 
 uninstall:
@@ -66,6 +68,7 @@ uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparser.$(LIBEXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/include/libparser.h"
 	-rm -f -- "$(DESTDIR)$(MANPREFIX)/man1/libparser-generate.1"
+	-rm -f -- "$(DESTDIR)$(MANPREFIX)/man3/libparser_parse_file.3"
 	-rm -f -- "$(DESTDIR)$(MANPREFIX)/man7/libparser.7"
 
 clean:
diff --git a/libparser_parse_file.3 b/libparser_parse_file.3
new file mode 100644
index 0000000..0f9b6e4
--- /dev/null
+++ b/libparser_parse_file.3
@@ -0,0 +1,116 @@
+.TH LIBPARSER_PARSE_FILE 3 LIBPARSER
+.SH NAME
+libparser_parse_file \- Parse input with libparser
+
+.SH SYNPOSIS
+.nf
+#include <libparser.h>
+
+struct libparser_unit {
+	const char *\fIrule\fP;
+	struct libparser_unit *\fIin\fP;
+	struct libparser_unit *\fInext\fP;
+	size_t \fIstart\fP;
+	size_t \fIend\fP;
+};
+
+extern const struct libparser_rule *const \fIlibparser_rule_table\fP[];
+
+int libparser_parse_file(const struct libparser_rule *const \fIrules\fP[],
+                         const char *\fIdata\fP, size_t \fIlength\fP,
+                         struct libparser_unit **\fIrootp\fP);
+.fi
+.PP
+Link with
+.IR \-lparser .
+
+.SH DESCRIPTION
+The
+.BR libparser_parse_file ()
+function parses the input given in the
+.I data
+parameter according to the grammar of the
+.B @start
+rule specified in the rule table specified in the
+.I rules
+parameter, which should be
+.I libparser_rule_table
+(see
+.BR libparser-generate (1)
+for more information.
+.PP
+The
+.I length
+argument shall specify the byte length of
+the input
+.IR data .
+.PP
+The resulting parse tree output, on success
+completion to
+.IR *rootp ,
+which must be manually and recursively deallocated
+with the
+.BR free (3)
+function when it is no longer need.
+.PP
+.IR *rootp->in
+will point to the result of the main rule as
+specified in when the
+.BR libparser-generate (1)
+utility was ran, and
+.IR *rootp->in->next
+will either point to
+.B @eof
+or
+.BR @noeof .
+.IR *rootp->next
+will be
+.IR NULL .
+For each node in the parsing tree,
+.I rule
+with be non-NULL, will not begin with an underscore
+.RB ( _ ),
+and will name the rule that the input matched in
+the node
+.RB ( \(dq@start\(dq
+for
+.IR *rootp ).
+.I start
+and
+.I end
+will pointer index of the first byte and the index
+one byte past the last byte in the input that matched
+to the rule for the node.
+.I in
+will point to the first closest descent from the node
+in the parse tree
+.RI ( NULL
+if none; rules starting with an underscore
+.RB ( _ )
+are ignored), and
+.I next
+will point to the node's next sibling in the parse tree
+.RI ( NULL
+if the node is its parents last closest descent).
+
+.SH RETURN VALUE
+The
+.BR libparser_parse_file ()
+function returns 1 or 0 upon successful completion;
+otherwise it returns -1 and sets
+.I errno
+to indicate the error. The return upon successful
+completion is normally 1, but is 0 if the parsing
+stopped at an exception mark
+.RB ( - ).
+
+.SH ERRORS
+The
+.BR libparser_parse_file ()
+function may fail for any reason specified for the
+.BR calloc (3)
+function.
+
+.SH SEE ALSO
+.BR libparser (7),
+.BR libparser-generate (1)
-- 
cgit v1.2.3-70-g09d2