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