Commit | Line | Data |
---|---|---|
9e91c8e7 MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" Keyword argument support | |
4 | .\" | |
5 | .\" (c) 2015 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of the Sensible Object Design, an object system for C. | |
11 | .\" | |
12 | .\" SOD is free software; you can redistribute it and/or modify | |
13 | .\" it under the terms of the GNU Library General Public License as | |
14 | .\" published by the Free Software Foundation; either version 2 of the | |
15 | .\" License, or (at your option) any later version. | |
16 | .\" | |
17 | .\" SOD is distributed in the hope that it will be useful, | |
18 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | .\" GNU Library General Public License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU Library General Public | |
23 | .\" License along with SOD; if not, write to the Free | |
24 | .\" Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, | |
25 | .\" MA 02111-1307, USA. | |
26 | . | |
27 | .\" Highlight using terminal escapes, rather than overstriking. | |
28 | .\"\X'tty: sgr 1' | |
29 | . | |
30 | .\" String definitions and font selection. | |
31 | .ie t \{\ | |
32 | . ds o \(bu | |
33 | . if \n(.g .fam P | |
34 | .\} | |
35 | .el \{\ | |
36 | . ds o o | |
37 | .\} | |
38 | . | |
39 | .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left | |
40 | .de hP | |
41 | .IP | |
42 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
43 | .. | |
44 | . | |
45 | .de t( | |
46 | 'in +\\n(.ku | |
47 | .. | |
48 | .de t) | |
49 | .in | |
50 | .. | |
51 | . | |
52 | .\"-------------------------------------------------------------------------- | |
53 | .TH keyword 3 "16 December 2015" "Straylight/Edgeware" "Sensible Object Design" | |
54 | . | |
55 | .SH NAME | |
56 | keyword \- keyword argument support library | |
57 | . | |
58 | .\"-------------------------------------------------------------------------- | |
59 | .SH SYNOPSIS | |
60 | .B #include <sod/keyword.h> | |
61 | .PP | |
62 | .B "struct kwval { const char *kw; const void *val; };" | |
63 | .br | |
64 | .B "struct kwtab { const struct kwval *v; size_t n; };" | |
65 | .br | |
66 | .BI "typedef void kw_unkhookfn(const char *" set ", const char *" kw ");" | |
67 | .PP | |
68 | .BI "#define " set "_KWSET(_) \e" | |
69 | .in +4m | |
70 | .BI "_(" name ", " type ", " default ") \e" | |
71 | .br | |
72 | \&... | |
73 | .in | |
74 | .IB declaration-specifiers " KWSET_STRUCT(" set ");" | |
75 | .br | |
76 | .IB declaration-specifiers " KWSET_PARSEFN(" set ")" | |
77 | .PP | |
78 | .B KWCALL | |
79 | .IB type0 " " func "(" type1 " " arg1 , | |
80 | .RB ... , | |
81 | .IB typen " " argn , | |
82 | .B "KWTAIL);" | |
83 | .br | |
84 | .BI "KWDECL(" set ", " kw ");" | |
85 | .br | |
86 | .BI "KW_PARSE(" set ", " kw ", " kwfirst ");" | |
87 | .br | |
88 | .BI "KW_PARSE_EMPTY(" set ", " kwfirst ");" | |
89 | .br | |
90 | .BI "KWPARSE(" set ");" | |
91 | .br | |
92 | .BI "KWPARSE_EMPTY(" set ");" | |
93 | .PP | |
94 | .I val | |
95 | .B = | |
96 | .IB func "(" arg1 , | |
97 | .RB ... , | |
98 | .IB argn , | |
99 | .BI "KWARGS(" \c | |
100 | .t( | |
101 | .BI "K(" name ", " value ")" | |
102 | .br | |
103 | .BI "K_VALIST(" ap ")" | |
104 | .br | |
105 | .BI "K_TAB(" v ", " n ")" | |
106 | .br | |
107 | .RB ... ); | |
108 | .t) | |
109 | .br | |
110 | .I val | |
111 | .B = | |
112 | .IB func "(" arg1 , | |
113 | .RB ... , | |
114 | .IB argn , | |
115 | .B "NO_KWARGS);" | |
116 | .PP | |
117 | .B unsigned | |
118 | .BI "KW_COUNT(" set ");" | |
119 | .br | |
120 | .B void | |
121 | .BI "KW_COPY(" \c | |
122 | .t( | |
123 | .IB fromset ", " toset "," | |
124 | .br | |
125 | .BI "const struct " fromset "_kwset *" kw "," | |
126 | .br | |
127 | .BI "struct kwval *" v ", size_t " n ");" | |
128 | .t) | |
129 | .PP | |
130 | .BI "void kw_unknown(const char *" set ", const char *" kw ); | |
131 | .br | |
132 | .BI "void kw_parseempty(\fP" \c | |
133 | .t( | |
134 | .BI "const char *" set , | |
135 | .BI "const char *" kwfirst , | |
136 | .BI "va_list *" ap , | |
137 | .br | |
138 | .BI "const struct kwval *" v , | |
139 | .BI "size_t " n ); | |
140 | .t) | |
141 | .PP | |
142 | .B "kw_unkhookfn *kw_unkhook;" | |
143 | .br | |
144 | .B "kw_unkhookfn kw_defunknown;" | |
145 | . | |
146 | .\"-------------------------------------------------------------------------- | |
147 | .SH DESCRIPTION | |
148 | . | |
149 | .SS Theory | |
150 | In standard C, | |
151 | the actual arguments provided to a function | |
152 | are matched up with the formal arguments | |
153 | given in the function definition | |
154 | according to their ordering in a list. | |
155 | Unless the (rather cumbersome) machinery for dealing with | |
156 | variable-length argument tails | |
157 | .RB ( <stdarg.h> ) | |
158 | is used, | |
159 | exactly the correct number of arguments must be supplied, | |
160 | and in the correct order. | |
161 | .PP | |
162 | A | |
163 | .I keyword argument | |
164 | is matched by its distinctive | |
165 | .IR name , | |
166 | rather than by its position in a list. | |
167 | Keyword arguments may be | |
168 | .IR omitted , | |
169 | causing some default behaviour by the function. | |
170 | A function can detect whether | |
171 | a particular keyword argument was supplied: | |
172 | so the default behaviour need not be the same as | |
173 | that caused by any specific value of the argument. | |
174 | .PP | |
175 | Keyword arguments can be provided in three ways. | |
176 | .hP 1. | |
177 | Directly, as a variable-length argument tail, | |
178 | consisting (for the most part \(en see below) of alternating | |
179 | keyword names, as pointers to null-terminated strings, and | |
180 | argument values, and | |
181 | terminated by a null pointer. | |
182 | This is somewhat error-prone, | |
183 | and the support library defines some macros | |
184 | which help ensure that keyword argument lists are well formed. | |
185 | .hP 2. | |
186 | Indirectly, through a | |
187 | .B va_list | |
188 | object capturing a variable-length argument tail | |
189 | passed to some other function. | |
190 | Such indirect argument tails have the same structure as | |
191 | the direct argument tails described above. | |
192 | Because | |
193 | .B va_list | |
194 | objects are hard to copy, | |
195 | the keyword-argument support library consistently passes | |
196 | .B va_list | |
197 | objects | |
198 | .I by reference | |
199 | throughout its programming interface. | |
200 | .hP 3. | |
201 | Indirectly, through a vector of | |
202 | .B struct kwval | |
203 | objects, | |
204 | each of which contains | |
205 | a keyword name, as a pointer to a null-terminated string, and | |
206 | the | |
207 | .I address | |
208 | of a corresponding argument value. | |
209 | (This indirection is necessary so that | |
210 | the items in the vector can be of uniform size.) | |
211 | Argument vectors are rather inconvenient to use, | |
212 | but are the only practical way in which a caller can decide at runtime | |
213 | which arguments to include in a call, | |
214 | which is useful when writing wrapper functions. | |
4f634d20 MW |
215 | .PP |
216 | Perhaps surprisingly, | |
217 | keyword arguments have a relatively small performance impact. | |
218 | On the author's aging laptop, | |
219 | a call to a simple function, | |
220 | passing two out of three keyword arguments, | |
221 | takes about 30 cycles longer than | |
222 | calling a standard function which just takes integer arguments. | |
223 | On the other hand, | |
224 | quite a lot of code is involved in decoding keyword arguments, | |
225 | so code size will naturally suffer. | |
9e91c8e7 MW |
226 | . |
227 | .SS Type definitions | |
228 | The header file defines two simple structure types. | |
229 | .PP | |
230 | .IP | |
231 | .nf | |
232 | .ft B | |
233 | struct kwval { | |
234 | const char *kw; | |
235 | const void *val; | |
236 | }; | |
237 | .fi | |
238 | .PP | |
239 | The | |
240 | .B kwval | |
241 | structure describes a keyword argument name/value pair. | |
242 | The | |
243 | .B kw | |
244 | member points to the name, | |
245 | as a null-terminated string. | |
246 | The | |
247 | .B val | |
248 | member always contains the | |
249 | .I address | |
250 | of the value. | |
251 | (This somewhat inconvenient arrangement | |
252 | makes the size of a | |
253 | .B kwval | |
254 | object independent of the actual argument type.) | |
255 | .PP | |
256 | .IP | |
257 | .nf | |
258 | .ft B | |
259 | struct kwtab { | |
260 | const struct kwval *v; | |
261 | size_t n; | |
262 | }; | |
263 | .fi | |
264 | .PP | |
265 | The | |
266 | .B kwtab | |
267 | structure describes a list of keyword arguments, | |
268 | represented as a vector of | |
269 | .B kwval | |
270 | structures. | |
271 | The | |
272 | .B v | |
273 | member points to the start of the vector; | |
274 | the | |
275 | .B n | |
276 | member contains the number of elements in the vector. | |
277 | .PP | |
278 | The | |
279 | .B kw_unkhookfn | |
280 | type is the type of | |
281 | unknown-keyword handler functions. | |
282 | See the descriptions of | |
283 | .B kw_unknown | |
284 | and | |
285 | .B kw_unkhook | |
286 | below. | |
287 | . | |
288 | .SS Calling functions with keyword arguments | |
289 | Functions which accept keyword arguments are ordinary C functions | |
290 | with variable-length argument tails. | |
291 | Hence, they can be called using ordinary C (of the right kind) | |
292 | and all will be well. | |
293 | However, argument lists must follow certain rules | |
294 | (which will be described in full below); | |
295 | failure to do this will result in | |
296 | .IR "undefined behaviour" . | |
297 | The header file provides integration with some C compilers | |
298 | in the form of macros which can be used to help the compiler diagnose | |
299 | errors in calls to keyword-accepting functions; | |
300 | but such support is rather limited at the moment. | |
301 | Some additional macros are provided for use in calls to such functions, | |
302 | and it is recommended that, where possible, these are used. | |
303 | In particular, it's all too easy to forget the trailing null terminator | |
304 | which marks the end of a list of keyword arguments. | |
305 | .PP | |
306 | That said, the underlying machinery is presented first, | |
307 | and the convenience macros are described later. | |
308 | .PP | |
309 | The argument tail, | |
310 | following the mandatory arguments, | |
311 | consists of a sequence of zero or more alternating | |
312 | keyword names, | |
313 | as pointers to null-terminated strings | |
314 | (with type | |
315 | .BR "const char *" ), | |
316 | and their argument values. | |
317 | This sequence is finally terminated by a null pointer | |
318 | (again with type | |
319 | .BR "const char *" ) | |
320 | in place of a keyword name. | |
321 | .PP | |
322 | Each function may define for itself which keyword names it accepts, | |
323 | and what types the corresponding argument values should have. | |
324 | There are also (currently) three special keyword names. | |
325 | .TP | |
326 | .B kw.valist | |
327 | This special keyword is followed by a pointer to | |
328 | a variable-length argument tail cursor object, of type | |
329 | .BR "va_list *" . | |
330 | This cursor object will be modified as the function extracts | |
331 | successive arguments from the tail. | |
332 | The argument tail should consist of alternating | |
333 | keyword names and argument values, as described above, | |
334 | including the first keyword name. | |
335 | (This is therefore different from the convention used when calling | |
336 | keyword argument parser functions: | |
337 | see the description of the | |
338 | .B KW_PARSEFN | |
339 | macro below for more details about these.) | |
340 | The argument tail may itself contain the special keywords. | |
341 | .TP | |
342 | .B kw.tab | |
343 | This special keyword is followed by | |
344 | .I two | |
345 | argument values: | |
346 | a pointer to the base of a vector of | |
347 | .B kwval | |
348 | structures, | |
349 | and the number of elements in this vector | |
350 | (as a | |
351 | .BR size_t ). | |
352 | Each element of the vector describes a single keyword argument: | |
353 | the | |
354 | .B kw | |
355 | member points to the keyword's name, and | |
356 | the | |
357 | .B val | |
358 | member points to the value. | |
359 | The vector may contain special keywords. | |
360 | The | |
361 | .B val | |
362 | pointer for a | |
363 | .B kw.valist | |
364 | argument should contain the address of an object of type | |
365 | .B "va_list *" | |
366 | (and not point directly to the cursor object, | |
367 | since | |
368 | .B val | |
369 | is has type | |
370 | .B "const void *" | |
371 | but the cursor will be modified as its argument tail is traversed). | |
372 | The | |
373 | .B val | |
374 | pointer for a | |
375 | .B kw.tab | |
376 | argument should contain the address of a | |
377 | .B kwtab | |
378 | structure which itself contains the base address and length of | |
379 | the argument vector to be processed. | |
380 | .TP | |
381 | .B kw.unknown | |
382 | This keyword is never accepted by any function. | |
383 | If it is encountered, | |
384 | the | |
385 | .B kw_unknown | |
386 | function is called to report the situation as an error; | |
387 | see below. | |
388 | .PP | |
389 | It is possible to construct a circular structure | |
390 | of indirect argument lists | |
391 | (in a number of ways). | |
392 | Don't try to pass such a structure to a function: | |
393 | the result will be unbounded recursion | |
394 | or some other bad outcome. | |
395 | .PP | |
396 | The macro | |
397 | .BI "KWARGS(" body ")" | |
398 | wraps up a sequence of keyword arguments. | |
399 | The single | |
400 | .I body | |
401 | argument consists of a sequence of calls to | |
402 | the keyword-argument macros described below, | |
403 | one after another without any separation. | |
404 | .PP | |
630d9305 MW |
405 | If there are no keyword arguments, |
406 | use the argument-less macro | |
9e91c8e7 | 407 | .B NO_KWARGS |
9e91c8e7 | 408 | instead. |
630d9305 MW |
409 | There are two reasons for this. |
410 | .hP \*o | |
411 | C89 doesn't permit empty macro arguments for some reason, | |
412 | so | |
413 | .B NO_KWARGS | |
414 | is necessary when using a C89 compiler. | |
415 | .hP \*o | |
416 | Omitting the null terminator is a common mistake, | |
417 | so | |
418 | .B <keyword.h> | |
419 | tries to get the compiler to warn if you miss it. | |
420 | However, the | |
421 | .B KWTAIL | |
422 | macro introduces an extra real argument | |
423 | .BR kwfirst_ , | |
424 | because it's not possible to scan a variable-length argument tail | |
425 | if there are no mandatory arguments. | |
426 | If you use | |
427 | .BR KWARGS() , | |
428 | with an empty argument list, | |
429 | then the null terminator is passed as | |
430 | .B kwfirst_ | |
431 | and the variable-length tail ends up empty, | |
432 | which might trigger a compiler warning | |
433 | about the missing terminator. | |
434 | .B NO_KWARGS | |
435 | passes | |
436 | .I two | |
437 | null terminators: | |
438 | a real one to indicate that there are no keyword arguments, | |
439 | and a dummy one to placate the compiler. | |
9e91c8e7 MW |
440 | .PP |
441 | The following keyword-argument macros can be used | |
442 | within | |
443 | .BR KWARGS 's | |
444 | .I body | |
445 | argument. | |
446 | .TP | |
447 | .BI "K(" name ", " value ")" | |
448 | Passes a keyword name and its corresponding value, | |
449 | as a pair of arguments. | |
450 | The | |
451 | .I name | |
452 | should be a single identifier | |
453 | (not a quoted string). | |
454 | The | |
455 | .I value | |
456 | may be any C expression | |
457 | of the appropriate type. | |
458 | .TP | |
459 | .BI "K_VALIST(" ap ")" | |
460 | Passes an indirect variable-length argument tail. | |
461 | The argument | |
462 | .I ap | |
463 | should be an lvalue of type | |
464 | .B va_list | |
465 | which will be passed by reference. | |
466 | .TP | |
467 | .BI "K_TAB(" v ", " n ")" | |
468 | Passes a vector of keyword arguments. | |
469 | The argument | |
470 | .I v | |
471 | should be the base address of the vector, and | |
472 | .I n | |
473 | should be the number of elements in the vector. | |
474 | . | |
475 | .SS Defining functions with keyword arguments | |
476 | A | |
477 | .I "keyword set" | |
478 | defines the collection of keyword arguments | |
479 | accepted by a particular function. | |
480 | The same keyword set may be used by several functions. | |
481 | (If your function currently accepts no keyword arguments, | |
482 | but you plan to add some later, | |
483 | do not define a keyword set, | |
484 | and use the | |
485 | .B KWPARSE_EMPTY | |
486 | macro described below.) | |
487 | .PP | |
488 | Each keyword set has a name, | |
489 | which is a C identifier. | |
490 | It's good to choose meaningful and distinctive names for keyword sets. | |
491 | Keyword set names are meaningful at runtime: | |
492 | they are used as part of the | |
493 | .B kw_unknown | |
494 | protocol (described below), | |
495 | and may be examined by handler functions, | |
496 | or reported to a user in error messages. | |
497 | For a keyword set which is used only by a single function, | |
498 | it is recommended that the set be given the same name as the function. | |
499 | .PP | |
500 | The keyword arguments for a keyword set named | |
501 | .I set | |
502 | are described by a `list macro' named | |
503 | .IB set _KWSET \fR. | |
504 | This macro takes a single argument, | |
505 | conventionally named | |
506 | .RB ` _ '. | |
507 | It should expand to a sequence of one or more list items of the form | |
508 | .IP | |
509 | .BI "_(" type ", " name ", " default ")" | |
510 | .PP | |
511 | with no separation between them. | |
512 | .PP | |
513 | For example: | |
514 | .IP | |
515 | .nf | |
516 | .ft B | |
517 | #define example_KWSET(_) \e | |
518 | .in +4m | |
519 | _(int, x, 0) \e | |
520 | _(const char *, y, NULL) | |
521 | .fi | |
522 | .ft P | |
523 | .PP | |
524 | Each | |
525 | .I name | |
526 | should be a distinct C identifier; | |
527 | they will be used to name structure members. | |
528 | An argument | |
529 | .I name | |
530 | should not end with the suffix | |
531 | .RB ` _suppliedp ' | |
532 | (for reasons which will soon become apparent). | |
533 | .PP | |
534 | Each | |
535 | .I type | |
536 | should be a C | |
537 | .I type-name | |
538 | such that | |
539 | .IP | |
540 | .IB type " " name ; | |
541 | .PP | |
542 | is a valid declaration: | |
543 | so it may consist of declaration specifiers and | |
544 | (possibly qualified) pointer declarator markers, | |
545 | but not array or function markers | |
546 | (since they must be placed after the | |
547 | .IR name ). | |
548 | This is the same requirement made by the standard | |
549 | .BR va_arg (3) | |
550 | macro. | |
551 | .PP | |
552 | Each | |
553 | .I default | |
554 | should be an initializer expression | |
555 | or brace-enclosed list, | |
556 | suitable for use in an aggregate initializer | |
557 | for a variable with automatic storage duration. | |
558 | (In C89, aggregate initializers may contain only constant expressions; | |
559 | this restriction was lifted in C99.) | |
560 | .PP | |
561 | The macro | |
562 | .B KWTAIL | |
563 | is expected to be used at the end of function parameter type list | |
564 | to indicate that the function accepts keyword arguments; | |
565 | if there are preceding mandatory arguments | |
566 | then the | |
567 | .B KWTAIL | |
568 | marker should be separated from them with a comma | |
569 | .RB ` , '. | |
570 | (It is permitted for a function parameter type list to contain | |
571 | only a | |
572 | .B KWTAIL | |
573 | marker.) | |
574 | .PP | |
575 | Specifically, | |
576 | the macro declares a mandatory argument | |
577 | .B const char *kwfirst_ | |
578 | (to collect the first keyword name), | |
579 | and a variable-length argument tail. | |
580 | .PP | |
581 | The macro | |
582 | .B KWPARSE | |
583 | (described below) | |
584 | assumes that the enclosing function's argument list ends with a | |
585 | .B KWTAIL | |
586 | marker. | |
587 | The marker should be included both in the function's definition and | |
588 | in any declarations, e.g., in the corresponding header file. | |
589 | .PP | |
590 | The | |
591 | .B KWCALL | |
592 | macro acts as a declaration specifier for | |
593 | functions which accept keyword arguments. | |
594 | Its effect is to arrange for the compiler to check, | |
595 | as far as is possible, | |
596 | that calls to the function are well-formed | |
597 | according to the keyword-argument rules. | |
598 | The exact checking performed depends on the compiler's abilities | |
599 | (and how well supported the compiler is): | |
600 | it may check that every other argument is a string; | |
601 | it may check that the list is terminated with a null pointer; | |
602 | it may not do anything at all. | |
603 | Again, this marker should be included in a function's definition and | |
604 | in any declarations. | |
605 | .PP | |
606 | The | |
607 | .B KWSET_STRUCT | |
608 | macro defines a | |
609 | .IR "keyword structure" . | |
610 | If | |
611 | .I set | |
612 | is a keyword-set name then | |
613 | .IP | |
614 | .BI "KWSET_STRUCT(" set ");" | |
615 | .PP | |
616 | declares a structure | |
617 | .B struct | |
618 | .IB set _kwargs \fR. | |
619 | For each argument defined in the keyword set, | |
620 | this structure contains two members: | |
621 | one has exactly the | |
622 | .I name | |
623 | and | |
624 | .I type | |
625 | listed in the keyword set definition; | |
626 | the other is a 1-bit-wide bitfield of type | |
627 | .B "unsigned int" | |
628 | named | |
629 | .IB name _suppliedp \fR. | |
630 | .PP | |
631 | The macro | |
632 | .B KWDECL | |
633 | declares and initializes a keyword argument structure variable. | |
634 | If | |
635 | .I set | |
636 | is a keyword-set name then | |
637 | .IP | |
638 | .I declaration-specifiers | |
639 | .BI "KWDECL(" set ", " kw ");" | |
640 | .PP | |
641 | declares a variable of type | |
642 | .B struct | |
643 | .IB set _kwargs | |
644 | named | |
645 | .IR kw . | |
646 | The optional | |
647 | .I declaration-specifiers | |
648 | may provide additional storage-class, | |
649 | qualifiers, | |
650 | or other declaration specifiers. | |
651 | The | |
652 | .RB ` _suppliedp ' | |
653 | flags are initialized to zero; | |
654 | the other members are initialized with the corresponding defaults | |
655 | from the keyword-set definition. | |
656 | .PP | |
657 | The macro | |
658 | .B KWSET_PARSEFN | |
659 | defines a keyword argument | |
660 | .IR "parser function" . | |
661 | If | |
662 | .I set | |
663 | is a keyword-set name then | |
664 | .IP | |
665 | .I declaration-specifiers | |
666 | .BI "KWSET_PARSEFN(" set ")" | |
667 | .PP | |
668 | (no trailing semicolon!) | |
669 | defines a function | |
670 | .IP | |
671 | .B void | |
672 | .IB set _kwparse( \c | |
673 | .t( | |
674 | .BI "struct " set "_kwargs *" kw "," | |
675 | .br | |
676 | .BI "const char *" kwfirst ", va_list *" ap "," | |
677 | .br | |
678 | .BI "const struct kwval *" v ", size_t " n ");" | |
679 | .t) | |
680 | .PP | |
681 | The macro call can | |
682 | (and usually will) | |
683 | be preceded by storage class specifiers such as | |
684 | .BR static , | |
685 | for example to adjust the linkage of the name. | |
686 | (I don't recommend declaring parser functions | |
687 | .BR inline : | |
688 | parser functions are somewhat large, and | |
689 | modern compilers are pretty good at | |
690 | figuring out whether to inline static functions.) | |
691 | .PP | |
692 | The function's behaviour is as follows. | |
693 | It parses keyword arguments from | |
694 | a variable-length argument tail, and/or | |
695 | a vector of | |
696 | .B kwval | |
697 | structures. | |
698 | When a keyword argument is recognized, | |
699 | for some keyword | |
700 | .IR name , | |
701 | the keyword argument structure pointed to by | |
702 | .I kw | |
703 | is updated: | |
704 | the flag | |
705 | .IB name _suppliedp | |
706 | is set to 1; | |
707 | and the argument value is stored (by simple assignment) in the | |
708 | .I name | |
709 | member. | |
710 | Hence, if the | |
711 | .RB ` _suppliedp ' | |
712 | members are initialized to zero, | |
713 | the caller can determine which keyword arguments were supplied. | |
714 | It is not possible to discover whether two or more arguments | |
715 | have the same keyword: | |
716 | in this case, | |
717 | the value from the last such argument is left | |
718 | in the keyword argument structure, | |
719 | and any values from earlier arguments are lost. | |
720 | (For this purpose, | |
721 | the argument vector | |
722 | .I v | |
723 | is scanned | |
724 | .I after | |
725 | the variable-length argument tail captured in | |
726 | .IR ap .) | |
727 | .PP | |
728 | The variable-argument tail is read from the list described by | |
729 | .BI * ap \fR. | |
730 | The argument tail is expected to consist of alternating | |
731 | keyword strings (as ordinary null-terminated strings) | |
732 | and the corresponding values, | |
733 | terminated by a null pointer of type | |
734 | .B "const char *" | |
735 | in place of a keyword; | |
736 | except that the first keyword | |
737 | (or terminating null pointer, if no arguments are provided) | |
738 | is expected to have been extracted already | |
739 | and provided as the | |
740 | .I kwfirst | |
741 | argument; | |
742 | the first argument retrieved using the | |
743 | .B va_list | |
744 | cursor object should then be the value | |
745 | corresponding to the keyword named by | |
746 | .IR kwfirst . | |
747 | (This slightly unusual convention makes it possible for a function to | |
748 | collect the first keyword as a separate mandatory argument, | |
749 | which is essential if there are no other mandatory arguments. | |
750 | It also means that the compiler will emit a diagnostic | |
751 | if you attempt to call a function which expects keyword arguments, | |
752 | but don't supply any and | |
753 | forget the null pointer which terminates the (empty) list.) | |
754 | If | |
755 | .I kwfirst | |
756 | is a null pointer, | |
757 | then | |
758 | .I ap | |
759 | need not be a valid pointer; | |
760 | otherwise, the cursor object | |
761 | .BI * ap | |
762 | will be modified as the function extracts | |
763 | successive arguments from the tail. | |
764 | .PP | |
765 | The keyword vector is read from the vector of | |
766 | .B kwval | |
767 | structures starting at address | |
768 | .I v | |
769 | and containing the following | |
770 | .I n | |
771 | items. | |
772 | If | |
773 | .I n | |
774 | is zero then | |
775 | .I v | |
776 | need not be a valid pointer. | |
777 | .PP | |
778 | The function also handles the special | |
779 | .B kw.valist | |
780 | and | |
781 | .B kw.tab | |
782 | arguments described above. | |
783 | If an unrecognized keyword argument is encountered, | |
784 | then | |
785 | .B kw_unknown | |
786 | is called: | |
787 | see below for details. | |
788 | .PP | |
789 | The | |
790 | .B KW_PARSE | |
791 | macro invokes a keyword argument parsing function. | |
792 | If | |
793 | .I set | |
794 | is a keyword-set name, | |
795 | .I kw | |
796 | names a keyword argument structure variable of type | |
797 | .B struct | |
798 | .IB set _kwargs \fR, | |
799 | and | |
800 | .I kwfirst | |
801 | is the name of the enclosing function's last mandatory argument, | |
802 | which must have type | |
803 | .BR "const char *" , | |
804 | then | |
805 | .IP | |
806 | .BI "KW_PARSE(" set ", " kw ", " kwfirst ");" | |
807 | .PP | |
808 | calls the function | |
809 | .IB set _kwparse | |
810 | with five arguments: | |
811 | the address of the keyword argument structure | |
812 | .IR kw ; | |
813 | the string pointer | |
814 | .IR kwfirst ; | |
815 | the address of a temporary argument-tail cursor object of type | |
816 | .BR va_list , | |
817 | constructed on the assumption that | |
818 | .I kwfirst | |
819 | is the enclosing function's final keyword argument; | |
820 | a null pointer; and | |
821 | the value zero (signifying an empty keyword-argument vector). | |
822 | If the variable | |
823 | .I kw | |
824 | was declared using | |
825 | .B KWDECL | |
826 | and the function | |
827 | .IB set _kwparse | |
828 | has been defined using | |
829 | .B KWSET_PARSEFN | |
830 | then the effect is to parse the keyword arguments passed to the function | |
831 | and set the members of | |
832 | .I kw | |
833 | appropriately. | |
834 | .PP | |
835 | The macro | |
836 | .B KWPARSE | |
837 | (note the lack of underscore) | |
838 | combines | |
839 | .B KWDECL | |
840 | and | |
841 | .BR KW_PARSE . | |
842 | If | |
843 | .I set | |
844 | is a keyword-set name then | |
845 | .IP | |
846 | .BI "KWPARSE(" set ");" | |
847 | .PP | |
848 | declares and initializes a keyword argument structure variable | |
849 | with the fixed name | |
850 | .BR kw , | |
851 | and parses the keyword arguments provided to the enclosing function, | |
852 | storing the results in | |
853 | .BR kw . | |
854 | It assumes that the first keyword name | |
855 | is in an argument named | |
856 | .BR kwfirst_ , | |
65f822bc | 857 | as set up by the |
5d3d5970 MW |
858 | .B KWTAIL |
859 | marker described above. | |
9e91c8e7 MW |
860 | .PP |
861 | The macro expands both to a variable declaration and a statement: | |
862 | in C89, declarations must precede statements, | |
863 | so under C89 rules this macro must appear exactly between | |
864 | the declarations at the head of a brace-enclosed block | |
865 | (typically the function body) | |
866 | and the statements at the end. | |
867 | This restriction was lifted in C99, | |
868 | so the macro may appear anywhere in the function body. | |
869 | However, it is recommended that callers avoid taking actions | |
870 | which might require cleanup | |
871 | before attempting to parse their keyword arguments, | |
872 | since keyword argument parsing functions invoke the | |
873 | .B kw_unknown | |
874 | handler if they encounter an unknown keyword, | |
875 | and the calling function will not get a chance | |
876 | to tidy up after itself if this happens. | |
877 | .PP | |
878 | As mentioned above, | |
879 | it is not permitted to define an empty keyword set. | |
880 | (Specifically, invoking | |
881 | .B KWSET_STRUCT | |
882 | for an empty keyword set would result in attempting to define | |
883 | a structure with no members, which C doesn't allow.) | |
884 | On the other hand, keyword arguments are a useful extension mechanism, | |
885 | and it's useful to be able to define a function which doesn't | |
886 | currently accept any keywords, | |
887 | but which might in the future be extended to allow keyword arguments. | |
888 | The macros | |
889 | .B KW_PARSE_EMPTY | |
890 | and | |
891 | .B KWPARSE_EMPTY | |
892 | are analogues of | |
893 | .B KW_PARSE | |
894 | and | |
895 | .B KWPARSE | |
896 | respectively, | |
897 | and handle this case. | |
898 | These macros take a keyword-set name as an argument, | |
899 | but this name is used only in diagnostic messages | |
900 | (e.g., if an unknown keyword name is encountered) | |
901 | and need not | |
902 | (and probably should not) | |
903 | correspond to a defined keyword set. | |
904 | .PP | |
905 | If | |
906 | .I set | |
907 | is an identifier then | |
908 | .IP | |
909 | .BI "KW_PARSE_EMPTY(" set ", " kwfirst ");" | |
910 | .PP | |
911 | calls the function | |
912 | .B kw_parseempty | |
913 | with five arguments: | |
914 | the | |
915 | .I set | |
916 | name, as a string; | |
917 | the string pointer | |
918 | .IR kwfirst ; | |
919 | the address of a temporary argument-tail cursor object of type | |
920 | .BR va_list , | |
921 | constructed on the assumption that | |
922 | .I kwfirst | |
923 | is the enclosing function's final keyword argument; | |
924 | a null pointer; and | |
925 | the value zero (signifying an empty keyword-argument vector). | |
926 | The effect is to check that the argument tail contains | |
927 | no keyword arguments other than the special predefined ones. | |
928 | .PP | |
929 | If | |
930 | .I set | |
931 | is an identifier then | |
932 | .IP | |
5d3d5970 | 933 | .BI "KWPARSE_EMPTY(" set ");" |
9e91c8e7 MW |
934 | .PP |
935 | (note the lack of underscore) | |
936 | checks that the enclosing function has been passed | |
937 | no keyword arguments other than the special predefined ones. | |
938 | It assumes that the function's parameter type list ends with the | |
939 | .B KWTAIL | |
940 | marker described above. | |
941 | .PP | |
942 | The | |
943 | .B kw_parseempty | |
944 | function checks an keyword argument list | |
945 | to make sure that contains no keyword arguments | |
946 | (other than the special ones described above). | |
947 | .PP | |
948 | The | |
949 | .I set | |
950 | argument should point to a null-terminated string: | |
951 | this will be reported as the keyword set name to | |
952 | .BR kw_unknown , | |
953 | though it need not | |
954 | (and likely will not) | |
955 | refer to any defined keyword set. | |
956 | The remaining arguments are as for | |
957 | the keyword parsing functions | |
958 | defined by the | |
959 | .B KWSET_PARSEFN | |
960 | macro. | |
961 | . | |
962 | .SS "Wrapper functions" | |
963 | Most users will not need the hairy machinery involving argument vectors. | |
964 | Their main use is in defining | |
965 | .IR "wrapper functions" . | |
966 | Suppose there is a function | |
967 | .I f | |
968 | which accepts some keyword arguments, | |
969 | and we want to write a function | |
970 | .I g | |
971 | which accepts the same keywords recognized by | |
972 | .I f | |
973 | and some additional ones. | |
974 | Unfortunately | |
975 | .I f | |
976 | may behave differently depending on whether or not | |
977 | a particular keyword argument is supplied at all, but | |
978 | it's not possible to synthesize a valid | |
979 | .B va_list | |
980 | other than by simply capturing a live argument tail, | |
981 | and it's not possible to decide at runtime | |
982 | whether or not to include some arguments in a function call. | |
983 | It's still possible to write | |
984 | .IR g , | |
985 | by building a vector of keyword arguments, | |
986 | collected one-by-one depending on the corresponding | |
987 | .RB ` _suppliedp ' | |
988 | flags (see below). | |
989 | A few macros are provided to make this task easier. | |
990 | .PP | |
991 | The macro | |
992 | .B KW_COUNT | |
993 | returns the number of keywords defined in a keyword set. | |
994 | If | |
995 | .I set | |
996 | is a keyword-set name, then | |
997 | .IP | |
998 | .BI "KW_COUNT(" set ")" | |
999 | .PP | |
1000 | returns the number of keywords defined by | |
1001 | .IR set , | |
1002 | as a constant expression of type | |
1003 | .BR "unsigned int" . | |
1004 | .PP | |
1005 | The macro | |
1006 | .B KW_COPY | |
1007 | populates a vector of | |
1008 | .B kwval | |
1009 | structures from a keyword-argument structure. | |
1010 | If | |
1011 | .I fromset | |
1012 | and | |
1013 | .I toset | |
1014 | are two keyword-set names then | |
1015 | .IP | |
1016 | .BI "KW_COPY(" fromset ", " toset ", " kw ", " v ", " n ");" | |
1017 | .PP | |
1018 | will populate the vector | |
1019 | .IR v , | |
1020 | taking argument values from | |
1021 | .IR kw . | |
1022 | The | |
1023 | .I toset | |
1024 | must be a subset of | |
1025 | .IR fromset : | |
1026 | i.e., for every keyword defined in | |
1027 | .I toset | |
1028 | there is a keyword defined in | |
1029 | .I fromset | |
1030 | with the same name and type. | |
1031 | The remaining arguments are as follows: | |
1032 | .I kw | |
1033 | is a pointer to a | |
1034 | .BI "struct " fromset "_kwset" | |
1035 | keyword-argument structure which has been filled in, | |
1036 | e.g., by the keyword-argument parsing function | |
1037 | .IB fromset _kwparse \fR; | |
1038 | .I v | |
1039 | is a pointer to a sufficiently large vector of | |
1040 | .B "struct kwval" | |
1041 | objects; | |
1042 | and | |
1043 | .I n | |
1044 | is an lvalue designating an object of integer type. | |
1045 | Successive elements of | |
1046 | .IR v , | |
1047 | starting at index | |
1048 | .IR n , | |
1049 | are filled in to refer to | |
1050 | the keyword arguments defined in | |
1051 | .I toset | |
1052 | whose | |
1053 | .RB ` _suppliedp ' | |
1054 | flag is set in the argument structure pointed to by | |
1055 | .IR kw ; | |
1056 | for each such argument, | |
1057 | a pointer to the keyword name is stored in | |
1058 | the corresponding vector element's | |
1059 | .B kw | |
1060 | member, and | |
1061 | a pointer to the argument value, | |
1062 | held in the keyword argument structure, | |
1063 | is stored in the vector element's | |
1064 | .B val | |
1065 | member. | |
1066 | At the end of this, | |
1067 | the index | |
1068 | .I n | |
1069 | is advanced so as to contain the index of the first unused element of | |
1070 | .IR v . | |
1071 | Hence, at most | |
1072 | .BI KW_COUNT( toset ) | |
1073 | elements of | |
1074 | .I v | |
1075 | will be used. | |
1076 | . | |
1077 | .SS Handling unknown-keyword errors | |
1078 | When parsing a variable-length argument tail, | |
1079 | it is not possible to continue after | |
1080 | encountering an unknown keyword name. | |
1081 | This is because it is necessary | |
1082 | to know the (promoted) type of the following argument value | |
1083 | in order to skip past it; | |
1084 | but the only clue provided as to the type is the keyword name, | |
1085 | which in this case is meaningless. | |
1086 | .PP | |
1087 | In this situation, | |
1088 | the parser functions generated by | |
1089 | .B KW_PARSEFN | |
1090 | (and the | |
1091 | .B kw_parseempty | |
1092 | function) | |
1093 | call | |
1094 | .BR kw_unknown . | |
1095 | This is a function of two arguments: | |
1096 | .I set | |
1097 | points to the name of the keyword set expected by the caller, | |
1098 | as a null-terminated string; and | |
1099 | .I kw | |
1100 | is the unknown keyword which was encountered. | |
1101 | All that | |
1102 | .B kw_unknown | |
1103 | does is invoke the function whose address is stored in | |
1104 | the global variable | |
1105 | .B kw_unkhook | |
1106 | with the same arguments. | |
1107 | The | |
1108 | .B kw_unknown | |
1109 | function never returns to its caller: | |
1110 | if the | |
1111 | .B kw_unkhook | |
1112 | function returns (which it shouldn't) | |
1113 | then | |
1114 | .B kw_unknown | |
1115 | writes a fatal error message to standard error | |
1116 | and calls | |
1117 | .BR abort (3). | |
1118 | .PP | |
1119 | By default | |
1120 | .B kw_unkhook | |
1121 | points to the function | |
1122 | .BR kw_defunknown , | |
1123 | which just writes an error message | |
1124 | quoting the keyword set name | |
1125 | and offending keyword | |
1126 | to standard error | |
1127 | and calls | |
1128 | .BR abort (3). | |
1129 | .PP | |
1130 | (In freestanding environments, | |
1131 | the behaviour may be somewhat different: | |
1132 | porting the library to such environments involves | |
1133 | choosing appropriate behaviour for the target platform.) | |
1134 | .PP | |
1135 | As an example of the kind of special effect | |
1136 | which can be achieved using this hook, | |
1137 | the following hacking answers whether | |
1138 | a function recognizes a particular keyword argument. | |
1139 | .IP | |
1140 | .nf | |
1141 | .ft B | |
1142 | #define KWARGS_TEST(k, val) KWARGS(K(k, val) K(kw.unknown, 0)) | |
1143 | ||
1144 | static jmp_buf kw_test_jmp; | |
1145 | ||
1146 | static void kw_test_unknown(const char *set, const char *kw) | |
1147 | { | |
1148 | if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1); | |
1149 | else longjmp(kw_test_jmp, 2); | |
1150 | } | |
1151 | ||
1152 | #define KW_TEST(flag, set, call) do { \e | |
1153 | kw_unkhookfn *oldunk = kw_unkhook; \e | |
1154 | kw_unkhook = kw_test_unknown; \e | |
1155 | switch (setjmp(kw_test_jmp)) { \e | |
1156 | case 0: call; abort(); \e | |
1157 | case 1: flag = 1; break; \e | |
1158 | case 2: flag = 0; break; \e | |
1159 | default: abort(); \e | |
1160 | } \e | |
1161 | kw_unkhook = oldunk; \e | |
1162 | } while (0) | |
1163 | ||
1164 | /* Example of use */ | |
1165 | int f; | |
1166 | KW_TEST(f, somefunc(1, "two", 3, KWARGS_TEST("shiny", 68.7))); | |
1167 | /* now f is nonzero if `somefunc' accepts the `shiny' keyword | |
1168 | * (which we hope wants a double argument) | |
1169 | */ | |
1170 | .ft P | |
1171 | .fi | |
1172 | . | |
1173 | .\"-------------------------------------------------------------------------- | |
1174 | .SH BUGS | |
1175 | . | |
1176 | The unknown-keyword hook is inadequate for a modern library, | |
1177 | but dealing with multiple threads isn't currently possible | |
1178 | without writing (moderately complex) system-specific code. | |
1179 | The author's intention is that the hook variable | |
1180 | .B kw_unkhook | |
1181 | be `owned' by some external library | |
1182 | which can make its functionality available to client programs | |
1183 | in a safer and more convenient way. | |
1184 | On Unix-like platforms | |
1185 | (including Cygwin) | |
1186 | that library will be (a later version) of | |
1187 | .BR mLib ; | |
1188 | other platforms will likely need different arrangements. | |
1189 | The author is willing to coordinate any such efforts. | |
1190 | .PP | |
1191 | The whole interface is rather clunky. | |
1192 | Working with keyword-argument vectors is especially unpleasant. | |
1193 | The remarkable thing is not that it's done well, | |
1194 | but that it can be done at all. | |
1195 | . | |
1196 | .\"-------------------------------------------------------------------------- | |
1197 | .SH SEE ALSO | |
1198 | . | |
1199 | .BR va_start (3), | |
1200 | .BR va_arg (3), | |
1201 | .BR va_end (3). | |
1202 | . | |
1203 | .\"-------------------------------------------------------------------------- | |
1204 | .SH AUTHOR | |
1205 | . | |
1206 | Mark Wooding, | |
1207 | <mdw@distorted.org.uk> | |
1208 | . | |
1209 | .\"----- That's all, folks -------------------------------------------------- |