1Tcl_ParseArgsObjv(3) Tcl Library Procedures Tcl_ParseArgsObjv(3)
2______________________________________________________________________________
6
8 Tcl_ParseArgsObjv - parse arguments according to a tabular description
9
11 #include <tcl.h>
12 int
14 Tcl_ParseArgsObjv(interp, argTable, objcPtr, objv, remObjv)
15
17 Tcl_Interp *interp (out) Where to store error mes‐
18 sages.
19 const Tcl_ArgvInfo *argTable (in) Pointer to array of option
21 descriptors.
22 int *objcPtr (in/out) A pointer to variable hold‐
24 ing number of arguments in
25 objv. Will be modified to
26 hold number of arguments
27 left in the unprocessed
28 argument list stored in
29 remObjv.
30 Tcl_Obj *const *objv (in) The array of arguments to
32 be parsed.
33 Tcl_Obj ***remObjv (out) Pointer to a variable that
35 will hold the array of
36 unprocessed arguments.
37 Should be NULL if no return
38 of unprocessed arguments is
39 required. If objcPtr is
40 updated to a non-zero
41 value, the array returned
42 through this must be deal‐
43 located using ckfree.
44______________________________________________________________________________
45
47 The Tcl_ParseArgsObjv function provides a system for parsing argument
48 lists of the form “-someName someValue ...”. Such argument lists are
49 commonly found both in the arguments to a program and in the arguments
50 to an individual Tcl command. This parser assumes that the order of the
51 arguments does not matter, other than in so far as later copies of a
52 duplicated option overriding earlier ones.
53 The argument array is described by the objcPtr and objv parameters, and
55 an array of unprocessed arguments is returned through the objcPtr and
56 remObjv parameters; if no return of unprocessed arguments is desired,
57 the remObjv parameter should be NULL. If any problems happen, including
58 if the “generate help” option is selected, an error message is left in
59 the interpreter result and TCL_ERROR is returned. Otherwise, the inter‐
60 preter result is left unchanged and TCL_OK is returned.
61 The collection of arguments to be parsed is described by the argTable
63 parameter. This points to a table of descriptor structures that is ter‐
64 minated by an entry with the type field set to TCL_ARGV_END. As conve‐
65 nience, the following prototypical entries are provided:
66 TCL_ARGV_AUTO_HELP
68 Enables the argument processor to provide help when passed the
69 argument “-help”.
70 TCL_ARGV_AUTO_REST
72 Instructs the argument processor that arguments after “--” are
73 to be unprocessed.
74 TCL_ARGV_TABLE_END
76 Marks the end of the table of argument descriptors.
77 ARGUMENT DESCRIPTOR ENTRIES
79 Each entry of the argument descriptor table must be a structure of type
80 Tcl_ArgvInfo. The structure is defined as this:
81 typedef struct {
83 int type;
84 const char *keyStr;
85 void *srcPtr;
86 void *dstPtr;
87 const char *helpStr;
88 ClientData clientData;
89 } Tcl_ArgvInfo;
90 The keyStr field contains the name of the option; by convention, this
92 will normally begin with a “-” character. The type, srcPtr, dstPtr and
93 clientData fields describe the interpretation of the value of the argu‐
94 ment, as described below. The helpStr field gives some text that is
95 used to provide help to users when they request it.
96 As noted above, the type field is used to describe the interpretation
98 of the argument's value. The following values are acceptable values for
99 type:
100 TCL_ARGV_CONSTANT
102 The argument does not take any following value argument. If this
103 argument is present, the (integer) value of the srcPtr field is
104 copied to the variable pointed to by the dstPtr field. The
105 clientData field is ignored.
106 TCL_ARGV_END
108 This value marks the end of all option descriptors in the table.
109 All other fields are ignored.
110 TCL_ARGV_FLOAT
112 This argument takes a following floating point value argument.
113 The value (once parsed by Tcl_GetDoubleFromObj) will be stored
114 as a double-precision value in the variable pointed to by the
115 dstPtr field. The srcPtr and clientData fields are ignored.
116 TCL_ARGV_FUNC
118 This argument optionally takes a following value argument; it is
119 up to the handler callback function passed in srcPtr to decide.
120 That function will have the following signature:
121 typedef int (Tcl_ArgvFuncProc)(
123 ClientData clientData,
124 Tcl_Obj *objPtr,
125 void *dstPtr);
126 The result is a boolean value indicating whether to consume the
128 following argument. The clientData is the value from the table
129 entry, the objPtr is the value that represents the following
130 argument or NULL if there are no following arguments at all, and
131 the dstPtr argument to the Tcl_ArgvFuncProc is the location to
132 write the parsed value to.
133 TCL_ARGV_GENFUNC
135 This argument takes zero or more following arguments; the han‐
136 dler callback function passed in srcPtr returns how many (or a
137 negative number to signal an error, in which case it should also
138 set the interpreter result). The function will have the follow‐
139 ing signature:
140 typedef int (Tcl_ArgvGenFuncProc)(
142 ClientData clientData,
143 Tcl_Interp *interp,
144 int objc,
145 Tcl_Obj *const *objv,
146 void *dstPtr);
147 The clientData is the value from the table entry, the interp is
149 where to store any error messages, the keyStr is the name of the
150 argument, objc and objv describe an array of all the remaining
151 arguments, and dstPtr argument to the Tcl_ArgvGenFuncProc is the
152 location to write the parsed value (or values) to.
153 TCL_ARGV_HELP
155 This special argument does not take any following value argu‐
156 ment, but instead causes Tcl_ParseArgsObjv to generate an error
157 message describing the arguments supported. All other fields
158 except the helpStr field are ignored.
159 TCL_ARGV_INT
161 This argument takes a following integer value argument. The
162 value (once parsed by Tcl_GetIntFromObj) will be stored as an
163 int in the variable pointed to by the dstPtr field. The srcPtr
164 field is ignored.
165 TCL_ARGV_REST
167 This special argument does not take any following value argu‐
168 ment, but instead marks all following arguments to be left
169 unprocessed. The srcPtr, dstPtr and clientData fields are
170 ignored.
171 TCL_ARGV_STRING
173 This argument takes a following string value argument. A pointer
174 to the string will be stored at dstPtr; the string inside will
175 have a lifetime linked to the lifetime of the string representa‐
176 tion of the argument value that it came from, and so should be
177 copied if it needs to be retained. The srcPtr and clientData
178 fields are ignored.
179
181 Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3)
182
184 argument, parse
185Tcl 8.6 Tcl_ParseArgsObjv(3)