Home

Plib 6.1.8 [STABLE]

Documentation for other versions may vary slightly (or moderately).

Description and dependancies

Plib is a static, header-only library that implements simple argument parsing. Static in this case means that zero memory allocation is used. Plib is also a minimal dependancy library, the only dependancies can be read at the top of the file:

#include <stdint.h>
#include <inttypes.h>
#include <sys/types.h>
#include <stdbool.h>

Parsing Style

How argument parsing functions

Plib uses a character-split method of locating and processing system arguments. What this means is that plib will take in a string argument one at a time and split it by a certain character with the first half being the argument name and the second part being the argument value, eg:

./my_program --test=123

argument given: "--test=123"
splitting at the '=' gives us,
argument name  : "--test"
argument value : "123"

As displayed in the mock output if we used the "split char" of '=' it would result in the argument name being "--test" and the value of the argument being "123". You can easily change the "split char" character as it is the final argument parsed into the raw parsing function.

Plib has support for two given flag names, the secondary flag name (often refered too as the "short" name) works just as the regular flag name would, I implemented this as a way to give shorter argument names as a secondary option as you see in majority of command line programs. An example of how a secondary argument is used would be with globally recognised arguments like --help which usually have a secondary option like -h.

Brief Introduction

Explaining how plib is used

Because Plib is completely static you don't have to worry about any exit functions, this still leaves us with three steps; initialization, processing and optionally error handling.

Initialization

How to create arguments

In plib each argument is held as a plib_Argument struct, each argument can have a flag name, short name and description given to it, along with this several special properties can be given to change the arguments behaviour.

// plib_Argument:
struct plib_Argument {
	char *flag;
	char *shrt;
	char *desc;
	
	uint8_t opt; 
	int idx;
	int vals[PL_MAX_ARG_V];
};

To initialize an argument you must first create an array of plib_Argument's:

static struct plib_Argument pl[1] = {
    { "flag name", "secondary name", "description" } 
    // ...
};

Note, use an enumerator to keep track of argument names (example in example.c)

Pre-processing

Plib has a loop-and-pointer based pre-processing system, there are several macros that let you loop through a range or individual argument(s). In each loop a global pointer is assigned the current index of the loop, these macros are as follows:

• plib_forEach(index_one, index_two, argument_array), Loop through a range in the argument array (pl as shown previously).
• plib_ForAll(argument_array), Loop through ALL arguments with a given argument array.
• plib_For(argument), as mentioned before each loop assigns a global variable the pointer value of the current argument index, this macro simply does that for a single argument, eg pl[0] from the prior section.

The global argument can be used under the varaible plib_Arg.

---

Now these loops arn't for nothing, inside a loop you can use the plib_ToggleProperty(argument_pointer, property) macro to change the macro simply does that for a single argument, eg pl[0] from the prior section.

Now these loops arn't for nothing, inside a loop you can use the plib_ToggleProperty(argument_pointer, property) macro to change the properties of an argument, the properties built into Plib are as follows:

• PLIB_ENABLED, Enables the current argument (arguments are disabled by default).
• PLIB_TAKESVALUE, Does the argument take a value? Plib will throw an exception if an argument is marked as taking a value but none are provided.
• PLIB_TAKESVALUES, Does the argument take multiple values. Note that PLIB_TAKESVALUE must be enabled also for this prop to work.
• PLIB_REQUIRED, Plib will throw an exception if a required argument is not used.

---

Each argument must be initialized before use, you can do this using the plib_CreateArgCount(argument_array). Alternatively if you'd like to run a ForAll loop directly after using the plib_CreateArgCount macro you can use plib_CreateArgAndForAll(argument_array), this means you could easily initialize the arguments and enable all of them like so:

plib_CreateArgAndForAll (pl)
    plib_ToggleProperty (plib_Arg, PLIB_ENABLED);       

Processing

This may be significantly different if you are using the wrong version.

To process arguments you can use the plib_Parse(argc, argv, argument_array, split_char) function, this function takes in argc and argv along with your defined argument list (pl) and the "split char" mentioned in the "Parsing Style" section.

Alternatively you can use the ifnot_plib_Parse(argument_array) macro which pulls argc and argv as long as they exist, it uses a default = as the ssplit char and returns 1 if plib_Parse threw an exception and a 0 if nothing went wrong.

Error handling

Plib was made with error transparency in mind, there is a global variable that holds data for both the cause and reason of any given error. As mentioned before you can use ifnot_plib_Parse(argument_array) to catch exceptions in the parsing process. Additionally you can use plib_ErrorReason to get the error code string (_plib_return_strings), these strings can actually be changed to give different messages on each error, this is a good idea if your project requires verbose error reporting. plib_ErrorCause(argument_array) will return the string of the argument that caused the error, if the error was a required argument error then it will return the flag name of the argument that was not given, this is why we must provide the argument array into it. plib_ErrorCause(argument_array) requires that argv be defined. You can reference PL_RETURN.index to get the index in argv of an argument that caused an exception, note that this index will be the index of an argument in your argument array if the error is a required argument array exception.

As requested with every other example, please read example.c for an idea of how to do this if you are stuck.

---

Help dialogs are built into Plib. You can use the plib_HelpMenu(argument_array) macro to display a basic arguments menu, this macro requires <stdio.h> for printf.

Post-parse processing

Now its time to actually fetch some of the arguments parsed. Because Plib uses a loop-and-pointer based system there are macros for both regular argument variables and pointer values. the regular functions are prefixed with plib_S (S for static) where the pointer macros are just prefixed with plib_, prefix the following with either of these depending on your variable type. Also note all of the following take one argument (unless stated otherwise) that being the actual argument you want to get the value or information about.

• ArgRun, evaluates to true if the argument has been run, evaluates to false if the argument was not run.
• ArgValueCount, Return the amount of values an argument was given.
• ArgValue(argument, number), returns the th value given to an argument. ensure that the number is less than that of ArgValueCount.
• ArgGetFirstValue, Returns the first value of an argument.

Read plib6.h for more information (specifically the very bottom is where these macros are).

Final debrief

Thank you for reading the entire documentation! I wish you the best of luck in using my library, If you have any questions refer to plib6.h where there are comments over more difficult sections, also feel free to open a new issue or email me directly for more information.

If you are struggling at any point for a visual representation of how plib works I strongly advise you view example.c which contains implementation examples.