diff options
Diffstat (limited to 'doc/ParseArgs.3')
| -rw-r--r-- | doc/ParseArgs.3 | 198 |
1 files changed, 0 insertions, 198 deletions
diff --git a/doc/ParseArgs.3 b/doc/ParseArgs.3 deleted file mode 100644 index 1ceafe5..0000000 --- a/doc/ParseArgs.3 +++ /dev/null @@ -1,198 +0,0 @@ -'\" -'\" Copyright (c) 2008 Donal K. Fellows -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.so man.macros -.TH Tcl_ParseArgsObjv 3 8.6 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_ParseArgsObjv \- parse arguments according to a tabular description -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_ParseArgsObjv\fR(\fIinterp, argTable, objcPtr, objv, remObjv\fR) -.SH ARGUMENTS -.AS "const Tcl_ArgvInfo" ***remObjv in/out -.AP Tcl_Interp *interp out -Where to store error messages. -.AP "const Tcl_ArgvInfo" *argTable in -Pointer to array of option descriptors. -.AP int *objcPtr in/out -A pointer to variable holding number of arguments in \fIobjv\fR. Will be -modified to hold number of arguments left in the unprocessed argument list -stored in \fIremObjv\fR. -.AP "Tcl_Obj *const" *objv in -The array of arguments to be parsed. -.AP Tcl_Obj ***remObjv out -Pointer to a variable that will hold the array of unprocessed arguments. -Should be NULL if no return of unprocessed arguments is required. If -\fIobjcPtr\fR is updated to a non-zero value, the array returned through this -must be deallocated using \fBckfree\fR. -.BE -.SH DESCRIPTION -.PP -The \fBTcl_ParseArgsObjv\fR function provides a system for parsing argument -lists of the form -.QW "\fB\-someName \fIsomeValue\fR ..." . -Such argument lists are commonly found both in the arguments to a program and -in the arguments to an individual Tcl command. This parser assumes that the -order of the arguments does not matter, other than in so far as later copies -of a duplicated option overriding earlier ones. -.PP -The argument array is described by the \fIobjcPtr\fR and \fIobjv\fR -parameters, and an array of unprocessed arguments is returned through the -\fIobjcPtr\fR and \fIremObjv\fR parameters; if no return of unprocessed -arguments is desired, the \fIremObjv\fR parameter should be NULL. If any -problems happen, including if the -.QW "generate help" -option is selected, an error message is left in the interpreter result and -TCL_ERROR is returned. Otherwise, the interpreter result is left unchanged and -TCL_OK is returned. -.PP -The collection of arguments to be parsed is described by the \fIargTable\fR -parameter. This points to a table of descriptor structures that is terminated -by an entry with the \fItype\fR field set to TCL_ARGV_END. As convenience, the -following prototypical entries are provided: -.TP -\fBTCL_ARGV_AUTO_HELP\fR -. -Enables the argument processor to provide help when passed the argument -.QW \fB\-help\fR . -.TP -\fBTCL_ARGV_AUTO_REST\fR -. -Instructs the argument processor that arguments after -.QW \fB\-\-\fR -are to be unprocessed. -.TP -\fBTCL_ARGV_TABLE_END\fR -. -Marks the end of the table of argument descriptors. -.SS "ARGUMENT DESCRIPTOR ENTRIES" -.PP -Each entry of the argument descriptor table must be a structure of type -\fBTcl_ArgvInfo\fR. The structure is defined as this: -.PP -.CS -typedef struct { - int \fItype\fR; - const char *\fIkeyStr\fR; - void *\fIsrcPtr\fR; - void *\fIdstPtr\fR; - const char *\fIhelpStr\fR; - ClientData \fIclientData\fR; -} \fBTcl_ArgvInfo\fR; -.CE -.PP -The \fIkeyStr\fR field contains the name of the option; by convention, this -will normally begin with a -.QW \fB\-\fR -character. The \fItype\fR, \fIsrcPtr\fR, \fIdstPtr\fR and \fIclientData\fR -fields describe the interpretation of the value of the argument, as described -below. The \fIhelpStr\fR field gives some text that is used to provide help to -users when they request it. -.PP -As noted above, the \fItype\fR field is used to describe the interpretation of -the argument's value. The following values are acceptable values for -\fItype\fR: -.TP -\fBTCL_ARGV_CONSTANT\fR -. -The argument does not take any following value argument. If this argument is -present, the int pointed to by the \fIsrcPtr\fR field is copied to the -\fIdstPtr\fR field. The \fIclientData\fR field is ignored. -.TP -\fBTCL_ARGV_END\fR -. -This value marks the end of all option descriptors in the table. All other -fields are ignored. -.TP -\fBTCL_ARGV_FLOAT\fR -. -This argument takes a following floating point value argument. The value (once -parsed by \fBTcl_GetDoubleFromObj\fR) will be stored as a double-precision -value in the variable pointed to by the \fIdstPtr\fR field. The \fIsrcPtr\fR -and \fIclientData\fR fields are ignored. -.TP -\fBTCL_ARGV_FUNC\fR -. -This argument optionally takes a following value argument; it is up to the -handler callback function passed in \fIsrcPtr\fR to decide. That function will -have the following signature: -.RS -.PP -.CS -typedef int (\fBTcl_ArgvFuncProc\fR)( - ClientData \fIclientData\fR, - Tcl_Obj *\fIobjPtr\fR, - void *\fIdstPtr\fR); -.CE -.PP -The result is a boolean value indicating whether to consume the following -argument. The \fIclientData\fR is the value from the table entry, the -\fIobjPtr\fR is the value that represents the following argument or NULL if -there are no following arguments at all, and the \fIdstPtr\fR argument to the -\fBTcl_ArgvFuncProc\fR is the location to write the parsed value to. -.RE -.TP -\fBTCL_ARGV_GENFUNC\fR -. -This argument takes zero or more following arguments; the handler callback -function passed in \fIsrcPtr\fR returns how many (or a negative number to -signal an error, in which case it should also set the interpreter result). The -function will have the following signature: -.RS -.PP -.CS -typedef int (\fBTcl_ArgvGenFuncProc\fR)( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIobjc\fR, - Tcl_Obj *const *\fIobjv\fR, - void *\fIdstPtr\fR); -.CE -.PP -The \fIclientData\fR is the value from the table entry, the \fIinterp\fR is -where to store any error messages, the \fIkeyStr\fR is the name of the -argument, \fIobjc\fR and \fIobjv\fR describe an array of all the remaining -arguments, and \fIdstPtr\fR argument to the \fBTcl_ArgvGenFuncProc\fR is the -location to write the parsed value (or values) to. -.RE -.TP -\fBTCL_ARGV_HELP\fR -. -This special argument does not take any following value argument, but instead -causes \fBTcl_ParseArgsObjv\fR to generate an error message describing the -arguments supported. All other fields except the \fIhelpStr\fR field are -ignored. -.TP -\fBTCL_ARGV_INT\fR -. -This argument takes a following integer value argument. The value (once parsed -by \fBTcl_GetIntFromObj\fR) will be stored as an int in the variable pointed -to by the \fIdstPtr\fR field. The \fIsrcPtr\fR field is ignored. -.TP -\fBTCL_ARGV_REST\fR -. -This special argument does not take any following value argument, but instead -marks all following arguments to be left unprocessed. The \fIsrcPtr\fR, -\fIdstPtr\fR and \fIclientData\fR fields are ignored. -.TP -\fBTCL_ARGV_STRING\fR -. -This argument takes a following string value argument. A pointer to the string -will be stored at \fIdstPtr\fR; the string inside will have a lifetime linked -to the lifetime of the string representation of the argument value that it -came from, and so should be copied if it needs to be retained. The -\fIsrcPtr\fR and \fIclientData\fR fields are ignored. -.SH "SEE ALSO" -Tcl_GetIndexFromObj(3), Tcl_Main(3), Tcl_CreateObjCommand(3) -.SH KEYWORDS -argument, parse -'\" Local Variables: -'\" fill-column: 78 -'\" End: |