.. _chapter_oechem_interface:

********************************************************************************
Command Line Interface Definition 
********************************************************************************
.. index :: command line interface definition

When not working with **Options** derived from :ref:`OEOptions <OESystem_OEOptions>`,
:ref:`OEInterface <OESystem_OEInterface>` class can still be used to create a command line
application. For such usage, :ref:`OEInterface <OESystem_OEInterface>` has a convenience
constructor that takes an interface definition and a command line to
parse. The constructor will configure the interface with the specified
definition, then parse the options from command line passed in through
``argv``.

.. oe:source:: GettingStartedWithOEInterface.cpp
   :language: c++
   :refnum:   1
   :caption:  Getting started with OEInterface command line parsing
   :frag:     SNIPPET

.. oe:source:: GettingStartedWithOEInterface.py
   :language: python
   :refnum:   1
   :caption:  Getting started with OEInterface command line parsing
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-GettingStartedWithOEInterface.py>`



.. oe:source:: GettingStartedWithOEInterface.java
   :language: java
   :refnum:   1
   :caption:  Getting started with OEInterface command line parsing
   :frag:     SNIPPET

.. oe:source:: GettingStartedWithOEInterface.cs
   :language: csharp
   :refnum:   1
   :caption:  Getting started with OEInterface command line parsing
   :frag:     SNIPPET

The values specified on the command line are then accessed on the
:ref:`OEInterface <OESystem_OEInterface>` object using a ``Get`` method that
corresponds to the type of the parameter. The following is an example
of executing the program in :oe:src:`Listing
1<SNIPPET-GettingStartedWithOEInterface>`:

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./GettingStartedWithOEInterface -b -i 12345 -f 0.5 -str foo
      -b = 1
      -i = 12345
      -f = 0.5
      -str = foo

.. oe:language:: python

   .. code-block:: bash

      prompt> ./GettingStartedWithOEInterface.py -b -i 12345 -f 0.5 -str foo
      -b = True
      -i = 12345
      -f = 0.5
      -str = foo

.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.GettingStartedWithOEInterface -b -i 12345 -f 0.5 -str foo
      -b = true
      -i = 12345
      -f = 0.5
      -str = foo

.. warning::

   The convenience constructor will call the system exit function
   forcing the program to exit in the following situations:

   - The interface definition is malformed
   - The user has requested help on any of the parameters, *e.g.*, ``--help -str``
   - The command line is malformed, *i.e.*, missing or extra parameters

   For these reasons the convenience constructor may not be suitable
   for use in a library setting, it is intended for standalone
   applications.

.. _section_accessing_parameter_values:

Parameter Value Access
================================================================================

The ``Get`` methods of the :ref:`OEInterface <OESystem_OEInterface>` returns the
value of the specified parameter the user entered on the command line,
or in the case that the parameter was not specified by the user on the
command line the default value specified in the interface definition
is returned.  If there is no default or user specified value the
default constructed object is returned (*i.e.*, 0.0f for ``float``
parameters and an empty string for ``string`` parameters) and a
warning is issued. For example, the following demonstrates how running
the program in :oe:src:`Listing 1<SNIPPET-GettingStartedWithOEInterface>`
without any arguments will display a lot of warnings about
uninitialized values being used.

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./GettingStartedWithOEInterface
      Warning: OEInterface::Get, requesting value of unset parameter -b
      -b = 0
      Warning: OEInterface::Get, requesting value of unset parameter -i
      -i = 0
      Warning: OEInterface::Get, requesting value of unset parameter -f
      -f = 0
      Warning: OEInterface::Get, requesting value of unset parameter -str
      -str =

.. oe:language:: python

   .. code-block:: bash

      prompt> ./GettingStartedWithOEInterface.py
      Warning: OEInterface::Get, requesting value of unset parameter -b
      -b = False
      Warning: OEInterface::Get, requesting value of unset parameter -i
      -i = 0
      Warning: OEInterface::Get, requesting value of unset parameter -f
      -f = 0.0
      Warning: OEInterface::Get, requesting value of unset parameter -str
      -str =

.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.GettingStartedWithOEInterface
      Warning: OEInterface::Get, requesting value of unset parameter -b
      -b = false
      Warning: OEInterface::Get, requesting value of unset parameter -i
      -i = 0
      Warning: OEInterface::Get, requesting value of unset parameter -f
      -f = 0.0
      Warning: OEInterface::Get, requesting value of unset parameter -str
      -str =

The warnings can be avoided by using the
:oe:meth:`OESystem::OEInterface::Has` method to check if there is no
default value or user specified value. :oe:src:`Listing
2<SNIPPET-UsingOEInterfaceHas>` demonstrates how to check for the existence of
certain parameters.

.. oe:source:: UsingOEInterfaceHas.cpp
   :language: c++
   :refnum:   2
   :caption:  Testing for parameter existence with the Has method
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceHas.py
   :language: python
   :refnum:   2
   :caption:  Testing for parameter existence with the Has method
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UsingOEInterfaceHas.py>`



.. oe:source:: UsingOEInterfaceHas.java
   :language: java
   :refnum:   2
   :caption:  Testing for parameter existence with the Has method
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceHas.cs
   :language: csharp
   :refnum:   2
   :caption:  Testing for parameter existence with the Has method
   :frag:     SNIPPET

The following demonstrates the output of the program in :oe:src:`Listing
2<SNIPPET-UsingOEInterfaceHas>`. Notice that only variables present on the
command line will trigger :oe:meth:`OESystem::OEInterface::Has` to
return ``true``. This is an important distinction when dealing with
``boolean`` parameters, :oe:meth:`OESystem::OEInterface::Has` will not
return the value of the ``boolean`` parameter, just the existence of
it.

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceHas
      prompt> ./UsingOEInterfaceHas -b
      -b = 1
      prompt> ./UsingOEInterfaceHas -i 2
      -i = 2
      prompt> ./UsingOEInterfaceHas -f 0.5
      -f = 0.5
      prompt> ./UsingOEInterfaceHas -str foo
      -str = foo


.. oe:language:: python

   .. code-block:: bash

      prompt> ./UsingOEInterfaceHas.py
      prompt> ./UsingOEInterfaceHas.py -b
      -b = True
      prompt> ./UsingOEInterfaceHas.py -i 2
      -i = 2
      prompt> ./UsingOEInterfaceHas.py -f 0.5
      -f = 0.5
      prompt> ./UsingOEInterfaceHas.py -str foo
      -str = foo


.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceHas -b
      -b = true
      prompt> java openeye.docexamples.oechem.UsingOEInterfaceHas -i 2
      -i = 2
      prompt> java openeye.docexamples.oechem.UsingOEInterfaceHas -f 0.5
      -f = 0.5
      prompt> java openeye.docexamples.oechem.UsingOEInterfaceHas -str foo
      -str = foo

.. _section_default_values:

Default Values
================================================================================

Using :oe:meth:`OESystem::OEInterface::Has` all over a program can
become quite clumsy. Therefore it is recommended to use ``!DEFAULT``
in the parameter interface definition to specify the parameter's
default value whenever a default value can be specified. When a
parameter has a default value :oe:meth:`OESystem::OEInterface::Has`
will always return ``true``. :oe:src:`Listing 3<SNIPPET-UsingOEInterfaceDefaults>`
demonstrates how to set a default value for a parameter.

.. oe:source:: UsingOEInterfaceDefaults.cpp
   :language: c++
   :refnum:   3
   :caption:  Setting a default value for a parameter
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceDefaults.py
   :language: python
   :refnum:   3
   :caption:  Setting a default value for a parameter
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UsingOEInterfaceDefaults.py>`



.. oe:source:: UsingOEInterfaceDefaults.java
   :language: java
   :refnum:   3
   :caption:  Setting a default value for a parameter
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceDefaults.cs
   :language: csharp
   :refnum:   3
   :caption:  Setting a default value for a parameter
   :frag:     SNIPPET

This allows the code to take a very simple structure that doesn't have
to care whether the parameter was actually specified on the command
line. The following is what is printed by the program in
:oe:src:`Listing 3<SNIPPET-UsingOEInterfaceDefaults>` when no arguments are
given.

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceDefaults
      -b = 0
      -i = 2
      -f = 0.5
      -str = foo

.. oe:language:: python

   .. code-block:: bash

      prompt> ./UsingOEInterfaceDefaults.py
      -b = False
      -i = 2
      -f = 0.5
      -str = foo


.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceDefaults
      -b = false
      -i = 2
      -f = 0.5
      -str = foo

.. _section_requiring_parameters:

Requiring Parameters
================================================================================

Programs usually have a bare minimum set of parameters that must be
specified. A parameter can be marked as required in the interface
definition by using ``!REQUIRED true`` in the parameter
definition. :oe:src:`Listing 4<SNIPPET-UsingOEInterfaceRequired>` demonstrates
making all the parameters used in the previous example required.

.. oe:source:: UsingOEInterfaceRequired.cpp
   :language: c++
   :refnum:   4
   :caption:  Requiring all parameters to be specified.
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceRequired.py
   :language: python
   :refnum:   4
   :caption:  Requiring all parameters to be specified.
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UsingOEInterfaceRequired.py>`



.. oe:source:: UsingOEInterfaceRequired.java
   :language: java
   :refnum:   4
   :caption:  Requiring all parameters to be specified.
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceRequired.cs
   :language: csharp
   :refnum:   4
   :caption:  Requiring all parameters to be specified.
   :frag:     SNIPPET

If any required parameter is missing from the command line
during the command line parsing stage an appropriate error message
will be thrown. The following demonstrates the error messages thrown
by the program in :oe:src:`Listing 4<SNIPPET-UsingOEInterfaceRequired>`:

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceRequired
      No arguments specified on the command line
      Required parameters:
          -b : An boolean parameter
          -i : An integer parameter
          -f : A float parameter
          -str : A string parameter
      For more help type:
        ./UsingOEInterfaceRequired --help

      prompt> ./UsingOEInterfaceRequired -b
      Fatal: Missing required parameter -i

.. oe:language:: python

   .. code-block:: bash

      prompt> ./UsingOEInterfaceRequired.py
      No arguments specified on the command line
      Required parameters:
          -b : An boolean parameter
          -i : An integer parameter
          -f : A float parameter
          -str : A string parameter
      For more help type:
        ./UsingOEInterfaceRequired.py --help

      prompt> ./UsingOEInterfaceRequired.py -b
      Fatal: Missing required parameter -i

.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceRequired
      No arguments specified on the command line
      Required parameters:
          -b : An boolean parameter
          -i : An integer parameter
          -f : A float parameter
          -str : A string parameter
      For more help type:
        UsingOEInterfaceRequired --help

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceRequired -b
      Fatal: Missing required parameter -i

.. _section_legal_and_illegal_values_and_ranges:

Legal and Illegal Values and Ranges
================================================================================

Some parameter types can have legal/illegal ranges and values.  These
are set with the ``!LEGAL_VALUE``, ``!ILLEGAL_VALUE``,
``!LEGAL_RANGE``, and ``!ILLEGAL_RANGE`` fields. The following are the
restrictions for certain parameter types:

.. describe:: bool

   Boolean parameters cannot have legal/illegal ranges and values.

.. describe:: int and float

   These parameters can have legal/illegal ranges and values.
   Checks for illegal ranges and values are performed first and if an
   invalid range or value is detected an error is returned.  Then
   legal ranges and values are checked, and if the parameter setting
   matches or there are no legal ranges or values it passes.  ``inf``
   and ``-inf`` can be used as range limits, along with regular
   numerical values.

.. describe:: string

   String parameters can have legal/illegal values, but not
   ranges. Checks for illegal values are performed first and if an
   invalid value is detected an error is returned. Then legal values are
   checked, and if the parameter setting matches it passes. Legal/illegal
   values for the string type support up to 2 ``*`` wildcards for
   pattern matches.  This is commonly used to force a file extension,
   *e.g.*, ``!LEGAL_VALUE *.txt``.


.. _section_parameter_lists:

Parameter Lists
================================================================================

Sometimes it is useful to allow multiple values for a given
parameter. The ``!LIST`` field is used to specify that a parameter can
have multiple values separated by spaces on the command line. The
:oe:meth:`OESystem::OEInterface::GetList` method should then be used to
get an iterator over the parameter's values. :oe:src:`Listing
5<SNIPPET-UsingOEInterfaceList>` demonstrates how to specify that a parameter
is a list of values and then how to access it with the
:oe:meth:`OESystem::OEInterface::GetList` method.

.. oe:source:: UsingOEInterfaceList.cpp
   :language: c++
   :refnum:   5
   :caption:  Specifying that a parameter is a list of values
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceList.py
   :language: python
   :refnum:   5
   :caption:  Specifying that a parameter is a list of values
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UsingOEInterfaceList.py>`



.. oe:source:: UsingOEInterfaceList.java
   :language: java
   :refnum:   5
   :caption:  Specifying that a parameter is a list of values
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceList.cs
   :language: csharp
   :refnum:   5
   :caption:  Specifying that a parameter is a list of values
   :frag:     SNIPPET

The command line parser will then assign elements as values based upon
their position in the ``argv`` that was passed to the program. This
allows the user to pass values that have spaces in them by simply
quoting the relevant section. The following demonstrates the behavior
of the program in :oe:src:`Listing 5<SNIPPET-UsingOEInterfaceList>`:

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceList -strs foo bar blah
      -strs = foo
              bar
              blah

      prompt> ./UsingOEInterfaceList -strs "foo bar" blah
      -strs = foo bar
              blah

.. oe:language:: python

   .. code-block:: bash

      prompt> ./UsingOEInterfaceList.py -strs foo bar blah
      -strs = foo
              bar
              blah

      prompt> ./UsingOEInterfaceList.py -strs "foo bar" blah
      -strs = foo bar
              blah

.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceList -strs foo bar blah
      -strs = foo
              bar
              blah

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceList -strs "foo bar" blah
      -strs = foo bar
              blah

.. _section_positional_parameters:

Positional Parameters
================================================================================

For commonly used parameters it is often useful to allow them to be
specified by their position on the command line. The ``!KEYLESS``
record is used to specify that a parameter can be assigned from a
positional value on the command line. :oe:src:`Listing
6<SNIPPET-UsingOEInterfaceKeyless>` demonstrates how to specify input and
output file name parameters that can be specified from their position
on the command line.

.. oe:source:: UsingOEInterfaceKeyless.cpp
   :language: c++
   :refnum:   6
   :caption:  Specifying keyless input and output file parameters
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceKeyless.py
   :language: python
   :refnum:   6
   :caption:  Specifying keyless input and output file parameters
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UsingOEInterfaceKeyless.py>`



.. oe:source:: UsingOEInterfaceKeyless.java
   :language: java
   :refnum:   6
   :caption:  Specifying keyless input and output file parameters
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceKeyless.cs
   :language: csharp
   :refnum:   6
   :caption:  Specifying keyless input and output file parameters
   :frag:     SNIPPET

``!KEYLESS`` parameters can still be specified using their command
line flag. However, positional arguments need to be the last values on
the command line. The following demonstrates how ``!KEYLESS``
parameters can and cannot be specified on the command line:

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceKeyless -i foo -o bar
      Input file = foo
      Output file = bar

      prompt> ./UsingOEInterfaceKeyless foo bar
      Input file = foo
      Output file = bar

      prompt> ./UsingOEInterfaceKeyless -i foo bar
      Input file = foo
      Output file = bar

      prompt> ./UsingOEInterfaceKeyless foo -o bar
      Fatal: Unknown parameter, foo, on command line


.. oe:language:: python

   .. code-block:: bash

      prompt> ./UsingOEInterfaceKeyless.py -i foo -o bar
      Input file name = foo
      Output file name = bar

      prompt> ./UsingOEInterfaceKeyless.py foo bar
      Input file name = foo
      Output file name = bar

      prompt> ./UsingOEInterfaceKeyless.py -i foo bar
      Input file name = foo
      Output file name = bar

      prompt> ./UsingOEInterfaceKeyless.py foo -o bar
      Fatal: Unknown parameter, foo, on command line

.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceKeyless -i foo -o bar
      Input file name = foo
      Output file name = bar

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceKeyless foo bar
      Input file name = foo
      Output file name = bar

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceKeyless -i foo bar
      Input file name = foo
      Output file name = bar

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceKeyless foo -o bar
      Fatal: Unknown parameter, foo, on command line

.. warning::

   An ambiguity occurs when mixing ``!KEYLESS`` with ``!LIST``. There
   is no way for the parser to differentiate between multiple values
   for a ``!LIST`` and different ``!KEYLESS`` parameters.
   :ref:`OEInterface <OESystem_OEInterface>` resolves this by requiring that any
   keyless list parameter must be the *last* keyless parameter.

.. _section_parameter_molecule:

Molecule Parameters
================================================================================

As the previous example illustrated how to handle simple parameters
such as ``float``, ``int`` or ``string``.
The :ref:`OEInterface <OESystem_OEInterface>` also provides a convenient way to
open a molecule file and return its first molecule.

.. oe:source:: OEInterfaceMolParam.cpp
   :language: c++
   :refnum:   7
   :caption:  Example of using molecule parameter
   :frag:     SNIPPET

.. oe:source:: OEInterfaceMolParam.py
   :language: python
   :refnum:   7
   :caption:  Example of using molecule parameter
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-OEInterfaceMolParam.py>`



.. oe:language:: c++

   .. code-block:: bash

      prompt> ./OEInterfaceMolParam -mol benzene.mol
      Number of heavy atoms in molecule = 6

.. oe:language:: python

   .. code-block:: bash

      prompt> python OEInterfaceMolParam.py -mol benzene.mol
      Number of heavy atoms in molecule = 6

Similarly the first multi-conformer molecule can be imported from a molecule
file by setting the type of a parameter as ``!TYPE OEMol``.

.. _section_command_line_help:

Command Line Help
================================================================================

The :ref:`OEInterface <OESystem_OEInterface>` object can have a significant
amount of information, default values, text descriptions, etc., about
the parameters it holds. All this information allows the
:ref:`OEInterface <OESystem_OEInterface>` to provide help to the user
interactively automatically based upon the interface
definition. :oe:src:`Listing 8<SNIPPET-UsingOEInterfaceHelp>` is a fairly
simple program, it just concatenates all the molecules given into a
single molecule. Though it has a fairly complex set of command line
parameters which :ref:`OEInterface <OESystem_OEInterface>` handles
automatically.

.. oe:source:: UsingOEInterfaceHelp.cpp
   :language: c++
   :refnum:   8
   :caption:  A program to concatenate any number of molecules together
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceHelp.py
   :language: python
   :refnum:   8
   :caption:  A program to concatenate any number of molecules together
   :frag:     SNIPPET

.. oe:language:: python

	:ref:`Full listing. <listing-UsingOEInterfaceHelp.py>`



.. oe:source:: UsingOEInterfaceHelp.java
   :language: java
   :refnum:   8
   :caption:  A program to concatenate any number of molecules together
   :frag:     SNIPPET

.. oe:source:: UsingOEInterfaceHelp.cs
   :language: csharp
   :refnum:   8
   :caption:  A program to concatenate any number of molecules together
   :frag:     SNIPPET

.. note::

   - ``!BRIEF`` can be used outside of a ``!PARAMETER`` to give a
     concise one line command line usage.
   - ``!ALIAS`` is used to specify an alternative name the parameter
     can be specified with.
   - ``!DETAIL`` is used for a more detailed description of the
     parameter.

Whenever there are ``!REQUIRED`` parameters the
:ref:`OEInterface <OESystem_OEInterface>` will complain about an empty command
line. This is usually the first way users interact with a command line
program so the goal is to give them only enough information to get the
program running. This is where specifying a top-level ``!BRIEF`` is
exceptionally useful to the end user. The following is the output of
the program in :oe:src:`Listing 8<SNIPPET-UsingOEInterfaceHelp>` when no
parameters are given:

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceHelp
      No arguments specified on the command line
      ./UsingOEInterfaceHelp : UsingOEInterfaceHelp [-d <delimiter>] [-o] <output> [-i] <input1> <input2> ...
      Required parameters:
          -output : The output file
          -inputs : The input files
      For more help type:
        ./UsingOEInterfaceHelp --help

.. oe:language:: python

   .. code-block:: bash

      prompt> ./UsingOEInterfaceHelp.py
      No arguments specified on the command line
      ./UsingOEInterfaceHelp.py : UsingOEInterfaceHelp.py [-d <delimiter>] [-o] <output> [-i] <input1> <input2> ...
      Required parameters:
          -output : The output file
          -inputs : The input files
      For more help type:
        ./UsingOEInterfaceHelp.py --help

.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceHelp
      No arguments specified on the command line
      UsingOEInterfaceHelp : UsingOEInterfaceHelp [-d <delimiter>] [-o] <output> [-i] <input1> <input2> ...
      Required parameters:
          -output : The output file
          -inputs : The input files
      For more help type:
        UsingOEInterfaceHelp --help


More information is accessible from the command line by specifying
``--help`` as the first argument on the command line. The following is
an example of requesting help from the program in :oe:src:`Listing
7<SNIPPET-UsingOEInterfaceHelp>`:

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceHelp --help
      ./UsingOEInterfaceHelp : UsingOEInterfaceHelp [-d <delimiter>] [-o] <output> [-i] <input1> <input2> ...
      Simple parameter list
          -delim : Title delimiter
          -inputs : The input files
          -output : The output file

      Additional help functions:
        ./UsingOEInterfaceHelp --help simple      : Get a list of simple parameters (as seen above)
        ./UsingOEInterfaceHelp --help all         : Get a complete list of parameters
        ./UsingOEInterfaceHelp --help defaults    : List the defaults for all parameters
        ./UsingOEInterfaceHelp --help <parameter> : Get detailed help on a parameter
        ./UsingOEInterfaceHelp --help html        : Create an html help file for this program

.. oe:language:: python

   .. code-block:: bash

      prompt>./UsingOEInterfaceHelp.py --help
      ./UsingOEInterfaceHelp.py : UsingOEInterfaceHelp.py [-d <delimiter>] [-o] <output> [-i] <input1> <input2> ...
      Simple parameter list
          -delim : Title delimiter
          -inputs : The input files
          -output : The output file

      Additional help functions:
        ./UsingOEInterfaceHelp.py --help simple      : Get a list of simple parameters (as seen above)
        ./UsingOEInterfaceHelp.py --help all         : Get a complete list of parameters
        ./UsingOEInterfaceHelp.py --help defaults    : List the defaults for all parameters
        ./UsingOEInterfaceHelp.py --help <parameter> : Get detailed help on a parameter
        ./UsingOEInterfaceHelp.py --help html        : Create an html help file for this program


.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceHelp --help
      UsingOEInterfaceHelp : UsingOEInterfaceHelp [-d <delimiter>] [-o] <output> [-i] <input1> <input2> ...
      Simple parameter list
          -delim : Title delimiter
          -inputs : The input files
          -output : The output file

      Additional help functions:
        UsingOEInterfaceHelp --help simple      : Get a list of simple parameters (as seen above)
        UsingOEInterfaceHelp --help all         : Get a complete list of parameters
        UsingOEInterfaceHelp --help defaults    : List the defaults for all parameters
        UsingOEInterfaceHelp --help <parameter> : Get detailed help on a parameter
        UsingOEInterfaceHelp --help html        : Create an html help file for this program

As seen above ``--help`` can take arguments that allow the user
introspect even further into the semantics of a particular parameter.

.. oe:language:: c++

   .. code-block:: bash

      prompt> ./UsingOEInterfaceHelp --help -inputs

      Contents of parameter -inputs
          Aliases : -i
          Type : string
          Allow list : true
          Default : (parameter does not have a default)
          Keyless : 2
          Simple : true
          Required : true
          Brief : The input files
          Detail
              A list of molecule files to add together. Note, only the
              first molecule from every file will be added.


.. oe:language:: python

   .. code-block:: bash

      prompt> ./UsingOEInterfaceHelp.py --help -inputs

      Contents of parameter -inputs
          Aliases : -i
          Type : string
          Allow list : true
          Default : (parameter does not have a default)
          Keyless : 2
          Simple : true
          Required : true
          Brief : The input files
          Detail
              A list of molecule files to add together. Note, only the
              first molecule from every file will be added.



.. oe:language:: java

   .. code-block:: bash

      prompt> java openeye.docexamples.oechem.UsingOEInterfaceHelp --help -inputs

      Contents of parameter -inputs
          Aliases : -i
          Type : string
          Allow list : true
          Default : (parameter does not have a default)
          Keyless : 2
          Simple : true
          Required : true
          Brief : The input files
          Detail
              A list of molecule files to add together. Note, only the
              first molecule from every file will be added.

.. note::

   :oe:func:`OESystem::OECheckHelp` is the low-level function used to
   check a command line for ``--help``. By default the
   :oe:meth:`OEInterface
   constructor<OESystem::OEInterface::Constructors>` and the
   :oe:func:`OESystem::OEParseCommandLine` function call
   :oe:func:`OESystem::OECheckHelp` automatically so most users will
   never need to use this function directly.

.. _section_interface_definition:

Interface Definition Specification
================================================================================

.. index :: itf interface definition specification

Configuring an :ref:`OEInterface <OESystem_OEInterface>` is the process of
telling the name, type, and other details of all the command line
parameters the program is going to use. An interface definition
consists of a collection of ``PARAMETER`` blocks optionally organized
into ``CATEGORY`` blocks. A ``PARAMETER`` block must always have the
following information:

:NAME: The command line flag, *e.g.*, ``-i``, ``-str``, ``-cutoff``
:TYPE: The kind of information being passed, *e.g.*, ``float``, ``int``, ``string``, ``bool``

A ``PARAMETER`` can also optionally contain the following additional
information:

:ALIAS: One or more aliases for the parameter name that are generally
        used to create shorthand for lengthy parameter names. For
        example a parameter named ``-energy_cutoff_window`` could be
        given an alias ``-ecw``, that would make typing
        ``-energy_cutoff_window 10.0`` on the command line equivalent
        to ``-ecw 10.0``.

:DEFAULT: A default value for the parameter that will be used if the
          parameter is not specified by the user on the command line.

:REQUIRED: A flag specifying that the parameter is required. If a
           parameter is required the program will throw an error if
           the user does not specify that parameter. By default
           parameters are not required.

:LIST: A flag specifying whether the parameter is a list of multiple
       values. For example, ``./program -inputs file1.smi file2.smi
       file3.smi``.

:KEYLESS: A number, ``N``, that specifies that this parameter may be
          fulfilled by the ``Nth`` value on the command line that does
          not have a parameter flag specifically associated with
          it. For example, if ``-i`` had a ``KEYLESS`` value of ``1``
          specified the following are equivalent command lines,
          ``./program -i foo.smi`` and ``./program foo.smi``.

:VISIBILITY: A visibility level that controls when the parameter
             appears when the users requests ``--help``. Valid values
             are: ``simple``, ``normal``, ``hidden``. The default is
             ``simple`` if a ``VISIBILITY`` isn't specified.

:LEGAL_VALUE: A valid value that the parameter can be. The parameter
              specified must be one of the values specified in a
              ``LEGAL_VALUE`` field.

:ILLEGAL_VALUE: A value that cannot be specified as the parameter
                value.

:LEGAL_RANGE: A range that the parameter value must fall into. More
              useful than ``LEGAL_VALUE`` when the parameter is a
              ``float``.

:ILLEGAL_RANGE: A range that the parameter value must not fall
                into. More useful than ``ILLEGAL_VALUE`` when the
                parameter is a ``float``.

:BRIEF: A one line description of the parameter that will be displayed
        to users when listing multiple command line options using the
        high-level ``--help`` functions.

:DETAIL: A multi line description of the parameter that will be displayed
         to users when the user requests help about a specific
         parameter, *e.g.*, ``--help -foo``.

Therefore, a ``PARAMETER`` block takes the following form:

.. code-block:: bash

   !PARAMETER <name> [order priority]
     !ALIAS <alias>
     !TYPE <type>
     !DEFAULT <default value>
     !REQUIRED <true or false>
     !LIST <true or false>
     !KEYLESS <N>
     !VISIBILITY <visibility>
     !LEGAL_VALUE <value>
     !ILLEGAL_VALUE <value>
     !LEGAL_RANGE <hi value> <low value>
     !ILLEGAL_RANGE <hi_value> <low_value>
     !BRIEF <brief description>
     !DETAIL
       <detailed description line 1>
       <detailed description line 2>
       <detailed description line 3>
       .
       .
       .
   !END

``PARAMETER`` blocks can then be organized into ``CATEGORY``
blocks. ``CATEGORY`` blocks can also contain nested ``CATEGORY``
blocks, there is no limit to the amount of nesting. The value
specified after the ``!CATEGORY`` specifier is the name of the
``CATEGORY``. The ``CATEGORY`` can also contain a ``!BRIEF`` to give a
human readable description of the grouping. The following interface
definition defines an interface definition with an "Input and Output"
category with sub-categories for input and output respectively. As
well as a category for various other parameters.

.. code-block:: bash

   !CATEGORY Input and Output
     !CATEGORY Input
       !PARAMETER -i
         ...
       !END
     !CATEGORY Output
       !PARAMETER -o
         ...
       !END
     !END
   !END
   !CATEGORY Other Stuff
     !PARAMETER -o
       ...
     !END
   !END

By default parameters and categories appear in alphabetical order. This
order can be adjusted however by adding an integer after the category or
parameter name in the interface definition. Parameters and categories
are then sorted first by this integer and secondarily by their names. If
this integer is unspecified, it is assumed to be zero. The following
example illustrates re-ordering of both categories and variables.

.. code-block:: bash

   !CATEGORY Input and Output 1
     !CATEGORY Input 1
       !PARAMETER -input 1
         ...
       !END
       !PARAMETER -dbase 2
         ...
       !END
    !CATEGORY Output 2
       !PARAMETER -output 1
         ...
       !END
       !PARAMETER -hits 2
         ...
       !END
     !END
   !END
   !CATEGORY Other Stuff 2
     !PARAMETER -o
       ...
     !END
   !END

