simionx.Type - A type system

simionx.Type - A type system (provides type checking).

SYNOPSIS

local Type = require "simionx.Type"

-- A function with parameter checked against a built-in type.
function sqrt(x)
  Type.nonnegative_integer:check(x)
  return math.sqrt(x)
end
assert(sqrt(0) == 0)

-- A custom type.
local T_color = Type(
  function(o) return o == "red" or o == "blue" end, "color")

-- A function with named parameter validation.
local argt
function format_thing(t)
  argt = argt or Type {
    mass  = Type.number,
    color = T_color + Type['nil']
  }; argt:check(t)
  return t.mass .. " " .. (t.color == nil and "unknown" or t.color)
end
assert(format_thing {mass = 10, color="blue"} == "10 blue")

DESCRIPTION

This module provides a Type class that represents variable types for type checking values. It is particularly useful for checking named arguments to functions.

A type object can be created as follows:

local T_positive_number = Type (
  function (o) return type(o) == "number" and o > 0 end,
  "positive number"
)

The first argument is a predicate function that returns whether the object o provided to it is of the given type. The second argument is a descriptive name of the type (used only for error reporting).

This module provides many common built-in types too. For example, positive_integer already implements the type described above.

Once you have a type, you can validate values against it. For example, the T:is() method returns a boolean value indicating whether the given value has the given type:

assert(Type.positive_number:is(2))
assert(not Type.positive_number:is(0))

The T:check() method is similar but raises an error, instead of retuning a value, if the type doesn’t match:

Type.positive_number:check(2) -- passes
Type.positive_number:check(0) -- raises error

Types can be composed with the + operator, which is a logical “OR”. The composed type will match values of either component type:

local T2 = Type.number + Type.string
assert(T2:is(3) and T2:is("a"))
assert(not T2:is({x=2}))

Types can also be composed by passing a table of key-value pairs to the Type function.:

local T3 = Type {
  mass  = Type.positive_number,
  color = Type.string + Type['nil']
}
assert(T3:is {mass = 2, color = "blue"})
assert(T3:is {mass = 2})

For a table t to match the type, it must have the same keys as the type table, and the values of t must match the corresponding types in the type table.

Note that in the above we write Type['nil'] rather than Type.nil. The latter is syntactially invalid in Lua since nil is a reserved word in Lua.

Note

This page is abridged from the full SIMION "Supplemental Documentation" (Help file). The following additional sections can be found in the full version of this page accessible via the "Help > Supplemental Documentation" menu in SIMION 8.1.1 or above:

• Interface

SOURCE

version: 20080821