Creating Parameters
===================

Parameters are always a list, consisting of zero to three items.
Parameters with three items are generally options that will be visible
at the command line.

Zero/One Item Lists
-------------------

Empty lists followed by a list of one item indicates a section break

.. code:: python

    [],
    ['Options'],

At the command line it results in a section break like so:

.. code:: python

      -v, --verbose         Produce more verbose output

      Options:
        --mult [MULT]         Testing mult. (Default: [10]) [Required]

Two Item Lists
--------------

Two item lists are aliases for flags/boolean options for backwards
compatability. Use them identically to three item lists without the
third section.

Three Item Lists
----------------

Three item lists are generally inclusive of all option types.

.. code:: python

    ['int', 'An integer parameter', {'required': True, 'validate':'Int', 'default': 10}],

-  The first parameter is the name, visible at the command line. It can
   optionally contain a POSIX style short option (one character),
   separated by a pipe.

.. code:: python

    # Python
    ['int|i', 'An integer parameter', {'required': True, 'validate':'Int', 'default': 10}],

    # --help
      -i [INT], --int [INT]
                              An integer parameter (Default: 10) [Required]

-  The second parameter provides a description of the parameter, as seen
   above. This is also used in the help text in Galaxy.
-  The third parameter provides attributes that configure the parameter.
   The following options are always available:

+------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| Dict Key   | Accepted Values   | Notes                                                                                                                                    |
+============+===================+==========================================================================================================================================+
| required   | True/False        | whether or not this parameter MUST be specified. If there is a default value, this is sufficient to pass the required requirement        |
+------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| validate   | String            | The parameter type, choose one of: Int, Float, String, Flag, File/Input, Option, GenomicTagOption                                        |
+------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| default    | {any}             | The default value for the parameter. Will be used in lieu of a user supplied value                                                       |
+------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| multiple   | True/False        | Should this parameter be accepted more than one time on the command line. If this is True, and default is specified, it MUST be a list   |
+------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+

.. code:: python

    ['int', 'An integer parameter', {'required': True, 'validate':'Int', 'default': 10}],
    ['float', 'A float', {'required': True, 'validate': 'Float','default': 1e-4}],
    ['string', 'A string value', {'required': True, 'multiple': True, 'default': ['Hello', 'World'], 'validate': 'String'}],
    ['option', 'A selection type parameter', {'required': False,'validate':
                                              'Option','options': {'a': 'Alpha', 'b': 'Bravo'} }],
    ['file', 'An input file', {'required': True, 'validate':'File/Input'}],

Some parameters have additional data that can be passed to them, like
numerical values have minimum and maximum values.

+-------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Validation Type   | Extra Parameter   | Description                                                                                                                                                                                                                                                                                        |
+===================+===================+====================================================================================================================================================================================================================================================================================================+
| Int               | min               | minimum value, must be greater than this value                                                                                                                                                                                                                                                     |
+-------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Int               | max               | maximum value, must be less than this value                                                                                                                                                                                                                                                        |
+-------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Float             | min               | minimum value, must be greater than this value                                                                                                                                                                                                                                                     |
+-------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Float             | max               | maximum value, must be less than this value                                                                                                                                                                                                                                                        |
+-------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| File/Input        | file\_format      | a list of formats, e.g. ``['fastq', 'fastqsanger']``                                                                                                                                                                                                                                               |
+-------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Option            | options           | a dict of options to enforce. At the command line these will be accepted as the key (short string), in galaxy they will be presented as the long version. For example ``{'a': 'Alpha', 'b': 'Bravo'}``, a command line user will write ``--option a`` while a galaxy user will select ``Alpha``.   |
+-------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+