======
Picker
======

.. default-domain:: bash

.. file:: picker

:Arguments: ``$1``... - List of choices to pick from
:Output: *stdout* - The choice that was selected
:Return Value: The choice selected, between 1 and N

Bash CLI version of :func:`picker`

.. rubric:: Example

.. code-block:: bash

  my_choice=$(picker Choice1 Choice2 ...)

.. function:: picker

:Arguments: * ``$1`` - Variable name to store choice in
            * ``$2``... - List of choices
:Parameters: - ``[DEFAULT_RESPONSE]`` - Default choice [1...$#] (when user presses enter only)
:Output: * ``${!1}`` - Stores text of choice selected
         * ``${!1}_index`` - Store the index in the array of the choice selected (starting at zero. So if 2 is selected, that's index 1)
         * TUI outputs to stderr.

Basic TUI for picking an option from a list of choices

Prints list of choices, and reads an answer until the user gives a valid response

.. rubric:: Example

.. code-block:: bash

  picker var "Choice one" "Choice II" "Choice 3"

  #if 2 is selected
  #var="Choice II"
  #var_index=1

.. rubric:: Bugs

If one of your choices has a newline in it, the value of ``${!1}`` will only contain the first line