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