AGENTS.md

eterScript - Agent Notes

Project Overview

BDFD-style scripting language implemented in Rust for general PC automation and scripting.

Language Syntax

• Everything is a function call prefixed with $
• Function arguments separated by semicolon ;
• Function calls use brackets: $functionName[arg1;arg2]
• Strings must be quoted: "Hello" not Hello
• Variable names are bare identifiers: $x is a variable reference
• Comments start with #

Working Features

Built-in Functions

Conversion

• $toNumber - Convert string/number/bool to number
• $toString - Convert any value to string

Math

• $add, $sub, $mul, $div, $mod, $pow, $sqrt
• $floor, $ceil, $round, $abs
• $rand, $randInt, $min, $max

Logic

• $if (lazy), $and (lazy), $or (lazy)
• $eq, $neq, $gt, $lt, $gte, $lte, $not

IO

• $print, $input, $readFile, $writeFile, $appendFile
• $fileExists, $deleteFile, $mkdir
• $listDir, $isDir, $isFile, $copyFile, $moveFile, $cd

Strings

• $strLen, $strSub, $strConcat, $strSplit, $strReplace
• $strLower, $strUpper, $strTrim, $strContains
• $startsWith, $endsWith, $repeat, $join, $slice, $padStart, $padEnd
• $chr, $ord

System

• $env, $args, $exit, $sleep, $pwd, $exec

Data

• $arrayCreate, $arrayGet, $arrayLen, $arrayPush, $arraySort
• $arrayMap (com callbacks!), $arrayFilter (com callbacks!), $arrayReduce (com callbacks!)
• $arrayRange, $arrayReverse, $arrayFlatten, $arrayUnique
• $arrayJoin, $arrayFind, $arrayIndexOf, $arrayContains, $arraySlice
• $dictCreate, $dictGet, $dictSet, $dictKeys, $dictValues
• $dictHas, $dictRemove, $dictEntries, $dictMerge
• $jsonParse, $jsonStringify
• $typeOf, $isNull, $isArray, $isObject, $isString, $isNumber, $isBool
• $len, $noop, $identity, $return

Network

• $httpGet, $httpPost, $httpPut, $httpDelete, $downloadFile
• $encodeUrl, $decodeUrl

Time

• $now, $timestamp, $formatDate, $timestampToDate

Crypto

• $base64Encode, $base64Decode, $hash (sha256, md5)

Regex

• $regexMatch, $regexReplace, $regexFind, $regexSplit

Special Forms (evaluator-level)

• $def[name;params;body] - Define a function. Params are space-separated, e.g., $def[add;a b;$add[$a;$b]]
• $set[varname;value] - Set a variable
• $if[cond;then;else] - Conditional (lazy: only evaluates chosen branch)
• $and[a;b;...] - Short-circuit AND
• $or[a;b;...] - Short-circuit OR
• $for[var;start;end;body] - For loop with range
• $while[cond;body] - While loop
• $break[] - Break out of loop
• $continue[] - Skip to next iteration
• $try[body;catch...] - Try/catch error handling (sets $error var)
• $throw[message] - Throw an error with message
• $return[value] - Early return from user function
• $arrayMap[arr;"funcName"] - Map with user-defined function callback
• $arrayFilter[arr;"funcName"] - Filter with user-defined function callback
• $arrayReduce[arr;initial;"funcName"] - Reduce with user-defined function callback

Control Flow Examples

# For loop
$for[i;0;10;$print[$i]]

# While loop
$set[x;0]
$while[$lt[$x;5];
    $print[$x]
    $set[x;$add[$x;1]]
]

# Break and Continue
$for[i;0;100;
    $if[$gte[$i;5];$break[];$noop[]]
    $print[$i]
]

# Try/Catch
$try[
    $readFile["missing.txt"]
;
    $print["File not found!"]
    $print[$error]
]

# Throw
$throw["Something went wrong"]

# Return
$def[safeDiv;a b;
    $if[$eq[$b;0];
        $return["Cannot divide by zero"]
    ;
        $div[$a;$b]
    ]
]

Callbacks Funcionais

$def[double;x;$mul[$x;2]]
$def[is_even;x;$eq[$mod[$x;2];0]]
$def[sum;a b;$add[$a;$b]]

$set[nums;$arrayCreate[1;2;3;4;5]]
$arrayMap[$nums;"double"]        # [2, 4, 6, 8, 10]
$arrayFilter[$nums;"is_even"]    # [2, 4]
$arrayReduce[$nums;0;"sum"]      # 15

Function Definitions

$def[double;x;$mul[$x;2]]
$def[fib;n;$if[$lt[$n;2];$n;$add[$fib[$sub[$n;1]];$fib[$sub[$n;2]]]]]

Important: Function parameters are space-separated inside the $def, not semicolon-separated:

# CORRECT:
$def[add;a b;$add[$a;$b]]

# WRONG:
$def[add;a;b;$add[$a;$b]]

Variables

$set[x;10]
$print[$x]

CLI Usage

# Evaluate expression
cargo run -- -e '$print["Hello"]'

# Run script file
cargo run -- script.eter

Example Scripts

See examples/ directory:

• hello.eter - Hello World
• math.eter - Math operations
• factorial.eter - Recursive factorial
• fibonacci.eter - Recursive Fibonacci
• variables.eter - Variable assignment
• fizzbuzz.eter - FizzBuzz with conditionals
• strings.eter - String manipulation
• calculadora.eter - Interactive calculator (single operation)
• calculadora_loop.eter - Interactive calculator with loop
• loops.eter - For and while loops
• error_handling.eter - Try/catch and throw
• collections.eter - ArrayMap/Filter/Reduce with callbacks
• dictionaries.eter - Dict operations

Architecture

• src/lexer.rs - Tokenizer and parser
• src/evaluator.rs - Expression evaluator with special forms, loops, error handling, stack traces, callbacks
• src/value.rs - Value types, expressions, RuntimeError with stack traces, ControlFlow enum
• src/functions/ - Built-in function implementations
• src/main.rs - CLI entry point

Recent Fixes

1. Semicolon handling - Parser skips semicolons between expressions
2. Empty-arg function calls - $x resolves to variable values
3. String interpolation - $varname inside strings replaced with values
4. Lazy evaluation - $if, $and, $or only evaluate needed branches
5. Recursive functions - Now work correctly with lazy evaluation
6. Comment support - # comments skip to end of line
7. EOF handling - Empty-arg calls at end-of-input work
8. Function params - Space-separated in $def, e.g., $def[foo;a b;$add[$a;$b]]
9. Loops - $for, $while, $break, $continue implemented as special forms
10. Error handling - $try, $throw with stack traces
11. Early return - $return from user functions
12. Callbacks funcionais - $arrayMap, $arrayFilter, $arrayReduce com funções definidas pelo usuário
13. Array utilities - $arrayRange, $arrayReverse, $arrayFlatten, $arrayUnique, $arrayJoin, $arrayContains, $arraySlice
14. Dict utilities - $dictSet, $dictKeys, $dictValues, $dictHas, $dictRemove, $dictEntries, $dictMerge

Known Limitations

• Variables are function-scoped (no closures)
• Error messages could be more descriptive in some edge cases