From 31ba10dc5950fa1be5df0805aea2a24fc8685420 Mon Sep 17 00:00:00 2001 From: Patrick McDermott Date: Fri, 28 Dec 2018 23:02:38 -0500 Subject: ob_parse_control(): Document --- (limited to 'lib') 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= -- cgit v0.9.1