<commit_before>=======
pimento
=======

simple CLI menu

features
========

a simple cli menu
-----------------

There is a single required argument:

* items - a finite iterable (list, tuple, etc) of items which the user will be prompted to choose from

.. code:: python

  from pimento import menu
  result = menu(['red', 'blue', 'green', 'grey'])

Prints:
::

  Options:
    red
    blue
    green
    grey
  Enter an option to continue: 

You may also enter your own pre-prompt:

.. code:: python

  from pimento import menu
  result = menu(
    ['red', 'blue', 'green', 'grey'],
    "Which color?"  # <--- custom pre_prompt arg
  )

Prints:
::

  Which color?
    red
    blue
    green
    grey
  Enter an option to continue: 

You may also enter your own post-prompt:

.. code:: python

  from pimento import menu
  result = menu(
    ['red', 'blue', 'green', 'grey'],
    "which color?",
    "Please select one: "  # <--- custom post_prompt arg
  )

Prints:
::

  which color?
    red
    blue
    green
    grey

partial matches
---------------

The user can select either a full option or a partial match.  All of the following will result in the user selecting ``blue``:

* ``b``
* ``bl``
* ``blu``
* ``blue``

re-prompting
------------

When an invalid option is entered, an actionable error message is printed, and the menu is re-prompted.

when no choice is entered:
~~~~~~~~~~~~~~~~~~~~~~~~~~

::<commit_msg>Fixed #40 - add a full-featured example<commit_after>=======
pimento
=======

simple CLI menu

* `examples`_
* `features`_
* `cli`_
* `installation`_
* `testing`_
* `API deprecation notice`_

examples
========

simple CLI menu prompting
-------------------------

There is a single required argument:

* items - a finite iterable (list, tuple, etc) of items which the user will be prompted to choose from

.. code:: python

  from pimento import menu
  result = menu(['red', 'blue', 'green', 'grey'])

Prints:
::

  Options:
    red
    blue
    green
    grey
  Enter an option to continue: 

Entering ``r`` results in ``red`` being returned from the function.

User input is matched case-sensitively from the beginning of each option.  Ambiguous, null, and invalid entries are handled, an error message displayed, and the menu reprompted automatically.

This is the simplest, default usage.  For more options, see the following example and the `features`_ list.
  
cli menu with all the features
------------------------------

* custom pre-prompt
* custom post-prompt
* indexing
* default selection
* case-insensitivity
* 'search' matching (vs 'match' matching)

.. code:: python

  from pimento import menu
  result = menu(
    ['RED', 'Red', 'blue', 'green', 'grey', 'light URPLE'],
    pre_prompt='Available colors:',
    post_prompt='Please select a color [{}]',
    default_index=1,
    indexed=True,
    insensitive=True,
    search=True
  )

Prints:
::

  Available colors:
    [0] RED
    [1] blue
    [2] green
    [3] grey
    [4] light URPLE
  Please select a color [blue]: 

Entering ``urple`` will result in the function returning ``light URPLE``.

features
========

* Sane defaults (see the `simple cli menu prompting`_ example)
* `custom pre-prompt`_
* `custom post-prompt`_
* `partial matches`_
* `re-prompting`_
* `using a default`_
* `using indices`_
* `deduplication`_
* `case-insensitivity`_
* `searching`_

custom pre-prompt
-----------------

You may specify any pre-prompt you wish to appear before the list of options:

.. code:: python

  from pimento import menu
  result = menu(
    ['red', 'blue', 'green', 'grey'],
    pre_prompt="Which color?"
  )

Prints:
::

  Which color?
    red
    blue
    green
    grey
  Enter an option to continue: 

custom post-prompt
------------------

You may specify any post-propmt you wish to appear after the list of options:

.. code:: python

  from pimento import menu
  result = menu(
    ['red', 'blue', 'green', 'grey'],
    post_prompt="Please select one: "
  )

Prints:
::

  Options:
    red
    blue
    green
    grey
  Please select one:

partial matches
---------------

The user can select either a full option or a partial match.  All of the following will result in the user selecting ``blue``:

* ``b``
* ``bl``
* ``blu``
* ``blue``

re-prompting
------------

When an invalid option is entered, an actionable error message is printed, and the menu is re-prompted.

when no choice is entered:
~~~~~~~~~~~~~~~~~~~~~~~~~~

::
{'fraction_non_alphanumeric': 0.1603879990976765, 'fraction_numerical': 0.0018046469659372885, 'mean_word_length': 2.838961038961039, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6379317', 'n_tokens_mistral': 1400, 'n_tokens_neox': 1324, 'n_words': 533}