stparseargs(3)

💖 stparseargs(3) 💖

okay bestie, this one lives in section 3 of the manual, and it's brought to you by the ShapeTools Toolkit Library — yes, that ShapeTools, the icon itself. buckle up, we're parsing command line args and it's giving main character energy 🎀

---

✨ NAME ✨

stParseArgs, stShortUsage — parse command line arguments 🫶

---

🌸 SYNOPSIS 🌸

#include <config.h>
#include <sttk.h>

int stParseArgs (int argCount, char *argVector,
                 int newArgCount, char *(*newArgVector[]), OptDesc
optionList[]);

voidstShortUsage (char *programName, OptDesc optionList[], char
*extraText);

---

🦋 DESCRIPTION 🦋

so stParseArgs is the one doing the actual work, and here's the tea: it parses the command line for options that you already declared in an option description list. you hand it your program's argument count and argument vector as argCount and argVector, and the option description list as optionList, and it just... handles it. periodt.

what it does is filter out all the known options (known = the ones from your option list) along with their arguments, and then it gives you back whatever tokens are left over from the command line in newArgVector with newArgCount. so like, the leftovers are yours to play with 💅

⚠️ important bestie: options on the command line must be preceded by a minus sign. no minus sign, no recognition. it's just not gonna happen, no cap.

the first entry in the argument vector — that's your program name — passes through the function without any damage. untouched. iconic behavior honestly.

and the best part? stParseArgs can be invoked multiple times with different option lists. she's flexible like that 🧚

---

🍓 the option list, explained

the option list is an array of option definitions that looks exactly like this:

typedef struct {
  char *OptName;
  int  OptKind;
  int  (*OptFunc)();
  int  *OptVar;
  char *OptStr;
} StOptDesc;

and the array gets finished off by an option definition that contains only null entries. that's the little "we're done here" signal, okay?

• OptName — the name of the option exactly how it shows up on the command line, but without the leading minus sign. don't include it, bestie.
• OptKind — a flag field that defines both the option type and the kind of action to be performed. two jobs, one field, she's versatile.

---

🌈 valid option types (aka OptKind tea)

• PSWITCH — the option is a switch and has no argument. this is the default, so if you don't say otherwise, this is what you get ✨
• PARG — the option has an argument immediately following the option on the command line.
• POARG — the option has an optional argument. cute and chill about it.

---

👑 the actions (what actually happens when an option shows up)

when an option shows up on the command line, the action performed refers either to OptFunc — a function that your application defines — or to OptVar — an application variable associated with that option. your choice, your vibe. the different kinds of action are:

• PCALL — call the function OptFunc. this is the default 💖
• PSET — set the variable OptVar to 1 (TRUE).
• PCLEAR — set the variable OptVar to 0 (FALSE).
• PTOGGLE — toggle the value of the variable OptVar between 1 (TRUE) and 0 (FALSE). flip flopping, but make it intentional 🦋
• PUSAGE — call stShortUsage (more on her below 👇).
• PFAIL — call stShortUsage (again, below 👇) and terminate program execution with return code 1. yeah. she said goodbye fr fr 💀

---

🎀 a little example, because examples ate

the following example shows some typical option definitions:

StOptDesc bindOptions[] = {
  { "help",    PFAIL,        NULL,           NULL,         NULL },
  { "trace",   PSWITCH|PSET, NULL,           &atBindTrace, NULL },
  { "since",   PCALL|PARG,   handleBaseline, NULL,         NULL },
  { "version", PCALL,        printVersion,   NULL,         NULL },
  { NULL,      NULL,         NULL,           NULL,         NULL },
};

see how that last line is all nulls? that's the array saying "that's a wrap" 🌸

---

💜 stShortUsage

stShortUsage generates a short usage message from the given optionList. the message starts with the programName and then lists all option in the option list (yes, every single one, she's thorough 👑). at the end, extraText gets added — but only if you actually gave her one. and where does this masterpiece go? standard error, obviously. 💅

---

🫶 reminder: stParseArgs returns an int, so check that return value, bestie. don't be out here ignoring her.

---

and that's the whole page, no notes. this was written for sttk-1.7, dated Thu Jun 24 17:43:31 1993 — yeah she's vintage, she's a classic, we stan a timeless icon 🎀✨