VistaIOParseFilterCmd(3)

💖 VistaIOParseFilterCmd — like, the manual page, but make it make sense ✨

okay bestie, so this is VistaIOParseFilterCmd(3) from the Library Functions Manual — yes, the "3" means it's a library function, we love a little section-number moment 🎀

---

🌸 NAME 🌸

VistaIOParseFilterCmd — parses your command line options and filenames, no cap 💅

---

✨ SYNOPSIS ✨

#include <vistaio.h>

void VistaIOParseFilterCmd (noptions, options, argc, argv, input, output)
       int noptions, argc;
       VistaIOOptionDescRec options[noptions];
       char *argv;
       FILE *input;
       FILE *output;

---

🦋 ARGUMENTS 🦋

• noptions — tells it how many entries are chillin' in that table of option descriptors. the headcount, basically 💁‍♀️
• options — where that table of option descriptors lives. hand over the address, bestie 📍
• argc — how many command line arguments you want parsed.
• argv — the vector of command line arguments to be parsed. the whole little parade 🎀
• input — returns a pointer to the input file. the input file is set the way the command line said, or else it defaults to the standard input stream. if input is NULL, then it's assumed that no input file is required at all (so don't come for it). note that the file is opened and ready for input by the time VistaIOParseFilterCmd returns — it did the work, you just show up 🔥
• output — same energy as input, except it returns the output file, which defaults to the standard output stream.

---

👑 DESCRIPTION 👑

VistaIOParseFilterCmd is the one that parses command line options and filenames for most Vista programs. iconic behaviour, honestly. it implements the standard Vista command line options -help, -in, and -out, and it reports all the errors from parsing or from trying to open the input and output files. its major limitation? it allows at most one input file and one output file. one each, that's the rule, periodt ✋

options that are particular to your program get specified in a table, and that table is given by the noptions and options arguments. want to know the form of this table? go read the VistaIOoption(3) manual page, iykyk 📖

the argc and argv arguments to VistaIOParseFilterCmd are normally identical to the parameters of the program's main function. same vibes, same values.

VistaIOParseFilterCmd uses the first command line argument, argv[0], in a call to VistaIOSetProgramName(3) to record the program's name for future error messages. it's literally writing down your name so it can yell at you later 💀

then the remaining command line arguments get processed sequentially, one at a time, no skipping. each argument is examined to determine whether it is an initial substring of any option keyword defined in the options table. if so, arguments following the keyword may be parsed as values associated with the option, and those values get stored at the locations specified by the options table. so it's giving prefix-matching main character energy 🌟

on top of the options specified by the options table, VistaIOParseFilterCmd also recognizes -help, -in, and -out. when it encounters -help, it prints the command usage information and exits — like, gone, bye 👋 the -in and -out arguments are used to identify input and output files, as is standard for Vista programs.

---

💜 SEE ALSO 💜

VistaIOParseCommand(3), VistaIOIdentifyFiles(3), VistaIOoption(3)

---

🙈 NOTES 🙈

VistaIOParseFilterCmd may modify the argv vector of command line arguments. so don't be shocked if your argv comes back different, bestie. it's not a bug, it's the vibe. 🫶

---

💀 DIAGNOSTICS 💀

VistaIOParseFilterCmd reports errors in command line options by printing directly to the standard error stream. and for all major errors, it also exits the program with a status code of 1 rather than return to the caller. not me just leaving the function call entirely 😭 the error reports include the program name obtained from argv[0].

the following messages may be produced:

• Duplicate -option option; ignoring all but last. — the specified option was found more than once on the command line. so it keeps the last one and ignores the rest of them. the final girl of options 💅
• Option -option has incorrect value arg. — one of the values associated with -option on the command line is arg, and that arg is of the wrong form with respect to the type of value required. wrong shape, wrong type, wrong era 🌈
• Option -option requires m value(s); found only n. — the option keyword -option must be followed by n values on the command line. only m were present, though. math is not mathing 📉
• Option -option must be specified. — the option -option is required but it was not present on the command line. it's mandatory and you forgot it, sorry babe 🎀
• Unable to open input/output file filename. — an error was detected while attempting to open a file named on the command line. the file said no 🚫

---

🌟 AUTHOR 🌟

David Lowe <lowe@cs.ubc.ca>

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

---

and that's the whole page, bestie — this little legend is from VistaIO Version 1.2.14, dated 28 January 1994 🦋✨ she's vintage, she's a library function, and she ate. mwah 💖🎀👑