.. default-domain:: chpl

.. module:: Version
   :synopsis: Support for reasoning about version numbers.

Version
=======
**Usage**

.. code-block:: chapel

   use Version;


or

.. code-block:: chapel

   import Version;

Support for reasoning about version numbers.

.. highlight:: chapel

This module contains features that support compile-time reasoning
about version numbers in general, and Chapel version numbers
specifically.  In more detail, it features:

* :var:`chplVersion`: the version number of the copy of ``chpl`` used
  to compile the program.

* :type:`sourceVersion`: a type that can be used to represent a semantic
  version number plus an optional commit value.

* :proc:`createVersion`: a utility function for creating new version values

Version numbers in this module are represented using ``param`` values
to permit code specialization by being able to reason about versions
at compile-time.

The :type:`sourceVersion` type supports:

* being printed out or cast to a ``param`` string

* compile-time comparisons via ``==``, ``!=``, ``<``, ``<=``, ``>``,
  and ``>``.  Generally speaking, "less than" corresponds to "is an
  earlier version than."  For example::

    if chplVersion < createVersion(1,23) then
      compilerWarning("This package doesn't support 'chpl' prior to 1.23.0");


.. data:: const chplVersion

   
   The version of ``chpl`` used to compile this program.  For an
   official Chapel release, this will have an empty ``commit`` value,
   while for a pre-release, it will indicate the Git SHA.
   
   Note that, for historical reasons, Chapel ``1.x.y``/``2.x.y``
   corresponds to version ``0.x.y``/``1.x.y`` in traditional semantic
   versioning.
   

.. function:: proc createVersion(param major: int, param minor: int, param update: int = 0, param commit: string = ""): sourceVersion(?)

   
   A helper function that creates a new version value from its
   arguments.
   
   :arg major: The major version number
   :type major: `int`
   
   :arg minor: The minor version number
   :type minor: `int`
   
   :arg update: The optional update version number (defaults to 0)
   :type update: `int`
   
   :arg commit: The optional commit ID (defaults to "")
   :type commit: `string`
   
   :returns: A new version value of type :type:`sourceVersion`.
   

.. record:: sourceVersion

   
   This record represents a software version in a Git repository.  It
   uses ``param`` values to represent its components in order to
   support compile-time comparison of version numbers which in turn
   permits code to specialize to specific versions of Chapel.  When
   printed or converted to a string, it is represented as ``version
   major.minor.update (commit)``.
   
   Note that ordered comparisons between two :type:`sourceVersion`
   values that only differ in their ``commit`` values are not
   supported due to the challenges involved in ordering commit
   values.  However, when a value with an empty ``update`` value is
   compared to one whose ``update`` is non-empty, the latter is
   considered to be earlier than (less than) the former, due to the
   interpretation that it represents a pre-release of the official
   release.
   


   .. attribute:: param major: int

      
      The major version number. For version ``2.0.1``, this would be ``2``.
      

   .. attribute:: param minor: int

      
      The minor version number. For version ``2.0.1``, this would be ``0``.
      

   .. attribute:: param update: int

      
      The update version number. For version ``2.0.1``, this would be ``1``.
      

   .. attribute:: param commit: string = ""

      The commit ID of the version (e.g., a Git SHA) 

.. method:: proc type sourceVersion.==(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool

.. method:: proc type sourceVersion.!=(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool

   
   Equality/inequality operators between two values of type
   :type:`sourceVersion` check whether or not the two values
   have identical major, minor, update, and commit values.
   

.. method:: proc type sourceVersion.<(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool

.. method:: proc type sourceVersion.<=(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool

.. method:: proc type sourceVersion.>(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool

.. method:: proc type sourceVersion.>=(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool

   
   Ordered comparisons between two values of type
   :type:`sourceVersion` are based on the ordering of the semantic
   versions of the two values, as defined by their ``major``,
   ``minor``, and ``update`` components.  If the two values have
   identical semantic versions, any cases that rely on an ordering of
   the commits will generate a compile-time error if the values have
   differing, non-empty ``commit`` values due to the challenge of
   ordering commits at compile-time.  An empty ``commit`` value is
   considered to come after (be greater than) a non-empty value, as
   the former is considered an official release and the latter a
   pre-release.