1 .\" Copyright (c) 2013-2014 Devin Teske <dteske@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .Nd configuration file parsing library
41 .Fa "struct fp_config options[], const char *path"
42 .Fa "int \*[lp]*unknown\*[rp]\*[lp]struct fp_config *option, uint32_t line"
43 .Fa "char *directive, char *value\*[rp], uint8_t processing_options"
45 .Ft "struct fp_config *"
47 .Fa "struct fp_config options[], const char *directive"
52 .Fa "char *source, const char *find, const char *replace"
56 .Fa "const char *source, const char *find"
73 library provides a light-weight, portable framework for parsing configuration
80 within the file pointed to by
82 to find directives and values which are then made available to the application.
84 Due to the fact that configuration files may have basic syntax differences,
85 the library does not attempt to impose any structure on the data but instead
86 provides raw data to a set of callback functions.
87 These callback functions can in-turn initiate abort through their return value,
88 allowing custom syntax validation during parsing.
90 Configuration directives, types, and callback functions are provided through
91 data structures defined in
93 .Bd -literal -offset indent
95 enum fp_cfgtype type; /* value type */
96 const char *directive; /* keyword */
97 union fp_cfgvalue value; /* value */
99 /* Pointer to function used when directive is found */
100 int (*action)(struct fp_config *option, uint32_t line,
101 char *directive, char *value);
105 FP_TYPE_NONE = 0x0000, /* for directives with no value */
106 FP_TYPE_BOOL = 0x0001, /* boolean */
107 FP_TYPE_INT = 0x0002, /* signed 32 bit integer */
108 FP_TYPE_UINT = 0x0004, /* unsigned 32 bit integer */
109 FP_TYPE_STR = 0x0008, /* string pointer */
110 FP_TYPE_STRARRAY = 0x0010, /* string array pointer */
111 FP_TYPE_DATA1 = 0x0020, /* void data type-1 (whatever) */
112 FP_TYPE_DATA2 = 0x0040, /* void data type-2 (whatever) */
113 FP_TYPE_DATA3 = 0x0080, /* void data type-3 (whatever) */
114 FP_TYPE_RESERVED1 = 0x0100, /* reserved data type-1 (future) */
115 FP_TYPE_RESERVED2 = 0x0200, /* reserved data type-2 (future) */
116 FP_TYPE_RESERVED3 = 0x0400, /* reserved data type-3 (future) */
120 void *data; /* Pointer to NUL-terminated string */
121 char *str; /* Pointer to NUL-terminated string */
122 char **strarray; /* Pointer to an array of strings */
123 int32_t num; /* Signed 32-bit integer value */
124 uint32_t u_num; /* Unsigned 32-bit integer value */
125 uint32_t boolean:1; /* Boolean integer value (0 or 1) */
130 .Fa processing_options
133 is a mask of bit fields which indicate various
135 The possible flags are as follows:
136 .Bl -tag -width FP_BREAK_ON_SEMICOLON
137 .It Dv FP_BREAK_ON_EQUALS
140 is normally considered part of the directive.
141 This flag enables terminating the directive at the equals sign.
142 Also makes equals sign optional and transient.
143 .It Dv FP_BREAK_ON_SEMICOLON
146 is normally considered part of the value.
147 This flag enables terminating the value at the semicolon.
148 Also allows multiple statements on a single line separated by semicolon.
149 .It Dv FP_CASE_SENSITIVE
150 Normally directives are matched case insensitively using
152 This flag enables directive matching to be case sensitive.
153 .It Dv FP_REQUIRE_EQUALS
154 If a directive is not followed by an equals, processing is aborted.
155 .It Dv FP_STRICT_EQUALS
156 Equals must be part of the directive to be considered a delimiter between
162 struct array pointer can be NULL and every directive will invoke the
166 The directive for each fp_config item in the
168 options argument is matched against each parsed directive using
170 until a match is found.
171 If a match is found, the
173 function for that fp_config directive is invoked with the line number,
174 directive, and value.
175 Otherwise if no match, the
178 .Pq with the same arguments .
186 aborts reading the file and returns the error value to its caller.
188 .Fn get_config_option
189 traverses the options-array and returns the option that matches via
191 or if no match a pointer to a static dummy struct is returned
192 .Pq whose values are all zero or NULL .
195 .Fa "struct fp_config"
196 is entirely optional as-is the use of
197 .Fa "enum fp_cfgtype"
199 .Fa "union fp_cfgvalue" .
200 For example, you could choose to pass a NULL pointer to
202 for the first argument and then provide a simple
206 that populates a singly-linked list of your own struct containing the
211 In addition, the following miscellaneous string manipulation routines are
214 .Bl -tag -width strexpandnl()
216 Replace all occurrences of
223 Count the number of occurrences of one string that appear in the
226 Return value is the total count.
227 An example use would be if you need to know how large a block of memory needs
232 Expand escape sequences in a buffer pointed to by
235 Expand only the escaped newlines in a buffer pointed to by
238 Convert a string to lower case.
245 library first appeared in
248 .An Devin Teske Aq dteske@FreeBSD.org
250 This is the first implementation of the library,
251 and the interface may be subject to refinement.