Language Reference

Complete reference of all built-in words in Pangea. Each word is shown with its English and Italian name.

Notation

Arity refers to how many arguments a word takes.
<angle brackets> indicate required arguments.
Comments start with # and run to the end of the line.

📤 Output

print / stampa

Output Arity: 1

print <value>

Description: Evaluates and prints the value to standard output, followed by a newline.

Example:

print 42
print add 5 6
print " Hello, World! "

Output:

42
11
Hello, World!

⌨️ Input And Conversion

read_text / leggi_testo

Input Arity: 0

read_text

Description: Reads one line from standard input and returns it as text.

Example:

set "line" read_text
print get "line"

Error/Edge Behavior:

At EOF, read_text returns "" (empty string).

to_number / numero_da_testo

Conversion Arity: 1

to_number <text>

Description: Converts text to a number using Lua numeric parsing rules.

Example:

print to_number "42"        → 42
print add to_number "7" 5   → 12

Error/Edge Behavior:

print to_number "abc"       → nil
      add to_number "abc" 5       → Lua runtime error (arithmetic on nil)

➕ Arithmetic

add / somma

Arithmetic Arity: 2

add <number1> <number2>

Description: Returns the sum of two numbers.

Example:

add 5 6          → 11
add -3 10        → 7
add add 1 2 3    → 6

multiply / moltiplica

Arithmetic Arity: 2

multiply <number1> <number2>

Description: Returns the product of two numbers.

Example:

multiply 7 8           → 56
multiply 3 add 2 3     → 15
multiply -1 5          → -5

modulus / modulo

Arithmetic Arity: 2

modulus <dividend> <divisor>

Description: Returns the remainder after division (modulo operation).

Example:

modulus 10 3      → 1
modulus 15 5      → 0
modulus 7 2       → 1

Use Case:

Check if a number is divisible by another:

equal 0 modulus 15 3    → true (15 is divisible by 3)

🔢 Comparison

equal / uguale

Comparison Arity: 2

equal <value1> <value2>

Description: Returns true if both values are equal, false otherwise.

Example:

equal 5 5              → true
equal 3 4              → false
equal " hello " " hello "  → true

greater / maggiore

Comparison Arity: 2

greater <value1> <value2>

Description: Returns true if value1 > value2.

Example:

greater 10 5      → true
greater 3 7       → false
greater 5 5       → false

🔀 Logic

true / vero

Logic Arity: 0

true

Description: Returns the boolean value true.

false / falso

Logic Arity: 0

false

Description: Returns the boolean value false.

nil / nullo

Logic Arity: 0

nil

Description: Returns the value nil (no value).

not / non

Logic Arity: 1

not <boolean>

Description: Logical negation. Returns the opposite boolean value.

Example:

not true              → false
not false             → true
not equal 3 4         → true
not greater 5 10      → true

🎯 Control Flow

if / se

Control Flow Arity: 3

if <condition> <then-branch> <else-branch>

Description: Conditional execution. Evaluates condition, then executes either the then-branch or else-branch.

Example:

if greater 5 3
    print " 5 is greater "
    print " 5 is not greater "

With blocks:

if equal $x 10 {
    print " x is 10 "
    print " doing something "
} {
    print " x is not 10 "
}

cond

Control Flow Arity: 1

cond { <condition> <result> ... }

Description: Multi-way conditional. Takes a block of condition result pairs and returns the result of the first truthy condition. Use else (or true) as the final condition for a default.

Example:

cond {
    not greater @1 59 "F"
    not greater @1 79 "C"
    else "A"
}

else / altrimenti

Control Flow Arity: 0

else

Description: Returns true. Used as the default clause in cond.

while / mentre

Control Flow Arity: 2

while <condition> <body>

Description: Loop that executes body while condition remains true.

Example:

i= 1
while not greater $i 5 {
    print $i
    i= add $i 1
}

Output:

do ... end / fai ... fine

Control Flow Special

do <statement1> <statement2> ... end

Description: Groups multiple statements into a single expression. Returns the value of the last statement.

Example:

set "result" do
    set "temp" 5
    multiply get "temp" get "temp"
end
print get "result"    → 25

return / ritorna

Control Flow Arity: 1

return <value>

Description: Returns a value from the enclosing function definition. Use return nil for no value.

Example:

define_word "square" 1 {
    return multiply @1 @1
}
print square 5      → 25

break / interrompi

Control Flow Arity: 1

break <value>

Description: Exits the innermost loop and returns <value> from it. Use break nil for no value. Only valid inside a loop in the same function.

Example:

i= 1
while not greater $i 20 {
    if equal 0 modulus $i 3 {
        break $i
    }
    i= add $i 1
}
print $i            → 3

continue / continua

Control Flow Arity: 0

continue

Description: Skips the rest of the current loop iteration and continues with the next one. Only valid inside a loop in the same function.

Example:

i= 0
while not greater $i 5 {
    i= add $i 1
    if equal 0 modulus $i 2 {
        continue
    }
    print $i
}

📦 Variables

set / metti

Variables Arity: 2

set <variable-name> <value>

Description: Stores a value in a variable in the current scope.

Example:

set "x" 10
set "name" "Alice"
set "result" add 5 6

Note: Use quoted strings for variable names and literal text.

get / prendi

Variables Arity: 1

get <variable-name>

Description: Retrieves the value of a variable from the current scope.

Example:

set "x" 42
print get "x"       → 42

sugar: $name / name= / @index / { }

Variables Sugar

$name → get "name" · name= value → set "name" value · @index → argument index · { → do · } → end

Description: $name is shorthand for get "name", name= value is shorthand for set "name" value, @index is shorthand for argument index, and { / } are shorthand for do / end.

Example:

x= 10
print $x        → 10
y= add $x 5
print $y        → 15

Note: Language-agnostic (works with prendi/metti in Italian). Quoted strings are unaffected: print "$x" prints the literal $x.

increment / incrementa

Variables Arity: 1

increment <variable-name>

Description: Increments a numeric variable by 1 and returns the new value.

Example:

set "i" 5
increment "i"     → 6
print get "i"       → 6

🔧 Functions

define_word / definisci_parola

Functions Arity: 3

define_word <name> <arity> <body>

Description: Defines a new word (function) with the specified name, number of arguments, and body.

Example:

define_word "square" 1
    multiply @1 @1

define_word "sum3" 3
    add @1 add @2 @3

print square 5      → 25
print sum3 1 2 3    → 6

argument / argomento

Functions Arity: 1

argument <index>

Description: Accesses a function parameter by index (1-based).

Example:

define_word "greet" 2 do
    print argument 1
    print argument 2
end

greet " Hello " " World "

namespace

Functions Arity: 0

namespace

Description: Returns the current function's namespace (variable table).

Example:

define_word "test" 1
    variable_set namespace "x" argument 1
    
test 42

📝 Advanced Variables

variable_set / metti_variabile

Advanced Arity: 3

variable_set <namespace> <name> <value>

Description: Sets a variable in a specific namespace (scope).

Example:

variable_set namespace "x" 100

variable_get / prendi_variabile

Advanced Arity: 2

variable_get <namespace> <name>

Description: Gets a variable from a specific namespace (scope).

Example:

print variable_get namespace "x"

📄 File Operations

!

File Arity: 1

! <filename>

Description: Executes the code in the specified file.

Example:

! "helper.words"
! "../tests/factorial.words"

Note: File paths are relative to the current working directory.

🎨 Special Operators

String literals

Special Syntax

"text"

Description: String literals are always quoted and are never evaluated as words.

Example:

set "x" "hello"
get "x"
print "line1\nline2"
print "quote: \"ok\""

Supported Escapes:

\" for quote
\\ for backslash
\n for newline
\t for tab

dont / non_fare

Special Arity: 1

dont <expression>

Description: Consumes one argument but does nothing. Used to comment out code or create no-op placeholders. For a simpler no-op, use pass (see below).

Example:

dont print " This won't be executed "
print " But this will "

pass / passa

Special Arity: 0

pass

Description: No-op word that does nothing. A cleaner alternative to dont nothing for empty branches.

Example:

if true
    pass
    print " not executed "

string / stringa

Special Removed

N/A

Description: Legacy keyword removed. Use quoted literals directly.

Example:

print "hello"

❓ Utilities

?

Utility Arity: 0

Description: Lists all defined words with their arities.

Example:

Output:

print<1 add<2 multiply<2 if<3 while<2 ...

exit / esci

Utility Arity: 0

exit

Description: Exits the REPL.

Example:

exit

🌐 Bilingual Reference Table

Category	English	Italian	Arity
Output	print	stampa	1
Arithmetic	add	somma	2
Arithmetic	multiply	moltiplica	2
Arithmetic	modulus	modulo	2
Comparison	equal	uguale	2
Comparison	greater	maggiore	2
Logic	true	vero	0
Logic	false	falso	0
Logic	not	non	1
Control Flow	if	se	3
Control Flow	while	mentre	2
Control Flow	do	fai	special
Control Flow	end	fine	special
Variables	set	metti	2
Variables	get	prendi	1
Variables	increment	incrementa	1
Functions	define_word	definisci_parola	3
Functions	argument	argomento	1
Special	dont	non_fare	1
Special	string	stringa	1
Special	exit	esci	0

💡 Missing a Feature?

Pangea is intentionally minimal. Missing features include:

Subtraction and division (use add ... -N for subtraction)
I/O operations (read from stdin, write to files)
Lists/arrays
Dictionaries/maps
String manipulation
Break statement in loops

These can be added by defining new Lua functions in word_definitions.

⚠ Known Limitations

No tail-call optimization (deep recursion may overflow)
No garbage collection control
Limited error messages
Case-sensitive keywords
File paths are relative to CWD, not script location