1Tcl_ParseArgsObjv(3)        Tcl Library Procedures        Tcl_ParseArgsObjv(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_ParseArgsObjv - parse arguments according to a tabular description
9

SYNOPSIS

11       #include <tcl.h>
12
13       int
14       Tcl_ParseArgsObjv(interp, argTable, objcPtr, objv, remObjv)
15

ARGUMENTS

17       Tcl_Interp *interp (out)                    Where  to  store error mes‐
18                                                   sages.
19
20       const Tcl_ArgvInfo *argTable (in)           Pointer to array of  option
21                                                   descriptors.
22
23       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
31       Tcl_Obj *const *objv (in)                   The  array  of arguments to
32                                                   be parsed.
33
34       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

DESCRIPTION

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
54       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
62       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
67       TCL_ARGV_AUTO_HELP
68              Enables  the  argument processor to provide help when passed the
69              argument “-help”.
70
71       TCL_ARGV_AUTO_REST
72              Instructs the argument processor that arguments after  “--”  are
73              to be unprocessed.
74
75       TCL_ARGV_TABLE_END
76              Marks the end of the table of argument descriptors.
77
78   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
82              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
91       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
97       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
101       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
107       TCL_ARGV_END
108              This value marks the end of all option descriptors in the table.
109              All other fields are ignored.
110
111       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
117       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
122                     typedef int (Tcl_ArgvFuncProc)(
123                             ClientData clientData,
124                             Tcl_Obj *objPtr,
125                             void *dstPtr);
126
127              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
134       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
141                     typedef int (Tcl_ArgvGenFuncProc)(
142                             ClientData clientData,
143                             Tcl_Interp *interp,
144                             int objc,
145                             Tcl_Obj *const *objv,
146                             void *dstPtr);
147
148              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
154       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
160       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
166       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
172       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

SEE ALSO

181       Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3)
182

KEYWORDS

184       argument, parse
185
186
187
188Tcl                                   8.6                 Tcl_ParseArgsObjv(3)
Impressum