3 .\" Keyword argument support
5 .\" (c) 2015 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the Sensible Object Design, an object system for C.
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.
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.
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.
27 .\" Highlight using terminal escapes, rather than overstriking.
30 .\" String definitions and font selection.
39 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
42 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
52 .\"--------------------------------------------------------------------------
53 .TH keyword 3 "16 December 2015" "Straylight/Edgeware" "Sensible Object Design"
56 keyword \- keyword argument support library
58 .\"--------------------------------------------------------------------------
60 .B #include <sod/keyword.h>
62 .B "struct kwval { const char *kw; const void *val; };"
64 .B "struct kwtab { const struct kwval *v; size_t n; };"
66 .BI "typedef void kw_unkhookfn(const char *" set ", const char *" kw ");"
68 .BI "#define " set "_KWSET(_) \e"
70 .BI "_(" name ", " type ", " default ") \e"
74 .IB declaration-specifiers " KWSET_STRUCT(" set ");"
76 .IB declaration-specifiers " KWSET_PARSEFN(" set ")"
79 .IB type0 " " func "(" type1 " " arg1 ,
84 .BI "KWDECL(" set ", " kw ");"
86 .BI "KW_PARSE(" set ", " kw ", " kwfirst ");"
88 .BI "KW_PARSE_EMPTY(" set ", " kwfirst ");"
90 .BI "KWPARSE(" set ");"
92 .BI "KWPARSE_EMPTY(" set ");"
101 .BI "K(" name ", " value ")"
103 .BI "K_VALIST(" ap ")"
105 .BI "K_TAB(" v ", " n ")"
118 .BI "KW_COUNT(" set ");"
123 .IB fromset ", " toset ","
125 .BI "const struct " fromset "_kwset *" kw ","
127 .BI "struct kwval *" v ", size_t " n ");"
130 .BI "void kw_unknown(const char *" set ", const char *" kw );
132 .BI "void kw_parseempty(\fP" \c
134 .BI "const char *" set ,
135 .BI "const char *" kwfirst ,
138 .BI "const struct kwval *" v ,
142 .B "kw_unkhookfn *kw_unkhook;"
144 .B "kw_unkhookfn kw_defunknown;"
146 .\"--------------------------------------------------------------------------
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
159 exactly the correct number of arguments must be supplied,
160 and in the correct order.
164 is matched by its distinctive
166 rather than by its position in a list.
167 Keyword arguments may be
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.
175 Keyword arguments can be provided in three ways.
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
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.
186 Indirectly, through a
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.
194 objects are hard to copy,
195 the keyword-argument support library consistently passes
199 throughout its programming interface.
201 Indirectly, through a vector of
204 each of which contains
205 a keyword name, as a pointer to a null-terminated string, and
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.
217 The header file defines two simple structure types.
230 structure describes a keyword argument name/value pair.
233 member points to the name,
234 as a null-terminated string.
237 member always contains the
240 (This somewhat inconvenient arrangement
243 object independent of the actual argument type.)
249 const struct kwval *v;
256 structure describes a list of keyword arguments,
257 represented as a vector of
262 member points to the start of the vector;
265 member contains the number of elements in the vector.
270 unknown-keyword handler functions.
271 See the descriptions of
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.
295 That said, the underlying machinery is presented first,
296 and the convenience macros are described later.
299 following the mandatory arguments,
300 consists of a sequence of zero or more alternating
302 as pointers to null-terminated strings
304 .BR "const char *" ),
305 and their argument values.
306 This sequence is finally terminated by a null pointer
309 in place of a keyword name.
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.
316 This special keyword is followed by a pointer to
317 a variable-length argument tail cursor object, of type
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
328 macro below for more details about these.)
329 The argument tail may itself contain the special keywords.
332 This special keyword is followed by
335 a pointer to the base of a vector of
338 and the number of elements in this vector
341 Each element of the vector describes a single keyword argument:
344 member points to the keyword's name, and
347 member points to the value.
348 The vector may contain special keywords.
353 argument should contain the address of an object of type
355 (and not point directly to the cursor object,
360 but the cursor will be modified as its argument tail is traversed).
365 argument should contain the address of a
367 structure which itself contains the base address and length of
368 the argument vector to be processed.
371 This keyword is never accepted by any function.
372 If it is encountered,
375 function is called to report the situation as an error;
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.
386 .BI "KWARGS(" body ")"
387 wraps up a sequence of keyword arguments.
390 argument consists of a sequence of calls to
391 the keyword-argument macros described below,
392 one after another without any separation.
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
398 should be used instead.
399 If you're using C99 or later,
400 it's fine to just write
404 The following keyword-argument macros can be used
410 .BI "K(" name ", " value ")"
411 Passes a keyword name and its corresponding value,
412 as a pair of arguments.
415 should be a single identifier
416 (not a quoted string).
419 may be any C expression
420 of the appropriate type.
422 .BI "K_VALIST(" ap ")"
423 Passes an indirect variable-length argument tail.
426 should be an lvalue of type
428 which will be passed by reference.
430 .BI "K_TAB(" v ", " n ")"
431 Passes a vector of keyword arguments.
434 should be the base address of the vector, and
436 should be the number of elements in the vector.
438 .SS Defining functions with keyword arguments
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,
449 macro described below.)
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
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.
463 The keyword arguments for a keyword set named
465 are described by a `list macro' named
467 This macro takes a single argument,
470 It should expand to a sequence of one or more list items of the form
472 .BI "_(" type ", " name ", " default ")"
474 with no separation between them.
480 #define example_KWSET(_) \e
483 _(const char *, y, NULL)
489 should be a distinct C identifier;
490 they will be used to name structure members.
493 should not end with the suffix
495 (for reasons which will soon become apparent).
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
511 This is the same requirement made by the standard
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.)
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
531 marker should be separated from them with a comma
533 (It is permitted for a function parameter type list to contain
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.
547 assumes that the enclosing function's argument list ends with a
550 The marker should be included both in the function's definition and
551 in any declarations, e.g., in the corresponding header file.
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
572 .IR "keyword structure" .
575 is a keyword-set name then
577 .BI "KWSET_STRUCT(" set ");"
582 For each argument defined in the keyword set,
583 this structure contains two members:
588 listed in the keyword set definition;
589 the other is a 1-bit-wide bitfield of type
592 .IB name _suppliedp \fR.
596 declares and initializes a keyword argument structure variable.
599 is a keyword-set name then
601 .I declaration-specifiers
602 .BI "KWDECL(" set ", " kw ");"
604 declares a variable of type
610 .I declaration-specifiers
611 may provide additional storage-class,
613 or other declaration specifiers.
616 flags are initialized to zero;
617 the other members are initialized with the corresponding defaults
618 from the keyword-set definition.
622 defines a keyword argument
623 .IR "parser function" .
626 is a keyword-set name then
628 .I declaration-specifiers
629 .BI "KWSET_PARSEFN(" set ")"
631 (no trailing semicolon!)
637 .BI "struct " set "_kwargs *" kw ","
639 .BI "const char *" kwfirst ", va_list *" ap ","
641 .BI "const struct kwval *" v ", size_t " n ");"
646 be preceded by storage class specifiers such as
648 for example to adjust the linkage of the name.
649 (I don't recommend declaring parser functions
651 parser functions are somewhat large, and
652 modern compilers are pretty good at
653 figuring out whether to inline static functions.)
655 The function's behaviour is as follows.
656 It parses keyword arguments from
657 a variable-length argument tail, and/or
661 When a keyword argument is recognized,
664 the keyword argument structure pointed to by
670 and the argument value is stored (by simple assignment) in the
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:
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.
688 the variable-length argument tail captured in
691 The variable-argument tail is read from the list described by
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
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
705 the first argument retrieved using the
707 cursor object should then be the value
708 corresponding to the keyword named by
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.)
722 need not be a valid pointer;
723 otherwise, the cursor object
725 will be modified as the function extracts
726 successive arguments from the tail.
728 The keyword vector is read from the vector of
730 structures starting at address
732 and containing the following
739 need not be a valid pointer.
741 The function also handles the special
745 arguments described above.
746 If an unrecognized keyword argument is encountered,
750 see below for details.
754 macro invokes a keyword argument parsing function.
757 is a keyword-set name,
759 names a keyword argument structure variable of type
764 is the name of the enclosing function's last mandatory argument,
769 .BI "KW_PARSE(" set ", " kw ", " kwfirst ");"
774 the address of the keyword argument structure
778 the address of a temporary argument-tail cursor object of type
780 constructed on the assumption that
782 is the enclosing function's final keyword argument;
784 the value zero (signifying an empty keyword-argument vector).
791 has been defined using
793 then the effect is to parse the keyword arguments passed to the function
794 and set the members of
800 (note the lack of underscore)
807 is a keyword-set name then
809 .BI "KWPARSE(" set ");"
811 declares and initializes a keyword argument structure variable
814 and parses the keyword arguments provided to the enclosing function,
815 storing the results in
817 It assumes that the first keyword name
818 is in an argument named
822 marker described above.
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
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.
842 it is not permitted to define an empty keyword set.
843 (Specifically, invoking
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.
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)
865 (and probably should not)
866 correspond to a defined keyword set.
870 is an identifier then
872 .BI "KW_PARSE_EMPTY(" set ", " kwfirst ");"
882 the address of a temporary argument-tail cursor object of type
884 constructed on the assumption that
886 is the enclosing function's final keyword argument;
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.
894 is an identifier then
896 .BI "KWPARSE_EMPTY(" set ");"
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
903 marker described above.
907 function checks an keyword argument list
908 to make sure that contains no keyword arguments
909 (other than the special ones described above).
913 argument should point to a null-terminated string:
914 this will be reported as the keyword set name to
917 (and likely will not)
918 refer to any defined keyword set.
919 The remaining arguments are as for
920 the keyword parsing functions
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
931 which accepts some keyword arguments,
932 and we want to write a function
934 which accepts the same keywords recognized by
936 and some additional ones.
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
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
948 by building a vector of keyword arguments,
949 collected one-by-one depending on the corresponding
952 A few macros are provided to make this task easier.
956 returns the number of keywords defined in a keyword set.
959 is a keyword-set name, then
961 .BI "KW_COUNT(" set ")"
963 returns the number of keywords defined by
965 as a constant expression of type
970 populates a vector of
972 structures from a keyword-argument structure.
977 are two keyword-set names then
979 .BI "KW_COPY(" fromset ", " toset ", " kw ", " v ", " n ");"
981 will populate the vector
983 taking argument values from
989 i.e., for every keyword defined in
991 there is a keyword defined in
993 with the same name and type.
994 The remaining arguments are as follows:
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;
1002 is a pointer to a sufficiently large vector of
1007 is an lvalue designating an object of integer type.
1008 Successive elements of
1012 are filled in to refer to
1013 the keyword arguments defined in
1017 flag is set in the argument structure pointed to by
1019 for each such argument,
1020 a pointer to the keyword name is stored in
1021 the corresponding vector element's
1024 a pointer to the argument value,
1025 held in the keyword argument structure,
1026 is stored in the vector element's
1032 is advanced so as to contain the index of the first unused element of
1035 .BI KW_COUNT( toset )
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.
1051 the parser functions generated by
1058 This is a function of two arguments:
1060 points to the name of the keyword set expected by the caller,
1061 as a null-terminated string; and
1063 is the unknown keyword which was encountered.
1066 does is invoke the function whose address is stored in
1069 with the same arguments.
1072 function never returns to its caller:
1075 function returns (which it shouldn't)
1078 writes a fatal error message to standard error
1084 points to the function
1086 which just writes an error message
1087 quoting the keyword set name
1088 and offending keyword
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.)
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.
1105 #define KWARGS_TEST(k, val) KWARGS(K(k, val) K(kw.unknown, 0))
1107 static jmp_buf kw_test_jmp;
1109 static void kw_test_unknown(const char *set, const char *kw)
1111 if (strcmp(kw, "kw.unknown")) longjmp(kw_test_jmp, 1);
1112 else longjmp(kw_test_jmp, 2);
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
1124 kw_unkhook = oldunk; \e
1127 /* Example of use */
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)
1136 .\"--------------------------------------------------------------------------
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
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
1149 that library will be (a later version) of
1151 other platforms will likely need different arrangements.
1152 The author is willing to coordinate any such efforts.
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.
1159 .\"--------------------------------------------------------------------------
1166 .\"--------------------------------------------------------------------------
1170 <mdw@distorted.org.uk>
1172 .\"----- That's all, folks --------------------------------------------------