-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathstropt.3.html
213 lines (191 loc) · 8.54 KB
/
stropt.3.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
Content-type: text/html; charset=UTF-8
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of STROPT</TITLE>
</HEAD><BODY>
<H1>STROPT</H1>
Section: C Library Functions (3)<BR>Updated: August 2022<BR><A HREF="#index">Index</A>
<A HREF="/#/man/index">Return to Main Contents</A><HR>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
stropt, stroptx, stropt2buf, stropt2str - Parse options from a string (it supports quotation, option arguments)
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>#include <<A HREF="file:///usr/include/stropt.h">stropt.h</A>></B>
<P>
<B>int stropt(const char *</B><I>input</I><B>, char **</B><I>tags</I><B>, char **</B><I>args</I><B>, char *</B><I>buf</I><B>);</B>
<P>
<B>int stroptx(const char *</B><I>input</I><B>, char *</B><I>features</I><B>, char *</B><I>sep</I><B>, int</B> <I>flags</I><B>, char **</B><I>tags</I><B>, char **</B><I>args</I><B>, char *</B><I>buf</I><B>);</B>
<P>
<B>char *stropt2buf(void *</B><I>buf</I><B>, size_t</B> <I>size</I><B>, char **</B><I>tags</I><B>, char **</B><I>args</I><B>, char</B> <I>sep</I><B>, char</B> <I>eq</I><B>);</B>
<P>
<B>char *stropt2str(char **</B><I>tags</I><B>, char **</B><I>args</I><B>, char</B> <I>sep</I><B>, char</B> <I>eq</I><B>);</B>
<A NAME="lbAD"> </A>
<H2>DESCRIPTION</H2>
This small library parses a list of options from a string. Options can be separated by spaces, commas, semicolons, tabs or new line. (e.g. <I>uppercase,bold,underlined</I> ). Options may have arguments (e.g. <I>ro,noatime,uid=0,gid=0</I> ). It is possible to protect symbols and spaces using quote, double quote and backslash (e.g. <I>values='1,2,3,4',equal=\=</I> )
<DL COMPACT>
<DT><B>stropt</B><DD>
This function parses a list of options from the string <I>input</I>. Options can be separated by commas, semicolons, tabs or new lines. Options may have arguments in the form <I>keyword=value</I>. <I>buf</I> is a temporary buffer, it must have the same size of the <I>input</I> string (including the NULL terminator). <I>tags</I> and <I>args</I> are the resulting arrays of options and arguments respectively. Both <I>tags</I> and <I>args</I> have one NULL terminator element at the end. When an option has not an argument the corresponding <I>args</I> element is NULL. For example if <I>input</I> is "font=12,typeface=bodoni,italic", <I>tags[0]</I>="font", <I>tags[1]</I>="typeface", <I>tags[2]</I>="italic", <I>tags[3]</I>=NULL, <I>args[0]</I>="12", <I>args[1]</I>="bodoni", <I>args[2]</I>=NULL, <I>args[3]</I>=NULL.
<DT><DD>
When <B>stropt</B> is called with <I>tags</I>, <I>args</I>, and <I>buf</I> set to <B>NULL</B>, it parses the input, counting the options. The return value can be used to allocate suitable arrays for <I>tags</I> and <I>args</I>.
<DT><DD>
It is possible to use the same variable as <I>input</I> and <I>buffer</I>. In this case the original value of <I>input</I> is overwritten.
<DT><B>stroptx</B><DD>
This is a more configurable extension of <B>stropt</B>. Arguments having the same names as in <B>stropt</B> have the same meaning as explained above.
<DT><DD>
The string <I>features</I> permits one to enable/disable some of the standard features. Each feature corresponds to a mnemonic character, when the character is in the <I>features</I> string the feature is enabled:
<DT><DD>
<B>'</B>: single quoting,
<DT><DD>
<B>"</B>: double quoting,
<DT><DD>
<B>\</B>: character escape,
<DT><DD>
<B>\n</B>:input in several lines,
<DT><DD>
<B>=</B>: allow arguments,
<DT><DD>
<B>#</B>: support comments.
<DT><DD>
If <I>features</I> is NULL all the features are enabled, when <I>features</I> is an empty string all features are disabled.
<DT><DD>
All the characters included in <I>sep</I> are considered as option separators. If <I>sep</I> is NULL, the default value is " \t;,".
<DT><DD>
The <I>flag</I> argument may include the bitwise OR of any of the following flag values:
<DT><DD>
<B>STROPTX_KEEP_QUOTATION_MARKS_IN_TAGS</B>: preserve the quotation marks in tags,
<DT><DD>
<B>STROPTX_KEEP_QUOTATION_MARKS_IN_ARGS</B>: preserve the quotation marks in args,
<DT><DD>
<B>STROPTX_KEEP_QUOTATION_MARKS</B>: shortcut for <B>STROPTX_KEEP_QUOTATION_MARKS_IN_TAGS | STROPTX_KEEP_QUOTATION_MARKS_IN_ARGS</B>
<DT><DD>
<B>STROPTX_ALLOW_MULTIPLE_SEP</B>: when it is not set, a sequence of separators is processed as a single separator, when it is set each sequence of two separators means an empty field in between.
<DT><DD>
<B>STROPTX_NEWLINE_TAGS</B>: when set each new line is encoded as a tag "\n".
<DT><B>stropt2buf</B><DD>
This function re-encodes an array of options (and an array of arguments) in a string. It is the inverse function of of <B>stropt</B>. Given a buffer <I>buf</I> of size <I>size</I>, the array of options <I>tags</I> with their corresponding values in the array <I>args</I> is encoded using the separator character <I>sep</I> and the assignment character <I>eq</I>.
<DT><DD>
Elements whose option tag (element of <I>tags</I>) value is <B>STROPTX_DELETED_TAG</B> are omitted in output.
<DT><B>stropt2str</B><DD>
This is the sibling function of <B>stropt2buf</B>. It uses dynamically allocated memory instead of a buffer provided by the caller. The resulting string must be deallocated using <A HREF="/#/man/man3/free.3.html">free</A>(3).
</DL>
<A NAME="lbAE"> </A>
<H2>RETURN VALUE</H2>
<DL COMPACT>
<DT>•<DD>
<B>stropt</B> and <B>stroptx</B> return the number of options + 1.
<DT>•<DD>
<B>stropt2buf</B> and <B>stropt2str</B> return the resulting string.
<DT><DD>
</DL>
<A NAME="lbAF"> </A>
<H2>EXAMPLES</H2>
The following function lists the option tags and arguments (without modyfying the input string).
<DL COMPACT>
<DT><DD>
<PRE>
void parse_args(char *input) {
int tagc = stropt(input, NULL, NULL, NULL);
if(tagc > 0) {
char buf[strlen(input)+1];
char *tags[tagc];
char *args[tagc];
stropt(input, tags, args, buf);
for (int i=0; i<tagc; i++)
printf("%s = %s\n",tags[i], args[i]);
}
}
</PRE>
<DT><DD>
</DL>
<P>
it is possible to use the same input string as the buffer for parsing (the value of the input string gets lost in this way).
<DL COMPACT>
<DT><DD>
<PRE>
void parse_args(char *input) {
int tagc = stropt(input, NULL, NULL, NULL);
if(tagc > 0) {
char *tags[tagc];
char *args[tagc];
stropt(input, tags, args, input);
for (int i=0; i<tagc; i++)
printf("%s = %s\n",tags[i], args[i]);
}
}
</PRE>
<DT><DD>
</DL>
<P>
when options to parse have no arguments, args can be set to NULL.
<DL COMPACT>
<DT><DD>
<PRE>
void parse_args(char *input) {
int tagc = stropt(input, NULL, NULL, NULL);
if(tagc > 0) {
char buf[strlen(input)+1];
char *tags[tagc];
stropt(input, tags, NULL, buf);
for (int i=0; i<tagc; i++)
printf("%s \n",tags[i]);
}
}
</PRE>
<DT><DD>
</DL>
<P>
The following complete program parses and re-encode a string of comma separated arguments deleting those which begin by an uppercase letter.
<DL COMPACT>
<DT><DD>
<PRE>
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
#include <<A HREF="file:///usr/include/ctype.h">ctype.h</A>>
#include <<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>>
#include <<A HREF="file:///usr/include/string.h">string.h</A>>
#include <<A HREF="file:///usr/include/stropt.h">stropt.h</A>>
char *delete_uppercase_options(const char *input) {
int tagc = stroptx(input, "", ",",STROPTX_ALLOW_MULTIPLE_SEP, NULL, NULL, NULL);
if(tagc > 0) {
char buf[strlen(input)+1];
char *tags[tagc];
int i;
stroptx(input, "", ",",STROPTX_ALLOW_MULTIPLE_SEP, tags, NULL, buf);
for (i = 0; i < tagc; i++)
if (tags[i] && isupper(tags[i][0]))
tags[i] = STROPTX_DELETED_TAG;
return stropt2str(tags, NULL, ',', '=');
} else
return NULL;
}
int main(int argc, char *argv[]) {
if (argc > 1) {
char *result = delete_uppercase_options(argv[1]);
printf("%s\n", result);
free(result);
}
return 0;
}
</PRE>
<DT><DD>
</DL>
<A NAME="lbAG"> </A>
<H2>AUTHOR</H2>
VirtualSquare. Project leader: Renzo Davoli.
<P>
<HR>
<A NAME="index"> </A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">RETURN VALUE</A><DD>
<DT><A HREF="#lbAF">EXAMPLES</A><DD>
<DT><A HREF="#lbAG">AUTHOR</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 15:22:07 GMT, November 27, 2023
</BODY>
</HTML>