21.14.1 GNU poke Version String Parsing Utilities

The Poke standard library provides utilities for parsing and comparing GNU poke versions, to allow you to implement conditional code paths or to check prerequisites.

Variable: string pk_version

Version string of the current instance of GNU poke.

Note that these functions are not generic to any version string, as they assume and verify the version strings generated by the GNU poke build system.

The GNU poke version string that this family of functions accepts fit the following template: ‘X.Y[.Z][-BRANCH-NN][-gXDIGITS][-dirty]’. Individually, these components are:

‘X’

The major component of this GNU poke version. Mandatory.

‘Y’

The minor component of this GNU poke version. Mandatory.

‘Z’

The subminor component of this GNU poke version. Optional.

‘BRANCH’

A free-form string signifying the current branch a given GNU poke build comes from. Optional. It has two special values:

‘maint’

For maintenance branches.

‘dev’

For the master development branch.

All values other than ‘dev’ are considered equal and lower than ‘dev’ by the comparison helper described below..

‘NN’

The number commits on ‘BRANCH’ since the ‘X.Y[.Z]’ tag. Present if and only if ‘BRANCH’ is present. This component is also called the offset.

‘XDIGITS’

The abbreviated commit hash this build was generated on. For the purposes of these functions, it is optional, however, in practice, it can only appear when ‘BRANCH’ is also present. Due to the ‘-g’ prefix, this component also makes a poke version string appropriate for Git operations, for example: git show 3.0-dev-22-g2e092.

‘-dirty’

This suffix is added if the Git tree this GNU poke version was built from is dirty.

The standard library provides the following structured representation of GNU poke versions:

type Pk_Version =
  struct
  {
    uint<8> major;
    uint<8> minor;
    uint<8> subminor;
    string branch;
    uint<32> offset;
    string commit;

    uint<8> has_branch_p;
    uint<8> has_subminor_p;
    uint<8> has_commit_p;
    uint<8> dirty_p;
  };

Function: string Pk_Version.to_string ()

Method that returns the printed representation of a version.

Function: Pk_Version pk_version_parse (string version)

Parses the string version into a new instance of Pk_Version, or raises E_inval if the string is invalid.

The standard library also provides the following helper function:

Function: int<32> pk_vercmp (any a, any b)

Returns a number greater than, equal to, or lower than zero if a compares greater than, equal to or lower than b, respectively, as a GNU poke version.

The type of a and b must be either string or Pk_Version, otherwise, this function raises an E_conv.

This function implements partial ordering, as it’s not possible to distinguish some version numbers as greater or lower than each other, as some could be seen as “lateral” to eachother. For instance, consider the strings ‘3.0-a-11-gabcdef’ and ‘3.0-b-11-gabcdef’. They are both 11 commits ahead of the 3.0 release, but they aren’t on the same lineage, and so, they can’t be considered as greater or lower than eachother. In cases like these, pk_vercmp will attempt to compare commit numbers as a crude measure.