.. _CLIABS/Arguments:

Arguments
#########

.. todo:: Naming convention

   * Basic classes |rarr| Argument
   * Named arguments |rarr| Flag
   * Character prefixes |rarr| Short, Long, Windows


.. _CLIABS/Arguments:Overview:

Overview
********

.. mermaid::

   graph LR;
     CLA[CommandLineArgument]
     style CLA stroke-dasharray: 5 5

     EA[ExecutableArgument]

     NA[NamedArgument]
     style NA stroke-dasharray: 5 5

     VA[ValuedArgument]
     style VA stroke-dasharray: 5 5

     NVA[NamedAndValuedArgument]
     style NVA stroke-dasharray: 5 5

     BF[BooleanFlag]
     style NVA stroke-dasharray: 5 5

     NTA[NamedTupledArgument]
     style NTA stroke-dasharray: 5 5

     NKVPA[NamedKeyValuePairsArgument]
     style NKVPA stroke-dasharray: 5 5

     CLA ----> EA
     CLA --> NA
     CLA --> VA
     NA --> NVA
     VA --> NVA
     NA --> BF
     VA --> BF
     NA --> NTA
     VA --> NTA
     NA --> NKVPA
     VA --> NKVPA

     CA["<b>CommandArgument</b><br/><div style='font-family: monospace'>command</div>"]
     FA[FlagArgument]
     style FA stroke-dasharray: 5 5

     NA ---> CA
     NA ---> FA

     SA["<b>StringArgument</b><br/><div style='font-family: monospace'>value</div>"]
     SLA["<b>StringListArgument</b><br/><div style='font-family: monospace'>value1 value2</div>"]
     PA["<b>PathArgument</b><br/><div style='font-family: monospace'>file1.txt</div>"]
     PLA["<b>PathListArgument</b><br/><div style='font-family: monospace'>file1.txt file2.txt</div>"]

     VA ---> SA
     VA ---> SLA
     VA ---> PA
     VA ---> PLA

     NVFA["<b>NamedAndValuedFlagArgument</b><br/><div style='font-family: monospace'>output=file.txt</div>"]
     style NVFA stroke-dasharray: 5 5
     NOVFA["<b>NamedAndOptionalValuedFlagArgument</b><br/><div style='font-family: monospace'>output=file.txt</div>"]
     style NOVFA stroke-dasharray: 5 5

     NVA --> NVFA
     NVA --> NOVFA


.. _CLIABS/Arguments/WithPrefix:

Without Prefix Character(s)
***************************

+--------------------------+--------------------------------+-------------------------------------------------------------------+
| **RAW Format**           | **Examples**                   | **Argument Class**                                                |
+--------------------------+--------------------------------+-------------------------------------------------------------------+
| ``executable``           | ``prog``                       | :class:`~pyTooling.CLIAbstraction.Argument.ExecutableArgument`    |
+--------------------------+--------------------------------+-------------------------------------------------------------------+
| ``--``                   | ``prog -option -- file1.txt``  | :class:`~pyTooling.CLIAbstraction.Argument.DelimiterArgument`     |
+--------------------------+--------------------------------+-------------------------------------------------------------------+
| ``command``              | ``prog help``                  | :class:`~pyTooling.CLIAbstraction.Command.CommandArgument`        |
+--------------------------+--------------------------------+-------------------------------------------------------------------+
| ``string``               | ``prog value``                 | :class:`~pyTooling.CLIAbstraction.Argument.StringArgument`        |
+--------------------------+--------------------------------+-------------------------------------------------------------------+
| ``string1`` ``string2``  | ``prog value1 value2``         | :class:`~pyTooling.CLIAbstraction.Argument.StringListArgument`    |
+--------------------------+--------------------------------+-------------------------------------------------------------------+
| ``path``                 | ``prog file1.txt``             | :class:`~pyTooling.CLIAbstraction.Argument.PathArgument`          |
+--------------------------+--------------------------------+-------------------------------------------------------------------+
| ``path1`` ``path2``      | ``prog File1.log File1.log``   | :class:`~pyTooling.CLIAbstraction.Argument.PathListArgument`      |
+--------------------------+--------------------------------+-------------------------------------------------------------------+

Executable
==========

An executable argument represents a program/executable. The internal value is a :class:`Path` object.


Command
=======

Commands are (usually) mutually exclusive arguments and the first argument in a list of arguments to a program. They are
used to logically group arguments.

While commands can or cannot have prefix characters, they shouldn't be confused with flag arguments or string arguments.

**Example:**

* ``prog command -arg1 --argument2``

.. seealso::

   * For simple flags (various formats). |br|
     |rarr| :mod:`~pyTooling.CLIAbstraction.Flag`
   * For string arguments. |br|
     |rarr| :class:`~pyTooling.CLIAbstraction.Argument.StringArgument`


String
======

A simple argument accepting any string value. If a string has a predefined format, more specific argument classes should
be used like :mod:`~pyTooling.CLIAbstraction.Command`, :mod:`~pyTooling.CLIAbstraction.Flag` or
:class:`~pyTooling.CLIAbstraction.Argument.PathArgument`.

.. seealso::

   * For path argument. |br|
     |rarr| :class:`~pyTooling.CLIAbstraction.Argument.PathArgument`


List of Strings
===============

Like :class:`~pyTooling.CLIAbstraction.Argument.StringArgument` but supporting a list of strings.

.. seealso::

   * For list of path arguments. |br|
     |rarr| :class:`~pyTooling.CLIAbstraction.Argument.PathListArgument`


Path
====

An argument accepting a :class:`~pathlib.Path` object.


List of Paths
=============

Like :class:`~pyTooling.CLIAbstraction.Argument.PathArgument` but supporting a list of paths.


.. _CLIABS/Arguments/WithoutPrefix:

With Prefix Character(s)
************************

Commonly used prefix characters are: single and double dash, single slash, or plus character(s).

+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Single Dash Argument Format**   | **Double Dash Argument Format**     | **Single Slash Argument Format**  | **Argument Class**                                                                                                                                                                                                                                   |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-command``                      | ``--command``                       | ``/command``                      | :class:`~pyTooling.CLIAbstraction.Command.ShortCommand`                       |br| :class:`~pyTooling.CLIAbstraction.Command.LongCommand`                       |br| :class:`~pyTooling.CLIAbstraction.Command.WindowsCommand`                       |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-flag``                         | ``--flag``                          | ``/flag``                         | :class:`~pyTooling.CLIAbstraction.Flag.ShortFlag`                             |br| :class:`~pyTooling.CLIAbstraction.Flag.LongFlag`                             |br| :class:`~pyTooling.CLIAbstraction.Flag.WindowsFlag`                             |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-flag`` |br| ``-no-flag``       | ``--flag`` |br| ``--no-flag``       | ``/flag`` |br| ``/no-flag``       | :class:`~pyTooling.CLIAbstraction.BooleanFlag.ShortBooleanFlag`               |br| :class:`~pyTooling.CLIAbstraction.BooleanFlag.LongBooleanFlag`               |br| :class:`~pyTooling.CLIAbstraction.BooleanFlag.WindowsBooleanFlag`               |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-flag`` |br| ``-flag=value``    | ``--flag`` |br| ``--flag=value``    | ``/flag`` |br| ``/flag=value``    | :class:`~pyTooling.CLIAbstraction.OptionalValuedFlag.ShortOptionalValuedFlag` |br| :class:`~pyTooling.CLIAbstraction.OptionalValuedFlag.LongOptionalValuedFlag` |br| :class:`~pyTooling.CLIAbstraction.OptionalValuedFlag.WindowsOptionalValuedFlag` |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-flag=value``                   | ``--flag=value``                    | ``/flag=value``                   | :class:`~pyTooling.CLIAbstraction.ValuedFlag.ShortValuedFlag`                 |br| :class:`~pyTooling.CLIAbstraction.ValuedFlag.LongValuedFlag`                 |br| :class:`~pyTooling.CLIAbstraction.ValuedFlag.WindowsValuedFlag`                 |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-flag=value1 -flag=value2``     | ``--flag=value1 --flag=value2``     | ``/flag=value1 /flag=value2``     | :class:`~pyTooling.CLIAbstraction.ValuedFlagList.ShortValuedFlagList`         |br| :class:`~pyTooling.CLIAbstraction.ValuedFlagList.LongValuedFlagList`         |br| :class:`~pyTooling.CLIAbstraction.ValuedFlagList.WindowsValuedFlagList`         |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-flag value``                   | ``--flag value``                    | ``/flag value``                   | :class:`~pyTooling.CLIAbstraction.ShortTupleFlag`                             |br| :class:`~pyTooling.CLIAbstraction.LongTupleFlag`                             |br| :class:`~pyTooling.CLIAbstraction.WindowsTupleFlag`                             |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``-gKey1=value1 -gKey2=value2``   | ``--gKey1=value1 --gKey2=value2``   | ``/g:Key1=value1 /g:Key2=value2`` | :class:`~pyTooling.CLIAbstraction.KeyValueFlag.ShortKeyValueFlag`             |br| :class:`~pyTooling.CLIAbstraction.KeyValueFlag.LongKeyValueFlag`             |br| :class:`~pyTooling.CLIAbstraction.KeyValueFlag.WindowsKeyValueFlag`             |
+-----------------------------------+-------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+


Command
=======

.. TODO:: Write documentation.

.. mermaid::

   graph LR;
     CLA[CommandLineArgument]
     style CLA stroke-dasharray: 5 5
     CLA --> NA[NamedArgument]
     style NA stroke-dasharray: 5 5
     NA --> CA["<b>CommandArgument</b><br/><div style='font-family: monospace'>command</div>"];
     CA --> SCA["<b>ShortCommand</b><br/><div style='font-family: monospace'>-command</div>"];
     CA --> LCA["<b>LongCommand</b><br/><div style='font-family: monospace'>--command</div>"];
     CA --> WCA["<b>WindowsCommand</b><br/><div style='font-family: monospace'>/command</div>"];


Flag
====

A flag is a command line argument that is either present or not. If present that argument is said to be activated or
true.

3 variants are predefined with prefixes ``-``, ``--`` and ``/``.

.. rubric:: Variants

.. mermaid::

   graph LR;
     CLA[CommandLineArgument]
     style CLA stroke-dasharray: 5 5
     CLA --> NA[NamedArgument]
     style NA stroke-dasharray: 5 5
     NA --> FA[FlagArgument]
     style FA stroke-dasharray: 5 5
     FA --> SFA["<b>ShortFlag</b><br/><div style='font-family: monospace'>-flag</div>"]
     FA --> LFA["<b>LongFlag</b><br/><div style='font-family: monospace'>--flag</div>"]
     FA --> WFA["<b>WindowsFlag</b><br/><div style='font-family: monospace'>/flag</div>"]


Flag with Value
===============

.. TODO:: Write documentation.


Boolean Flag
============

.. TODO:: Write documentation.


Flag with Optional Value
========================

.. TODO:: Write documentation.


List of Flags with Value
========================

.. TODO:: Write documentation.


Flag with Value as a Tuple
==========================

.. TODO:: Write documentation.