Built-ins

Nilakan has value-producing builtins and effectful procedures. Both use call syntax. A procedure call is a statement and cannot be used where an expression value is required.

Signatures

| Function | Returns | Notes | | -------------------------------------- | ------------ | ----------------------------------------------------------------- | | str() | str | Returns the empty string. | | str(value) | str | Converts any non-error Nilakan value to text. | | bool(value=False) | bool | Converts a non-error Nilakan value by the truth rules below. | | num(value) | num \| err | Converts a number, boolean, or decimal string. | | len(obj) | num | Collection size; strings count Unicode code points. | | ord(c) | num \| err | ValueError/NLK4002 unless c is one Unicode character. | | chr(i) | str \| err | ValueError/NLK4002 unless i is a valid Unicode code point. | | list(iterable=()) | list | Converts a list, tuple, set, dict, or string. Dicts produce keys. | | tuple(iterable=()) | tuple | Converts a tuple, list, set, dict, or string. Dicts produce keys. | | set(iterable=()) | set | Converts a set, list, tuple, dict, or string. Dicts produce keys. | | dict(iterable=()) | dict | Converts a dict or a list/tuple of two-item lists or tuples. | | err(name, message, code) | err | Creates an error value from three strings. | | is_err(value, *, name=..., code=...) | bool | Matches an error, optionally by exact name and/or code. | | err_name(value) | str | Returns an error value’s name. | | err_message(value) | str | Returns an error value’s message. | | err_code(value) | str | Returns an error value’s diagnostic code. |

Parameters

| Function | Parameter rules | | -------------------------- | ---------------------------------------------------------------- | | str(value) | accepts any direct non-error value. | | bool(value) | accepts numbers, booleans, strings, and containers. | | num(value) | accepts a number, boolean, or Nilakan decimal string. | | len(obj) | obj must be str, list, tuple, set, or dict. | | ord(c) | c must be a one-character string. | | chr(i) | i must be an integer Unicode code point. | | list(iterable) | iterable must be list, tuple, set, dict, or str. | | tuple(iterable) | iterable must be tuple, list, set, dict, or str. | | set(iterable) | iterable must be set, list, tuple, dict, or str. | | dict(iterable) | iterable must be a dict or a list/tuple of two-item sequences. | | err(name, message, code) | all three parameters must be strings. | | is_err(value) | accepts any value; name and code are keyword-only strings. | | err_name(value) | value must be err. | | err_message(value) | value must be err. | | err_code(value) | value must be err. |

Builtin and member-method arguments can be passed by Python-style documentation names, such as len(obj=xs) or "abc".replace(old="a", new="x"). Python defaults that are concrete Nilakan values are implemented. Python defaults that are None are deferred until Nilakan has a null value.

Dict conversion to list, tuple, or set uses keys. Set and dictionary conversion preserves insertion order. list(), tuple(), set(), and dict() create empty collections.

str(value) returns strings unchanged. Numbers use their canonical decimal representation, booleans use True and False, and containers use Nilakan literal formatting.

bool(value) is false for False, zero, an empty string, or an empty container. Other supported values are true. Guards still require a boolean; use bool(value) when conversion is intended.

num(value) returns numbers unchanged, converts booleans to 1 or 0, and parses signed integer or decimal strings after removing surrounding Nilakan whitespace. Exponent notation, hexadecimal notation, Infinity, and NaN are not accepted.

Errors

num() still requires one argument. str() returns ""; bool() defaults to False.

Invalid numeric text returns ValueError/NLK4002. Unsupported conversion input types are fatal type diagnostics.

ord() requires exactly one Unicode character. chr() requires an integer in the valid Unicode range. A domain miss returns ValueError/NLK4002; type and arity failures are fatal diagnostics.

dict(x) requires pair items when converting from a list or tuple. Each pair must itself be a two-item list or tuple.

Ordinary built-ins reject direct error arguments. The error inspection built-ins are the exception: is_err() accepts any value, and err_name(), err_message(), and err_code() require a direct error. is_err filters are exact and case-sensitive; when both name and code are supplied they are combined with AND.

Only explicitly registered operation failures become error values. num(), ord(), and chr() register their value-domain failures. Type and arity failures remain fatal diagnostics.

Print Procedure

print(*objects, sep=" ", end="\n") writes Nilakan-formatted values separated by sep and followed by end. It is valid at top level, inside functions, and inside commit loops.

print is a procedure, so value = print(...) is invalid. A user function that directly or transitively calls print is also effectful and may only be called as a statement.

Output inside a commit round is transactional. Nilakan publishes it only when the round commits. Output from a failed round or a discarded speculative primed-guard round is discarded. Output committed by a nested loop remains buffered until every enclosing round commits.

file is deferred until Nilakan has file values. str(x) returns a string value; it does not select the quote style used by print.

Examples

print(str(True))
print(len(["a", "b", "c"]))
print(ord("A"))
print(chr(65))

failure: err = err("MyError", "bad input", "APP0001")
print(is_err(failure))
print(is_err(failure, name="MyError", code="APP0001"))
print(err_name(failure))

keys = list({"a": 1, "b": 2})
print(keys)

pairs = [["name", "nilakan"], ["version", 1]]
print(dict(pairs))