Tya v0.3 Draft Language Spec

This document is the draft language specification for Tya v0.3.

v0.3 builds on v0.2. The theme is standard attached libraries: Tya should ship small .tya modules that can be imported without a package manager.

v0.2 remains the baseline. Anything not changed here follows the v0.2 specification.

Goals

Included in v0.3

v0.3 adds:

Not Included in v0.3

v0.3 does not include:

Standard Attached Libraries

Standard attached libraries are .tya modules shipped with the Tya distribution. They are imported with the same syntax as user modules.

import string
import array

print string.blank("  ")
print array.empty([])

The standard attached library is not a package manager. It does not download remote code, resolve dependency versions, or install third-party modules.

Standard modules should be written as normal Tya modules whenever practical. v0.3 does not add native-backed standard modules. Format-heavy modules such as JSON and CSV are intentionally deferred.

v0.3 keeps v0.2 module syntax:

import module_name

print module_name.member()

Import aliases are still not included.

The v0.3 module search order is:

  1. The importing file's directory.
  2. Directories listed in TYA_PATH, searched left to right.
  3. The stdlib/ directory shipped with Tya.

TYA_PATH uses the host platform's path-list separator.

The module file name still matches the module name.

string.tya -> module string

Installed tools must be able to find the shipped stdlib/ directory even when tya is run outside the source checkout. Packaged installs may place it under the same shared data root as the C runtime, for example:

share/tya/stdlib/string.tya
share/tya/stdlib/array.tya

Initial Standard Modules

The initial v0.3 standard attached library should stay lightweight. It should prove the attached-library mechanism before adding parser-heavy modules.

Initial module candidates:

Example string API:

import string

print string.blank("  ")
print string.present("tya")

Example array API:

import array

print array.empty([])
print array.first(["tya"])

The exact attached library API is documented in docs/STDLIB.md.

Dictionary Direction

Dictionaries remain the main structured data value in v0.3.

Dictionary member access is still invalid.

print user["name"] # ok
print user.name    # invalid

v0.3 should improve library organization without changing dictionary syntax into object syntax.

v0.2 Baseline

v0.3 keeps the v0.2 builtins, commands, diagnostics, formatting behavior, and module syntax unless this document explicitly changes them.

Standard Builtins

v0.3 keeps every v0.2 standard builtin.

Collections

map(items, item -> item * 2)
filter(items, item -> item > 10)
find(items, item -> item == "tya")
any(items, item -> item == "tya")
all(items, item -> len(item) > 0)
sum = total, item -> total + item
reduce(items, 0, sum)

map(array, function) returns a new array containing the mapped values.

filter(array, function) returns a new array containing values for which the function returns truthy.

find(array, function) returns the first value for which the function returns truthy. If no value matches, it returns nil.

any(array, function) returns true if the function returns truthy for at least one value.

all(array, function) returns true if the function returns truthy for every value.

reduce(array, initial, function) folds an array from left to right. The function receives the current accumulator and the item.

Equality

equal(left, right)

equal(left, right) performs deep equality for v0.3 runtime values.

The == operator keeps its existing v0.1 behavior. equal is the explicit choice for deep equality in scripts and tests.

Input

read_line()

read_line() reads one line from standard input and returns it without the trailing newline. At end of input, it returns nil.

Command Line

v0.3 keeps the v0.2 user-facing commands:

tya run file.tya [args...]
tya build file.tya -o output
tya version

v0.3 keeps:

tya check file.tya
tya fmt file.tya
tya emit-c file.tya

tya check lexes, parses, and checks the file without writing an executable. It exits with status 0 when the program is valid and non-zero when diagnostics are emitted.

tya fmt writes formatted Tya source to standard output by default.

tya fmt file.tya

In-place formatting can be added with an explicit option:

tya fmt -w file.tya

tya emit-c emits generated C to standard output. This makes C emission a public developer-facing command instead of a hidden inspection option.

Diagnostics

v0.3 diagnostics should be friendly and source-oriented.

Diagnostics should include:

Example format:

main.tya:3:8: expected expression after +
  total = count +
                ^

Diagnostics should avoid Go implementation terms such as token struct names, panic traces, or internal node names unless an explicit developer inspection command asks for them.

Formatting

tya fmt defines the canonical source layout.

Formatting rules:

The formatter is allowed to be conservative in v0.3. It should prefer stable, predictable output over aggressive rewriting.

Reference Implementation

The v0.3 reference implementation remains the Go compile-to-C implementation:

Go lexer
Go parser
Go AST
Go checker
Go C emitter
C runtime
v0.3 specification tests

The current execution path remains:

Tya source -> lexer -> parser -> AST -> checker -> C emitter -> C compiler -> executable

The Tya-written compiler can continue separately, but v0.3 language authority comes from the spec and the Go compile-to-C reference implementation.