Tya v0.24 Specification

This document is the specification for Tya v0.24 after v0.23 data-format and utility stdlib expansion.

Theme

Tya v0.24 expands the standard library with scripting essentials: time/date, random, expanded math, external process execution, hex encoding, cryptographic digests, secure random, and a small linear-algebra matrix module.

The v0.24 stdlib makes Tya practical as a shell-script replacement: scripts can read the clock, sleep, run subprocesses, hash files for caching, and generate cryptographically secure tokens.

Goals

(MD5/SHA1/SHA256/SHA384/SHA512).

Included in v0.24

v0.24 includes all v0.23 behavior and adds:

log2, log10, exp, sin, cos, tan, asin, acos, atan, atan2, plus pi and e constants)

Not Included in v0.24

v0.24 does not include:

Importing

All v0.24 modules are standard attached-library modules.

import time
import random
import math
import process
import hex
import digest
import secure_random
import matrix

time

The time module reads the system clock and provides simple formatting.

Functions

or "unix")

Example

import time

start = time.now()
time.sleep(0.5)
println time.since(start)
println time.format(time.now())

Errors

time.parse raises a structured error on invalid input.

time.sleep raises when the argument is negative or non-numeric.

time is UTC-only in v0.24 except where the system clock provides local time (time.now() returns wall clock seconds without timezone information).

random

The random module provides a seedable pseudo-random number generator (PRNG). It is **not cryptographically secure**. Use secure_random for tokens, IDs, salts, and similar.

Functions

Example

import random

random.seed(42)
println random.int(1, 6)
println random.float()
println random.choice(["red", "green", "blue"])

random.seed(value) accepts an int or a string. With no seed call, the generator is seeded from the system clock at first use; results are not reproducible.

math Expansion

v0.24 expands math (already present from v0.20) with elementary numeric functions and two constants.

New functions

New constants

Constants are values, not functions: math.pi, not math.pi().

math.abs, math.min, math.max, math.clamp from v0.20 stay unchanged.

Errors

math.sqrt of a negative number raises. math.log / math.log2 / math.log10 of a non-positive number raises. Other domain errors follow C math behavior (NaN propagates).

process

The process module runs external commands.

Functions

command is an array of strings: the program name (or path) followed by arguments. Passing a single string is **not** supported; this prevents shell-string injection.

Result dict

{
  exit_code: 0,
  stdout: "the captured stdout text",
  stderr: "the captured stderr text",
}

stdout and stderr are strings. Output is buffered fully into memory.

Options dict

All options are optional:

receives only this environment (replaces, does not merge).

Example

import process

result = process.run(["git", "rev-parse", "HEAD"])
println result["stdout"]

process.run(["sh", "-c", "echo $X"], { env: { X: "tya" } })

Errors

process.run raises when the program cannot be launched (e.g. file not found, permission denied). A non-zero exit code does **not** raise; it is reported in exit_code.

hex

The hex module encodes and decodes hexadecimal text.

Functions

Example

import hex

println hex.encode("Tya")     # 547961
println hex.decode("547961")  # Tya

hex.decode accepts uppercase or lowercase. Whitespace is not allowed in the input. Odd-length input raises a structured error.

digest

The digest module computes cryptographic message digests.

Functions

Example

import digest

println digest.sha256("hello")
# 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

For files, combine with file.read:

import digest, file

println digest.sha256(file.read("config.toml"))

Notes

hex-encoded digest.

new security work.

secure_random

The secure_random module provides cryptographically secure random data. It uses the operating system's CSPRNG (/dev/urandom, getrandom, getentropy).

Functions

Example

import secure_random

token = secure_random.hex(16)           # 32 chars
session = secure_random.uuid()          # 550e8400-e29b-41d4-a716-446655440000
salt = secure_random.bytes(16)
println secure_random.int(0, 100)

Notes

terminated at the C level, callers should generally consume the bytes via secure_random.hex or secure_random.base64 instead of bytes if NUL bytes might appear.

avoid modulo bias.

matrix

The matrix module provides basic 2-D matrix operations on numeric values. It is implemented in pure Tya.

Construction

A matrix is represented as a dict:

{ rows: 2, cols: 3, data: [[1, 2, 3], [4, 5, 6]] }

Element access

Operations

Larger matrices raise an error in v0.24.

Example

import matrix

a = matrix.new([[1, 2], [3, 4]])
b = matrix.identity(2)

println matrix.add(a, b)["data"]      # [[2, 2], [3, 5]]
println matrix.mul(a, a)["data"]      # [[7, 10], [15, 22]]
println matrix.transpose(a)["data"]   # [[1, 3], [2, 4]]
println matrix.det(a)                 # -2
println matrix.at(a, 0, 1)            # 2

Errors

elements.

Out of scope

Inverse, eigenvalue decomposition, LU/QR decomposition, sparse storage, broadcasting, vector convenience functions, complex numbers, GPU offload, all out of v0.24.

Diagnostics

v0.24 implementations should report source-oriented errors for:

Diagnostics should mention the module name, function name, expected argument shape, and actual value kind when available.