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