Docs - TSL — Time Script Language

Getting Started

TSL (Time Script Language) is a small programming language that transpiles to JavaScript. It uses indentation for blocks and has simple syntax.

Installation

npm install

Quick Start

Create a file hello.tsl:

# Hello World
print("Hello, World!")

Run it:

node src/cli.js hello.tsl

Build to JavaScript

node src/cli.js hello.tsl -o hello.js

Syntax

Comments

Use # for line comments:

# This is a comment
x = 10  # inline comment

Keywords

Keyword	Description
`if`	Conditional statement
`else`	Alternate branch
`for`	Loop over iterable
`in`	Used with for
`while`	Conditional loop
`function`	Function declaration
`return`	Return from function
`break`	Exit loop early
`continue`	Skip to next iteration
`pass`	No-op statement
`true` / `false`	Boolean literals
`null`	Null literal
`and` / `or` / `not`	Logical operators

Block Structure

TSL uses indentation to define code blocks, not braces or keywords.

if x > 10:
    print(x)
else:
    print("small")

Data Types

Numbers

x = 10
pi = 3.14

Strings

name = "hello"
greeting = 'world'

Escape sequences: \n, \t, \\, \", \'

Booleans

flag = true
disabled = false

Null

value = null

Type Summary

Type	TSL Literal	JavaScript Output
Number	`10`, `3.14`	`10`, `3.14`
String	`"hi"`, `'hi'`	`"hi"`
Boolean	`true`, `false`	`true`, `false`
Null	`null`	`null`
Array	`[1, 2]`	`[1, 2]`
Object	`{x: 1}`	`{ x: 1 }`

Operators

Arithmetic

Operator	Description
`+`	Addition
`-`	Subtraction
`*`	Multiplication
`/`	Division
`%`	Modulo

Comparison

Operator	Description
`<`	Less than
`<=`	Less than or equal
`>`	Greater than
`>=`	Greater than or equal
`==`	Equal
`!=`	Not equal

Logical

Operator	Description
`and`	Logical AND
`or`	Logical OR
`not`	Logical NOT (prefix)

Operator Precedence (highest to lowest)

()
not
*, /, %
+, -
<, <=, >, >=
==, !=
and
or

Variables

Assignment uses =. The first assignment in a scope creates a variable (generates let).

x = 10      # generates: let x = 10;
x = 20      # generates: x = 20;

Identifiers

Must start with a letter or _
Followed by letters, digits, or _
Case-sensitive
Cannot be a keyword

Control Flow

If / Else

x = 15
if x > 10:
    print("big")
else:
    print("small")

While

counter = 3
while counter > 0:
    print(counter)
    counter = counter - 1

For

for i in range(5):
    print(i)

Break / Continue

for i in range(10):
    if i == 3:
        continue
    if i == 7:
        break
    print(i)

Functions

Declaration

function add(a, b):
    return a + b

result = add(10, 20)

No Return Value

function greet(name):
    print("Hello, " + name)

Scope

Each function creates a new lexical scope. Variables inside are local to that function.

x = 10

function foo():
    x = 20      # shadows outer x

foo()
print(x)      # prints 10

Arrays

Create

numbers = [1, 2, 3, 4, 5]

Access

first = numbers[0]

Assignment

numbers[0] = 10

Iteration

total = 0
for num in numbers:
    total = total + num

Objects

Create

player = {
    x: 100,
    y: 200
}

Member Access

print(player.x)
player.x = 300

Chained Access

matrix = { rows: 3, cols: 4, data: [1, 2, 3] }
print(matrix.data[0])

CLI Reference

Command	Description
`node src/cli.js <file.tsl>`	Compile and show generated JS
`node src/cli.js build <file.tsl>`	Build to stdout
`node src/cli.js build <file.tsl> -o <out.js>`	Build to file
`node src/cli.js check <file.tsl>`	Validate only
`node src/cli.js --version`	Show version

Error System

Errors are categorized by pipeline stage:

Category	Class	Description
Lexer Error	`LexerError`	Invalid characters or unterminated strings
Parser Error	`ParserError`	Unexpected tokens or missing syntax
Semantic Error	`ValidationError`	`return` outside function, `break`/`continue` outside loop
Generator Error	`GeneratorError`	Unknown AST node type
Runtime Error	`RuntimeError`	Execution errors

Every compiler error includes: filename, line, column, and message.