Claro/docs/SPEC.md

Claro Language Specification

Current package: Claro v1.18.26
Status: Living v1 specification

This document defines the intended behavior of the Claro language. It is written to reduce breaking changes and keep the v1 line teachable and predictable.

---

1. Design goals

1. Easy to learn: readable keywords, minimal punctuation.
2. Accessible: consistent rules, simple mental model, clear errors.
3. General-purpose scripting: files, JSON/CSV, small tools.
4. Safe by default: TRY/CATCH, predictable runtime behavior.

Current scope notes:

• Concurrency is being developed as beginner-safe tasks first; native threads are not exposed as the beginner API.
• Advanced static typing exists as a foundation and is still being expanded.
• Metaprogramming/macros are not a current goal.

---

2. Source files

• UTF-8 text files.
• LF or CRLF line endings.
• Trailing whitespace is ignored.
• Empty lines are ignored.

---

3. Comments

3.1 Single-line

# starts a comment to end-of-line.

3.2 Multi-line block

A block comment starts with COMMENT and ends with ENDCOMMENT. Everything between is ignored.

---

4. Runtime values (types)

Claro is dynamically typed. A value is one of:

• NONE
• NUMBER (floating point; also used for integers)
• TEXT
• BOOL (YES / NO)
• LIST (ordered; 1-based indexing)
• MAP (dictionary; keys are TEXT)

---

5. Variables

5.1 Assignment

SET name TO "Alex"
SET n TO 10

5.2 Built-ins

These names are used by the runtime:

• RESULT — value returned by the most recent CALL
• LASTERROR — most recent error message
• LASTERRORFILE — file name for most recent error
• LASTERRORLINE — line number for most recent error

User code can read these. Writing them is allowed but discouraged.

---

6. Expressions

Expressions can appear in SET/IF/RETURN/etc.

Operators (high → low precedence):

1. ( ... )
2. NOT x
3. * /
4. + -
5. = != < <= > >=
6. AND OR

Rules:

• + concatenates text if either operand is TEXT.
• Comparisons return BOOL.

---

7. Commands (statements)

Keywords are case-insensitive. Each statement is one line beginning with a keyword.

Output

SAY expr

Conditionals

IF cond
    ...
ELSEIF cond
    ...
ELSE
    ...
ENDIF

Loops

Numeric:

FOR i FROM a TO b
    ...
DONE

Iteration:

FOR EACH item IN listOrMap
    ...
DONE

Repeat:

REPEAT
    ...
UNTIL cond

---

8. Functions

Define:

TEACH name TAKES a, b
    ...
    RETURN expr
LEARNED

Call:

CALL name WITH x, y

After CALL, RESULT contains the returned value (or NONE if no RETURN executed).

---

9. Errors

Raise:

RAISE "message"

Handle:

TRY
    ...
CATCH
    SAY LASTERROR
ENDTRY

Rules:

• Errors inside TRY jump to CATCH.
• Errors outside TRY terminate the program with non-zero exit code.
• LASTERROR*, including file/line, update on error.

---

10. Data structures

LIST

1-based indexing:

SET xs TO LIST
ADD 1 TO xs
GET xs AT 1 AS first

MAP

TEXT keys:

SET m TO MAP
PUT m KEY "k" VALUE 1
GET m KEY "k" AS v

---

11. JSON

Parse:

PARSE JSON text AS value

Make:

MAKE JSON value AS text
MAKE JSON PRETTY value AS text

Parse errors should report a position (character offset) and context snippet.

---

12. Imports

IMPORT "path/to/module.claro" AS mod
EXPORT ALL

Import resolution order:

1. Relative to the importing file’s folder
2. Each folder in CLARO_PATH
3. Current working directory

---

13. CLI

claro run file.claro
claro repl
claro fmt file.claro [--inplace]
claro check file.claro
claro test

---

14. v1 stabilization notes

These details may still be refined within the v1 line:

• exact numeric precision rules
• MAP iteration ordering
• exact wording/format of error messages
• REPL multi-line behaviors
• the boundary between dynamic runtime behavior and optional static checks