| figpar.3 (289794) | figpar.3 (290275) |
|---|---|
| 1.\" Copyright (c) 2013-2015 Devin Teske <dteske@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 8 unchanged lines hidden (view full) --- 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 23.\" SUCH DAMAGE. 24.\" | 1.\" Copyright (c) 2013-2015 Devin Teske <dteske@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 8 unchanged lines hidden (view full) --- 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 23.\" SUCH DAMAGE. 24.\" |
| 25.\" $FreeBSD: head/lib/libfigpar/figpar.3 289794 2015-10-23 07:37:27Z dteske $ | 25.\" $FreeBSD: head/lib/libfigpar/figpar.3 290275 2015-11-02 20:03:59Z dteske $ |
| 26.\" | 26.\" |
| 27.Dd Oct 22, 2015 | 27.Dd Nov 2, 2015 |
| 28.Dt FIGPAR 3 29.Os 30.Sh NAME 31.Nm figpar , 32.Nm parse_config , 33.Nm get_config_option 34.Nd configuration file parsing library 35.Sh LIBRARY 36.Lb libfigpar 37.Sh SYNOPSIS 38.In figpar.h 39.Ft int 40.Fo parse_config | 28.Dt FIGPAR 3 29.Os 30.Sh NAME 31.Nm figpar , 32.Nm parse_config , 33.Nm get_config_option 34.Nd configuration file parsing library 35.Sh LIBRARY 36.Lb libfigpar 37.Sh SYNOPSIS 38.In figpar.h 39.Ft int 40.Fo parse_config |
| 41.Fa "struct fp_config options[], const char *path" 42.Fa "int \*[lp]*unknown\*[rp]\*[lp]struct fp_config *option, uint32_t line" | 41.Fa "struct figpar_config options[], const char *path" 42.Fa "int \*[lp]*unknown\*[rp]\*[lp]struct figpar_config *option, uint32_t line" |
| 43.Fa "char *directive, char *value\*[rp], uint8_t processing_options" 44.Fc | 43.Fa "char *directive, char *value\*[rp], uint8_t processing_options" 44.Fc |
| 45.Ft "struct fp_config *" | 45.Ft "struct figpar_config *" |
| 46.Fo get_config_option | 46.Fo get_config_option |
| 47.Fa "struct fp_config options[], const char *directive" | 47.Fa "struct figpar_config options[], const char *directive" |
| 48.Fc 49.In string_m.h 50.Ft int 51.Fo replaceall 52.Fa "char *source, const char *find, const char *replace" 53.Fc 54.Ft unsigned int 55.Fo strcount --- 30 unchanged lines hidden (view full) --- 86provides raw data to a set of callback functions. 87These callback functions can in-turn initiate abort through their return value, 88allowing custom syntax validation during parsing. 89.Pp 90Configuration directives, types, and callback functions are provided through 91data structures defined in 92.In figpar.h : 93.Bd -literal -offset indent | 48.Fc 49.In string_m.h 50.Ft int 51.Fo replaceall 52.Fa "char *source, const char *find, const char *replace" 53.Fc 54.Ft unsigned int 55.Fo strcount --- 30 unchanged lines hidden (view full) --- 86provides raw data to a set of callback functions. 87These callback functions can in-turn initiate abort through their return value, 88allowing custom syntax validation during parsing. 89.Pp 90Configuration directives, types, and callback functions are provided through 91data structures defined in 92.In figpar.h : 93.Bd -literal -offset indent |
| 94struct fp_config { 95 enum fp_cfgtype type; /* value type */ 96 const char *directive; /* keyword */ 97 union fp_cfgvalue value; /* value */ | 94struct figpar_config { 95 enum figpar_cfgtype type; /* value type */ 96 const char *directive; /* keyword */ 97 union figpar_cfgvalue value; /* value */ |
| 98 99 /* Pointer to function used when directive is found */ | 98 99 /* Pointer to function used when directive is found */ |
| 100 int (*action)(struct fp_config *option, uint32_t line, | 100 int (*action)(struct figpar_config *option, uint32_t line, |
| 101 char *directive, char *value); 102}; 103 | 101 char *directive, char *value); 102}; 103 |
| 104enum fp_cfgtype { 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) */ | 104enum figpar_cfgtype { 105 FIGPAR_TYPE_NONE = 0x0000, /* directives with no value */ 106 FIGPAR_TYPE_BOOL = 0x0001, /* boolean */ 107 FIGPAR_TYPE_INT = 0x0002, /* signed 32 bit integer */ 108 FIGPAR_TYPE_UINT = 0x0004, /* unsigned 32 bit integer */ 109 FIGPAR_TYPE_STR = 0x0008, /* string pointer */ 110 FIGPAR_TYPE_STRARRAY = 0x0010, /* string array pointer */ 111 FIGPAR_TYPE_DATA1 = 0x0020, /* void data type-1 (open) */ 112 FIGPAR_TYPE_DATA2 = 0x0040, /* void data type-2 (open) */ 113 FIGPAR_TYPE_DATA3 = 0x0080, /* void data type-3 (open) */ 114 FIGPAR_TYPE_RESERVED1 = 0x0100, /* reserved data type-1 */ 115 FIGPAR_TYPE_RESERVED2 = 0x0200, /* reserved data type-2 */ 116 FIGPAR_TYPE_RESERVED3 = 0x0400, /* reserved data type-3 */ |
| 117}; 118 | 117}; 118 |
| 119union fp_cfgvalue { | 119union figpar_cfgvalue { |
| 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) */ 126}; 127.Ed 128.Pp 129The 130.Fa processing_options 131argument to 132.Fn parse_config 133is a mask of bit fields which indicate various 134processing options. 135The possible flags are as follows: | 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) */ 126}; 127.Ed 128.Pp 129The 130.Fa processing_options 131argument to 132.Fn parse_config 133is a mask of bit fields which indicate various 134processing options. 135The possible flags are as follows: |
| 136.Bl -tag -width FP_BREAK_ON_SEMICOLON 137.It Dv FP_BREAK_ON_EQUALS | 136.Bl -tag -width FIGPAR_BREAK_ON_SEMICOLON 137.It Dv FIGPAR_BREAK_ON_EQUALS |
| 138An equals sign 139.Pq Ql Li = 140is normally considered part of the directive. 141This flag enables terminating the directive at the equals sign. 142Also makes equals sign optional and transient. | 138An equals sign 139.Pq Ql Li = 140is normally considered part of the directive. 141This flag enables terminating the directive at the equals sign. 142Also makes equals sign optional and transient. |
| 143.It Dv FP_BREAK_ON_SEMICOLON | 143.It Dv FIGPAR_BREAK_ON_SEMICOLON |
| 144A semicolon 145.Pq Ql Li \; 146is normally considered part of the value. 147This flag enables terminating the value at the semicolon. 148Also allows multiple statements on a single line separated by semicolon. | 144A semicolon 145.Pq Ql Li \; 146is normally considered part of the value. 147This flag enables terminating the value at the semicolon. 148Also allows multiple statements on a single line separated by semicolon. |
| 149.It Dv FP_CASE_SENSITIVE | 149.It Dv FIGPAR_CASE_SENSITIVE |
| 150Normally directives are matched case insensitively using 151.Xr fnmatch 3 . 152This flag enables directive matching to be case sensitive. | 150Normally directives are matched case insensitively using 151.Xr fnmatch 3 . 152This flag enables directive matching to be case sensitive. |
| 153.It Dv FP_REQUIRE_EQUALS | 153.It Dv FIGPAR_REQUIRE_EQUALS |
| 154If a directive is not followed by an equals, processing is aborted. | 154If a directive is not followed by an equals, processing is aborted. |
| 155.It Dv FP_STRICT_EQUALS | 155.It Dv FIGPAR_STRICT_EQUALS |
| 156Equals must be part of the directive to be considered a delimiter between 157directive and value. 158.El 159.Pp 160The 161.Fa options 162struct array pointer can be NULL and every directive will invoke the 163.Fn unknown 164function argument. 165.Pp | 156Equals must be part of the directive to be considered a delimiter between 157directive and value. 158.El 159.Pp 160The 161.Fa options 162struct array pointer can be NULL and every directive will invoke the 163.Fn unknown 164function argument. 165.Pp |
| 166The directive for each fp_config item in the | 166The directive for each figpar_config item in the |
| 167.Fn parse_config 168options argument is matched against each parsed directive using 169.Xr fnmatch 3 170until a match is found. 171If a match is found, the 172.Fn action | 167.Fn parse_config 168options argument is matched against each parsed directive using 169.Xr fnmatch 3 170until a match is found. 171If a match is found, the 172.Fn action |
| 173function for that fp_config directive is invoked with the line number, | 173function for that figpar_config directive is invoked with the line number, |
| 174directive, and value. 175Otherwise if no match, the 176.Fn unknown 177function is invoked 178.Pq with the same arguments . 179.Pp 180If either 181.Fa action --- 5 unchanged lines hidden (view full) --- 187.Pp 188.Fn get_config_option 189traverses the options-array and returns the option that matches via 190.Xr strcmp 3 , 191or if no match a pointer to a static dummy struct is returned 192.Pq whose values are all zero or NULL . 193.Pp 194The use of | 174directive, and value. 175Otherwise if no match, the 176.Fn unknown 177function is invoked 178.Pq with the same arguments . 179.Pp 180If either 181.Fa action --- 5 unchanged lines hidden (view full) --- 187.Pp 188.Fn get_config_option 189traverses the options-array and returns the option that matches via 190.Xr strcmp 3 , 191or if no match a pointer to a static dummy struct is returned 192.Pq whose values are all zero or NULL . 193.Pp 194The use of |
| 195.Fa "struct fp_config" | 195.Fa "struct figpar_config" |
| 196is entirely optional as-is the use of | 196is entirely optional as-is the use of |
| 197.Fa "enum fp_cfgtype" | 197.Fa "enum figpar_cfgtype" |
| 198or | 198or |
| 199.Fa "union fp_cfgvalue" . | 199.Fa "union figpar_cfgvalue" . |
| 200For example, you could choose to pass a NULL pointer to 201.Fn parse_config 202for the first argument and then provide a simple 203.Fa unknown 204function based on 205.Xr queue 3 206that populates a singly-linked list of your own struct containing the 207.Fa directive --- 44 unchanged lines hidden --- | 200For example, you could choose to pass a NULL pointer to 201.Fn parse_config 202for the first argument and then provide a simple 203.Fa unknown 204function based on 205.Xr queue 3 206that populates a singly-linked list of your own struct containing the 207.Fa directive --- 44 unchanged lines hidden --- |