path: root/js/baba-yaga/docs/ref.txt

BABA YAGA LANGUAGE REFERENCE
============================

SYNTAX
------
var : value;                    // assignment
var Type; var : value;          // typed assignment  
f : x -> body;                  // function
f : x y -> body;                // multi-param function
f : (x: Type) -> Type -> body;  // typed function
f : x -> y -> body;             // curried function
f : x -> with (locals) -> body; // with locals
f : x -> with rec (fns) -> body;// with mutual recursion

LITERALS
--------
42                              // Int
3.14                            // Float  
"text"                          // String
true false                      // Bool
[1,2,3]                         // List
{a:1, b:2}                      // Table
PI INFINITY                     // constants

OPERATORS (precedence high→low)
-------------------------------
f x, obj.prop                   // call, access
- !                             // unary minus, not
* / %                           // multiply, divide, modulo
+ -                             // add, subtract  
= != < <= > >=                  // comparison
and or                          // logical
..                              // string concat

CONTROL FLOW
------------
when x is                       // pattern match
  0 then "zero"
  Int then "number" 
  _ then "other";

when x y is                     // multi-discriminant
  0 0 then "origin"
  _ _ then "other";

x if (condition) then result    // pattern guard
_ then "fallback";

TYPES
-----
Int Float Number String Bool List Table Result Function

Int ⊂ Float ⊂ Number            // type hierarchy
Ok value | Err message          // Result variants

ARRAY OPERATIONS
----------------
// Core HOFs
map f xs                        // [f x | x <- xs]
filter p xs                     // [x | x <- xs, p x]
reduce f z xs                   // f(...f(f(z,x1),x2)...,xn)

// Array programming  
scan f z xs                     // cumulative reduce
cumsum xs                       // cumulative sum
cumprod xs                      // cumulative product
at indices xs                   // xs[indices]
where p xs                      // indices where p x is true
take n xs                       // first n elements
drop n xs                       // drop first n elements
broadcast f scalar xs           // f scalar to each x
zipWith f xs ys                 // [f x y | (x,y) <- zip xs ys]
reshape dims xs                 // reshape flat array to matrix
flatMap f xs                    // concat (map f xs)

// List manipulation
append xs x                     // xs ++ [x]
prepend x xs                    // [x] ++ xs  
concat xs ys                    // xs ++ ys
update xs i x                   // xs with xs[i] = x
removeAt xs i                   // xs without xs[i]
slice xs start end              // xs[start:end]
length xs                       // |xs|

// Utilities
chunk xs n                      // split xs into chunks of size n
range start end                 // [start..end]
repeat n x                      // [x,x,...] (n times)
sort.by xs f                    // sort xs by key function f
group.by xs f                   // group xs by key function f

TABLE OPERATIONS
----------------
set tbl k v                     // tbl with tbl[k] = v
remove tbl k                    // tbl without tbl[k]
merge tbl1 tbl2                 // tbl1 ∪ tbl2
keys tbl                        // [k | k <- tbl]
values tbl                      // [tbl[k] | k <- tbl]
shape x                         // metadata: kind, rank, shape, size

STRING OPERATIONS
-----------------
str.concat s1 s2 ...            // s1 + s2 + ...
str.split s delim               // split s by delim
str.join xs delim               // join xs with delim
str.length s                    // |s|
str.substring s start end       // s[start:end]
str.replace s old new           // replace old with new in s
str.trim s                      // strip whitespace
str.upper s                     // uppercase
str.lower s                     // lowercase
text.lines s                    // split by newlines
text.words s                    // split by whitespace

MATH OPERATIONS
---------------
// Arithmetic
math.abs x                      // |x|
math.sign x                     // -1, 0, or 1
math.min x y, math.max x y      // min/max
math.clamp x lo hi              // clamp x to [lo,hi]

// Rounding  
math.floor x, math.ceil x       // ⌊x⌋, ⌈x⌉
math.round x, math.trunc x      // round, truncate

// Powers & logs
math.pow x y                    // x^y
math.sqrt x                     // √x
math.exp x, math.log x          // e^x, ln(x)

// Trigonometry
math.sin x, math.cos x, math.tan x
math.asin x, math.acos x, math.atan x, math.atan2 y x
math.deg x, math.rad x          // degrees ↔ radians

// Random
math.random                     // [0,1)
math.randomInt lo hi            // [lo,hi]

FUNCTION COMBINATORS
--------------------
flip f                          // λx y. f y x
apply f x                       // f x  
pipe x f                        // f x (reverse apply)
compose f g                     // λx. f (g x) (binary compose)

VALIDATION & DEBUG
------------------
// Validation
validate.notEmpty x             // x is not empty
validate.range lo hi x          // lo ≤ x ≤ hi  
validate.type "Type" x          // x has type Type
validate.email x                // x is valid email

// Debugging
debug.print [name] value        // print with optional name
debug.inspect x                 // detailed inspection
assert condition message        // throw if condition false

I/O
---
io.out value                    // print value
io.in                           // read stdin

JAVASCRIPT INTEROP
------------------
io.callJS fnName args           // call JS function synchronously
io.callJSAsync fnName args      // call JS function asynchronously
io.getProperty obj propName     // get JS object property
io.setProperty obj propName val // set JS object property
io.hasProperty obj propName     // check if JS property exists
io.jsArrayToList jsArray        // convert JS array to Baba Yaga list
io.listToJSArray list           // convert Baba Yaga list to JS array
io.objectToTable jsObj          // convert JS object to Baba Yaga table
io.tableToObject table          // convert Baba Yaga table to JS object
io.getLastJSError               // get last JS error (if available)
io.clearJSError                 // clear last JS error (if available)

EXAMPLES
--------
// Fibonacci
fib : n -> when n is 0 then 0 1 then 1 _ then (fib (n-1)) + (fib (n-2));

// Array processing pipeline
process : xs ->
  with (
    filtered : filter (x -> (x % 2) = 0) xs;
    doubled : map (x -> x * 2) filtered;
    summed : reduce (acc x -> acc + x) 0 doubled;
  ) -> summed;

// Result handling
safeDivide : x y -> when y is 0 then Err "div by zero" _ then Ok (x / y);
use : r -> when r is Ok v then v Err _ then 0;

// Pattern matching with guards
classify : x -> when x is
  n if ((n > 0) and (n < 10)) then "small positive"
  n if (n >= 10) then "large positive"  
  n if (n < 0) then "negative"
  _ then "zero";

// Mutual recursion
evenOdd : n -> with rec (
  even : x -> when x is 0 then true _ then odd (x - 1);
  odd : x -> when x is 0 then false _ then even (x - 1);
) -> {even: even n, odd: odd n};

// Array programming
matrix : reshape [2,3] [1,2,3,4,5,6];   // [[1,2,3],[4,5,6]]
indices : where (x -> x > 3) [1,2,3,4,5]; // [3,4] 
selected : at indices [10,20,30,40,50];   // [40,50]