object

# `command_line_options`

Command line options parsing predicates. Uses object-based option specifications with the `command_line_option` category.

Availability:
`logtalk_load(command_line_options(loader))`
Author: Marcus Uneson and Paulo Moura
Version: 1:1:0
Date: 2026-07-13
Compilation flags:
`static, context_switching_calls`
Imports:
`public` options
Uses:
atom
list
meta
numberlist
term_io
type
user
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `parse/4`

Parses the arguments `AppArguments` according to the option objects `OptionObjects` using default parsing options.

Compilation flags:
`static`
Template:
`parse(OptionObjects,AppArguments,Options,PositionalArguments)`
Mode and number of proofs:
`parse(+list(object),+list(atom),-list,-list(atom))` - `one_or_error`
Exceptions:
`OptionObjects` is a variable, a partial list, or contains an option object definition with an insufficiently instantiated value:
`instantiation_error`
`OptionObjects` is neither a variable nor a list of valid object identifiers:
`type_error(list(object),OptionObjects)`
An option object is missing the `name/1` predicate:
`existence_error(predicate,name/1)`
An option object predicate returns a value with an invalid type:
`type_error(Type,Term)`
An option object predicate returns a value outside the expected domain:
`domain_error(Domain,Term)`
The option set contains a duplicate option name:
`domain_error(unique_key,Name)`
The option set contains a duplicate short flag:
`domain_error(unique_short_flag,ShortFlag)`
The option set contains a duplicate long flag:
`domain_error(unique_long_flag,LongFlag)`
`AppArguments` is a variable or a partial list:
`instantiation_error`
`AppArguments` is neither a variable nor a list of atoms:
`type_error(list(atom),AppArguments)`
An unknown flag is found:
`existence_error(command_line_option,Argument)`
A flag value cannot be parsed as the option type:
`type_error(flag_value,Type)`
A short option is written using the disallowed `-f=value` syntax:
`syntax_error(disallowed: <shortflag>=<value>)`

### `parse/5`

Parses the arguments `AppArguments` according to the option objects `OptionObjects` and the parsing options `ParseOptions`. `Options` is a list of parsed options as `Name(Value)` terms by default (or `Func(Name,Value)` when the `output_functor(Func)` parse option is used). `PositionalArguments` are the remaining non-dashed arguments. `ParseOptions` include `output_functor(Func)`, `duplicated_flags(Keep)` (one of `keepfirst`, `keeplast`, `keepall`; default `keeplast`), and `allow_empty_flag_spec(Bool)` (default `true`).

Compilation flags:
`static`
Template:
`parse(OptionObjects,AppArguments,Options,PositionalArguments,ParseOptions)`
Mode and number of proofs:
`parse(+list(object),+list(atom),-list,-list(atom),+list)` - `one_or_error`
Exceptions:
`ParseOptions` is a variable, a partial list, or contains a variable option:
`instantiation_error`
`ParseOptions` is neither a variable nor a list:
`type_error(list,ParseOptions)`
An element of `ParseOptions` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element of `ParseOptions` is a compound term but not a valid option:
`domain_error(option,Option)`
`OptionObjects` is a variable, a partial list, or contains an option object definition with an insufficiently instantiated value:
`instantiation_error`
`OptionObjects` is neither a variable nor a list of valid object identifiers:
`type_error(list(object),OptionObjects)`
An option object is missing the `name/1` predicate:
`existence_error(predicate,name/1)`
An option object predicate returns a value with an invalid type:
`type_error(Type,Term)`
An option object predicate returns a value outside the expected domain:
`domain_error(Domain,Term)`
The option set contains a duplicate option name:
`domain_error(unique_key,Name)`
The option set contains a duplicate short flag:
`domain_error(unique_short_flag,ShortFlag)`
The option set contains a duplicate long flag:
`domain_error(unique_long_flag,LongFlag)`
An option has no short or long flags and empty flag specifications are disallowed:
`domain_error(non_empty_flag_spec,Name)`
`AppArguments` is a variable or a partial list:
`instantiation_error`
`AppArguments` is neither a variable nor a list of atoms:
`type_error(list(atom),AppArguments)`
An unknown flag is found:
`existence_error(command_line_option,Argument)`
A flag value cannot be parsed as the option type:
`type_error(flag_value,Type)`
A short option is written using the disallowed `-f=value` syntax:
`syntax_error(disallowed: <shortflag>=<value>)`

### `help/2`

Synthesizes a help text `Help` as an atom from the option objects `OptionObjects` using default help options.

Compilation flags:
`static`
Template:
`help(OptionObjects,Help)`
Mode and number of proofs:
`help(+list(object),-atom)` - `one_or_error`
Exceptions:
`OptionObjects` is a variable, a partial list, or contains an option object definition with an insufficiently instantiated value:
`instantiation_error`
`OptionObjects` is neither a variable nor a list of valid object identifiers:
`type_error(list(object),OptionObjects)`
An option object is missing the `name/1` predicate:
`existence_error(predicate,name/1)`
An option object predicate returns a value with an invalid type:
`type_error(Type,Term)`
An option object predicate returns a value outside the expected domain:
`domain_error(Domain,Term)`
The option set contains a duplicate option name:
`domain_error(unique_key,Name)`
The option set contains a duplicate short flag:
`domain_error(unique_short_flag,ShortFlag)`
The option set contains a duplicate long flag:
`domain_error(unique_long_flag,LongFlag)`

### `help/3`

Synthesizes a help text `Help` as an atom from the option objects `OptionObjects` using the given `HelpOptions`. `HelpOptions` include `line_width(Width)` (default 80), `min_help_width(Width)` (default 40), `break_long_flags(Boolean)` (default `false`), `suppress_empty_meta(Boolean)` (default `true`), and `allow_empty_flag_spec(Bool)` (default `true`).

Compilation flags:
`static`
Template:
`help(OptionObjects,Help,HelpOptions)`
Mode and number of proofs:
`help(+list(object),-atom,+list)` - `one_or_error`
Exceptions:
`HelpOptions` is a variable, a partial list, or contains a variable option:
`instantiation_error`
`HelpOptions` is neither a variable nor a list:
`type_error(list,HelpOptions)`
An element of `HelpOptions` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element of `HelpOptions` is a compound term but not a valid option:
`domain_error(option,Option)`
`OptionObjects` is a variable, a partial list, or contains an option object definition with an insufficiently instantiated value:
`instantiation_error`
`OptionObjects` is neither a variable nor a list of valid object identifiers:
`type_error(list(object),OptionObjects)`
An option object is missing the `name/1` predicate:
`existence_error(predicate,name/1)`
An option object predicate returns a value with an invalid type:
`type_error(Type,Term)`
An option object predicate returns a value outside the expected domain:
`domain_error(Domain,Term)`
The option set contains a duplicate option name:
`domain_error(unique_key,Name)`
The option set contains a duplicate short flag:
`domain_error(unique_short_flag,ShortFlag)`
The option set contains a duplicate long flag:
`domain_error(unique_long_flag,LongFlag)`
An option has no short or long flags and empty flag specifications are disallowed:
`domain_error(non_empty_flag_spec,Name)`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)

See also

command_line_option