ela
Contents

ManualLanguage

Types

In the terminalela --spec types

  • Dynamic (duck) typing for variables.

  • The types are string, number, boolean (true or false), list and map, and null.

  • A number is written in decimal digits, with _ between two digits to group them and one . before a fraction: 1_000_000, 2.5. 0x1F, 0o644 and 1e3 are errors that say what to write instead; float("1e3") reads an exponent from text. A leading zero is an error, 0644 as much as 07, since C and Bash read it as octal; a file mode stays text, chmod 0644 notes.txt, where it is a command's word.

  • Proc parameters may optionally be typed; typed parameters are checked.

Type and type_of #

type_of(x) gives a value's type as a member of Type, the language's enum of value types, built in as env is:

type_of("a")         # Type.STRINGtype_of(12.5)        # Type.NUMBERtype_of(true)        # Type.BOOLtype_of([1, 2])      # Type.LISTtype_of({"a": 1})    # Type.MAPtype_of(null)        # Type.NULLtype_of($task)       # Type.STRUCT, for a struct valuetype_of(Type.LIST)   # Type.ENUM, for an enum member
  • Type's members are STRING, NUMBER, BOOL, TIME, LIST, MAP, NULL, STRUCT and ENUM, in that order. A misspelt one is an error when the script is read, and Tab offers them. No variable, constant, parameter, loop variable, proc, struct or enum can take the name, and a script that tries, Type = 1 anywhere, a branch that never runs included, stops before line 1.
  • type_of takes any value, null included, and is never an error. Its result compares with == and works in switch: if type_of($v) == Type.LIST. ela --lint knows it is a Type, so a parameter typed number refuses it before the run, and one typed Type takes it.
  • A time is a number, the seconds since 1970 that time.now() gives, so type_of(time.now()) is Type.NUMBER. Type.TIME names a table's column of times (PACKAGES.md, Column types); type_of never gives it.
  • A job, a table and a pid(...) are values ela builds, read by their fields or passed on, as a struct is: type_of gives Type.STRUCT. A struct's own name is not part of it.
  • table.of's types = takes STRING, NUMBER, BOOL and TIME only, as a column holds plain values; another member there is an error that names the four.
for v in json.decode(file.read("config.json"))["targets"]    switch type_of($v)    case Type.STRING        deploy($v)    case Type.MAP        deploy($v["host"])    case        fail "a target is a host or a map with one, got $v"    end switchend for

A switch that gives a value and has no else names every member it needs, as for any enum (Values from switch and if):

kind = switch type_of($v)    case Type.LIST, Type.MAP; "a collection"    case Type.NULL; "nothing"end switch
kinds.ela:1:8: error: this switch gives a value and has no else, and its cases miss Type.STRING, Type.NUMBER, Type.BOOL, Type.TIME, Type.STRUCT, Type.ENUM: add a case for each, or an else

null #

null is a value that says "nothing here", as JSON's and YAML's null does. A script can store it, compare it and pass it on; anything else done with it is an error at that line.

  • It comes from the literal null, from json.decode and yaml.decode, and from an optional struct field that is not set. Nothing else gives it: an undefined variable, a missing map key, an unset $env.NAME, a missing $keyring.NAME and a value a failed try left unset are errors, so a typo never becomes null.
  • It may be held by a variable, a map value, a list item, an optional field (port: number?), an untyped parameter and an optional parameter (port: number?). A parameter typed without ?, and a field without it, refuse it.
  • $v == null and $v != null test a value already in hand; null == null is true, and null against any other value is false rather than an error. switch takes case null, and the bare case matches null with the rest.
  • has($x, "k") says whether a map key or a struct field has a value: false when it is missing or null. It never errors, so it is the test for a field or key that may be either.
  • Assigning it to env.NAME removes that environment variable, as with env.NAME = null does for a block (The environment); env.get's fallback refuses it.
  • Arithmetic, < and the other orderings, min, max and list.sum, a condition, and/or/not, text ("${x}", a command's word, str.*), len, for, an index and a field read all refuse null, and the error names has or == null. There is no truthiness: if $s.port is an error whether the port is set or not, since conditions are booleans.
  • A list or map that holds null shows it as null, as its literal.
struct Task    title: string    due: string?end struct t = Task{title: "rotate the keys"}if has($t, "due")    echo "due $t.due"end if r = json.decode($(curl -s https://metrics.example/api/range))total = 0for v in $r["values"]    if $v == null        continue    end if    total = $total + $vend for patch = {"metadata": {"labels": {"old": null}}}kubectl patch deploy web --type merge -p "${json.encode($patch)}"

A map tells a key set to null from a missing key, and encode writes the first back as null; has answers false for both. The rare script that needs the difference asks the keys: has(map.keys($m), "k").