# GNU Make Standard Library

The GNU Make Standard Library (GMSL) is a collection of functions implemented using native GNU Make functionality that provide list and string manipulation, integer arithmetic, associative arrays, stacks, and debugging facilities. The GMSL is released under the BSD License.
[Project Page] [Download] [Discussion Forum]

## Using GMSL

The two files needed are gmsl and __gmsl. To include the GMSL in your Makefile do

    include gmsl

gmsl automatically includes __gmsl. To check that you have the right version of gmsl use the gmsl_compatible function (see below). The current version is 1 1 9.
The GMSL package also includes a test suite for GMSL. Just run make -f gmsl-tests.

## Logical Operators

GMSL has boolean $(true) (a non-empty string) and $(false) (an empty string). The following operators can be used with those variables.

not
Arguments: A boolean value
Returns: Returns $(true) if the boolean is $(false) and vice versa

and
Arguments: Two boolean values
Returns: Returns $(true) if both of the booleans are true

or
Arguments: Two boolean values
Returns: Returns $(true) if either of the booleans is true

xor
Arguments: Two boolean values
Returns: Returns $(true) if exactly one of the booleans is true

nand
Arguments: Two boolean values
Returns: Returns value of 'not and'

nor
Arguments: Two boolean values
Returns: Returns value of 'not or'

xnor
Arguments: Two boolean values
Returns: Returns value of 'not xor'

## List Manipulation Functions

A list is a string of characters; the list separator is a space.

first
Arguments: 1: A list
Returns: Returns the first element of a list

last
Arguments: 1: A list
Returns: Returns the last element of a list

rest
Arguments: 1: A list
Returns: Returns the list with the first element removed

chop
Arguments: 1: A list
Returns: Returns the list with the last element removed

map
Arguments: 1: Name of function to $(call) for each element of list
2: List to iterate over calling the function in 1
Returns: The list after calling the function on each element

pairmap
Arguments: 1: Name of function to $(call) for each pair of elements
2: List to iterate over calling the function in 1
3: Second list to iterate over calling the function in 1
Returns: The list after calling the function on each pair of elements

leq
Arguments: 1: A list to compare against...
2: ...this list
Returns: Returns $(true) if the two lists are identical

lne
Arguments: 1: A list to compare against...
2: ...this list
Returns: Returns $(true) if the two lists are different

reverse
Arguments: 1: A list to reverse
Returns: The list with its elements in reverse order

uniq
Arguments: 1: A list to deduplicate
Returns: The list with elements in order without duplicates

length
Arguments: 1: A list
Returns: The number of elements in the list

## String Manipulation Functions

A string is any sequence of characters.

seq
Arguments: 1: A string to compare against...
2: ...this string
Returns: Returns $(true) if the two strings are identical

sne
Arguments: 1: A string to compare against...
2: ...this string
Returns: Returns $(true) if the two strings are not the same

strlen
Arguments: 1: A string
Returns: Returns the length of the string

substr
Arguments: 1: A string
2: Start offset (first character is 1)
3: Ending offset (inclusive)
Returns: Returns a substring

split
Arguments: 1: The character to split on
2: A string to split
Returns: Splits a string into a list separated by spaces at the split
character in the first argument

merge
Arguments: 1: The character to put between fields
2: A list to merge into a string
Returns: Merges a list into a single string, list elements are separated
by the character in the first argument

tr
Arguments: 1: The list of characters to translate from
2: The list of characters to translate to
3: The text to translate
Returns: Returns the text after translating characters

uc
Arguments: 1: Text to upper case
Returns: Returns the text in upper case

lc
Arguments: 1: Text to lower case
Returns: Returns the text in lower case

## Set Manipulation Functions

Sets are represented by sorted, deduplicated lists. To create a set from a list use set_create, or start with the empty_set and set_insert individual elements. The empty set is defined as empty_set.

set_create
Arguments: 1: A list of set elements
Returns: Returns the newly created set

set_insert
Arguments: 1: A single element to add to a set
2: A set
Returns: Returns the set with the element added

set_remove
Arguments: 1: A single element to remove from a set
2: A set
Returns: Returns the set with the element removed

set_is_member
Arguments: 1: A single element
2: A set
Returns: Returns $(true) if the element is in the set

set_is_not_member
Arguments: 1: A single element
2: A set
Returns: Returns $(false) if the element is in the set

set_union
Arguments: 1: A set
2: Another set
Returns: Returns the union of the two sets

set_intersection
Arguments: 1: A set
2: Another set
Returns: Returns the intersection of the two sets

set_is_subset
Arguments: 1: A set
2: Another set
Returns: Returns $(true) if the first set is a subset of the second

set_equal
Arguments: 1: A set
2: Another set
Returns: Returns $(true) if the two sets are identical

## Integer Arithmetic Functions

Integers are represented by lists with the equivalent number of x's. For example the number 4 is x x x x. The maximum integer that the library can handle as input (i.e. as the argument to a call to int_encode) is 65536. There is no limit on integer size for internal computations or output.
The arithmetic library functions come in two forms: one form of each function takes integers as arguments and the other form takes the encoded form (x's created by a call to int_encode). For example, there are two plus functions: plus (called with integer arguments and returns an integer) and int_plus (called with encoded arguments and returns an encoded result).
plus will be slower than int_plus because its arguments and result have to be translated between the x's format and integers. If doing a complex calculation use the int_* forms with a single encoding of inputs and single decoding of the output. For simple calculations the direct forms can be used.

int_decode
Arguments: 1: A number of x's representation
Returns: Returns the integer for human consumption that is represented
by the string of x's

int_encode
Arguments: 1: A number in human-readable integer form
Returns: Returns the integer encoded as a string of x's

int_plus
Arguments: 1: A number in x's representation
2: Another number in x's represntation
Returns: Returns the sum of the two numbers in x's representation

plus (wrapped version of int_plus)
Arguments: 1: An integer
2: Another integer
Returns: Returns the sum of the two integers

int_subtract
Arguments: 1: A number in x's representation
2: Another number in x's represntation
Returns: Returns the difference of the two numbers in x's representation,
or outputs an error on a numeric underflow

subtract (wrapped version of int_subtract)
Arguments: 1: An integer
2: Another integer
Returns: Returns the difference of the two integers,
or outputs an error on a numeric underflow

int_multiply
Arguments: 1: A number in x's representation
2: Another number in x's represntation
Returns: Returns the product of the two numbers in x's representation

multiply (wrapped version of int_multiply)
Arguments: 1: An integer
2: Another integer
Returns: Returns the product of the two integers

int_divide
Arguments: 1: A number in x's representation
2: Another number in x's represntation
Returns: Returns the result of integer division of argument 1 divided
by argument 2 in x's representation

divide (wrapped version of int_divide)
Arguments: 1: An integer
2: Another integer
Returns: Returns the integer division of the first argument by the second

int_modulo
Arguments: 1: A number in x's representation
2: Another number in x's represntation
Returns: Returns the remainder of integer division of argument 1 divided
by argument 2 in x's representation

modulo (wrapped version of int_modulo)
Arguments: 1: An integer
2: Another integer
Returns: Returns the remainder of integer division of the first argument by the second

int_max, int_min
Arguments: 1: A number in x's representation
2: Another number in x's represntation
Returns: Returns the maximum or minimum of its arguments in x's
representation

max, min
Arguments: 1: An integer
2: Another integer
Returns: Returns the maximum or minimum of its integer arguments

int_gt, int_gte, int_lt, int_lte, int_eq, int_ne
Arguments: Two x's representation numbers to be compared
Returns: $(true) or $(false)
int_gt First argument greater than second argument
int_gte First argument greater than or equal to second argument
int_lt First argument less than second argument
int_lte First argument less than or equal to second argument
int_eq First argument is numerically equal to the second argument
int_ne First argument is not numerically equal to the second argument

gt, gte, lt, lte, eq, ne
Arguments: Two integers to be compared
Returns: $(true) or $(false)
gt First argument greater than second argument
gte First argument greater than or equal to second argument
lt First argument less than second argument
lte First argument less than or equal to second argument
eq First argument is numerically equal to the second argument
ne First argument is not numerically equal to the second argument
increment adds 1 to its argument, decrement subtracts 1. Note that
decrement does not range check and hence will not underflow, but
will incorrectly say that 0 - 1 = 0

int_inc
Arguments: 1: A number in x's representation
Returns: The number incremented by 1 in x's representation

inc
Arguments: 1: An integer
Returns: The argument incremented by 1

int_dec
Arguments: 1: A number in x's representation
Returns: The number decremented by 1 in x's representation

dec
Arguments: 1: An integer
Returns: The argument decremented by 1

int_double
Arguments: 1: A number in x's representation
Returns: The number doubled (i.e. * 2) and returned in x's representation

double
Arguments: 1: An integer
Returns: The integer times 2

int_halve
Arguments: 1: A number in x's representation
Returns: The number halved (i.e. / 2) and returned in x's representation

halve
Arguments: 1: An integer
Returns: The integer divided by 2

sequence
Arguments: 1: An integer
2: An integer
Returns: The sequence [arg1 arg2] if arg1 >= arg2 or [arg2 arg1] if arg2 > arg1

dec2hex, dec2bin, dec2oct
Arguments: 1: An integer
Returns: The decimal argument converted to hexadecimal, binary or octal

## Associative Arrays

An associate array maps a key value (a string with no spaces in it) to a single value (any string).

set
Arguments: 1: Name of associative array
2: The key value to associate
3: The value associated with the key
Returns: Nothing

get
Arguments: 1: Name of associative array
2: The key to retrieve
Returns: The value stored in the array for that key

keys
Arguments: 1: Name of associative array
Returns: Returns a list of all defined keys in the array

defined
Arguments: 1: Name of associative array
2: The key to test
Returns: Returns true if the key is defined (i.e. not empty)

## Named Stacks

A stack is an ordered list of strings (with no spaces in them).

push
Arguments: 1: Name of stack
2: Value to push onto the top of the stack (must not contain
a space)
Returns: None

pop
Arguments: 1: Name of stack
Returns: Top element from the stack after removing it

peek
Arguments: 1: Name of stack
Returns: Top element from the stack without removing it

depth
Arguments: 1: Name of stack
Returns: Number of items on the stack

## Function memoization

To reduce the number of calls to slow functions (such as $(shell) a single memoization function is provided.

memoize
Arguments: 1: Name of function to memoize
2: String argument for the function
Returns: Result of $1 applied to $2 but only calls $1 once for each unique $2

## Miscellaneous and Debugging Facilities

GMSL defines the following constants; all are accessed as normal GNU Make variables by wrapping them in $() or ${}.

Constant | Value | Purpose
true | T | Boolean for $(if) and return from GMSL functions
false |  | Boolean for $(if) and return from GMSL functions
gmsl_version | 1 0 0 | GMSL version number as list: major minor revision

gmsl_compatible
Arguments: List containing the desired library version number (maj min rev)
Returns: $(true) if this version of the library is compatible
with the requested version number, otherwise $(false)

gmsl-print-% (target not a function)
Arguments: The % should be replaced by the name of a variable that you
wish to print out.
Action: Echos the name of the variable that matches the % and its value.
For example, 'make gmsl-print-SHELL' will output the value of
the SHELL variable

gmsl-echo-% (target not a function)
Arguments: The % should be replaced by the name of a variable that you
wish to print out.
Action: Echos the value of the variable that matches the %.
For example, 'make gmsl-echo-SHELL' will output the value of
the SHELL variable

assert
Arguments: 1: A boolean that must be true or the assertion will fail
2: The message to print with the assertion
Returns: None

assert_exists
Arguments: 1: Name of file that must exist, if it is missing an assertion
will be generated
Returns: None

GMSL has a number of environment variables (or command-line overrides) that control various bits of functionality:

Variable | Purpose
GMSL_NO_WARNINGS | If set prevents GMSL from outputting warning messages: artithmetic functions generate underflow warnings.
GMSL_NO_ERRORS | If set prevents GMSL from generating fatal errors: division by zero or failed assertions are fatal.
GMSL_TRACE | Enables function tracing. Calls to GMSL functions will result in name and arguments being traced.

Copyright (c) 2005-2020 John Graham-Cumming.

John Graham-Cumming's work on this project was sponsored by Electric Cloud, Inc. |