The version string used for file names and documentation is created using a pattern string.

For file names, and branch names in the Codeberg pages repository, any dots in the version string are replaced with underscores.

Substitutions

Within a pattern string, several substitutions will be made:

• Unescaped whitespace is discarded.
• Parentheses are discarded, but must balance.
• A single character can be treated as a literal character by backslash-escaping it.
• A variable name surrounded by @ characters (e.g. @foo@) is replaced with the variable's value. A non existent variable expands to nothing, which in some contexts is different from expanding to an empty string.
• A contiguous sequence of whitespace characters can be kept in the version string by surrounding them with @ characters. For example @ @.

Variables include:

• version The basic version, as defined in the VERSION file.
• revision The git revision. This is currently only available inside a Git working directory, rather than source unpacked from a distribution tarball, but in future it will be copied into the source distro. The same goes for all the repository related variables.
• extra_commits The number of extra commits after the release tag.
• extra_commits_nz The same as extra_commits but not defined if extra_commits is zero.
• dirty Only defined if in a dirty working directory. Expands to dirty.
• release Only defined in a tagged release commit. Expands to release.

Functions

A function is a name with a trailing ?, optionally followed (immediately) by parenthesised, comma separated arguments.

Nesting arguments

    foo?(arg1 @None, (arg2, more arg2) even more arg2)

Here the function foo gets two arguments. In fact it gets something like this:

[
    [
        Token("arg1"),
    ],

    [
        [
            Token("arg2"),
            Token(","),
            Token("more"),
            Token("arg2")
        ],
        Token("even"),
        Token("more"),
        Token("arg2")
    ]
]

But some functions don't care about that. Many flatten all the arguments into one token, and many flatten each argument into one token each. See tools/verpat.py for more insight into how it works, particularly the function decorators like @StringArgsFunc.

The join family

The join functions are join, join_dumb, and join_no_empties. The first argument to a join function is a separator string, and the remaining arguments are joined into one string token using the separator.

The difference is in which arguments are pruned before joining. join will remove any tokens with no value. Tokens with a value of "" will be kept.

• join: prune null tokens before joining
• join_no_empties: prune null tokens and those with empty string values
• join_dumb: don't prune anything

Not pruning anything means that for example join_dumb?(:,,,) will produce ::. Whereas join?(:,,,) will produce an empty string.

The conditional family

The conditional functions are:

• if
• exists
• not_empty

They take arguments like this:

if? (
    condition 1,
    true_statement 1,
    condition 2,
    true_statement 2,
    else_statement
)

There can be any number of conditions, and the else statement is optional.

If condition 1 is matched, the next argument is preserved as-is, but everything else is discarded. If condition 1 is false, condition 2 is tested, and so on. If no condition is met, and there is an else statement (the final argument), that argument is preserved as is and everything else is discarded.

The difference between the conditional functions is the type of test they perform.

exists? is true if the conditional argument contains any non-null tokens. You can put a literal empty string into the argument as @@, so there is at least one possible way for an empty non-null token to appear. However, the expansion of @varname@ when varname is not the name of a variable, would not pass the existence test.

not_empty also fails if an empty string is used as the condition.

if also considers a string which, when stripped of leading and trailing whitespace, is an integer or floating point literal which represents zero, to be a false value.

A conditional function which does not match any of its conditions and has no else argument will not produce tokens, not even an empty string.