summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPatrick McDermott <patrick.mcdermott@libiquity.com>2018-12-28 23:02:38 (EST)
committer Patrick McDermott <patrick.mcdermott@libiquity.com>2018-12-28 23:02:38 (EST)
commit31ba10dc5950fa1be5df0805aea2a24fc8685420 (patch)
treea8e482dcd233f9d7d1ece07e56128b53e0fe30a6
parent62a6fcf474376024094664db30b075c4a9d71161 (diff)
ob_parse_control(): Document
-rw-r--r--lib/control.sh23
-rw-r--r--man/local.mk1
2 files changed, 24 insertions, 0 deletions
diff --git a/lib/control.sh b/lib/control.sh
index fd07bed..fcb649f 100644
--- a/lib/control.sh
+++ b/lib/control.sh
@@ -51,6 +51,29 @@ _ob_parse_control_error()
return 0
}
+## @brief Parse a control file
+## @details \fBob_parse_control\fP parses a control file of field names and
+## values formatted like RFC 822 (or RFC 2822 or RFC 5322) headers.
+## For each field, \fBob_parse_control\fP calls \fIfield_cb\fP after
+## setting \fIOB_CONTROL_NAME\fP to the field name and
+## \fIOB_CONTROL_VALUE\fP to the field value. If \fIreq_fields\fP and
+## \fIopt_fields\fP are given, \fBob_parse_control\fP verifies that the
+## input control file contains all fields listed in \fIreq_fields\fP
+## and no fields that are listed in neither \fIreq_fields\fP nor
+## \fIopt_fields\fP. If \fIfield_cb\fP returns non-zero,
+## \fBob_parse_control\fP stops parsing and immediately returns,
+## without verifying that all required fields were found.
+## @operand file req The control file to parse, or "-" for standard input.
+## @operand field_cb req Callback to run for each field.
+## @operand req_fields opt Required fields that must appear in the control file.
+## @operand opt_fields opt Optional fields that may appear in the control file.
+## @return Returns 0 after parsing, or 125 if called with an incorrect number of
+## arguments.
+## @stderr Prints error messages on parse errors.
+## @pure maybe This function sets global variables, but they're only intended
+## for use by \fIfield_cb\fP, which is called during the lifetime of
+## this function. Whether this function is subshell-safe in
+## practice depends on whether \fIfield_cb\fP is subshell-safe.
ob_parse_control()
{
local file=
diff --git a/man/local.mk b/man/local.mk
index 9dc5252..2cb3565 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -35,6 +35,7 @@ man3_MANS = \
%reldir%/ob_get_text_domain.3 \
%reldir%/ob_info.3 \
%reldir%/ob_parse_changelog.3 \
+ %reldir%/ob_parse_control.3 \
%reldir%/ob_parse_dep.3 \
%reldir%/ob_reduce_deps.3 \
%reldir%/ob_set_text_domain.3 \