.. index:: single: command_line_options
.. _command_line_options/0:

.. rst-class:: right

**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`` :ref:`options <options/0>`
| **Uses:**
|    :ref:`atom <atom/0>`
|    :ref:`list <list/0>`
|    :ref:`meta <meta/0>`
|    :ref:`numberlist <numberlist/0>`
|    :ref:`term_io <term_io/0>`
|    :ref:`type <type/0>`
|    :ref:`user <user/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: parse/4
.. _command_line_options/0::parse/4:

``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>)``


------------

.. index:: parse/5
.. _command_line_options/0::parse/5:

``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>)``


------------

.. index:: help/2
.. _command_line_options/0::help/2:

``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)``


------------

.. index:: help/3
.. _command_line_options/0::help/3:

``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)

.. seealso::

   :ref:`command_line_option <command_line_option/0>`

