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