.. default-domain:: bash

============
Requirements
============

.. file:: requirements.bsh

A set of functions for determining if you meet the required versions.

.. function:: meet_requirements

:Arguments: ``$1`` - Version you are checking
            [``$2``...] - Version rules

* Supports versions of any length, ``1``, ``1.0``, ``1.0.0.0.0.0``, etc...
* Supports an alpha version after the last number, ``1.0.2rc5``
* Supported version rules:
  * ``==``, ``=``- Does version equal this version. ``1`` is the same as ``1.0.0``, but not ``1.0.0p1``
  * ``!=`` - Does the version not equal this version
  * ``<`` - Is this version less than this version
  * ``<=`` - Is this version less than or equal to this version
  * ``>`` - Is this version greater than this version
  * ``>=`` - Is this version greater than or equal to this version
  * ``or`` - All rules are ``and`` ed together, unless separated by an ``or``, in which case a new group of ``and`` ed rules are started. Only one group has to be true for the result to be true. There is currently no support for rules more complex than this.

.. rubric:: Example

.. code-block:: bash

   meet_requirements 1.0.0 "<2.0.0" ">0.5.0"
   meet_requirements 1.0.0 =1
   meet_requirements 1.0.0 "<2.0.0" ">0.5.0" or ">3.0.0"
   meet_requirements 3.1.0 "<2.0.0" ">0.5.0" or ">3.0.0"

.. function:: version_eq

Checks to see if version ``$1`` equals ``$2``. Slightly more complex than a simple ``=``. For example: ``1.0p1`` is the same as ``1.0.0.0p1``

:Arguments: ``$1`` - LHS version
            ``$2`` - RHS version

.. seealso::

  :func:`meet_requirements`

.. function:: version_lt

Checks to see if version ``$1`` is less than ``$2``.

:Arguments: ``$1`` - LHS version
            ``$2`` - RHS version

.. seealso::

  :func:`meet_requirements`

.. function:: version_gt

Checks to see if version ``$1`` is greater than ``$2``.

:Arguments: ``$1`` - LHS version
            ``$2`` - RHS version

.. seealso::

  :func:`meet_requirements`

.. function:: split_version_string

:Arguments: - ``$1`` - Variable name to store the array in
            - ``$2`` - The version string

Splits a version string up into its elements and stores them in an array.

Any values starting with a non-numerical character are optionally stored in the last element as pre-release/metadata (including leading/trailing whitespace).

.. rubric:: Example:

.. code-block:: bash

   $ split_version_string x "$(bash_version)"
   $ declare -p x
   declare -a x=([0]="5" [1]="0" [2]="11" [3]="r1")

.. function:: split_version_string_and_remainder

:Arguments: - ``$1`` - Variable name to store the array in
            - ``$2`` - Variable name to store leftover versioning information in (anything starting with a non-numeric character)
            - ``$3`` - The version string

Splits a version string up into its elements and stores them in an array.

Any non-numerical values are stored in a separate variable as pre-release/metadata (including leading/trailing whitespace)