Tcl_ParseArgsObjv(3tcl)

💖 Tcl_ParseArgsObjv 💖

okay bestie, welcome to the Tcl Library Procedures glow-up, this is the page for Tcl_ParseArgsObjv and it is literally the thing that makes -someName someValue style arguments happen ✨

---

🌸 NAME 🌸

Tcl_ParseArgsObjv — parse arguments according to a tabular description 💅

---

✨ SYNOPSIS ✨

#include <tcl.h>

int
Tcl_ParseArgsObjv(interp, argTable, objcPtr, objv, remObjv)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (out) — where to store error messages. that's it, that's the job 🫶
• const Tcl_ArgvInfo *argTable (in) — pointer to the array of option descriptors.
• Tcl_Size | int *objcPtr (in/out) — a pointer to a variable holding the number of arguments in objv. it gets modified to hold the number of arguments left in the unprocessed argument list stored in remObjv. it may be (Tcl_Size *)NULL when it's not used. if it points to a variable whose type is not Tcl_Size, a compiler warning will be generated. and if your extension is compiled with -DTCL_8_API, this function will return NULL for argument lists with more than INT_MAX elements (which should trigger proper error-handling), otherwise expect it to crash 😭💀
• Tcl_Obj *const *objv (in) — the array of arguments to be parsed.
• 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 objcPtr is updated to a non-zero value, the array returned through this must be deallocated using Tcl_Free. no cap, free your memory 🧚

---

🌈 DESCRIPTION 🌈

Tcl_ParseArgsObjv provides a whole system for parsing argument lists shaped like "-someName someValue ...". this vibe is everywhere — in the arguments to a program and in the arguments to an individual Tcl command. this parser assumes the order of the arguments does not matter, except in the way that later copies of a duplicated option override earlier ones. so the last one wins, periodt 👑

the argument array is described by the objcPtr and objv parameters, and an array of unprocessed arguments is returned through the objcPtr and remObjv parameters. if no return of unprocessed arguments is desired, the remObjv parameter should be NULL.

if any problems happen — including if the "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. iconic behavior, no drama ✨

the collection of arguments to be parsed is described by the argTable parameter. this points to a table of descriptor structures that is terminated by an entry with the type field set to TCL_ARGV_END.

as convenience, the following prototypical entries are provided:

• TCL_ARGV_AUTO_HELP — enables the argument processor to provide help when passed the argument "-help". bestie said "read the docs" 📖
• TCL_ARGV_AUTO_REST — instructs the argument processor that arguments after "--" are to be unprocessed.
• TCL_ARGV_TABLE_END — marks the end of the table of argument descriptors.

---

🦋 ARGUMENT DESCRIPTOR ENTRIES 🦋

each entry of the argument descriptor table must be a structure of type Tcl_ArgvInfo. the structure is defined as this:

typedef struct {
    int type;
    const char *keyStr;
    void *srcPtr;
    void *dstPtr;
    const char *helpStr;
    void *clientData;
} Tcl_ArgvInfo;

the keyStr field contains the name of the option; by convention, this will normally begin with a "-" character. the type, srcPtr, dstPtr and clientData fields describe the interpretation of the value of the argument, as described below. the helpStr field gives some text that is used to provide help to users when they request it. 🫶

as noted above, the type field is used to describe the interpretation of the argument's value. the following values are acceptable values for type:

• TCL_ARGV_CONSTANT — the argument does not take any following value argument. if this argument is present, the (integer) value of the srcPtr field is copied to the variable pointed to by the dstPtr field. the clientData field is ignored. it just shows up and drops a number, main character energy 💅
• TCL_ARGV_END — this value marks the end of all option descriptors in the table. all other fields are ignored. that's the ✨ the end ✨
• TCL_ARGV_FLOAT — this argument takes a following floating point value argument. the value (once parsed by Tcl_GetDoubleFromObj) will be stored as a double-precision value in the variable pointed to by the dstPtr field. the srcPtr and clientData fields are ignored.
• TCL_ARGV_FUNC — this argument optionally takes a following value argument; it is up to the handler callback function passed in srcPtr to decide. that function will have the following signature:

typedef int (Tcl_ArgvFuncProc)(
        void *clientData,
        Tcl_Obj *objPtr,
        void *dstPtr);

the result is a boolean value indicating whether to consume the following argument. the clientData is the value from the table entry, the objPtr is the value that represents the following argument or NULL if there are no following arguments at all, and the dstPtr argument to the Tcl_ArgvFuncProc is the location to write the parsed value to.

• TCL_ARGV_GENFUNC — this argument takes zero or more following arguments; the handler callback function passed in srcPtr 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:

typedef Tcl_Size (Tcl_ArgvGenFuncProc)(
        void *clientData,
        Tcl_Interp *interp,
        Tcl_Size objc,
        Tcl_Obj *const *objv,
        void *dstPtr);

the clientData is the value from the table entry, the interp is where to store any error messages, objc and objv describe an array of all the remaining arguments, and the dstPtr argument to the Tcl_ArgvGenFuncProc is the location to write the parsed value (or values) to. go off, callback 🔥

• TCL_ARGV_HELP — this special argument does not take any following value argument, but instead causes Tcl_ParseArgsObjv to generate an error message describing the arguments supported. all other fields except the helpStr field are ignored. yes bestie, "help" is technically an error, that's just how it is 🙈
• TCL_ARGV_INT — this argument takes a following integer value argument. the value (once parsed by Tcl_GetIntFromObj) will be stored as an int in the variable pointed to by the dstPtr field. the srcPtr field is ignored.
• TCL_ARGV_REST — this special argument does not take any following value argument, but instead marks all following arguments to be left unprocessed. the srcPtr, dstPtr and clientData fields are ignored.
• TCL_ARGV_STRING — this argument takes a following string value argument. a pointer to the string will be stored at dstPtr; 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 srcPtr and clientData fields are ignored.

⚠️ girlypop, listen to the TCL_ARGV_STRING note. that pointer is on a timer. if you need it longer, copy it. no borrowing forever, we don't do that here 😭

---

💜 REFERENCE COUNT MANAGEMENT 💜

the values in the objv argument to Tcl_ParseArgsObjv will not have their reference counts modified by this function. the interpreter result may be modified on error; the values passed should not be the interpreter result with no further reference added. stay safe out there, handle your refcounts 🫶

---

🌟 SEE ALSO 🌟

• Tcl_GetIndexFromObj(3tcl)
• Tcl_Main(3tcl)
• Tcl_CreateObjCommand(3tcl)

---

👑 KEYWORDS 👑

argument, parse

---

okay that's the whole page, you're officially a Tcl_ParseArgsObjv girlie now 💖 this was the Tcl 8.6 era of the manual, and honestly? she ate. go parse something with a cute little argTable and text me when it works, mwah 🎀🦋✨