VistaIOParseCommand(3)

💖 NAME 💖

VistaIOParseCommand — bestie, this is the one that parses your command line arguments for you ✨

(also, hi, this page lives in the Library Functions Manual, just so you know where you are 🫶)

---

🌸 SYNOPSIS 🌸

#include <vistaio.h>

VistaIOBoolean VistaIOParseCommand (noptions, options, argc, argv)
       int noptions, *argc;
       VistaIOOptionDescRec options[noptions];
       char *argv;

---

🎀 ARGUMENTS 🎀

• noptions — how many entries are chillin' in the table of option descriptors. Just the count, that's it 💅
• options — where that table of option descriptors actually lives. Give it the location, bestie 📍
• argc — on the way in: how many command line arguments we're parsing. On the way out: it hands you back the number of arguments that were not recognized as valid options. She's a two-way street 👑
• argv — on the way in: the vector of command line arguments to parse. On the way out: a vector of the arguments that weren't recognized as valid options. Also does double duty, icon behavior 🦋

---

✨ DESCRIPTION ✨

So basically, VistaIOParseCommand parses your command line arguments according to a table that describes which command line options are valid. The VistaIOoption(3) manual page is the one that spills the tea on what goes in that table and what forms command line options are allowed to take. The noptions and options arguments tell it how long the table is and where to find it. Periodt.

The argc and argv arguments you pass to VistaIOParseCommand are normally literally the same ones your program's main function got. But lowkey watch out — you pass the address of main's argc, not the actual value of argc. Yes, really. Do not skip that ampersand, I'm begging 😭

VistaIOParseCommand takes the very first command line argument, argv[0], and feeds it to a call to VistaIOSetProgramName(3) so the program's name gets recorded for future error messages. Cute, right? It remembers who it's talking to 💖

Then it works through the rest of the command line arguments in order, from argv[1] all the way through argv[*argc - 1]. For each argument it checks: is this an initial substring of any option keyword defined in the options table? If yes, the arguments that come after that keyword might get parsed as values belonging to that option, and those values get stored at the locations the options table points to. And if the option takes a variable number of values, VistaIOParseCommand will allocate a vector of exactly the right length for them. No cap, it does the math for you 🧮 After the value arguments, it expects either another option keyword or the end of the command line argument list. That's the vibe check.

If VistaIOParseCommand runs into an argument that could be an option keyword (based on where it sits among the command line arguments) but it isn't one of the keywords defined in the table? It just... glides right past it. No complaints, no drama. Any arguments like that which don't get recognized are handed back to you, the caller — peep the RETURN VALUES section below 👇

VistaIOParseCommand also keeps receipts: it checks that every required option shows up exactly once on the command line, and that every optional option shows up at most once. If an option shows up more than once, it prints a message and only the values from the last appearance of that option survive. Sorry to the earlier ones, they didn't make the cut 💀 Also — the options table entry for an optional option can specify the location of a VistaIOBoolean that gets set to tell you whether that option was encountered. VistaIOParseCommand sets that VistaIOBoolean to TRUE if the option showed up, and FALSE if it didn't. Binary. Slay.

On top of all the options in your table, VistaIOParseCommand always recognizes the option -help. The moment it sees -help, it ignores every remaining argument on the command line, sets *argc to 1 to say "yeah all arguments are accounted for," and returns FALSE to say the command line parse did not complete successfully. Those returned indications are normally what makes the caller print the command usage info — you can see exactly that in the code example below 🔥

---

👑 RETURN VALUES 👑

VistaIOParseCommand returns FALSE if an option on the command line doesn't have the right number of values of the right form. It also returns FALSE if a required option is missing from the command line arguments. And finally, it returns FALSE if it bumps into a -help option. Otherwise? TRUE, bestie. So TRUE means the command was parsed successfully by VistaIOParseCommand and your program is free to keep going on that basis 💅

VistaIOParseCommand also hands you back a revised argv containing only the command line arguments it didn't recognize as valid options, and in *argc it gives you the count of those arguments. It shuffles the elements of the argv vector of strings around so that all the arguments that aren't part of valid options end up in the first *argc elements. At minimum there will be one of them: the program's name. Others might be options that the programmer, for whatever reason, chose not to handle with VistaIOParseCommand — like, say, X Windows parameters that have to go to XtDisplayInitialize(3Xt) instead. You do you, boo 🦋

---

🌈 EXAMPLES 🌈

Here's a code fragment that parses command line arguments with VistaIOParseCommand. Whatever it doesn't recognize gets parsed some other way (for example, by XtDisplayInitialize(3Xt)). And then, if any arguments are still left over — not recognized by either parser — they get printed along with info on the valid program options. Full circle, iconic 💖

#include <vistaio.h>

static VistaIOOptionDescRec options[] = { /* option table entries */ };

int main (int argc, char *argv)
{
       if (! VistaIOParseCommand (VistaIONumber (options), options, & argc, argv))
              goto Usage;

       /* Parse arguments remaining in argv[1] ... argv[argc - 1]. */

       ...

       if (argc > 1) {
              VistaIOReportBadArgs (argc, argv);
Usage:
              VistaIOReportUsage (argv[0], VistaIONumber (options), options, NULL);
              fprintf (stderr, "    plus any X Windows options.\n\n");
              exit (1);
       }

       ...

}

---

💜 SEE ALSO 💜

• VistaIOReportBadArgs(3)
• VistaIOReportUsage(3)
• VistaIOIdentifyFiles(3)
• VistaIOoption(3)

---

🔥 DIAGNOSTICS 🔥

VistaIOParseCommand reports errors in command line options by printing directly to the standard error stream. Error reports include the program name it got from argv[0]. Here's the lineup of messages it might produce:

• Duplicate -option option; ignoring all but last.'' — that option was found more than once on the command line.
• Option -option has incorrect value arg.'' — one of the values associated with -option on the command line is arg, and it's the wrong form compared to the type of value that was required.
• Option -option requires m value(s); found only n.'' — the option keyword -option has to be followed by n values on the command line. Only m were actually there though. Oops 🙈
• Option -option must be specified.'' — the option -option is required but it never showed up on the command line. Not invited to the party, apparently.

On top of all that, VistaIOParseCommand may invoke VistaIOError with this message:

• Parsing of command options with type values is not implemented.'' — options, as described in the options table, have to take values that are of type VistaIOBit, VistaIOUByte, VistaIOSByte, VistaIOShort, VistaIOLong, VistaIOFloat, VistaIODouble, VistaIOBoolean, or VistaIOString. VistaIOParseCommand hit a table entry describing an option of type type instead. Rude of that table, honestly 😭

---

🌸 AUTHOR 🌸

Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

---

💌 okay bestie that's the whole page!! and just so we're keeping it 100 — this was VistaIO Version 1.2.14, dated 24 April 1993, filed under VistaIOParseCommand(3). go parse those args, you absolute main character 👑✨🎀