VistaIOoption(3)

✨ VistaIOoption ✨

okay bestie, this one's a manual page from the VistaIO library — Library Functions Manual energy, and it's literally the blueprint for how a program describes its own command line options. 💅

---

🌸 NAME 🌸

VistaIOoption — a table describing command line options

---

🎀 SYNOPSIS 🎀

#include <vistaio.h>

typedef struct {
       VistaIOStringConst keyword;/* keyword signaling option */
       VistaIORepnKind repn;    /* type of value supplied by option */
       int number;              /* number of values supplied */
       VistaIOPointer value;    /* location for storing value(s) */
       VistaIOBoolean *found;   /* whether optional arg found */
       VistaIODictEntry *dict;  /* optional dict of value keywords */
       VistaIOStringConst blurb;/* on-line help blurb */
} VistaIOOptionDescRec;

typedef struct {
       int number;              /* number of arguments */
       VistaIOPointer vector;   /* vector of arguments */
} VistaIOArgVector;

#define VistaIORequiredOpt ((VistaIOBoolean *) ...)
#define VistaIOOptionalOpt ((VistaIOBoolean *) ...)

---

💖 DESCRIPTION 💖

so the routines that parse your command line options and print out help on how to use your program? they need a whole description of which options are valid. that description is a table, and every entry in that table is a VistaIOOptionDescRec record. one entry = one option, periodt. this page explains how to set up those entries for every flavor of option you might have. 🦋

an option shows up on the command line as an argument shaped like -keyword. after it, you might get extra arguments that hand over values for that option. the keyword field of a VistaIOOptionDescRec holds the keyword that identifies that option — and no, it does not include the leading - character. on an actual command line you can type that keyword in abbreviated form as long as the abbreviation is unambiguous — like, it has to match the first characters of exactly one option keyword. otherwise it's giving chaos. 😭

an option exists to communicate one or more values to your program. those values are the type named by the repn field, which holds one of these constants: VistaIOBitRepn, VistaIOUByteRepn, VistaIOSByteRepn, VistaIOShortRepn, VistaIOLongRepn, VistaIOFloatRepn, VistaIODoubleRepn, VistaIOBooleanRepn, or VistaIOStringRepn. ✨

the number field says how many values get entered with the option. if number is positive, you must supply exactly that many values on the command line. if number is zero, any number of values may be supplied — including literally none at all. flexible queen behavior. 👑

the value field is where the entered values get stored. if number is positive, value points to a vector of number entries of the type indicated by repn. (like, if number is 2 and repn is VistaIOShortRepn, then value points to a vector of two VistaIOShort's.) 🍓

if number is zero, value points to a variable of type VistaIOArgVector — a structure describing a variable-length vector. and here's the cute part: you don't have to initialize this structure before parsing your program's command line options. nope. its fields get set during parsing, telling you how many values were actually found and where the allocated memory holding them lives. the structure's number field says how many values were found. its vector field points to a vector of number elements of the type specified by repn. main character energy fr fr. 💜

the found field of a VistaIOOptionDescRec tells you whether an option is required (it must be specified on the command line) or optional (it doesn't have to be). to signal a required option — oxymoron noted 😭 — found should contain the value VistaIORequiredOpt. to signal an optional option — redundancy noted 😭 — found should contain VistaIOOptionalOpt, or the address of a VistaIOBoolean variable. when a command line gets parsed, that VistaIOBoolean variable gets set to TRUE if the option was encountered, and FALSE if it wasn't. no cap.

an option's values are entered as command line arguments in a form that depends on the option's repn field:

🌈 value formats by repn 🌈

• VistaIOBitRepn through VistaIOLongRepn — each value may be an integer number with an optional sign. if its first digit is 0, it's assumed to be an octal number. if it begins with 0x or 0X (following any sign), it's assumed to be a hexadecimal number. otherwise, it's assumed to be a decimal number. slay.
• VistaIOFloatRepn or VistaIODoubleRepn — each value may be a floating-point number. simple as that bestie 💅
• VistaIOBooleanRepn — each value may be one of the keywords false, no, or off (representing FALSE), or true, yes, or on (representing TRUE). also, if a Boolean option requires a single value and the option keyword is not followed by a recognized value keyword, a value of TRUE is assumed. sneaky but iconic. 🔥
• VistaIOStringRepn — each value is any command line argument that does not start with a single - character. but wait — an argument consisting only of - is interpreted as a string value, and an argument beginning with at least two - characters is interpreted as a string value beginning with one fewer -. these conventions let string values be told apart from options while still letting you enter literally any string value you want. genius honestly. 🧚

you can also specify a dictionary of keywords to supplement the recognized forms of option values. dictionaries get described over in the VistaIOdictionary(3) manual page. the dict field of the VistaIOOptionDescRec points to such a dictionary, or it holds NULL if there's no dictionary of keywords for that option's values. the example below shows how a dictionary gets supplied. 💖

finally, the blurb field of the VistaIOOptionDescRec holds a short string describing what the option is for or what its value arguments look like. this string gets included whenever any help information about command usage is printed. so make it cute, but make it accurate. ✨

---

👑 EXAMPLES 👑

picture a program that accepts these options:

• -in — optional, and followed by any number of string values.
• -out — optional, and followed by a single string value.
• -color — required, and followed by one of the keywords red, green, or blue.
• -scale — optional, and followed by two floating-point numbers. if not specified, this option's values should both default to 1.0.
• -iff — an optional boolean flag.

this code fragment defines an option table for that program:

static VistaIOArgVector in_args;
static VistaIOString out_arg;
static VistaIOLong color_arg;
static VistaIOFloat scale_args[2] = { 1.0, 1.0 };
static VistaIOBoolean iff_arg = FALSE;
static VistaIOBoolean in_found, out_found;

static VistaIODictEntry dictionary[] = {
       { "red", 0 },
       { "blue", 1 },
       { "green", 2 },
       { NULL }
};

static VistaIOOptionDescRec options[] = {
       { "in", VistaIOStringRepn, 0, & in_args, & in_found, NULL,
           "Image to be processed" },
       { "out", VistaIOStringRepn, 1, & out_arg, & out_found, NULL,
           "File to receive result" },
       { "color", VistaIOLongRepn, 1, & color, VistaIORequiredOpt, & dictionary,
           "Color band" },
       { "scale", VistaIOFloatRepn, 2, scale_args, VistaIOOptionalOpt, NULL,
           "Scaling in each dimension" },
       { "iff", VistaIOBooleanRepn, 1, & iff_arg, VistaIOOptionalOpt, NULL,
           "Output in UBC IFF format" }
};

this program may be invoked with any of the following commands:

program -color red

program -in file1 file2 -color red

program -in - -out file3 -color blue -scale 0.5 0.5

program -color green -iff

program -iff false -color red

---

🦋 SEE ALSO 🦋

• VistaIOParseCommand(3)
• VistaIOPrintOptions(3)
• VistaIOPrintOptionValue(3)
• VistaIOReportBadArgs(3)
• VistaIOReportUsage(3)
• VistaIOIdentifyFiles(3)
• VistaIOdictionary(3)

---

💜 AUTHOR 💜

Art Pope <pope@cs.ubc.ca>

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

---

and that's the whole page bestie, we ate and left no crumbs 💅

VistaIO Version 1.2.14 · 6 June 1994 · VistaIOoption(3) 🎀 mwah, bye! 🫶