% limb manual
% parseopt(3)
% limb 0.1.0
% 2023-07-24

# NAME

parseopt - parse command-line options

# SYNOPSIS

    #include <limb/parseopt.h>

```pre hl
int parseopt(int <em>argc</em>, const char **<em>argv</em>, const struct option *<em>options</em>,
             unsigned int <em>flags</em>, struct parseopt *<em>ctx</em>)

const char *PO_ARG(struct parseopt *<em>ctx</em>)
u16 PO_CUR(struct parseopt *<em>ctx</em>)
int PO_IDX(struct parseopt *<em>ctx</em>)
```

# DESCRIPTION

The `parseopt`() function parses command-line arguments. Its arguments `argc`
and `argv` are the argument count and array as passed to the `main`() function
on program invocation.

The `options` argument is a pointer to the first element of an array defining
all possible options. See [[Options]] below for more.

The `flags` argument allows to enable certain options, see [[FLAGS]] below.

The last argument `ctx` is pointer to an opaque structure, that should be
initialized to *PARSEOPT_ZERO*.

When `parseopt`() returns a positive value, i.e. an option was successfully
found, the `PO_ARG`() macro will return a pointer to the option's argument if
any (NULL otherwise). It is similar to the global `optarg` from [getopt](3).

Additionally, the `PO_IDX`() macro will return the index of said option within
the `options` array.  When an error occurs, it can either be -1 or, in the case
of abbreviated long options (and more than one option did match), the
first-matching option.

When `parseopt`() returns 0, the `PO_CUR`() macro will return the index in
`argv` of the first non-option element. In that way, it is similar to the global
`optind` from [getopt](3).

## Parsing

Parsing starts at element 1, as expected from a typical `argv`.

An element of `argv` starting with '-' is treated as an option element. If
followed by a second dash, then a long option name is expected to follow, else a
short option character.

An element of "--" has special meaning, indicating the end of options and
stopping parsing, i.e. `parseopt`() will return 0 when encountered.

When an option has been identified, `parseopt`() will return its `id` if it is
non-zero, else its `shortopt` (see [[Options]] below).

Parsing stops when the first non-option element is encountered, or an element
"--" is met.

## Options

Long options do not require to be specified in full, and an abbreviation will
be recognized as long as there's no other match possible. (This behavior can be
disabled, see [[FLAGS]] below.)

When an argument is required, it can be specified within the same element,
following a '\=' for long options, or as the next element. Optional arguments
can only be specified within the same element.

An element for short options can specify more than one option in a row, so long
as they don't accept argument. When an option accepts an argument (whether
optional or not), what follows next within the element will be treated as the
option's argument. (Note that it remains possible to specify a /required/
argument as next element.)

`options` must be a pointer to the first element of an array of *struct option*,
which contains the following members :

        const char  shortopt;
        const char *longopt;
        u16 arg     : 2;
        u16 flags   : 10;
        int id;

The meanings of different members are :

: `shortopt`
:: The character of the short option. Obviously this should be a character that
:: can be found on the command line. Valid values are comprised between 33
:: (0x21) and 126 (0x7E), which includes all alphanumeric ASCII characters.

: `longopt`
:: The name of the long option.

: `arg`
:: One of the constants *ARG_NONE*, *ARG_REQ* or *ARG_OPT* to indicate whether
:: the option takes no argument, requires an argument, or accepts an optional
:: argument, respectively.

: `flags`
:: Not used, leave at 0. (See [loadopt](3) for possible use.)

: `id`
:: An integer value unique to this option, to recognize when it is parsed. It
:: must be a value >= 128 (*OPTID_FIRST*), or 0 (*OPTID_SHORTOPT*) in which
:: case `shortopt` will be returned instead.
:: ! INFO:
:: ! Other values (between 1 and 32) are reserved for internal use.

To define options you can use the following convenience macros :

: *OPTION_ARG_NONE*(`shortopt`, `longopt`, `flags`, `id`)
:: To define an option taking no arguments

: *OPTION_ARG_OPT*(`shortopt`, `longopt`, `flags`, `id`)
:: To define an option accepting an optional argument

: *OPTION_ARG_REQ*(`shortopt`, `longopt`, `flags`, `id`)
:: To define an option requiring an argument

The last element of the array must be set to *OPTION_DONE* (all members set to 0
except `flags` set to 1) to indicate the end.

# FLAGS

It is possible to define some options via the `flags` argument, whose value is
constructed as a bitwise-inclusive OR of flags from the following list :

: *PARSEOPT_STRICT*
:: Long options can not be abbreviated, and must be exact match.

: *PARSEOPT_SILENT*
:: Do not emit any warnings in case of errors.


# RETURN VALUE

If an option was successfully found, `parseopt`() returns the option's `id`
unless it is *OPTID_SHORTOPT*, in which case its `shortopt` is returned instead.
When all command-line options have been parsed it returns 0.

If an error occurs, it returns -1 and sets `errno` to indicate the error.

! NOTE:
! In case of error, `parseopt`() will also write a warning explaining the error
! on *stderr* (done through the [warn](3) family of functions), /unless/
! *PARSEOPT_SILENT* was specified in its `flags` argument.

# ERRORS

The `parseopt`() function may fail if :

: *EINVAL*
:: Option name was missing, i.e. the element was "-" only

: *ENOENT*
:: Unknown option

: *ENOMSG*
:: An option requiring an argument was found, but no argument was specified.

# SEE ALSO

[loadopt](3), [autoopt.h](0)