``roleplay`` commands
=====================

.. csv-table::
  :widths: auto

  "**Plugin**", :class:`~shellbot.plugins.roleplay.Roleplay`
  "**Brief**", "Roleplay commands (dices, randomness and analysis)."


`dice <../plugins/roleplay.html#shellbot.plugins.roleplay.Roleplay.dice>`_
--------------------------------------------------------------------------

.. csv-table::
  :widths: auto

  "**Aliases**", "No alias"
  "**Brief**", "Roll a dice with 6 sides or as specified."
  "**Usage**", ``dice [expr]``

.. code-block:: text

        positional arguments:
          expr  a dice expression to perform


Examples
~~~~~~~~

.. csv-table::
    :widths: auto

    "``dice``","Equivalent to ""dice 1d6""."
    "``dice d100``","Return an element of [1, 100] (e.g. [32])."
    "``dice 4d6``","Return a 4-uplets of elements in [1, 6] (e.g. [1, 4, 3, 2])."
    "``dice 4d6...``","Return the sum of the 4-uplets of elements in [1, 6] (e.g. [1, 4, 3, 2] yields 10)."
    "``dice 4d6+``","Return a (ascending) sorted 4-uplet of elements in [1, 6] (e.g. [1, 4, 2, 5] yields [1, 2, 4, 5])."
    "``dice 2d6-``","Return a (descrasing) sorted 4-uplets of elements in [1, 6] (e.g. [1, 4, 2, 5] yields [5, 4, 2, 1])."
    "``dice 5d4+3``","Keep the 3 highest rolls of a 5-uplet of elements in [1, 4]."
    "``dice 5d4-3``","Keep the 3 lowest rolls of a 5-uplet of elements in [1, 4]."
    "``dice 2d8++``","Equivalent to ""dice 2d8+1"" ."
    "``dice 2d8--``","Equivalent to ""dice 2d8-1""."

Details
~~~~~~~

The ``dicetype`` parameter is a positional argument specifying both the dice
type and the last operation to execute before returning a result.

The ``dicetype`` parameter is parsed via the pattern ``[N]d[limit][suffix]``,
where ``N`` denotes the number of dices (defaults to *1*), ``limit`` the number
of dices faces (defaults to *6*) and ``suffix`` belongs to the following table.
Errors due to the suffix are silented.

+------------+-----------------------------------------------------------+
| suffix     | Description                                               |
+============+===========================================================+
| ``...``    | Return the sum of the results                             |
+------------+-----------------------------------------------------------+
| ``+``      | Sort (ascending order) the list of rolls                  |
+------------+-----------------------------------------------------------+
| ``++``     | Return the highest value.                                 |
+------------+-----------------------------------------------------------+
| ``+n``     | Keep the ``n`` (or less) highest values                   |
+------------+-----------------------------------------------------------+
| ``-``      | Sort (descreasing order) the list of rolls                |
+------------+-----------------------------------------------------------+
| ``--``     | Return the lowest value.                                  |
+------------+-----------------------------------------------------------+
| ``-n``     | Keep the ``n`` (or less) lowest values                    |
+------------+-----------------------------------------------------------+


`flipcoin <../plugins/roleplay.html#shellbot.plugins.roleplay.Roleplay.flipcoin>`_
----------------------------------------------------------------------------------

.. csv-table::
  :widths: auto

  "**Aliases**", "flc"
  "**Brief**", "Simulate a coin tossing or finitely many coin tossings."
  "**Usage**", ``flipcoin [n]``

.. code-block:: text

        positional arguments:
          n  optional number of coin tossings to execute


Examples
~~~~~~~~

.. csv-table::
    :widths: auto

    "``flipcoin``","Equivalent to ""flipcoin 1""."
    "``flipcoin 10``","Simulate 10 coin tossings."

`randint <../plugins/roleplay.html#shellbot.plugins.roleplay.Roleplay.randint>`_
--------------------------------------------------------------------------------

.. csv-table::
  :widths: auto

  "**Aliases**", "No alias"
  "**Brief**", "Generate a random integer or a random sequence of integers within the given bounds."
  "**Usage**", ``randint [expr]``

.. code-block:: text

        positional arguments:
          expr  a string denoting the range and the number of execution


Examples
~~~~~~~~

.. csv-table::
    :widths: auto

    "``randint``","Equivalent to ""randint 1:6:1""."
    "``randint 10``","Generate a random integer in [1, 10]."
    "``randint 0:10``","Generate a random integer in [0, 10]."
    "``randint (-100):10``","Generate a random integer in [-100, 10]."
    "``randint 10:20:2``","Generate a pair of random integers in [10, 20]."
    "``randint 10::3``","Generate a 3-uplet of random integers in [10, +∞]."
    "``randint ::2``","Generate a pair of random integers in [1, 6]."
    "``randint :22:4``","Generate a 4-uplet of random integers in [1, 22]."

Details
~~~~~~~

If one desires to include negative numbers for the bounds, they must place parentheses around them. If the number is converted into emoticons (thanks to Discord), it is still possible to escape numbers by placing parentheses around.

`randuser <../plugins/roleplay.html#shellbot.plugins.roleplay.Roleplay.randuser>`_
----------------------------------------------------------------------------------

.. csv-table::
  :widths: auto

  "**Aliases**", "No alias"
  "**Brief**", "Picks a random server's member and displays it."
  "**Usage**", ``randuser``