Tk_ParseArgv(3tk)

💖 Tk_ParseArgv 💖

okay so, welcome to the Tk_ParseArgv(3tk) page from Tk Library Procedures — this is literally the function that eats your command-line arguments and figures out what they mean, and honestly it's kind of iconic for it. 🎀

---

✨ NAME ✨

Tk_ParseArgv — process command-line options

---

🦋 SYNOPSIS 🦋

#include <tk.h>

int
Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags)

---

🌸 ARGUMENTS 🌸

• Tcl_Interp *interp (in) — the interpreter bestie you hand your error messages to. If something goes wrong, the tea gets spilled here.
• Tk_Window tkwin (in) — the window to use when the arguments specify Tk options. If it's NULL, then no Tk options get processed at all, periodt.
• int argcPtr (in/out) — pointer to the number of arguments in argv. It gets modified so it holds the number of unprocessed arguments that are still hanging around after the call. glow-up.
• const char **argv (in/out) — the command line arguments that got passed to your main program. Also modified, so it holds the unprocessed arguments left over after the call. 💅
• Tk_ArgvInfo *argTable (in) — an array of argument descriptors, terminated by the element whose type is TK_ARGV_END. It's the menu, basically.
• int flags (in) — if it's non-zero, it specifies one or more flags that control how the arguments get parsed. Different flags can be OR'ed together. The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG, TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS. 🫶

---

👑 DESCRIPTION 👑

Tk_ParseArgv processes an array of command-line arguments according to a table describing the kinds of arguments that are expected. Every single argument in argv gets processed in turn: if it matches one of the entries in argTable, that argument gets processed according to that entry and then discarded. The arguments that don't match anything in argTable get copied down to the beginning of argv (keeping their original order, no chaos) and handed back to the caller.

At the end of the call, Tk_ParseArgv sets *argcPtr to hold the number of arguments left in argv, and argv[*argcPtr] will hold the value NULL. Normally, Tk_ParseArgv assumes argv[0] is a command name, so it gets treated like an argument that doesn't match argTable and gets returned to the caller. BUT — if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in flags, then argv[0] gets processed just like all the other elements of argv. main character treatment for argv[0], fr fr.

Tk_ParseArgv normally returns the value TCL_OK. If an error happens while parsing the arguments, then TCL_ERROR is returned and Tk_ParseArgv leaves an error message in the result of interpreter interp, in the standard Tcl fashion. 😭 In the event of an error return, *argvPtr will not have been modified, but argv could have been partially modified. The possible causes of errors are explained below. (yes bestie, there are more parts coming, we're not done)

The argTable array specifies the kinds of arguments that are expected; each of its entries has the following structure:

typedef struct {
    const char *key;
    int type;
    void *src;
    void *dst;
    const char *help;
} Tk_ArgvInfo;

The key field is a string such as -display or -bg that gets compared with the values in argv. Type indicates how to process an argument that matches key (more on this below, keep scrolling 🌈). Src and dst are additional values used in processing the argument. Their exact usage depends on type, but typically src indicates a value and dst indicates where to store the value. The char * declarations for src and dst are just placeholders: the actual types may be different. Lastly, help is a string giving a brief description of this option; this string gets printed when users ask for help about command-line options. 💖

When processing an argument in argv, Tk_ParseArgv compares the argument to each of the key's in argTable. Tk_ParseArgv selects the first specifier whose key matches the argument exactly, if such a specifier exists. Otherwise, Tk_ParseArgv selects a specifier for which the argument is a unique abbreviation. If the argument is a unique abbreviation for more than one specifier, then an error is returned. And if there's no matching entry in argTable at all, then the argument gets skipped and returned to the caller. no notes. ✨

Once a matching argument specifier is found, Tk_ParseArgv processes the argument according to the type field of the specifier. The argument that matched key is called "the matching argument" in the descriptions below. As part of the processing, Tk_ParseArgv may also use the next argument in argv after the matching argument, which is called "the following argument". The legal values for type, and the processing that they cause, are as follows:

---

🎀 TK_ARGV_END 🎀

Marks the end of the table. The last entry in argTable must have this type; all of its other fields are ignored and it will never match any arguments. It's the period at the end of the sentence, bestie.

🎀 TK_ARGV_CONSTANT 🎀

Src is treated as an integer and dst is treated as a pointer to an integer. Src is stored at *dst. The matching argument is discarded. ✨

🎀 TK_ARGV_INT 🎀

The following argument must contain an integer string in the format accepted by strtol (e.g. 0 and 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). Dst is treated as a pointer to an integer; the following argument is converted to an integer value and stored at *dst. Src is ignored. The matching and following arguments are discarded from argv. 💅

🎀 TK_ARGV_FLOAT 🎀

The following argument must contain a floating-point number in the format accepted by strtol. Dst is treated as the address of a double-precision floating point value; the following argument is converted to a double-precision value and stored at *dst. The matching and following arguments are discarded from argv. 🍓

🎀 TK_ARGV_STRING 🎀

In this form, dst is treated as a pointer to a (char *); Tk_ParseArgv stores at *dst a pointer to the following argument, and discards the matching and following arguments from argv. Src is ignored. 🌸

🎀 TK_ARGV_UID 🎀

This form is similar to TK_ARGV_STRING, except that the argument is turned into a Tk_Uid by calling Tk_GetUid. Dst is treated as a pointer to a Tk_Uid; Tk_ParseArgv stores at *dst the Tk_Uid corresponding to the following argument, and discards the matching and following arguments from argv. Src is ignored. 🧚

🎀 TK_ARGV_CONST_OPTION 🎀

This form causes a Tk option to be set (as if the option command had been invoked). The src field is treated as a pointer to a string giving the value of an option, and dst is treated as a pointer to the name of the option. The matching argument is discarded. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist). 🙈

🎀 TK_ARGV_OPTION_VALUE 🎀

This form is similar to TK_ARGV_CONST_OPTION, except that the value of the option is taken from the following argument instead of from src. Dst is used as the name of the option. Src is ignored. The matching and following arguments are discarded. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist). 💜

🎀 TK_ARGV_OPTION_NAME_VALUE 🎀

In this case the following argument is taken as the name of a Tk option and the argument after that is taken as the value for that option. Both src and dst are ignored. All three arguments are discarded from argv. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist). 🌈

🎀 TK_ARGV_HELP 🎀

When this kind of option is encountered, Tk_ParseArgv uses the help fields of argTable to format a message describing all the valid arguments. The message is placed in interpreter interp's result and Tk_ParseArgv returns TCL_ERROR. When this happens, the caller normally prints the help message and aborts. If the key field of a TK_ARGV_HELP specifier is NULL, then the specifier will never match any arguments; in this case the specifier simply provides extra documentation, which will be included when some other TK_ARGV_HELP entry causes help information to be returned. 🫶

🎀 TK_ARGV_REST 🎀

This option is used by programs or commands that allow the last several of their options to be the name and/or options for some other program. If a TK_ARGV_REST argument is found, then Tk_ParseArgv does not process any of the remaining arguments; it returns them all at the beginning of argv (along with any other unprocessed arguments). In addition, Tk_ParseArgv treats dst as the address of an integer value, and stores at *dst the index of the first of the TK_ARGV_REST options in the returned argv. This allows the program to distinguish the TK_ARGV_REST options from other unprocessed options that preceded the TK_ARGV_REST. 👑

🎀 TK_ARGV_FUNC 🎀

For this kind of argument, src is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the following structure:

int
func(dst, key, nextArg)
    char *dst;
    char *key;
    char *nextArg;
{
}

The dst and key parameters will contain the corresponding fields from the argTable entry, and nextArg will point to the following argument from argv (or NULL if there are not any more arguments left in argv). If func uses nextArg (so that Tk_ParseArgv should discard it), then it should return 1. Otherwise it should return 0 and TkParseArgv will process the following argument in the normal fashion. In either event the matching argument is discarded. 🔥

🧚 TK_ARGV_GENFUNC 🧚

okay bestie this one is the general procedural escape hatch — the "fine, you handle it yourself" option. It takes src and treats it as the address of a procedure, then hands that procedure all of the remaining arguments. That procedure has to look exactly like this:

int
genfunc(dst, interp, key, argc, argv)
    char *dst;
    Tcl_Interp *interp;
    char *key;
    int argc;
    char **argv;
{
}

So like, dst and key are gonna hold the matching fields from the argTable entry — no surprises there. interp is literally the same interp argument that got passed to Tcl_ParseArgv, same one, no swap. And argc/argv? Those point at every option that comes after the one that matched. All of them. The whole squad. 💅

Now genfunc should act like a mini Tk_ParseArgv: chew through as many of those remaining arguments as it can handle, then give back whatever's left by compacting them to the front of argv, starting right at argv[0]. It returns a count of how many arguments are still hanging out in argv, and then Tk_ParseArgv takes over and processes those leftovers. 🫶

But if genfunc hits an error? 😭 It has to leave an error message in interpreter interp's result the usual Tcl way, and return -1. When that happens, Tk_ParseArgv aborts its processing and returns TCL_ERROR. No take-backs.

---

✨ FLAGS ✨

• TK_ARGV_DONT_SKIP_FIRST_ARG — normally Tk_ParseArgv treats argv[0] like a program or command name and just hands it back to you as if it never matched argTable at all. Give this flag and argv[0] gets zero special treatment. It's just another argument now, bestie.
• TK_ARGV_NO_ABBREV — by default Tk_ParseArgv is chill and accepts unique abbreviations for the key values in argTable. Set this and only exact matches are acceptable. No vibes-based guessing. ⭐
• TK_ARGV_NO_LEFTOVERS — normally unrecognized arguments get returned to the caller like "here, you deal with this." But if this bit is set in flags, Tk_ParseArgv will return an error the second it bumps into any argument that doesn't match argTable. The one and only exception? argv[0], which still comes back to you with no errors, as long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified. 🎀
• TK_ARGV_NO_DEFAULTS — normally Tk_ParseArgv searches an internal table of standard argument specifiers on top of argTable. Set this bit in flags and it uses only argTable, zero default table, none, gone. 💀

---

🌸 EXAMPLE 🌸

Here's a whole argTable definition plus some sample command lines that actually use the options. And bestie, watch what happens to argc and argv: arguments that Tk_ParseArgv processes get eliminated from argv, and argc gets updated to reflect the smaller number of arguments. Iconic behavior honestly. 👑

/*
 * Define and set default values for globals.
 */
int debugFlag = 0;
int numReps = 100;
char defaultFileName[] = "out";
char *fileName = defaultFileName;
Boolean exec = FALSE;

/*
 * Define option descriptions.
 */
Tk_ArgvInfo argTable[] = {
    {"-X", TK_ARGV_CONSTANT, (char *) 1, &debugFlag,
        "Turn on debugging printfs"},
    {"-N", TK_ARGV_INT, NULL, &numReps,
        "Number of repetitions"},
    {"-of", TK_ARGV_STRING, NULL, &fileName,
        "Name of file for output"},
    {"x", TK_ARGV_REST, NULL, &exec,
        "File to exec, followed by any arguments (must be last argument)."},
    {NULL, TK_ARGV_END, NULL, NULL,
        NULL}
};

int main(int argc, char *argv[])
{
    ...

    if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
        fprintf(stderr, "%s\n", Tcl_GetString(Tcl_GetObjResult(interp)));
        exit(1);
    }

    /*
     * Remainder of the program.
     */
}

Also lowkey important: default values can totally be assigned to the variables named in argTable — those variables only get overwritten if the specific arguments are actually present in argv. So your defaults stay cozy until something shows up to replace them. 🦋

Here are some example command lines and their effects:

prog -N 200 infile        # just sets the numReps variable to 200
prog -of out200 infile    # sets fileName to reference "out200"
prog -XN 10 infile        # sets the debug flag, also sets numReps

And in all of the examples above, argc gets set by Tk_ParseArgv to 2, argv[0] will be "prog", argv[1] will be "infile", and argv[2] will be NULL. That's the whole vibe check right there. ✨

---

💖 KEYWORDS 💖

arguments, command line, options

---

and that's the whole page, bestie!! 💜 we did it!! this was Tk_ParseArgv(3tk) from the Tk crew — go forth and parse those arguments with main character energy, no cap, periodt. 🌈🫶🎀