diff options
Diffstat (limited to 'js/scripting-lang/tutorials')
18 files changed, 4140 insertions, 0 deletions
diff --git a/js/scripting-lang/tutorials/00_Introduction.md b/js/scripting-lang/tutorials/00_Introduction.md new file mode 100644 index 0000000..cfd2c80 --- /dev/null +++ b/js/scripting-lang/tutorials/00_Introduction.md @@ -0,0 +1,434 @@ +# Tutorial: Learning the Scripting Language + +This guide will teach you how to use this functional programming language, assuming you have basic programming knowledge and a passing familiarity with functional programming concepts. + +## What You'll Learn + +By the end of this tutorial, you'll be able to: + +- Write basic programs with functions and data +- Use pattern matching for conditional logic (our only control flow) +- Work with tables (our only data structures) +- Apply functional programming patterns +- Use the standard library's combinators + +## Getting Started + +### Running Your First Program + +Create a file called `hello.txt` with this content: + +```plaintext +/* Your first program */ +..out "Hello, World!"; +``` + +Run it with: +```bash +node lang.js hello.txt +``` + +You should see: `Hello, World!` + +### Basic Values and Variables + +The language supports numbers, strings, and booleans: + +```plaintext +/* Basic values */ +name : "Lucy Snowe"; +age : 18; +is_student : true; + +/* Output values */ +..out name; +..out age; +..out is_student; +``` + +**Key Point**: Variables are immutable - once assigned, they cannot be changed. + +## Functions: The Building Blocks + +### Defining Functions + +Functions are defined using arrow syntax: + +```plaintext +/* Simple function */ +double : x -> x * 2; + +/* Function with multiple parameters */ +add : x y -> x + y; + +/* Using functions */ +result : double 5; +sum : add 3 4; +..out result; /* Output: 10 */ +..out sum; /* Output: 7 */ +``` + +### Function Application + +Functions are applied by putting the function name followed by arguments: + +```plaintext +/* Function application */ +square : x -> x * x; +result : square 5; +..out result; /* Output: 25 */ + +/* Multiple applications */ +double : x -> x * 2; +increment : x -> x + 1; +result : increment (double 5); +..out result; /* Output: 11 */ +``` + +**Key Point**: Unary minus works without parentheses: `f -5` applies `f` to `negate(5)`. Use spaces around binary operators for clarity: `5 - 3` for subtraction. See the [Juxtaposition tutorial](01_Juxtaposition_Function_Application.md#negative-numbers-and-spacing) for detailed information about operator spacing. + +## Pattern Matching with `when` + +Instead of if/else statements, we use pattern matching: + +```plaintext +/* Basic pattern matching */ +classify : x -> + when x is + 0 then "zero" + 1 then "one" + _ then "other"; + +/* Using the function */ +..out (classify 0); /* Output: "zero" */ +..out (classify 1); /* Output: "one" */ +..out (classify 5); /* Output: "other" */ +``` + +The `_` is a wildcard that matches anything. + +### Multiple Value Patterns + +You can match on multiple values: + +```plaintext +/* Multiple value patterns */ +compare : x y -> + when x y is + 0 0 then "both zero" + 0 _ then "x is zero" + _ 0 then "y is zero" + _ _ then "neither zero"; + +/* Using the function */ +..out (compare 0 0); /* Output: "both zero" */ +..out (compare 0 5); /* Output: "x is zero" */ +..out (compare 3 0); /* Output: "y is zero" */ +..out (compare 3 5); /* Output: "neither zero" */ +``` + +## Tables: Our Data Structures + +Tables are like objects or dictionaries in other languages: + +```plaintext +/* Creating tables */ +person : {name: "Alice", age: 30, city: "NYC"}; +numbers : {1, 2, 3, 4, 5}; + +/* Accessing values */ +..out person.name; +..out person["age"]; +..out numbers[1]; /* Note: indexing starts at 1 */ +``` + +### Table Operations + +Tables support element-wise operations: + +```plaintext +/* Transform every value in a table */ +double : x -> x * 2; +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; +..out doubled[1]; /* Output: 2 */ +..out doubled[2]; /* Output: 4 */ + +/* Filter values in a table */ +is_even : x -> x % 2 = 0; +evens : filter @is_even numbers; +..out evens[2]; /* Output: 2 */ +..out evens[4]; /* Output: 4 */ +``` + +**Key Point**: The `@` symbol creates a function reference, which is needed for higher-order functions. + +## Function Composition + +### Combining Functions + +You can combine functions to create new ones: + +```plaintext +/* Function composition */ +double : x -> x * 2; +increment : x -> x + 1; + +/* Right-to-left composition (like the (mostly) regular mathematical style) */ +double_then_increment : compose @increment @double; +result : double_then_increment 5; +..out result; /* Output: 11 (5*2=10, then 10+1=11) */ + +/* Left-to-right composition (pipeline style) */ +increment_then_double : pipe @increment @double; +result : increment_then_double 5; +..out result; /* Output: 12 (5+1=6, then 6*2=12) */ +``` + +### The `via` Operator + +The language has a special `via` operator for composition: + +```plaintext +/* Using the via operator */ +double : x -> x * 2; +increment : x -> x + 1; +square : x -> x * x; + +/* This is equivalent to compose */ +result : double via increment via square 3; +..out result; /* Output: 20 (3^2=9, 9+1=10, 10*2=20) */ +``` + +## Working with Multiple Tables + +### Element-wise Operations + +The `each` combinator lets you combine multiple tables: + +```plaintext +/* Element-wise addition */ +table1 : {a: 1, b: 2, c: 3}; +table2 : {a: 10, b: 20, c: 30}; +sum : each @add table1 table2; +..out sum.a; /* Output: 11 */ +..out sum.b; /* Output: 22 */ +..out sum.c; /* Output: 33 */ + +/* Adding a scalar to every element */ +numbers : {1, 2, 3, 4, 5}; +incremented : each @add numbers 10; +..out incremented[1]; /* Output: 11 */ +..out incremented[2]; /* Output: 12 */ +``` + +## Immutable Table Operations + +The `t.` namespace provides immutable table operations: + +```plaintext +/* Creating and modifying tables */ +person : {name: "Alice", age: 30}; + +/* Immutable update */ +updated : t.set person "age" 31; +..out updated.age; /* Output: 31 */ +..out person.age; /* Output: 30 (original unchanged) */ + +/* Immutable merge */ +updates : {age: 32, city: "NYC"}; +merged : t.merge person updates; +..out merged.age; /* Output: 32 */ +..out merged.city; /* Output: "NYC" */ +..out merged.name; /* Output: "Alice" */ + +/* Safe access with defaults */ +name : t.get person "name" "Unknown"; +city : t.get person "city" "Unknown"; +..out name; /* Output: "Alice" */ +..out city; /* Output: "Unknown" */ +``` + +## Recursive Functions + +Functions can call themselves: + +```plaintext +/* Factorial function */ +factorial : n -> + when n is + 0 then 1 + _ then n * (factorial (n - 1)); + +/* Using factorial */ +..out factorial 5; /* Output: 120 */ +..out factorial 0; /* Output: 1 */ +``` + +## Practical Examples + +### Data Processing Pipeline + +```plaintext +/* Processing a list of numbers */ +numbers : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Filter even numbers, double them, then sum */ +is_even : x -> x % 2 = 0; +double : x -> x * 2; + +/* Pipeline: filter -> map -> reduce */ +evens : filter @is_even numbers; +doubled : map @double evens; +total : reduce @add 0 doubled; + +..out total; /* Output: 60 (2+4+6+8+10)*2 = 60 */ +``` + +### Table Transformation + +```plaintext +/* Working with structured data */ +people : { + alice: {name: "Alice", age: 30, city: "NYC"}, + bob: {name: "Bob", age: 25, city: "LA"}, + charlie: {name: "Charlie", age: 35, city: "Chicago"} +}; + +/* Extract all ages */ +get_age : person -> person.age; +ages : map @get_age people; +..out ages.alice; /* Output: 30 */ +..out ages.bob; /* Output: 25 */ + +/* Find people over 30 */ +is_over_30 : person -> person.age > 30; +seniors : filter @is_over_30 people; +..out seniors.charlie.name; /* Output: "Charlie" */ +``` + +## Common Patterns + +### Partial Application + +Functions can be partially applied: + +```plaintext +/* Creating specialized functions */ +add : x y -> x + y; +add_ten : add 10; + +/* Using the specialized function */ +..out (add_ten 5); /* Output: 15 */ +..out (add_ten 20); /* Output: 30 */ +``` + +### Function References + +Use `@` to pass functions as arguments: + +```plaintext +/* Higher-order functions */ +apply_twice : f x -> f (f x); +double : x -> x * 2; + +/* Using apply_twice */ +result : apply_twice @double 3; +..out result; /* Output: 12 (3*2=6, 6*2=12) */ +``` + +## Debugging and Testing + +### Assertions + +Use assertions to test your code: + +```plaintext +/* Testing your functions */ +double : x -> x * 2; +..assert (double 5) = 10; +..assert (double 0) = 0; +..assert (double (-3)) = -6; + +..out "All tests passed!"; +``` + +### Debug Output + +Add debug output to understand what's happening: + +```plaintext +/* Debugging a function */ +process_data : x -> { + ..out "Processing:"; + ..out x; + result : x * 2; + ..out "Result:"; + ..out result; + result +}; + +final : process_data 5; +..out "Final result:"; +..out final; +``` + +## Best Practices + +### Break Down Complex Operations + +```plaintext +/* Complex operation broken down */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Step 1: Filter */ +is_even : x -> x % 2 = 0; +evens : filter @is_even data; + +/* Step 2: Transform */ +square : x -> x * x; +squared : map @square evens; + +/* Step 3: Aggregate */ +total : reduce @add 0 squared; +..out total; +``` + +### Use Pattern Matching for Conditionals + +```plaintext +/* Good: Pattern matching */ +classify : x -> + when x is + 0 then "zero" + 1 then "one" + _ then "other"; +``` + +### Embrace Immutability + +```plaintext +/* Good: Immutable operations */ +person : {name: "Alice", age: 30}; +updated : t.set person "age" 31; +/* person remains unchanged */ + +/* Avoid: Trying to modify existing data, + this language doesn't support mutation */ +``` + +## Next Steps + +You now have a solid foundation in the scripting language! Here are some areas to explore: + +1. **Advanced Pattern Matching**: Complex patterns and nested matching +2. **Table Comprehensions**: Building tables from other data +3. **Function Composition**: Building complex transformations +4. **Error Handling**: Working with edge cases and invalid data +5. **Performance**: Understanding how the language executes your code + +For a deep dive into combinators and advanced problem-solving patterns, check out the **[Combinators Deep Dive tutorial](Combinators_Deep_Dive.md)**. + +The language is designed to be functional and expressive. As you practice, you'll find that many operations become more natural when you think in terms of data transformations rather than step-by-step instructions. + +Happy coding! \ No newline at end of file diff --git a/js/scripting-lang/tutorials/01_Function_Calls.md b/js/scripting-lang/tutorials/01_Function_Calls.md new file mode 100644 index 0000000..b251386 --- /dev/null +++ b/js/scripting-lang/tutorials/01_Function_Calls.md @@ -0,0 +1,176 @@ +# Function Calls + +## What is Juxtaposition? + +In Baba Yaga you call functions by putting them next to each other. + +```plaintext +/* + JavaScript: f(x, y) + Baba Yaga: f x y +*/ +``` + +## Basic Examples + +```plaintext +/* Simple function calls */ +add 5 3; /* Instead of add(5, 3) */ +multiply 4 7; /* Instead of multiply(4, 7) */ +subtract 10 3; /* Instead of subtract(10, 3) */ + +/* Function calls with tables */ +/* ...we'll talk more about @ in a bit */ +map @double {1, 2, 3, 4, 5}; +filter @is_even {1, 2, 3, 4, 5, 6}; +reduce @add 0 {1, 2, 3, 4, 5}; +``` + +## How It Works + +The parser automatically translates juxtaposition into nested calls to `apply`, so that + +```plaintext +/* f x y becomes: apply(apply(f, x), y) */ +/* map double {1, 2, 3} becomes: apply(apply(map, double), {1, 2, 3}) */ +``` + +## Precedence Rules + +Juxtaposition has lower precedence than operators, + +```plaintext +result : add 5 multiply 3 4; +/* Parsed as: add 5 (multiply 3 4) */ +/* Result: 5 + (3 * 4) = 17 */ +/* Not as: (add 5 multiply) 3 4 */ +``` +With Baba Yaga you'll use juxtaposition when you + +- call functions with arguments +- build function composition chains +- work with combinators like `map`, `filter`, `reduce` + +You won't use it, exactly, when you are + +- defining functions (use `:` and `->`) +- assigning values (use `:`) +- using operators (use `+`, `-`, `*`, etc.) + +## Common Patterns + +```plaintext +/* Data processing pipeline */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; +is_even : x -> x % 2 = 0; +double : x -> x * 2; +sum : x -> reduce add 0 x; + +/* Pipeline using juxtaposition */ +result : sum map double filter is_even data; +/* Reads: sum (map double (filter is_even data)) */ +/* Result: 60 */ +``` + +## Using Parentheses for Control + +Juxtaposition eliminates the need for parentheses in most cases, parentheses are available for when you need explicit control over precedence or grouping. + +```plaintext +/* Without parentheses - left-associative */ +result1 : add 5 multiply 3 4; +/* Parsed as: add 5 (multiply 3 4) */ +/* Result: 5 + (3 * 4) = 17 */ + +/* With parentheses - explicit grouping */ +result2 : add (add 1 2) (multiply 3 4); +/* Explicitly: (1 + 2) + (3 * 4) = 3 + 12 = 15 */ + +/* Complex nested operations */ +result3 : map double (filter is_even (map increment {1, 2, 3, 4, 5})); +/* Step by step: + 1. map increment {1, 2, 3, 4, 5} → {2, 3, 4, 5, 6} + 2. filter is_even {2, 3, 4, 5, 6} → {2, 4, 6} + 3. map double {2, 4, 6} → {4, 8, 12} +*/ + +/* Hard to read without parentheses */ +complex : map double filter is_even map increment {1, 2, 3, 4, 5}; + +/* Much clearer with parentheses */ +complex : map double (filter is_even (map increment {1, 2, 3, 4, 5})); + +/* Or break it into steps for maximum clarity */ +step1 : map increment {1, 2, 3, 4, 5}; +step2 : filter is_even step1; +step3 : map double step2; +``` + +Parentheses are also helpful for debugging because they let you isolate specific pieces of a program or chain. + +```plaintext +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Test each step separately */ +filtered : filter @is_even data; +doubled : map @double filtered; +final : reduce @add 0 doubled; + +/* Or use parentheses to test intermediate results */ +test1 : filter is_even data; /* {2, 4, 6, 8, 10} */ +test2 : map double (filter is_even data); /* {4, 8, 12, 16, 20} */ +``` + +## Spacing Rules + +Baba Yaga uses spacing to distinguish between unary and binary operators...mostly just minus. + +- **Unary minus**: `-5` (no leading space) → `negate(5)` +- **Binary minus**: `5 - 3` (spaces required) → `subtract(5, 3)` +- **Legacy fallback**: `5-3` → `subtract(5, 3)` (but spaces are recommended) + +The parser distinguishes between these scenarios based off of spaces, and kinda best guess heuristics. It *should* work as expected in most cases. + +- **Unary minus** (negative numbers): `-5` → `negate(5)` +- **Binary minus** (subtraction): `5 - 3` → `subtract(5, 3)` + +Spacing makes expressions less ambiguous. + +### Common Patterns + +```plaintext +/* Function calls with negative numbers */ +double : x -> x * 2; +result : double -5; /* unary minus */ +result2 : double (-5); /* explicit grouping */ + +/* Comparisons with negative numbers */ +is_negative : x -> x < 0; +test1 : is_negative -5; /* unary minus */ + +/* Complex expressions with negative numbers */ +validate_age : age -> (age >= 0) and (age <= 120); +test2 : validate_age -5; /* unary minus */ + +/* Arithmetic with proper spacing */ +result3 : -5 + 3; /* unary minus + binary plus */ +result4 : 5 - 3; /* binary minus with spaces */ +result5 : (-5) + 3; /* explicit grouping */ +``` + +#### Best Practices + +- **Use spaces around binary operators**: `5 - 3`, `5 + 3`, `5 * 3` +- **Unary minus works without parentheses**: `-5`, `f -5` +- **Legacy syntax still works**: `(-5)`, `5-3` (but spaces are recommended) +- **When in doubt, use spaces**: It makes code more readable and follows conventions + +#### When You Might Encounter This + +- **Arithmetic operations**: `-5 + 3`, `5 - 3`, `(-5) + 3` +- **Comparisons**: `-5 >= 0`, `5 - 3 >= 0` +- **Function calls**: `f -5`, `f (-5)`, `map double -3` +- **Logical expressions**: `(-5 >= 0) and (-5 <= 120)` +- **Pattern matching**: `when x is -5 then "negative five"` + +To make everyone's life easier, use spaces around binary operators. \ No newline at end of file diff --git a/js/scripting-lang/tutorials/02_Function_Composition.md b/js/scripting-lang/tutorials/02_Function_Composition.md new file mode 100644 index 0000000..a6137b4 --- /dev/null +++ b/js/scripting-lang/tutorials/02_Function_Composition.md @@ -0,0 +1,138 @@ +# Function Composition + +## What is the `via` Operator? + +The `via` operator is a function composition operator that combines functions from right to left. + +```plaintext +/* f via g = compose(f, g) */ +/* f via g via h = compose(f, compose(g, h)) */ +``` + +The `via` operator is right-associative and matches mathematical notation where `(f ∘ g ∘ h)(x) = f(g(h(x)))`. + +```plaintext +/* Define simple functions */ +double : x -> x * 2; +increment : x -> x + 1; +square : x -> x * x; + +/* Using via composition */ +result1 : double via increment 5; +/* Result: 12 (5+1=6, 6*2=12) */ + +/* Chained via composition */ +result2 : double via increment via square 3; +/* Result: 20 (3^2=9, 9+1=10, 10*2=20) */ +``` + +The key insight is that `via` groups from right to left. + +```plaintext +/* This expression: */ +double via increment via square 3 + +/* Groups as: */ +double via (increment via square) 3 + +/* Which translates to: */ +compose(double, compose(increment, square))(3) + +/* With the execution order of: */ +/* 1. square(3) = 9 */ +/* 2. increment(9) = 10 */ +/* 3. double(10) = 20 */ +``` + +## Precedence rules and `via` + +The `via` operator has higher precedence than function application: + +```plaintext +/* via binds tighter than juxtaposition */ +double via increment 5 + +/* This is parsed as: */ +(double via increment) 5 +``` + +## More examples + +```plaintext +/* Data processing pipeline */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; +is_even : x -> x % 2 = 0; +double : x -> x * 2; +sum : x -> reduce add 0 x; + +/* Pipeline using via */ +process_pipeline : sum via map double via filter is_even; +result : process_pipeline data; +/* Reads: sum via (map double via filter is_even) */ +/* Result: 60 */ +``` + +You'll note that we don't need to use `@` here -- `via` is kinda special-cased because it is an ergonomic feature. It can work with function names directly because it's specifically for function composition. Higher-order functions like `map`, `filter`, and `reduce` require explicit function references using `@` because they need a way to distinguish between calling a function immediately vs passing it as an argument while `via` only ever takes in functions. + + +A goal with the `via` operator is to align with mathematical function composition: + +```plaintext +/* Mathematical: (f ∘ g ∘ h)(x) = f(g(h(x))) */ +/* Baba Yaga: f via g via h x = f(g(h(x))) */ +``` + +## When to Use `via` + +**Use `via` when you want:** +- Natural reading: `f via g via h` reads as "f then g then h" +- Mathematical notation: Matches `(f ∘ g ∘ h)` notation +- Concise syntax: Shorter than nested `compose` calls +- Right-to-left flow: When you think of data flowing right to left + +**Don't use `via` when:** +- You need left-to-right composition (use `pipe`) +- You want explicit mathematical style (use `compose`) +- You're working with simple function calls (use juxtaposition) +- If you don't wanna + +## Common Patterns + +```plaintext +/* Data transformation pipeline */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; +is_even : x -> x % 2 = 0; +double : x -> x * 2; +sum : x -> reduce add 0 x; + +/* Pipeline: filter → map → reduce */ +process_pipeline : sum via map double via filter is_even; +result : process_pipeline data; +/* Result: 60 (filter evens: {2,4,6,8,10}, double: {4,8,12,16,20}, sum: 60) */ + +/* Validation chain */ +validate_positive : x -> x > 0; +validate_even : x -> x % 2 = 0; +validate_small : x -> x < 10; + +/* Chain validations */ +all_validations : validate_small via validate_even via validate_positive; +result : all_validations 6; /* 6 > 0, 6 % 2 = 0, 6 < 10 */ +/* Result: true */ +``` + +## Debugging `via` Chains + +To understand execution order, break down the chain: + +```plaintext +/* Complex chain: */ +result : square via double via increment via square 2; + +/* Break it down: */ +/* 1. square(2) = 4 */ +/* 2. increment(4) = 5 */ +/* 3. double(5) = 10 */ +/* 4. square(10) = 100 */ +/* Result: 100 */ +``` \ No newline at end of file diff --git a/js/scripting-lang/tutorials/03_Table_Operations.md b/js/scripting-lang/tutorials/03_Table_Operations.md new file mode 100644 index 0000000..b8d349f --- /dev/null +++ b/js/scripting-lang/tutorials/03_Table_Operations.md @@ -0,0 +1,136 @@ +# Table Operations + +## What are Element-Wise Operations? + +Element-wise operations automatically apply functions to every element in a table without explicit loops or iteration syntax like `forEach`. + +```plaintext +/* Instead of for each element in table, apply function */ +/* You write function table */ +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; /* {2, 4, 6, 8, 10} */ +``` + +Most main-stream programming languages require explicit loops or iteration. Baba Yaga takes a clue from array languages like APL, BQN, uiua, K, etc., and automatically handles element-wise operations. + +## Basic Examples + +```plaintext +/* Define a simple function */ +double : x -> x * 2; + +/* Apply to table elements automatically */ +numbers : {1, 2, 3, 4, 5}; +result : map @double numbers; +/* Result: {2, 4, 6, 8, 10} */ + +/* Filter elements automatically */ +is_even : x -> x % 2 = 0; +evens : filter @is_even numbers; +/* Result: {2, 4} */ + +/* Reduce all elements automatically */ +sum : reduce @add 0 numbers; +/* Result: 15 (1+2+3+4+5) */ +``` + +## Table-Specific Operations + +The `t.` namespace provides additional element-wise operations especially meant for tables. + +```plaintext +/* Table-specific operations */ +data : {a: 1, b: 2, c: 3}; + +/* Get all keys */ +keys : t.keys data; /* {"a", "b", "c"} */ + +/* Get all values */ +values : t.values data; /* {1, 2, 3} */ + +/* Get key-value pairs */ +pairs : t.pairs data; /* {{key: "a", value: 1}, {key: "b", value: 2}, {key: "c", value: 3}} */ + +/* Check if key exists */ +has_a : t.has data "a"; /* true */ +has_d : t.has data "d"; /* false */ + +/* Get value by key */ +value_a : t.get data "a"; /* 1 */ +``` + +## Complex Examples + +```plaintext +/* Data processing pipeline */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Define helper functions */ +is_even : x -> x % 2 = 0; +double : x -> x * 2; +sum : x -> reduce @add 0 x; + +/* Complete pipeline: filter → map → reduce */ +result : sum map double filter is_even data; +/* Step 1: filter @is_even data → {2, 4, 6, 8, 10} */ +/* Step 2: map @double {2, 4, 6, 8, 10} → {4, 8, 12, 16, 20} */ +/* Step 3: sum {4, 8, 12, 16, 20} → 60 */ +/* Result: 60 */ +``` + +## Nested Tables + +Element-wise operations work with nested table structures, too + +```plaintext +/* Nested table */ +people : { + alice: {name: "Alice", age: 30, scores: {85, 90, 88}}, + bob: {name: "Bob", age: 25, scores: {92, 87, 95}}, + charlie: {name: "Charlie", age: 35, scores: {78, 85, 82}} +}; + +/* Extract ages */ +ages : map (x -> x.age) people; +/* Result: {alice: 30, bob: 25, charlie: 35} */ + +/* Calculate average scores for each person */ +get_average : person -> reduce add 0 person.scores / 3; +averages : map get_average people; +/* Result: {alice: 87.67, bob: 91.33, charlie: 81.67} */ +``` + +## The `each` Combinator + +The `each` combinator provides multi-argument element-wise operations: + +```plaintext +/* each for multi-argument operations */ +numbers : {1, 2, 3, 4, 5}; +multipliers : {10, 20, 30, 40, 50}; + +/* Multiply corresponding elements */ +result : each @multiply numbers multipliers; +/* Result: {10, 40, 90, 160, 250} */ + +/* Compare corresponding elements */ +is_greater : each @greaterThan numbers {3, 3, 3, 3, 3}; +/* Result: {false, false, false, true, true} */ +``` + +## Immutability + +All element-wise operations return new tables. In Baba Yaga all values, including tables are immutable. + +```plaintext +/* Original table */ +original : {a: 1, b: 2, c: 3}; + +/* Operations return new tables */ +doubled : map @double original; /* {a: 2, b: 4, c: 6} */ +greater_then : x -> x > 1; +filtered : filter @greater_then original; /* {b: 2, c: 3} */ + +/* Original is unchanged */ +/* original is still {a: 1, b: 2, c: 3} */ +``` \ No newline at end of file diff --git a/js/scripting-lang/tutorials/04_Currying.md b/js/scripting-lang/tutorials/04_Currying.md new file mode 100644 index 0000000..55bd3bf --- /dev/null +++ b/js/scripting-lang/tutorials/04_Currying.md @@ -0,0 +1,167 @@ +# Currying + +## What is Partial Application? + +Partial application means that functions automatically return new functions when called with fewer arguments than they expect. This is also called currying. + +```plaintext +/* Functions automatically return new functions when partially applied */ +add : x y -> x + y; +add_five : add 5; /* Returns a function that adds 5 */ +result : add_five 3; /* 8 */ +``` + +Most programming languages require explicit syntax for partial application or currying. When using Baba Yagay, every function is automatically curried. + +## Basic Examples + +```plaintext +/* Define a two-argument function */ +add : x y -> x + y; + +/* Call with both arguments */ +result1 : add 5 3; /* 8 */ + +/* Call with one argument - returns a new function */ +add_five : add 5; /* Returns: y -> 5 + y */ + +/* Call the returned function */ +result2 : add_five 3; /* 8 */ + +/* Chain partial applications */ +add_ten : add 10; /* y -> 10 + y */ +add_ten_five : add_ten 5; /* 15 */ +``` + +## How It Works + +Partial application happens automatically with nested function returns. + +```plaintext +/* When you define: add : x y -> x + y; */ +/* Baba Yaga creates: add = x -> (y -> x + y) */ + +/* When you call: add 5 */ +/* It returns: y -> 5 + y */ + +/* When you call: add 5 3 */ +/* It calls: (y -> 5 + y)(3) = 5 + 3 = 8 */ +``` + +Partial application works with any number of arguments. + +```plaintext +/* Three-argument function */ +multiply_add : x y z -> x * y + z; + +/* Partial application examples */ +multiply_by_two : multiply_add 2; /* y z -> 2 * y + z */ +multiply_by_two_add_ten : multiply_add 2 5; /* z -> 2 * 5 + z */ + +/* Full application */ +result1 : multiply_add 2 5 3; /* 2 * 5 + 3 = 13 */ +result2 : multiply_by_two 5 3; /* 2 * 5 + 3 = 13 */ +result3 : multiply_by_two_add_ten 3; /* 2 * 5 + 3 = 13 */ +``` + +All standard library functions support partial application, too! + +```plaintext +/* Arithmetic functions */ +double : multiply 2; /* x -> 2 * x */ +increment : add 1; /* x -> x + 1 */ +decrement : subtract 1; /* x -> x - 1 */ + +/* Comparison functions */ +is_positive : greaterThan 0; /* x -> x > 0 */ +is_even : equals 0; /* This won't work as expected - see below */ + +/* Logical functions */ +always_true : logicalOr true; /* x -> true || x */ +always_false : logicalAnd false; /* x -> false && x */ +``` + +## Common Patterns + +```plaintext +/* Pattern 1: Creating specialized functions */ +numbers : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Create specialized filters */ +is_even : x -> x % 2 = 0; +is_odd : x -> x % 2 = 1; +is_greater_than_five : x -> x > 5; + +/* Use with map and filter - note the @ operator for higher-order functions */ +evens : filter @is_even numbers; /* {2, 4, 6, 8, 10} */ +odds : filter @is_odd numbers; /* {1, 3, 5, 7, 9} */ +large_numbers : filter @is_greater_than_five numbers; /* {6, 7, 8, 9, 10} */ + +/* Pattern 2: Creating transformation functions */ +double : multiply 2; +triple : multiply 3; +add_ten : add 10; + +/* Apply transformations - @ operator required for map */ +doubled : map @double numbers; /* {2, 4, 6, 8, 10, 12, 14, 16, 18, 20} */ +tripled : map @triple numbers; /* {3, 6, 9, 12, 15, 18, 21, 24, 27, 30} */ +plus_ten : map @add_ten numbers; /* {11, 12, 13, 14, 15, 16, 17, 18, 19, 20} */ +``` + +You can use partial application with function composition. + +```plaintext +/* Create specialized functions */ +double : multiply 2; +increment : add 1; +square : x -> x * x; + +/* Compose partially applied functions - @ operator required for compose */ +double_then_increment : compose @increment @double; +increment_then_square : compose @square @increment; + +/* Use in pipelines */ +result1 : double_then_increment 5; /* double(5)=10, increment(10)=11 */ +result2 : increment_then_square 5; /* increment(5)=6, square(6)=36 */ +``` + +## Table Operations with Partial Application + +The `t.` namespace functions also support partial application: + +```plaintext +/* Create specialized table operations */ +get_name : t.get "name"; +get_age : t.get "age"; +has_admin : t.has "admin"; + +/* Use with map - @ operator required for higher-order functions */ +people : { + alice: {name: "Alice", age: 30, admin: true}, + bob: {name: "Bob", age: 25, admin: false}, + charlie: {name: "Charlie", age: 35, admin: true} +}; + +names : map @get_name people; /* {alice: "Alice", bob: "Bob", charlie: "Charlie"} */ +ages : map @get_age people; /* {alice: 30, bob: 25, charlie: 35} */ +admins : map @has_admin people; /* {alice: true, bob: false, charlie: true} */ +``` + +## The `each` Combinator with Partial Application + +The `each` combinator works well with partial application: + +```plaintext +/* Create specialized comparison functions */ +is_greater_than_three : x -> x > 3; +is_less_than_seven : x -> x < 7; + +/* Use with each for element-wise comparison - @ operator required for each */ +numbers : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +greater_than_three : each @is_greater_than_three numbers; +/* Result: {false, false, false, true, true, true, true, true, true, true} */ + +less_than_seven : each @is_less_than_seven numbers; +/* Result: {true, true, true, true, true, true, false, false, false, false} */ +``` \ No newline at end of file diff --git a/js/scripting-lang/tutorials/05_Pattern_Matching.md b/js/scripting-lang/tutorials/05_Pattern_Matching.md new file mode 100644 index 0000000..c6097c3 --- /dev/null +++ b/js/scripting-lang/tutorials/05_Pattern_Matching.md @@ -0,0 +1,247 @@ +# `when` Expressions (Pattern Matching) + +## What are `when` Expressions? + +This is kinda where the whole idea for Baba Yaga started. Pattern matching is an approach to flow control. We do this in Baba Yaga using the `when` expression. It provides pattern matching functionality, allowing you to match values against patterns and execute different code based on the match. + +```plaintext +/* Pattern matching with when expressions */ +result : when x is + 0 then "zero" + 1 then "one" + _ then "other"; +``` + +Baba Yaga's pattern matching syntax has a lot of insporations, but especially `cond` patterns, Gleam's pattern matching, and Roc's, too. + +## Basic Examples + +```plaintext +/* Simple pattern matching */ +x : 5; +result : when x is + 0 then "zero" + 1 then "one" + 2 then "two" + _ then "other"; +/* Result: "other" */ + +/* Pattern matching with numbers */ +grade : 85; +letter_grade : when grade is + 90 then "A" + 80 then "B" + 70 then "C" + 60 then "D" + _ then "F"; +/* Result: "B" */ +``` + +## Pattern Types + +### Literal Patterns +```plaintext +/* Match exact values */ +result : when value is + true then "yes" + false then "no" + _ then "maybe"; +``` + +### Wildcard Pattern +```plaintext +/* _ matches anything */ +result : when x is + 0 then "zero" + _ then "not zero"; +``` + +### Function Reference Patterns +```plaintext +/* Match function references using @ operator */ +double : x -> x * 2; +square : x -> x * x; + +which : x -> when x is + @double then "doubling function" + @square then "squaring function" + _ then "other function"; + +test1 : which double; +test2 : which square; +``` + +As is called out elsewhere, too, the `@` operator is required when matching function references in patterns. This distinguishes between calling a function and matching against the function itself. + +### Boolean Patterns +```plaintext +/* Match boolean values */ +result : when condition is + true then "condition is true" + false then "condition is false"; +``` + +## Complex Examples + +```plaintext +/* Grade classification with ranges */ +score : 85; +grade : when score is + when score >= 90 then "A" + when score >= 80 then "B" + when score >= 70 then "C" + when score >= 60 then "D" + _ then "F"; +/* Result: "B" */ + +/* Multiple conditions */ +x : 5; +y : 10; +result : when x is + when x = y then "equal" + when x > y then "x is greater" + when x < y then "x is less" + _ then "impossible"; +/* Result: "x is less" */ +``` + +## Advanced Pattern Matching + +You can match multiple values with complex expressions: + +```plaintext +/* FizzBuzz implementation using multi-value patterns */ +fizzbuzz : n -> + when (n % 3) (n % 5) is + 0 0 then "FizzBuzz" + 0 _ then "Fizz" + _ 0 then "Buzz" + _ _ then n; + +/* Test the FizzBuzz function */ +result1 : fizzbuzz 15; /* "FizzBuzz" */ +result2 : fizzbuzz 3; /* "Fizz" */ +result3 : fizzbuzz 5; /* "Buzz" */ +result4 : fizzbuzz 7; /* 7 */ +``` + +You can access table properties directly in patterns: + +```plaintext +/* User role checking */ +user : {role: "admin", level: 5}; + +access_level : when user.role is + "admin" then "full access" + "user" then "limited access" + _ then "no access"; +/* Result: "full access" */ +``` + +You can use function calls in patterns. Be warned, though -- they require parentheses to help disambiguate them from other references, though. + +```plaintext +/* Even/odd classification */ +is_even : n -> n % 2 = 0; + +classify : n -> + when (is_even n) is + true then "even number" + false then "odd number"; + +/* Test the classification */ +result1 : classify 4; /* "even number" */ +result2 : classify 7; /* "odd number" */ +``` + +Function calls in patterns must be wrapped in parentheses! + +This'll work: +```plaintext +when (is_even n) is true then "even" +when (complex_func x y) is result then "matched" +``` + +This won't work: +```plaintext +when is_even n is true then "even" /* Ambiguous parsing */ +``` + +You can nest `when` expressions for complex logic: + +```plaintext +/* Nested pattern matching */ +x : 5; +y : 10; +result : when x is + 0 then when y is + 0 then "both zero" + _ then "x is zero" + 1 then when y is + 1 then "both one" + _ then "x is one" + _ then when y is + 0 then "y is zero" + 1 then "y is one" + _ then "neither special"; +/* Result: "neither special" */ +``` + +## Using `when` with Functions + +```plaintext +/* Function that uses pattern matching */ +classify_number : x -> when x is + 0 then "zero" + (x % 2 = 0) then "even" + (x % 2 = 1) then "odd" + _ then "unknown"; + +/* Use the function */ +result1 : classify_number 0; /* "zero" */ +result2 : classify_number 4; /* "even" */ +result3 : classify_number 7; /* "odd" */ +``` + +## Common Patterns + +```plaintext +/* Value classification */ +classify_age : age -> when age is + (age < 13) then "child" + (age < 20) then "teenager" + (age < 65) then "adult" + _ then "senior"; + +/* Error handling */ +safe_divide : x y -> when y is + 0 then "error: division by zero" + _ then x / y; + +/* Status mapping */ +status_code : 404; +status_message : x -> + when x is + 200 then "OK" + 404 then "Not Found" + 500 then "Internal Server Error" + _ then "Unknown Error"; +``` + +## When to Use `when` pattern matching + +**Use `when` expressions when:** +- You need to match values against multiple patterns +- You want to replace complex if/else chains +- You're working with enumerated values +- You need to handle different cases based on value types +- You want to make conditional logic more readable +- **You need to match multiple values simultaneously** (multi-value patterns) +- **You want to access table properties in patterns** (table access) +- **You need to use function results in patterns** (function calls with parentheses) +- **You're implementing complex validation logic** (multi-field validation) +- **You need to match function references** (using `@` operator) + +**Don't use `when` expressions when:** +- You only have a simple true/false condition (use logical operators) +- You're working with complex nested conditions (consider breaking into functions) \ No newline at end of file diff --git a/js/scripting-lang/tutorials/06_Immutable_Tables.md b/js/scripting-lang/tutorials/06_Immutable_Tables.md new file mode 100644 index 0000000..8502603 --- /dev/null +++ b/js/scripting-lang/tutorials/06_Immutable_Tables.md @@ -0,0 +1,251 @@ +# Immutable Tables with Functional Operations + +## What are Immutable Tables? + +Immutable tables are data structures that **cannot be modified after creation**. All operations on tables return **new tables** rather than modifying the original. + +```plaintext +/* All table operations return new tables */ +original : {a: 1, b: 2, c: 3}; +modified : t.set original "d" 4; /* Returns new table */ +/* original is unchanged: {a: 1, b: 2, c: 3} */ +/* modified is: {a: 1, b: 2, c: 3, d: 4} */ +``` + +## Why is This Esoteric? + +Most programming languages allow direct modification of data structures. Our language enforces **complete immutability** - no mutation operations exist at all. + +## Basic Examples + +```plaintext +/* Create a table */ +original : {name: "Alice", age: 30, city: "New York"}; + +/* All operations return new tables */ +with_job : t.set original "job" "Engineer"; +with_updated_age : t.set original "age" 31; +without_city : t.delete original "city"; + +/* Original table is unchanged */ +/* original is still {name: "Alice", age: 30, city: "New York"} */ +``` + +## Table Operations + +### Setting Values +```plaintext +/* t.set table key value - returns new table with key set */ +data : {a: 1, b: 2}; +updated : t.set data "c" 3; +/* updated: {a: 1, b: 2, c: 3} */ +/* data: {a: 1, b: 2} (unchanged) */ +``` + +### Deleting Keys +```plaintext +/* t.delete table key - returns new table without the key */ +data : {a: 1, b: 2, c: 3}; +without_b : t.delete data "b"; +/* without_b: {a: 1, c: 3} */ +/* data: {a: 1, b: 2, c: 3} (unchanged) */ +``` + +### Merging Tables +```plaintext +/* t.merge table1 table2 - returns new table with combined keys */ +table1 : {a: 1, b: 2}; +table2 : {c: 3, d: 4}; +merged : t.merge table1 table2; +/* merged: {a: 1, b: 2, c: 3, d: 4} */ +/* table1 and table2 unchanged */ +``` + +### Getting Values +```plaintext +/* t.get table key - returns value (doesn't modify table) */ +data : {name: "Alice", age: 30}; +name : t.get data "name"; /* "Alice" */ +age : t.get data "age"; /* 30 */ +/* data unchanged */ +``` + +### Checking Keys +```plaintext +/* t.has table key - returns boolean (doesn't modify table) */ +data : {name: "Alice", age: 30}; +has_name : t.has data "name"; /* true */ +has_job : t.has data "job"; /* false */ +/* data unchanged */ +``` + +## Element-Wise Operations + +All element-wise operations return new tables: + +```plaintext +/* map returns new table - @ operator required for higher-order functions */ +numbers : {a: 1, b: 2, c: 3}; +double : x -> x * 2; +doubled : map @double numbers; /* {a: 2, b: 4, c: 6} */ +/* numbers unchanged: {a: 1, b: 2, c: 3} */ + +/* filter returns new table - @ operator required for higher-order functions */ +is_greater_than_one : x -> x > 1; +filtered : filter @is_greater_than_one numbers; /* {b: 2, c: 3} */ +/* numbers unchanged: {a: 1, b: 2, c: 3} */ +``` + +## Complex Examples + +```plaintext +/* Building complex tables immutably */ +base_user : {name: "Alice", age: 30}; + +/* Add multiple properties */ +with_email : t.set base_user "email" "alice@example.com"; +with_address : t.set with_email "address" "123 Main St"; +with_phone : t.set with_address "phone" "555-1234"; + +/* Or merge with another table */ +contact_info : {email: "alice@example.com", phone: "555-1234"}; +complete_user : t.merge base_user contact_info; +/* Result: {name: "Alice", age: 30, email: "alice@example.com", phone: "555-1234"} */ +``` + +## Nested Tables + +Immutability works with nested table structures: + +```plaintext +/* Nested table */ +user : { + name: "Alice", + profile: { + age: 30, + preferences: { + theme: "dark", + notifications: true + } + } +}; + +/* Update nested property - creates new nested structure */ +updated_preferences : t.set user.profile.preferences "theme" "light"; +/* This creates new tables at each level */ +/* user unchanged, updated_preferences has new nested structure */ +``` + +## Functional Programming Patterns + +Immutability enables pure functional programming patterns: + +```plaintext +/* Pure function - no side effects */ +update_age : user new_age -> t.set user "age" new_age; + +/* Multiple updates create new tables */ +user1 : {name: "Alice", age: 30}; +user2 : update_age user1 31; +user3 : update_age user2 32; + +/* All tables exist independently */ +/* user1: {name: "Alice", age: 30} */ +/* user2: {name: "Alice", age: 31} */ +/* user3: {name: "Alice", age: 32} */ +``` + +## When to Use Immutable Tables + +**Use immutable tables when:** +- You want to prevent accidental data modification +- You're building functional programming patterns +- You need to track data changes over time +- You want to ensure thread safety (if applicable) +- You're working with complex data transformations + +**Don't use immutable tables when:** +- You need to modify data in place for performance reasons +- You're working with very large datasets that can't be copied +- You need to perform side effects on data structures + +## Common Patterns + +```plaintext +/* Pattern 1: Building up data structures */ +base_config : {debug: false, timeout: 30}; + +/* Add development settings */ +dev_config : t.merge base_config { + debug: true, + log_level: "verbose" +}; + +/* Add production settings */ +prod_config : t.merge base_config { + timeout: 60, + cache_enabled: true +}; + +/* Pattern 2: Data transformation pipeline */ +user_data : {name: "Alice", age: 30, scores: {85, 90, 88}}; + +/* Transform user data */ +with_average : t.set user_data "average_score" (reduce @add 0 user_data.scores / 3); +with_grade : t.set with_average "grade" (when with_average.average_score is + when with_average.average_score >= 90 then "A" + when with_average.average_score >= 80 then "B" + _ then "C"); + +/* Pattern 3: State management */ +initial_state : {count: 0, items: {}}; + +/* State transitions */ +increment_state : state -> t.set state "count" (state.count + 1); +add_item_state : state item -> t.set state "items" (t.set state.items item.id item); + +/* Apply transitions */ +state1 : increment_state initial_state; +state2 : add_item_state state1 {id: "item1", name: "First Item"}; +``` + +## Performance Considerations + +```plaintext +/* Immutability can be expensive for large tables */ +large_table : {/* ... many entries ... */}; + +/* Each operation creates a new copy */ +updated1 : t.set large_table "key" "value"; +updated2 : t.set updated1 "key2" "value2"; +/* This creates multiple copies of the large table */ + +/* Consider batching operations */ +batch_update : table -> t.merge table { + key1: "value1", + key2: "value2", + key3: "value3" +}; +/* Single operation instead of multiple */ +``` + +## Key Takeaways + +1. **Complete immutability** - no mutation operations exist +2. **New tables returned** - all operations return new data structures +3. **Original unchanged** - source tables are never modified +4. **Functional patterns** - enables pure functional programming +5. **Composable operations** - operations can be chained safely +6. **@ operator required** - for higher-order functions like `map`, `filter`, `reduce` + +## Why This Matters + +Immutable tables make the language safer and more functional: + +- **No side effects** - functions can't accidentally modify data +- **Predictable behavior** - data never changes unexpectedly +- **Functional style** - encourages pure functions and composition +- **Debugging ease** - data state is always predictable +- **Thread safety** - no shared mutable state issues + +This feature makes the language feel more like pure functional languages like Haskell! 🚀 \ No newline at end of file diff --git a/js/scripting-lang/tutorials/07_Function_References.md b/js/scripting-lang/tutorials/07_Function_References.md new file mode 100644 index 0000000..4ca1616 --- /dev/null +++ b/js/scripting-lang/tutorials/07_Function_References.md @@ -0,0 +1,220 @@ +# Function References with `@` Symbol + +## What are Function References? + +Function references allow you to pass functions as values without calling them immediately. The `@` symbol creates a reference to a function. + +```plaintext +/* @ symbol for function references */ +double : x -> x * 2; +numbers : {1, 2, 3}; +result : map @double numbers; /* @double is a function reference */ +``` + +## Why is This Esoteric? + +The `@` symbol for function references is unique to our language. Most languages use just the function name or different syntax like `&function` or `function.bind()`. + +## Basic Examples + +```plaintext +/* Define a function */ +double : x -> x * 2; + +/* Function reference vs function call */ +function_ref : @double; /* Reference to the function */ +function_call : double 5; /* Call the function with argument 5 */ + +/* Use function reference with combinators */ +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; /* {2, 4, 6, 8, 10} */ +``` + +## How It Works + +The `@` symbol tells the language to treat the identifier as a function reference rather than calling the function: + +```plaintext +/* Without @ - function is called immediately */ +result1 : map double numbers; /* Error: double is not a function reference */ + +/* With @ - function reference is passed */ +result2 : map @double numbers; /* Works: @double is a function reference */ +``` + +## Common Use Cases + +### With `map` +```plaintext +/* Map function references over collections */ +numbers : {1, 2, 3, 4, 5}; + +/* Arithmetic functions */ +doubled : map @double numbers; /* {2, 4, 6, 8, 10} */ +incremented : map @increment numbers; /* {2, 3, 4, 5, 6} */ +squared : map @square numbers; /* {1, 4, 9, 16, 25} */ + +/* Custom functions */ +add_ten : x -> x + 10; +plus_ten : map @add_ten numbers; /* {11, 12, 13, 14, 15} */ +``` + +### With `filter` +```plaintext +/* Filter with function references */ +numbers : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Built-in comparison functions */ +evens : filter @is_even numbers; /* {2, 4, 6, 8, 10} */ +positives : filter @is_positive numbers; /* {1, 2, 3, 4, 5, 6, 7, 8, 9, 10} */ + +/* Custom filter functions */ +is_greater_than_five : x -> x > 5; +large_numbers : filter @is_greater_than_five numbers; /* {6, 7, 8, 9, 10} */ +``` + +### With `reduce` +```plaintext +/* Reduce with function references */ +numbers : {1, 2, 3, 4, 5}; + +/* Arithmetic operations */ +sum : reduce @add 0 numbers; /* 15 */ +product : reduce @multiply 1 numbers; /* 120 */ + +/* Custom reduce functions */ +max_value : reduce @max 0 numbers; /* 5 */ +min_value : reduce @min 1000 numbers; /* 1 */ +``` + +### With `each` +```plaintext +/* Each with function references */ +numbers1 : {1, 2, 3, 4, 5}; +numbers2 : {10, 20, 30, 40, 50}; + +/* Element-wise operations */ +sums : each @add numbers1 numbers2; /* {11, 22, 33, 44, 55} */ +products : each @multiply numbers1 numbers2; /* {10, 40, 90, 160, 250} */ +``` + +## Function Composition with References + +Function references work seamlessly with composition: + +```plaintext +/* Compose function references */ +double : x -> x * 2; +increment : x -> x + 1; +square : x -> x * x; + +/* Compose references */ +double_then_increment : compose @increment @double; +increment_then_square : compose @square @increment; + +/* Use in pipelines */ +result1 : double_then_increment 5; /* double(5)=10, increment(10)=11 */ +result2 : increment_then_square 5; /* increment(5)=6, square(6)=36 */ +``` + +## The `via` Operator with References + +Function references work with the `via` operator: + +```plaintext +/* Via with function references */ +result1 : @double via @increment 5; /* 12 */ +result2 : @double via @increment via @square 3; /* 20 */ + +/* Complex pipeline */ +pipeline : @sum via @map @double via @filter @is_even; +result3 : pipeline {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; /* 60 */ +``` + +## Table Operations with References + +The `t.` namespace functions can be referenced: + +```plaintext +/* Table operation references */ +data : {a: 1, b: 2, c: 3}; + +/* Get all keys */ +keys : @t.keys data; /* {"a", "b", "c"} */ + +/* Get all values */ +values : @t.values data; /* {1, 2, 3} */ + +/* Check if key exists */ +has_a : @t.has data "a"; /* true */ +``` + +## When to Use Function References + +**Use function references when:** +- Passing functions to combinators like `map`, `filter`, `reduce` +- Building function composition chains +- Creating reusable function components +- Working with higher-order functions +- Avoiding immediate function execution + +**Don't use function references when:** +- You want to call the function immediately +- You're working with simple function calls +- You need to pass arguments to the function + +## Common Patterns + +```plaintext +/* Pattern 1: Function pipelines */ +numbers : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Pipeline with references */ +pipeline : @sum via @map @double via @filter @is_even; +result : pipeline numbers; /* 60 */ + +/* Pattern 2: Reusable function components */ +double : x -> x * 2; +increment : x -> x + 1; +square : x -> x * x; + +/* Create reusable transformations */ +double_transform : @map @double; +increment_transform : @map @increment; +square_transform : @map @square; + +/* Use transformations */ +data : {1, 2, 3, 4, 5}; +doubled : double_transform data; /* {2, 4, 6, 8, 10} */ +incremented : increment_transform data; /* {2, 3, 4, 5, 6} */ +squared : square_transform data; /* {1, 4, 9, 16, 25} */ + +/* Pattern 3: Conditional function application */ +condition : true; +function_to_use : when condition is + true then @double + _ then @square; + +result : map function_to_use {1, 2, 3, 4, 5}; +/* Result depends on condition */ +``` + +## Key Takeaways + +1. **@ symbol** - creates function references +2. **No immediate execution** - function is not called when referenced +3. **Combinator compatibility** - works with `map`, `filter`, `reduce`, `each` +4. **Composition support** - works with `compose`, `pipe`, `via` +5. **Higher-order functions** - enables passing functions as arguments + +## Why This Matters + +Function references with the `@` symbol make the language more functional: + +- **Higher-order functions** - functions can be passed as values +- **Composability** - functions can be combined and reused +- **Functional style** - emphasizes function composition over method calls +- **Clear syntax** - distinguishes between function calls and references +- **Reusability** - function references can be stored and reused + +This feature makes the language feel more like functional programming languages where functions are first-class citizens! 🚀 \ No newline at end of file diff --git a/js/scripting-lang/tutorials/08_Combinators.md b/js/scripting-lang/tutorials/08_Combinators.md new file mode 100644 index 0000000..7fe2db9 --- /dev/null +++ b/js/scripting-lang/tutorials/08_Combinators.md @@ -0,0 +1,261 @@ +# Combinator-Based Architecture + +## What is Combinator-Based Architecture? + +Combinator-based architecture means the entire language is built from simple, composable functions called **combinators**. There are no classes, no inheritance, no methods - everything is function composition. + +```plaintext +/* Everything is built from combinators */ +/* map, filter, reduce, compose, pipe, each, via */ +/* No classes, no inheritance, no methods */ +``` + +## Why is This Esoteric? + +Most programming languages are built around objects, classes, and methods. Our language is built entirely around **function composition** and **combinators** - a completely different paradigm. + +## Core Combinators + +### `map` - Transform Elements +```plaintext +/* map applies a function to every element in a collection */ +double : x -> x * 2; +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; /* {2, 4, 6, 8, 10} */ + +/* map works with any function */ +increment : x -> x + 1; +incremented : map @increment numbers; /* {2, 3, 4, 5, 6} */ +``` + +### `filter` - Select Elements +```plaintext +/* filter keeps elements that satisfy a condition */ +is_even : x -> x % 2 = 0; +numbers : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; +evens : filter @is_even numbers; /* {2, 4, 6, 8, 10} */ + +/* filter with custom conditions */ +is_greater_than_five : x -> x > 5; +large_numbers : filter @is_greater_than_five numbers; /* {6, 7, 8, 9, 10} */ +``` + +### `reduce` - Accumulate Elements +```plaintext +/* reduce combines all elements into a single value */ +numbers : {1, 2, 3, 4, 5}; +sum : reduce @add 0 numbers; /* 15 */ +product : reduce @multiply 1 numbers; /* 120 */ + +/* reduce with custom accumulation */ +max_value : reduce @max 0 numbers; /* 5 */ +min_value : reduce @min 1000 numbers; /* 1 */ +``` + +### `each` - Multi-Argument Operations +```plaintext +/* each applies a function to corresponding elements from multiple collections */ +numbers1 : {1, 2, 3, 4, 5}; +numbers2 : {10, 20, 30, 40, 50}; + +/* Element-wise addition */ +sums : each @add numbers1 numbers2; /* {11, 22, 33, 44, 55} */ + +/* Element-wise multiplication */ +products : each @multiply numbers1 numbers2; /* {10, 40, 90, 160, 250} */ +``` + +## Function Composition Combinators + +### `compose` - Mathematical Composition +```plaintext +/* compose(f, g)(x) = f(g(x)) */ +double : x -> x * 2; +increment : x -> x + 1; +square : x -> x * x; + +/* Compose functions */ +double_then_increment : compose @increment @double; +increment_then_square : compose @square @increment; + +/* Use composed functions */ +result1 : double_then_increment 5; /* double(5)=10, increment(10)=11 */ +result2 : increment_then_square 5; /* increment(5)=6, square(6)=36 */ +``` + +### `pipe` - Pipeline Composition +```plaintext +/* pipe(f, g)(x) = g(f(x)) - left to right */ +double_then_square : pipe @double @square; +result : double_then_square 5; /* double(5)=10, square(10)=100 */ +``` + +### `via` - Natural Composition +```plaintext +/* via provides natural composition syntax */ +complex_transform : double via increment via square; +result : complex_transform 3; /* square(3)=9, increment(9)=10, double(10)=20 */ +``` + +## Building Complex Operations + +### Data Processing Pipeline +```plaintext +/* Build complex operations from simple combinators */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Pipeline: filter → map → reduce */ +is_even : x -> x % 2 = 0; +double : x -> x * 2; +sum : x -> reduce @add 0 x; + +/* Combine combinators */ +pipeline : sum via map @double via filter @is_even; +result : pipeline data; /* 60 */ + +/* Step by step: + 1. filter @is_even data → {2, 4, 6, 8, 10} + 2. map @double {2, 4, 6, 8, 10} → {4, 8, 12, 16, 20} + 3. sum {4, 8, 12, 16, 20} → 60 +*/ +``` + +### Validation Chain +```plaintext +/* Build validation from combinators */ +validate_positive : x -> x > 0; +validate_even : x -> x % 2 = 0; +validate_small : x -> x < 10; + +/* Chain validations */ +all_validations : validate_small via validate_even via validate_positive; +result : all_validations 6; /* true (6 > 0, 6 % 2 = 0, 6 < 10) */ +``` + +## Table-Specific Combinators + +The `t.` namespace provides table-specific combinators: + +```plaintext +/* Table operations as combinators */ +data : {a: 1, b: 2, c: 3}; + +/* Get keys and values */ +keys : t.keys data; /* {"a", "b", "c"} */ +values : t.values data; /* {1, 2, 3} */ + +/* Check and get values */ +has_a : t.has data "a"; /* true */ +value_a : t.get data "a"; /* 1 */ + +/* Transform tables */ +with_d : t.set data "d" 4; /* {a: 1, b: 2, c: 3, d: 4} */ +without_b : t.delete data "b"; /* {a: 1, c: 3} */ + +/* Merge tables */ +table1 : {a: 1, b: 2}; +table2 : {c: 3, d: 4}; +merged : t.merge table1 table2; /* {a: 1, b: 2, c: 3, d: 4} */ +``` + +## Advanced Combinator Patterns + +### Function Factories +```plaintext +/* Create combinators that generate other combinators */ +create_multiplier : factor -> multiply factor; +double : create_multiplier 2; +triple : create_multiplier 3; + +/* Use generated combinators */ +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; /* {2, 4, 6, 8, 10} */ +tripled : map @triple numbers; /* {3, 6, 9, 12, 15} */ +``` + +### Conditional Combinators +```plaintext +/* Combinators that choose based on conditions */ +conditional_map : condition transform_false transform_true -> + when condition is + true then transform_true + _ then transform_false; + +/* Use conditional combinator */ +is_positive : x -> x > 0; +double : x -> x * 2; +square : x -> x * x; + +conditional_transform : conditional_map is_positive @square @double; +result : map conditional_transform {1, -2, 3, -4, 5}; +/* Result: {1, -4, 9, -8, 25} (positive numbers squared, negative doubled) */ +``` + +### Recursive Combinators +```plaintext +/* Combinators that can be applied recursively */ +repeat_transform : n transform -> + when n is + 0 then identity + _ then compose transform (repeat_transform (n - 1) transform); + +/* Use recursive combinator */ +double : x -> x * 2; +double_three_times : repeat_transform 3 @double; +result : double_three_times 5; /* 40 (5 * 2 * 2 * 2) */ +``` + +## When to Use Combinators + +**Use combinators when:** +- Processing collections of data +- Building data transformation pipelines +- Creating reusable function components +- Working with functional programming patterns +- Building complex operations from simple ones + +**Don't use combinators when:** +- You need side effects (combinators are pure) +- You need complex object-oriented patterns +- You're working with simple, one-off operations +- You need imperative control flow + +## Common Patterns + +```plaintext +/* Pattern 1: Data transformation pipeline */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + +/* Build pipeline from combinators */ +pipeline : sum via map @double via filter @is_even; +result : pipeline data; /* 60 */ + +/* Pattern 2: Validation pipeline */ +validate_user : user -> + all_validations : validate_email via validate_age via validate_name; + all_validations user; + +/* Pattern 3: Configuration builder */ +build_config : base_config overrides -> + t.merge base_config overrides; +``` + +## Key Takeaways + +1. **Function composition** - everything is built from function composition +2. **No objects** - no classes, inheritance, or methods +3. **Composable** - combinators can be combined into complex operations +4. **Pure functions** - no side effects, predictable behavior +5. **Mathematical thinking** - operations are mathematical transformations + +## Why This Matters + +Combinator-based architecture makes the language fundamentally different: + +- **Mathematical foundation** - based on function theory and category theory +- **Composability** - complex operations built from simple, reusable parts +- **Predictability** - pure functions with no side effects +- **Functional thinking** - encourages thinking in terms of transformations +- **No state management** - no mutable state to manage + +This architecture makes the language feel more like mathematical notation than traditional programming! 🚀 \ No newline at end of file diff --git a/js/scripting-lang/tutorials/09_Expression_Based.md b/js/scripting-lang/tutorials/09_Expression_Based.md new file mode 100644 index 0000000..f699390 --- /dev/null +++ b/js/scripting-lang/tutorials/09_Expression_Based.md @@ -0,0 +1,201 @@ +# No Explicit Return Statements + +## What are Implicit Returns? + +Functions automatically return the last evaluated expression without needing an explicit `return` statement. + +```plaintext +/* Functions return the last expression automatically */ +add : x y -> x + y; /* Automatically returns x + y */ +double : x -> x * 2; /* Automatically returns x * 2 */ +``` + +## Why is This Esoteric? + +Most programming languages require explicit `return` statements. Our language makes them **implicit** - the last expression is automatically returned. + +## Basic Examples + +```plaintext +/* Simple functions with implicit returns */ +add : x y -> x + y; +result : add 5 3; /* 8 */ + +/* Single expression functions */ +double : x -> x * 2; +increment : x -> x + 1; +square : x -> x * x; + +/* All automatically return their last expression */ +result1 : double 5; /* 10 */ +result2 : increment 5; /* 6 */ +result3 : square 5; /* 25 */ +``` + +## Complex Functions + +Even complex functions with multiple expressions return the last one: + +```plaintext +/* Function with multiple expressions */ +complex_function : x -> + doubled : x * 2; + incremented : doubled + 1; + squared : incremented * incremented; + squared; /* This is what gets returned */ + +result : complex_function 3; +/* Step 1: doubled = 3 * 2 = 6 */ +/* Step 2: incremented = 6 + 1 = 7 */ +/* Step 3: squared = 7 * 7 = 49 */ +/* Result: 49 */ +``` + +## Conditional Returns + +Functions with conditional logic return the last expression in the executed branch: + +```plaintext +/* Function with conditional logic */ +classify_number : x -> + when x is + 0 then "zero" + when x % 2 = 0 then "even" + when x % 2 = 1 then "odd" + _ then "unknown"; + +/* Each branch returns its last expression */ +result1 : classify_number 0; /* "zero" */ +result2 : classify_number 4; /* "even" */ +result3 : classify_number 7; /* "odd" */ +``` + +## Nested Functions + +Nested functions also use implicit returns: + +```plaintext +/* Nested function definitions */ +outer_function : x -> + inner_function : y -> y * 2; + inner_function x; + +/* The nested function returns its last expression */ +result : outer_function 5; /* 10 */ +``` + +## Table Operations + +Table operations return the last expression: + +```plaintext +/* Function that creates and modifies tables */ +create_user_profile : name age -> + base_profile : {name: name, age: age}; + with_id : t.set base_profile "id" "user_123"; + with_timestamp : t.set with_id "created" "2024-01-01"; + with_timestamp; /* Returns the final table */ + +result : create_user_profile "Alice" 30; +/* Result: {name: "Alice", age: 30, id: "user_123", created: "2024-01-01"} */ +``` + +## Function Composition + +Implicit returns work seamlessly with function composition: + +```plaintext +/* Functions that return functions */ +create_multiplier : factor -> + multiplier : x -> x * factor; + multiplier; /* Returns the multiplier function */ + +/* Use the returned function */ +double : create_multiplier 2; +triple : create_multiplier 3; + +result1 : double 5; /* 10 */ +result2 : triple 5; /* 15 */ +``` + +## Common Patterns + +### Data Transformation +```plaintext +/* Transform data with implicit returns */ +transform_user_data : user -> + with_full_name : t.set user "full_name" (user.first_name + " " + user.last_name); + with_age_group : t.set with_full_name "age_group" ( + when user.age < 18 then "minor" + when user.age < 65 then "adult" + _ then "senior" + ); + with_age_group; /* Returns the transformed user */ + +user : {first_name: "Alice", last_name: "Smith", age: 30}; +result : transform_user_data user; +/* Result: {first_name: "Alice", last_name: "Smith", age: 30, full_name: "Alice Smith", age_group: "adult"} */ +``` + +### Validation Functions +```plaintext +/* Validation with implicit returns */ +validate_user : user -> + name_valid : user.name != ""; + age_valid : user.age > 0 && user.age < 120; + email_valid : user.email.contains "@"; + name_valid && age_valid && email_valid; /* Returns boolean */ + +user : {name: "Alice", age: 30, email: "alice@example.com"}; +is_valid : validate_user user; /* true */ +``` + +### Configuration Builders +```plaintext +/* Build configuration with implicit returns */ +build_config : base_config environment -> + dev_config : when environment is + "development" then t.merge base_config {debug: true, log_level: "verbose"} + "production" then t.merge base_config {debug: false, log_level: "error"} + _ then base_config; + dev_config; /* Returns the final config */ + +base : {timeout: 30, retries: 3}; +result : build_config base "development"; +/* Result: {timeout: 30, retries: 3, debug: true, log_level: "verbose"} */ +``` + +## When to Use Implicit Returns + +**Implicit returns work well when:** +- Functions have a single, clear purpose +- The return value is obvious from the function name +- Functions are pure (no side effects) +- Functions are used in composition chains +- The logic is straightforward + +**Consider explicit structure when:** +- Functions have complex conditional logic +- Multiple return paths are confusing +- Functions perform side effects +- The return value is not obvious + +## Key Takeaways + +1. **Last expression returned** - the last evaluated expression is automatically returned +2. **No return keyword** - no explicit `return` statements needed +3. **Conditional returns** - the last expression in the executed branch is returned +4. **Nested functions** - nested functions also use implicit returns +5. **Composition friendly** - works seamlessly with function composition + +## Why This Matters + +Implicit returns make the language more functional and concise: + +- **Concise syntax** - less boilerplate code +- **Functional style** - emphasizes expressions over statements +- **Composition focus** - functions are treated as expressions +- **Mathematical thinking** - functions are mathematical mappings +- **Readability** - clear flow from input to output + +This feature makes the language feel more like mathematical functions than traditional programming procedures! 🚀 \ No newline at end of file diff --git a/js/scripting-lang/tutorials/10_Tables_Deep_Dive.md b/js/scripting-lang/tutorials/10_Tables_Deep_Dive.md new file mode 100644 index 0000000..9d66d1b --- /dev/null +++ b/js/scripting-lang/tutorials/10_Tables_Deep_Dive.md @@ -0,0 +1,271 @@ +# Table Literals as Primary Data Structure + +## What are Table Literals? + +Tables are the **only** data structure in our language. They serve as objects, arrays, maps, and any other collection type you might need. + +```plaintext +/* Tables serve multiple purposes */ +/* As objects: {name: "Alice", age: 30} */ +/* As arrays: {1, 2, 3, 4, 5} */ +/* As maps: {key1: "value1", key2: "value2"} */ +/* As nested structures: {user: {name: "Alice", scores: {85, 90, 88}}} */ +``` + +## Why is This Esoteric? + +Most languages have separate types for different data structures (arrays, objects, maps, sets, etc.). Our language uses **one unified structure** for everything. + +## Basic Table Syntax + +### Key-Value Pairs (Objects) +```plaintext +/* Create object-like tables */ +person : {name: "Alice", age: 30, city: "New York"}; +user : {id: 123, email: "alice@example.com", active: true}; + +/* Access properties */ +name : person.name; /* "Alice" */ +age : person.age; /* 30 */ +``` + +### Array-Like Tables +```plaintext +/* Create array-like tables */ +numbers : {1, 2, 3, 4, 5}; +names : {"Alice", "Bob", "Charlie"}; +mixed : {1, "hello", true, 3.14}; + +/* Access by index (using bracket notation) */ +first_number : numbers[0]; /* 1 */ +second_name : names[1]; /* "Bob" */ +``` + +### Mixed Tables +```plaintext +/* Tables can mix key-value pairs and array elements */ +mixed_table : { + name: "Alice", + scores: {85, 90, 88}, + metadata: {created: "2024-01-01", version: 1.0} +}; +``` + +## Table Operations + +### Creating Tables +```plaintext +/* Empty table */ +empty : {}; + +/* Single element */ +single : {42}; + +/* Key-value pairs */ +config : {debug: true, timeout: 30, retries: 3}; + +/* Mixed content */ +complex : { + id: 123, + tags: {"important", "urgent"}, + settings: {theme: "dark", notifications: true} +}; +``` + +### Accessing Values +```plaintext +/* Dot notation for keys */ +data : {name: "Alice", age: 30}; +name : data.name; /* "Alice" */ + +/* Bracket notation for indices or dynamic keys */ +numbers : {1, 2, 3, 4, 5}; +first : numbers[0]; /* 1 */ +second : numbers[1]; /* 2 */ + +/* Dynamic key access */ +key : "name"; +value : data[key]; /* "Alice" */ +``` + +### Nested Tables +```plaintext +/* Deeply nested structures */ +user_profile : { + personal: { + name: "Alice", + age: 30, + contact: { + email: "alice@example.com", + phone: "555-1234" + } + }, + preferences: { + theme: "dark", + notifications: true, + languages: {"English", "Spanish"} + } +}; + +/* Access nested values */ +email : user_profile.personal.contact.email; /* "alice@example.com" */ +theme : user_profile.preferences.theme; /* "dark" */ +first_language : user_profile.preferences.languages[0]; /* "English" */ +``` + +## Table-Specific Operations + +The `t.` namespace provides table-specific operations: + +```plaintext +/* Table operations */ +data : {a: 1, b: 2, c: 3}; + +/* Get keys */ +keys : t.keys data; /* {"a", "b", "c"} */ + +/* Get values */ +values : t.values data; /* {1, 2, 3} */ + +/* Get key-value pairs */ +pairs : t.pairs data; /* {{key: "a", value: 1}, {key: "b", value: 2}, {key: "c", value: 3}} */ + +/* Check if key exists */ +has_a : t.has data "a"; /* true */ +has_d : t.has data "d"; /* false */ + +/* Get value by key */ +value_a : t.get data "a"; /* 1 */ + +/* Get table length */ +length : t.length data; /* 3 */ +``` + +## Element-Wise Operations + +Tables work seamlessly with element-wise operations: + +```plaintext +/* Map over table values - @ operator required for higher-order functions */ +numbers : {a: 1, b: 2, c: 3, d: 4, e: 5}; +double : x -> x * 2; +doubled : map @double numbers; /* {a: 2, b: 4, c: 6, d: 8, e: 10} */ + +/* Filter table values - @ operator required for higher-order functions */ +is_even : x -> x % 2 = 0; +evens : filter @is_even numbers; /* {b: 2, d: 4} */ + +/* Reduce table values - @ operator required for higher-order functions */ +sum : reduce @add 0 numbers; /* 15 */ +``` + +## Common Patterns + +### Configuration Objects +```plaintext +/* Build configuration objects */ +base_config : { + timeout: 30, + retries: 3, + debug: false +}; + +/* Environment-specific overrides */ +dev_config : t.merge base_config { + debug: true, + log_level: "verbose" +}; + +prod_config : t.merge base_config { + timeout: 60, + cache_enabled: true +}; +``` + +### Data Transformation +```plaintext +/* Transform data structures */ +raw_data : { + users: { + alice: {name: "Alice", age: 30, scores: {85, 90, 88}}, + bob: {name: "Bob", age: 25, scores: {92, 87, 95}} + } +}; + +/* Extract and transform user data */ +transform_user : user -> { + name: user.name, + age: user.age, + average_score: reduce @add 0 user.scores / 3 +}; + +transformed_users : map @transform_user raw_data.users; +/* Result: { + alice: {name: "Alice", age: 30, average_score: 87.67}, + bob: {name: "Bob", age: 25, average_score: 91.33} +} */ +``` + +### Nested Data Processing +```plaintext +/* Process nested table structures */ +company_data : { + departments: { + engineering: { + employees: { + alice: {name: "Alice", role: "Developer", salary: 80000}, + bob: {name: "Bob", role: "Manager", salary: 100000} + } + }, + marketing: { + employees: { + charlie: {name: "Charlie", role: "Designer", salary: 70000} + } + } + } +}; + +/* Extract all employee names - @ operator required for higher-order functions */ +get_names : dept -> map @(emp -> emp.name) dept.employees; +all_names : map @get_names company_data.departments; +/* Result: { + engineering: {"Alice", "Bob"}, + marketing: {"Charlie"} +} */ +``` + +## When to Use Tables + +**Use tables when you need:** +- **Objects** - key-value pairs for structured data +- **Arrays** - ordered collections of values +- **Maps** - dynamic key-value mappings +- **Nested structures** - complex hierarchical data +- **Mixed data** - combinations of different data types + +**Tables are perfect for:** +- Configuration objects +- User data and profiles +- API responses and requests +- Data transformation pipelines +- Complex nested structures + +## Key Takeaways + +1. **Unified structure** - one data type for all collections +2. **Flexible syntax** - supports both key-value pairs and array elements +3. **Nested support** - can contain other tables +4. **Element-wise operations** - works with `map`, `filter`, `reduce` (using `@` operator) +5. **Immutable operations** - all operations return new tables + +## Why This Matters + +Table literals as the primary data structure make the language simpler and more unified: + +- **Simplicity** - only one data structure to learn +- **Flexibility** - can represent any collection type +- **Consistency** - same operations work on all data +- **Composability** - tables can be nested and combined +- **Functional style** - immutable operations on all data + +This feature makes the language feel more like mathematical sets and relations than traditional programming data structures! 🚀 \ No newline at end of file diff --git a/js/scripting-lang/tutorials/11_Standard_Library.md b/js/scripting-lang/tutorials/11_Standard_Library.md new file mode 100644 index 0000000..f26828d --- /dev/null +++ b/js/scripting-lang/tutorials/11_Standard_Library.md @@ -0,0 +1,129 @@ +# Standard Library Overview + +## What is the Standard Library? + +The Baba Yaga standard library provides a comprehensive set of functions for common operations. Everything is a function - even operators like `+` and `*` are just functions under the hood. + +## Core Categories + +### Arithmetic Functions +```plaintext +/* Basic arithmetic */ +add 5 3; /* 8 */ +subtract 10 4; /* 6 */ +multiply 6 7; /* 42 */ +divide 20 5; /* 4 */ +modulo 17 5; /* 2 */ +power 2 8; /* 256 */ +negate 42; /* -42 */ +``` + +### Comparison Functions +```plaintext +/* Comparisons return booleans */ +equals 5 5; /* true */ +notEquals 3 7; /* true */ +lessThan 3 7; /* true */ +greaterThan 10 5; /* true */ +lessEqual 5 5; /* true */ +greaterEqual 8 3; /* true */ +``` + +### Logical Functions +```plaintext +/* Logical operations */ +logicalAnd true false; /* false */ +logicalOr true false; /* true */ +logicalXor true true; /* false */ +logicalNot true; /* false */ +``` + +### Higher-Order Functions +```plaintext +/* Function manipulation */ +compose @double @increment 5; /* 12 */ +pipe @increment @double 5; /* 12 */ +apply @add 3 4; /* 7 */ +curry @add 3; /* function that adds 3 */ +``` + +### Collection Functions +```plaintext +/* Working with collections */ +map @double {1, 2, 3}; /* {2, 4, 6} */ +filter @is_even {1, 2, 3, 4}; /* {2, 4} */ +reduce @add 0 {1, 2, 3}; /* 6 */ +each @add {1, 2} {10, 20}; /* {11, 22} */ +``` + +### Enhanced Combinators +```plaintext +/* Utility functions */ +identity 42; /* 42 */ +constant 5 10; /* 5 */ +flip @subtract 5 10; /* 5 (10 - 5) */ +on @length @add "hello" "world"; /* 10 */ +both @is_even @is_positive 6; /* true */ +either @is_even @is_negative 6; /* true */ +``` + +## Table Operations (`t.` namespace) + +All table operations are immutable and return new tables: + +```plaintext +/* Table-specific operations */ +data : {a: 1, b: 2, c: 3}; +doubled : t.map @double data; /* {a: 2, b: 4, c: 6} */ +filtered : t.filter @is_even data; /* {b: 2} */ +updated : t.set data "d" 4; /* {a: 1, b: 2, c: 3, d: 4} */ +removed : t.delete data "b"; /* {a: 1, c: 3} */ +merged : t.merge data {d: 4, e: 5}; /* {a: 1, b: 2, c: 3, d: 4, e: 5} */ +value : t.get data "a"; /* 1 */ +has_key : t.has data "b"; /* true */ +count : t.length data; /* 3 */ +``` + +## When to Use Which Function + +- **Use `map`** for transforming every element in a collection +- **Use `filter`** for selecting elements that match a condition +- **Use `reduce`** for combining all elements into a single value +- **Use `each`** for element-wise operations across multiple collections +- **Use `t.map`/`t.filter`** when you want to emphasize table operations +- **Use `compose`** for mathematical-style function composition (right-to-left) +- **Use `pipe`** for pipeline-style composition (left-to-right) + +## Common Patterns + +```plaintext +/* Data processing pipeline */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; +is_even : x -> x % 2 = 0; +double : x -> x * 2; +sum : x -> reduce @add 0 x; + +/* Process: filter evens, double them, sum the result */ +result : sum map @double filter @is_even data; +/* Result: 60 */ + +/* Table transformation */ +users : { + alice: {name: "Alice", age: 25}, + bob: {name: "Bob", age: 30} +}; +get_age : x -> x.age; +is_adult : x -> x >= 18; +format_age : x -> x + " years old"; + +/* Get formatted ages of adult users */ +adult_ages : map @format_age filter @is_adult map @get_age users; +/* Result: {alice: "25 years old", bob: "30 years old"} */ +``` + +## Next Steps + +Now that you understand the standard library, explore: +- [Advanced Combinators](14_Advanced_Combinators.md) for complex patterns +- [IO Operations](12_IO_Operations.md) for input/output +- [Error Handling](13_Error_Handling.md) for robust programs \ No newline at end of file diff --git a/js/scripting-lang/tutorials/12_IO_Operations.md b/js/scripting-lang/tutorials/12_IO_Operations.md new file mode 100644 index 0000000..de22f0a --- /dev/null +++ b/js/scripting-lang/tutorials/12_IO_Operations.md @@ -0,0 +1,208 @@ +# IO Operations + +## What are IO Operations? + +IO (Input/Output) operations allow your functional programs to interact with the outside world. Baba Yaga provides a minimal set of IO operations that keep side effects contained and explicit. + +## Basic Output + +### Simple Output +```plaintext +/* Output values to console */ +..out "Hello, World!"; +..out 42; +..out true; +..out {name: "Alice", age: 30}; +``` + +### Output with Expressions +```plaintext +/* Output computed values */ +result : 5 + 3 * 2; +..out result; /* Output: 11 */ + +/* Output function results */ +double : x -> x * 2; +..out double 7; /* Output: 14 */ + +/* Output table operations */ +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; +..out doubled; /* Output: {2, 4, 6, 8, 10} */ +``` + +## Assertions + +Assertions help you verify your program's behavior: + +```plaintext +/* Basic assertions */ +..assert 5 = 5; /* Passes */ +..assert 3 + 2 = 5; /* Passes */ +..assert true; /* Passes */ +..assert false; /* Fails with error */ + +/* Assertions with messages */ +..assert "5 equals 5" 5 = 5; /* Passes */ +..assert "3 + 2 equals 5" 3 + 2 = 5; /* Passes */ +..assert "This will fail" 1 = 2; /* Fails with message */ +``` + +### Testing Functions +```plaintext +/* Test function behavior */ +factorial : n -> + when n is + 0 then 1 + _ then n * (factorial (n - 1)); + +/* Test cases */ +..assert "factorial 0 = 1" factorial 0 = 1; +..assert "factorial 1 = 1" factorial 1 = 1; +..assert "factorial 5 = 120" factorial 5 = 120; +``` + +## Emit and Listen Pattern + +The `..emit` and `..listen` pattern provides a way to interface functional code with external systems: + +### Emitting Events +```plaintext +/* Emit events with data */ +..emit "user_created" {id: 123, name: "Alice"}; +..emit "data_processed" {count: 42, success: true}; +..emit "error_occurred" {message: "Invalid input", code: 400}; +``` + +### Listening for Events +```plaintext +/* Listen for specific events */ +..listen "user_created" handle_user_created; +..listen "data_processed" handle_data_processed; +..listen "error_occurred" handle_error; +``` + +### Event Handlers +```plaintext +/* Define event handlers */ +handle_user_created : user_data -> + ..out "New user created:"; + ..out user_data.name; + +handle_data_processed : result -> + when result.success is + true then ..out "Processing successful: " + result.count + " items" + false then ..out "Processing failed"; + +handle_error : error -> + ..out "Error: " + error.message; + ..out "Code: " + error.code; +``` + +## Input Operations + +### Reading Input +```plaintext +/* Read input from user */ +name : ..in "Enter your name: "; +..out "Hello, " + name + "!"; + +/* Read and process input */ +age_input : ..in "Enter your age: "; +age : parseInt age_input; +..out "You are " + age + " years old"; +``` + +## IO Best Practices + +### Keep Side Effects Explicit +```plaintext +/* Good: Clear IO operations */ +process_data : data -> + result : transform data; + ..out "Processing complete"; + ..emit "data_processed" result; + result; + +/* Avoid: Hidden side effects in pure functions */ +bad_transform : data -> + ..out "Processing..."; /* Side effect in "pure" function */ + data * 2; +``` + +### Use Assertions for Testing +```plaintext +/* Test your functions thoroughly */ +is_even : x -> x % 2 = 0; +double : x -> x * 2; + +/* Test individual functions */ +..assert "0 is even" is_even 0 = true; +..assert "1 is not even" is_even 1 = false; +..assert "double 5 = 10" double 5 = 10; + +/* Test composed functions */ +doubled_evens : compose @double @is_even; +..assert "doubled_evens 6 = true" doubled_evens 6 = true; +``` + +### Structured Output +```plaintext +/* Use tables for structured output */ +user : {name: "Alice", age: 30, city: "NYC"}; +..out "User Profile:"; +..out " Name: " + user.name; +..out " Age: " + user.age; +..out " City: " + user.city; + +/* Or output the entire structure */ +..out user; +``` + +## Common Patterns + +### Data Processing Pipeline +```plaintext +/* Process data with IO feedback */ +data : {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; +..out "Processing " + t.length data + " items"; + +is_even : x -> x % 2 = 0; +double : x -> x * 2; +sum : x -> reduce @add 0 x; + +/* Process with progress updates */ +evens : filter @is_even data; +..out "Found " + t.length evens + " even numbers"; + +doubled : map @double evens; +..out "Doubled values:"; +..out doubled; + +total : sum doubled; +..out "Sum of doubled evens: " + total; + +/* Emit final result */ +..emit "processing_complete" {input_count: t.length data, result: total}; +``` + +### Error Handling +```plaintext +/* Handle potential errors gracefully */ +safe_divide : x y -> + when y = 0 then + ..emit "division_error" {dividend: x, divisor: y}; + "Error: Division by zero" + _ then x / y; + +/* Test error handling */ +..out safe_divide 10 2; /* 5 */ +..out safe_divide 10 0; /* Error: Division by zero */ +``` + +## Next Steps + +Now that you understand IO operations, explore: +- [Error Handling](13_Error_Handling.md) for robust error management +- [Integration Patterns](15_Integration_Patterns.md) for external system integration +- [Best Practices](16_Best_Practices.md) for writing clean code \ No newline at end of file diff --git a/js/scripting-lang/tutorials/13_Error_Handling.md b/js/scripting-lang/tutorials/13_Error_Handling.md new file mode 100644 index 0000000..07aff5a --- /dev/null +++ b/js/scripting-lang/tutorials/13_Error_Handling.md @@ -0,0 +1,256 @@ +# Error Handling + +## What is Error Handling? + +Error handling in Baba Yaga is based on functional programming principles - instead of throwing exceptions, we use pattern matching and return values to handle errors gracefully. + +## Basic Error Handling + +### Using Pattern Matching +```plaintext +/* Handle division by zero */ +safe_divide : x y -> + when y = 0 then "Error: Division by zero" + _ then x / y; + +/* Test the function */ +..out safe_divide 10 2; /* 5 */ +..out safe_divide 10 0; /* Error: Division by zero */ +``` + +### Return Error Values +```plaintext +/* Return structured error information */ +divide_with_error : x y -> + when y = 0 then {error: true, message: "Division by zero", dividend: x} + _ then {error: false, result: x / y}; + +/* Handle the result */ +result : divide_with_error 10 0; +when result.error is + true then ..out "Error: " + result.message + false then ..out "Result: " + result.result; +``` + +## Assertions for Validation + +### Input Validation +```plaintext +/* Validate function inputs */ +factorial : n -> + ..assert "n must be non-negative" n >= 0; + when n is + 0 then 1 + _ then n * (factorial (n - 1)); + +/* Test validation */ +..out factorial 5; /* 120 */ +/* factorial -1; */ /* Would fail assertion */ +``` + +### Data Validation +```plaintext +/* Validate table structure */ +validate_user : user -> + ..assert "user must have name" t.has user "name"; + ..assert "user must have age" t.has user "age"; + ..assert "age must be positive" user.age > 0; + user; + +/* Test validation */ +valid_user : {name: "Alice", age: 30}; +invalid_user : {name: "Bob"}; /* Missing age */ + +validated : validate_user valid_user; +/* validate_user invalid_user; */ /* Would fail assertion */ +``` + +## Error Patterns + +### Maybe Pattern +```plaintext +/* Maybe pattern for optional values */ +find_user : id users -> + when t.has users id then {just: true, value: t.get users id} + _ then {just: false}; + +/* Handle maybe results */ +users : { + alice: {name: "Alice", age: 30}, + bob: {name: "Bob", age: 25} +}; + +result : find_user "alice" users; +when result.just is + true then ..out "Found: " + result.value.name + false then ..out "User not found"; + +not_found : find_user "charlie" users; +when not_found.just is + true then ..out "Found: " + not_found.value.name + false then ..out "User not found"; +``` + +### Either Pattern +```plaintext +/* Either pattern for success/error */ +parse_number : input -> + parsed : parseInt input; + when parsed = NaN then {left: "Invalid number: " + input} + _ then {right: parsed}; + +/* Handle either results */ +valid : parse_number "42"; +when valid.left is + _ then ..out "Error: " + valid.left + _ then ..out "Success: " + valid.right; + +invalid : parse_number "abc"; +when invalid.left is + _ then ..out "Error: " + invalid.left + _ then ..out "Success: " + invalid.right; +``` + +## Error Recovery + +### Fallback Values +```plaintext +/* Provide fallback values */ +get_config : key default_value config -> + when t.has config key then t.get config key + _ then default_value; + +/* Use with fallbacks */ +config : {debug: true, timeout: 30}; +debug_mode : get_config "debug" false config; /* true */ +retries : get_config "retries" 3 config; /* 3 (fallback) */ +``` + +### Retry Logic +```plaintext +/* Simple retry with exponential backoff */ +retry_operation : operation max_attempts -> + attempt_operation : attempt -> + when attempt > max_attempts then {error: "Max attempts exceeded"} + _ then + result : operation; + when result.error is + true then + delay : power 2 attempt; /* Exponential backoff */ + ..out "Attempt " + attempt + " failed, retrying in " + delay + "ms"; + attempt_operation (attempt + 1) + false then result; + + attempt_operation 1; +``` + +## Error Propagation + +### Chaining Error Handling +```plaintext +/* Chain operations that might fail */ +process_user_data : user_id -> + /* Step 1: Find user */ + user_result : find_user user_id users; + when user_result.just is + false then {error: "User not found: " + user_id} + _ then + user : user_result.value; + + /* Step 2: Validate user */ + validation_result : validate_user user; + when validation_result.error is + true then {error: "Invalid user data"} + _ then + /* Step 3: Process user */ + processed : process_user user; + {success: true, data: processed}; +``` + +## Testing Error Conditions + +### Test Error Cases +```plaintext +/* Test both success and error cases */ +test_safe_divide : -> + /* Test successful division */ + ..assert "10 / 2 = 5" safe_divide 10 2 = 5; + + /* Test division by zero */ + error_result : safe_divide 10 0; + ..assert "Division by zero returns error" error_result = "Error: Division by zero"; + + ..out "All tests passed"; + +/* Run the tests */ +test_safe_divide; +``` + +### Property-Based Testing +```plaintext +/* Test properties of error handling */ +test_divide_properties : -> + /* Property: safe_divide x 1 = x */ + ..assert "x / 1 = x" safe_divide 42 1 = 42; + + /* Property: safe_divide x 0 always returns error */ + ..assert "x / 0 always errors" safe_divide 5 0 = "Error: Division by zero"; + ..assert "x / 0 always errors" safe_divide -3 0 = "Error: Division by zero"; + + /* Property: safe_divide 0 x = 0 (when x ≠ 0) */ + ..assert "0 / x = 0" safe_divide 0 5 = 0; + + ..out "All properties verified"; +``` + +## Best Practices + +### Keep Error Handling Explicit +```plaintext +/* Good: Explicit error handling */ +process_data : data -> + when data = null then {error: "No data provided"} + _ then + result : transform data; + when result.error is + true then result + false then {success: true, data: result.data}; + +/* Avoid: Silent failures */ +bad_process : data -> + transform data; /* What if this fails? */ +``` + +### Use Descriptive Error Messages +```plaintext +/* Good: Descriptive errors */ +validate_age : age -> + when age < 0 then "Age cannot be negative: " + age + when age > 150 then "Age seems unrealistic: " + age + _ then age; + +/* Avoid: Generic errors */ +bad_validate : age -> + when age < 0 then "Invalid input" /* Too generic */ + _ then age; +``` + +### Handle Errors at the Right Level +```plaintext +/* Handle errors where you have context */ +process_user : user_id -> + user : find_user user_id; + when user.just is + false then + ..emit "user_not_found" {user_id: user_id, timestamp: now()}; + "User not found" + _ then + process_user_data user.value; +``` + +## Next Steps + +Now that you understand error handling, explore: +- [Integration Patterns](15_Integration_Patterns.md) for external system error handling +- [Advanced Combinators](14_Advanced_Combinators.md) for error handling patterns +- [Best Practices](16_Best_Practices.md) for writing robust code \ No newline at end of file diff --git a/js/scripting-lang/tutorials/14_Advanced_Combinators.md b/js/scripting-lang/tutorials/14_Advanced_Combinators.md new file mode 100644 index 0000000..28937d1 --- /dev/null +++ b/js/scripting-lang/tutorials/14_Advanced_Combinators.md @@ -0,0 +1,295 @@ +# Advanced Combinators + +## What are Advanced Combinators? + +Advanced combinators are powerful patterns that combine multiple functions and operations to solve complex problems. They build on the basic combinators you've already learned. + +## Partial Application and Currying + +### Creating Specialized Functions +```plaintext +/* Basic partial application */ +add : x y -> x + y; +add_ten : add 10; +result : add_ten 5; /* 15 */ + +/* Complex partial application */ +format_with_prefix : prefix value -> prefix + ": " + value; +format_name : format_with_prefix "Name"; +format_age : format_with_prefix "Age"; + +person : {name: "Alice", age: 30}; +formatted_name : format_name person.name; /* "Name: Alice" */ +formatted_age : format_age person.age; /* "Age: 30" */ +``` + +### Currying with Combinators +```plaintext +/* Create specialized functions */ +multiply_by : x y -> x * y; +double : multiply_by 2; +triple : multiply_by 3; + +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; /* {2, 4, 6, 8, 10} */ +tripled : map @triple numbers; /* {3, 6, 9, 12, 15} */ +``` + +## Higher-Order Combinators + +### Combinators that Work with Other Combinators +```plaintext +/* Apply a combinator to multiple collections */ +apply_to_all : combinator collections -> + reduce @t.merge {} (map @combinator collections); + +/* Example usage */ +add_one : x -> x + 1; +collections : {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}}; +all_incremented : apply_to_all @map @add_one collections; +/* Result: {1: 2, 2: 3, 3: 4, 4: 5, 5: 6, 6: 7, 7: 8, 8: 9, 9: 10} */ +``` + +### Composing Multiple Functions +```plaintext +/* Compose many functions together */ +compose_many : functions -> + reduce @compose @identity functions; + +/* Example usage */ +double_then_increment : compose @increment @double; +complex_transform : compose @double_then_increment @square; +result : complex_transform 3; +/* Result: 19 (3^2=9, 9*2=18, 18+1=19) */ +``` + +## Memoization Pattern + +### Caching Function Results +```plaintext +/* Simple memoization */ +memoize : f -> { + cache: {}, + compute: x -> + when t.has cache x then t.get cache x + _ then { + result: f x, + new_cache: t.set cache x (f x) + } +}; + +/* Using memoized function */ +expensive_calc : x -> x * x * x; /* Simulate expensive computation */ +memoized_calc : memoize @expensive_calc; +result1 : memoized_calc.compute 5; /* Computes 125 */ +result2 : memoized_calc.compute 5; /* Uses cached result */ +``` + +## Real-World Problem Solving + +### E-commerce Order Processing +```plaintext +/* Process customer orders */ +orders : { + order1: {customer: "Alice", items: {book: 2, pen: 5}, status: "pending"}, + order2: {customer: "Bob", items: {laptop: 1}, status: "shipped"}, + order3: {customer: "Charlie", items: {book: 1, pen: 3}, status: "pending"} +}; + +prices : {book: 15, pen: 2, laptop: 800}; + +/* Calculate order totals */ +calculate_total : order -> { + customer: order.customer, + total: reduce @add 0 (map @calculate_item_total order.items), + status: order.status +}; + +calculate_item_total : item quantity -> + when item is + "book" then 15 * quantity + "pen" then 2 * quantity + "laptop" then 800 * quantity + _ then 0; + +/* Process all orders */ +processed_orders : map @calculate_total orders; +..out processed_orders; +``` + +### Data Transformation Pipeline +```plaintext +/* Transform user data through multiple stages */ +users : { + alice: {name: "Alice", age: 25, city: "NYC", active: true}, + bob: {name: "Bob", age: 30, city: "LA", active: false}, + charlie: {name: "Charlie", age: 35, city: "NYC", active: true} +}; + +/* Pipeline stages */ +filter_active : users -> filter @is_active users; +add_greeting : users -> map @add_greeting_to_user users; +format_output : users -> map @format_user_output users; + +is_active : user -> user.active; +add_greeting_to_user : user -> t.merge user {greeting: "Hello, " + user.name}; +format_user_output : user -> { + name: user.name, + greeting: user.greeting, + location: user.city +}; + +/* Execute pipeline */ +active_users : filter_active users; +greeted_users : add_greeting active_users; +formatted_users : format_output greeted_users; + +..out formatted_users; +``` + +## Advanced Patterns + +### Lazy Evaluation +```plaintext +/* Lazy evaluation with thunks */ +lazy : computation -> { + compute: computation, + evaluated: false, + result: null, + get: -> + when evaluated then result + _ then { + computed_result: compute, + new_lazy: { + compute: computation, + evaluated: true, + result: computed_result, + get: -> computed_result + } + } +}; + +/* Use lazy evaluation */ +expensive_operation : -> { + /* Simulate expensive computation */ + ..out "Computing..."; + 42 +}; + +lazy_result : lazy expensive_operation; +/* Computation hasn't happened yet */ + +actual_result : lazy_result.get; +/* Now computation happens */ +``` + +### Continuation-Passing Style +```plaintext +/* Continuation-passing style for complex control flow */ +process_with_continuation : data success_cont error_cont -> + when data = null then error_cont "No data provided" + _ then + processed : transform data; + when processed.error is + true then error_cont processed.message + false then success_cont processed.result; + +/* Use continuations */ +success_handler : result -> ..out "Success: " + result; +error_handler : error -> ..out "Error: " + error; + +process_with_continuation "valid data" success_handler error_handler; +process_with_continuation null success_handler error_handler; +``` + +## Performance Optimization + +### Avoiding Redundant Computations +```plaintext +/* Cache expensive computations */ +expensive_transform : data -> + /* Simulate expensive operation */ + data * data * data; + +/* With caching */ +transform_with_cache : { + cache: {}, + transform: data -> + when t.has cache data then t.get cache data + _ then { + result: expensive_transform data, + new_cache: t.set cache data (expensive_transform data) + } +}; + +/* Use cached version */ +result1 : transform_with_cache.transform 5; /* Computes */ +result2 : transform_with_cache.transform 5; /* Uses cache */ +``` + +### Lazy Collections +```plaintext +/* Lazy collection processing */ +lazy_map : f collection -> { + f: f, + collection: collection, + get: index -> + when index >= t.length collection then null + _ then f (t.get collection index) +}; + +/* Use lazy mapping */ +numbers : {1, 2, 3, 4, 5}; +expensive_double : x -> { + /* Simulate expensive operation */ + ..out "Doubling " + x; + x * 2 +}; + +lazy_doubled : lazy_map @expensive_double numbers; +/* No computation yet */ + +first_result : lazy_doubled.get 0; /* Only computes for index 0 */ +``` + +## Best Practices + +### Keep Combinators Focused +```plaintext +/* Good: Single responsibility */ +filter_by_age : min_age users -> + filter @(is_older_than min_age) users; + +is_older_than : min_age user -> user.age >= min_age; + +/* Avoid: Multiple responsibilities */ +bad_filter : min_age max_age users -> + filter @(complex_age_check min_age max_age) users; +``` + +### Use Descriptive Names +```plaintext +/* Good: Clear intent */ +process_active_users : users -> + filter @is_active (map @add_user_id users); + +/* Avoid: Generic names */ +process : data -> + filter @check (map @transform data); +``` + +### Compose, Don't Nest +```plaintext +/* Good: Composed functions */ +pipeline : compose @format_output (compose @add_metadata (filter @is_valid data)); + +/* Avoid: Deep nesting */ +nested : format_output (add_metadata (filter @is_valid data)); +``` + +## Next Steps + +Now that you understand advanced combinators, explore: +- [Integration Patterns](15_Integration_Patterns.md) for external system integration +- [Error Handling](13_Error_Handling.md) for robust error management +- [Best Practices](16_Best_Practices.md) for writing clean code \ No newline at end of file diff --git a/js/scripting-lang/tutorials/15_Integration_Patterns.md b/js/scripting-lang/tutorials/15_Integration_Patterns.md new file mode 100644 index 0000000..72e31ca --- /dev/null +++ b/js/scripting-lang/tutorials/15_Integration_Patterns.md @@ -0,0 +1,386 @@ +# Integration Patterns + +## What are Integration Patterns? + +Integration patterns show how to connect Baba Yaga programs with external systems, APIs, and other services while maintaining functional purity through the `..emit` and `..listen` pattern. + +## Basic Integration Concepts + +### Emit and Listen Pattern +```plaintext +/* Emit events to external systems */ +..emit "user_created" {id: 123, name: "Alice"}; +..emit "data_processed" {count: 42, success: true}; + +/* Listen for external events */ +..listen "user_created" handle_user_created; +..listen "data_processed" handle_data_processed; +``` + +### State Management +```plaintext +/* Get current state from external system */ +current_state : ..listen; + +/* Process based on state */ +user_id : current_state.user_id; +user_data : current_state.user_data; + +/* Emit processed result */ +..emit "user_processed" { + id: user_id, + processed_data: transform user_data +}; +``` + +## API Integration + +### HTTP Request Pattern +```plaintext +/* Emit HTTP requests */ +..emit { + action: "http_request", + method: "GET", + url: "https://api.example.com/users/123" +}; + +/* Emit POST request with data */ +..emit { + action: "http_request", + method: "POST", + url: "https://api.example.com/users", + data: {name: "Alice", email: "alice@example.com"} +}; +``` + +### API Response Handling +```plaintext +/* Listen for API responses */ +..listen "api_response" handle_api_response; + +handle_api_response : response -> + when response.success is + true then + ..out "API call successful:"; + ..out response.data + false then + ..out "API call failed:"; + ..out response.error; +``` + +## Database Integration + +### Database Operations +```plaintext +/* Emit database queries */ +..emit { + action: "db_query", + type: "select", + table: "users", + where: {id: 123} +}; + +/* Emit insert operation */ +..emit { + action: "db_query", + type: "insert", + table: "users", + data: {name: "Bob", email: "bob@example.com"} +}; +``` + +### Database Response Processing +```plaintext +/* Process database results */ +..listen "db_result" handle_db_result; + +handle_db_result : result -> + when result.type = "select" then + users : result.data; + processed_users : map @format_user users; + ..out "Found " + t.length users + " users"; + processed_users + _ then result.data; +``` + +## File System Integration + +### File Operations +```plaintext +/* Emit file operations */ +..emit { + action: "file_operation", + type: "read", + path: "/data/users.json" +}; + +/* Emit write operation */ +..emit { + action: "file_operation", + type: "write", + path: "/output/processed.json", + content: processed_data +}; +``` + +### File Processing +```plaintext +/* Process file contents */ +..listen "file_result" handle_file_result; + +handle_file_result : result -> + when result.type = "read" then + data : parse_json result.content; + processed : transform_data data; + processed + _ then result; +``` + +## Event-Driven Architecture + +### Event Processing Pipeline +```plaintext +/* Process incoming events */ +process_event : event -> + when event.type = "user_created" then + user : event.data; + validated_user : validate_user user; + when validated_user.valid is + true then + ..emit "user_validated" validated_user.data; + validated_user.data + false then + ..emit "validation_failed" validated_user.errors; + null + _ then event.data; +``` + +### Event Handlers +```plaintext +/* Register event handlers */ +..listen "user_created" process_event; +..listen "order_placed" process_event; +..listen "payment_received" process_event; +``` + +## External Service Integration + +### Third-Party API Integration +```plaintext +/* Integrate with external service */ +integrate_payment : order -> + payment_data : { + amount: order.total, + currency: "USD", + customer_id: order.customer_id + }; + + ..emit { + action: "external_api", + service: "stripe", + endpoint: "/payments", + method: "POST", + data: payment_data + }; + + payment_data; +``` + +### Service Response Handling +```plaintext +/* Handle external service responses */ +..listen "external_api_response" handle_external_response; + +handle_external_response : response -> + when response.service = "stripe" then + when response.success is + true then + ..emit "payment_successful" response.data; + response.data + false then + ..emit "payment_failed" response.error; + null + _ then response; +``` + +## Real-World Integration Example + +### E-commerce Order Processing +```plaintext +/* Complete order processing pipeline */ +process_order : order -> + /* Step 1: Validate order */ + validation_result : validate_order order; + when validation_result.valid is + false then + ..emit "order_invalid" validation_result.errors; + null + _ then + /* Step 2: Check inventory */ + ..emit { + action: "db_query", + type: "select", + table: "inventory", + where: {product_id: order.product_id} + }; + + /* Step 3: Process payment */ + payment_result : integrate_payment order; + + /* Step 4: Update inventory */ + ..emit { + action: "db_query", + type: "update", + table: "inventory", + where: {product_id: order.product_id}, + data: {quantity: decrement_quantity order.quantity} + }; + + /* Step 5: Send confirmation */ + ..emit { + action: "email", + to: order.customer_email, + subject: "Order Confirmed", + template: "order_confirmation", + data: order + }; + + {order_id: order.id, status: "processed"}; +``` + +## Error Handling in Integration + +### Graceful Degradation +```plaintext +/* Handle integration failures */ +safe_api_call : api_request -> + ..emit api_request; + + /* Set timeout for response */ + timeout_result : wait_for_response 5000; + when timeout_result.timeout is + true then + ..emit "api_timeout" api_request; + {error: "API timeout", fallback: true} + _ then timeout_result.response; +``` + +### Retry Logic +```plaintext +/* Retry failed operations */ +retry_operation : operation max_retries -> + attempt_operation : attempt -> + when attempt > max_retries then + ..emit "max_retries_exceeded" operation; + {error: "Max retries exceeded"} + _ then + result : operation; + when result.error is + true then + delay : power 2 attempt; /* Exponential backoff */ + ..emit "retry_attempt" {attempt: attempt, delay: delay}; + retry_operation operation max_retries + false then result; + + attempt_operation 1; +``` + +## Testing Integration + +### Mock External Services +```plaintext +/* Test integration without real services */ +test_payment_integration : -> + /* Mock order */ + test_order : { + id: "test_123", + total: 100, + customer_id: "cust_456" + }; + + /* Test payment integration */ + result : integrate_payment test_order; + + /* Verify emitted events */ + ..assert "Payment data emitted" result.amount = 100; + ..assert "Payment data emitted" result.currency = "USD"; + + ..out "Payment integration test passed"; +``` + +### Integration Test Patterns +```plaintext +/* Test complete integration flow */ +test_order_flow : -> + /* Test order */ + test_order : { + id: "test_123", + product_id: "prod_789", + quantity: 2, + customer_email: "test@example.com", + total: 50 + }; + + /* Process order */ + result : process_order test_order; + + /* Verify result */ + ..assert "Order processed successfully" result.status = "processed"; + ..assert "Order ID preserved" result.order_id = "test_123"; + + ..out "Order flow test passed"; +``` + +## Best Practices + +### Keep Integration Pure +```plaintext +/* Good: Pure function with explicit side effects */ +process_data : data -> + transformed : transform data; + ..emit "data_processed" transformed; + transformed; + +/* Avoid: Hidden side effects */ +bad_process : data -> + ..emit "processing_started"; /* Hidden side effect */ + transform data; +``` + +### Use Structured Events +```plaintext +/* Good: Structured event data */ +..emit { + type: "user_created", + timestamp: now(), + data: {id: 123, name: "Alice"}, + metadata: {source: "web_form", version: "1.0"} +}; + +/* Avoid: Unstructured events */ +..emit "user_created Alice 123"; /* Hard to parse */ +``` + +### Handle Errors Gracefully +```plaintext +/* Good: Explicit error handling */ +safe_integration : request -> + when request.valid is + false then + ..emit "integration_error" {request: request, error: "Invalid request"}; + null + _ then + result : call_external_service request; + when result.error is + true then + ..emit "service_error" result; + result.fallback_value + false then result.data; +``` + +## Next Steps + +Now that you understand integration patterns, explore: +- [Error Handling](13_Error_Handling.md) for robust error management +- [Advanced Combinators](14_Advanced_Combinators.md) for complex integration patterns +- [Best Practices](16_Best_Practices.md) for writing maintainable code \ No newline at end of file diff --git a/js/scripting-lang/tutorials/16_Best_Practices.md b/js/scripting-lang/tutorials/16_Best_Practices.md new file mode 100644 index 0000000..8a6b246 --- /dev/null +++ b/js/scripting-lang/tutorials/16_Best_Practices.md @@ -0,0 +1,236 @@ +# Operator Spacing Best Practices + +## Why Spacing Matters + +The language uses spacing to distinguish between different types of operators and make expressions unambiguous. Proper spacing follows functional language conventions and makes your code more readable. + +## Minus Operator Spacing + +### Unary Minus (Negative Numbers) + +Unary minus works without parentheses and requires no leading space: + +```plaintext +/* ✅ CORRECT - Unary minus without parentheses */ +-5; /* negate(5) */ +-3.14; /* negate(3.14) */ +-x; /* negate(x) */ +f -5; /* f(negate(5)) */ +map double -3; /* map(double, negate(3)) */ +``` + +### Binary Minus (Subtraction) + +Binary minus requires spaces on both sides: + +```plaintext +/* ✅ CORRECT - Binary minus with spaces */ +5 - 3; /* subtract(5, 3) */ +10 - 5; /* subtract(10, 5) */ +x - y; /* subtract(x, y) */ +3.14 - 1.5; /* subtract(3.14, 1.5) */ +``` + +### Legacy Syntax (Still Works) + +Legacy syntax continues to work for backward compatibility: + +```plaintext +/* ✅ CORRECT - Legacy syntax still works */ +(-5); /* negate(5) - explicit grouping */ +f (-5); /* f(negate(5)) - explicit grouping */ +5-3; /* subtract(5, 3) - legacy fallback */ +``` + +### Complex Expressions + +Complex expressions with mixed operators work correctly: + +```plaintext +/* ✅ CORRECT - Complex expressions */ +-5 + 3; /* add(negate(5), 3) */ +-5 - 3; /* subtract(negate(5), 3) */ +-5 * 3; /* multiply(negate(5), 3) */ +-5 + 3 - 2; /* subtract(add(negate(5), 3), 2) */ +``` + +## General Operator Spacing + +### Binary Operators + +All binary operators should have spaces around them: + +```plaintext +/* ✅ CORRECT - Binary operators with spaces */ +5 + 3; /* add(5, 3) */ +5 * 3; /* multiply(5, 3) */ +5 / 3; /* divide(5, 3) */ +5 % 3; /* modulo(5, 3) */ +5 ^ 3; /* power(5, 3) */ +``` + +### Comparison Operators + +Comparison operators require spaces: + +```plaintext +/* ✅ CORRECT - Comparison operators with spaces */ +5 = 3; /* equals(5, 3) */ +5 != 3; /* notEquals(5, 3) */ +5 < 3; /* lessThan(5, 3) */ +5 > 3; /* greaterThan(5, 3) */ +5 <= 3; /* lessEqual(5, 3) */ +5 >= 3; /* greaterEqual(5, 3) */ +``` + +### Logical Operators + +Logical operators require spaces: + +```plaintext +/* ✅ CORRECT - Logical operators with spaces */ +true and false; /* logicalAnd(true, false) */ +true or false; /* logicalOr(true, false) */ +true xor false; /* logicalXor(true, false) */ +``` + +### Unary Operators + +Unary operators (except minus) don't require special spacing: + +```plaintext +/* ✅ CORRECT - Unary operators */ +not true; /* logicalNot(true) */ +not false; /* logicalNot(false) */ +``` + +## When to Use Parentheses + +### Explicit Grouping + +Use parentheses when you need explicit control over precedence: + +```plaintext +/* ✅ CORRECT - Explicit grouping */ +(-5) + 3; /* add(negate(5), 3) - explicit grouping */ +f (-5); /* f(negate(5)) - explicit grouping */ +(5 + 3) * 2; /* multiply(add(5, 3), 2) - explicit grouping */ +``` + +### Complex Expressions + +Use parentheses to make complex expressions more readable: + +```plaintext +/* ✅ CORRECT - Complex expressions with parentheses */ +(-5 + 3) * 2; /* multiply(add(negate(5), 3), 2) */ +(-5) * (3 + 2); /* multiply(negate(5), add(3, 2)) */ +``` + +## Common Patterns + +### Function Calls with Negative Numbers + +```plaintext +/* ✅ CORRECT - Function calls with negative numbers */ +double -5; /* double(negate(5)) */ +map double -3; /* map(double, negate(3)) */ +filter is_negative {-5, 0, 5}; /* filter(is_negative, {-5, 0, 5}) */ +``` + +### Comparisons with Negative Numbers + +```plaintext +/* ✅ CORRECT - Comparisons with negative numbers */ +-5 >= 0; /* greaterEqual(negate(5), 0) */ +-5 < 0; /* lessThan(negate(5), 0) */ +is_negative -5; /* is_negative(negate(5)) */ +``` + +### Arithmetic with Mixed Operators + +```plaintext +/* ✅ CORRECT - Mixed arithmetic */ +-5 + 3 - 2; /* subtract(add(negate(5), 3), 2) */ +5 * -3 + 2; /* add(multiply(5, negate(3)), 2) */ +(-5) * 3 + 2; /* add(multiply(negate(5), 3), 2) */ +``` + +## Best Practices Summary + +### Do's + +- ✅ **Use spaces around binary operators**: `5 - 3`, `5 + 3`, `5 * 3` +- ✅ **Unary minus works without parentheses**: `-5`, `f -5` +- ✅ **Use parentheses for explicit grouping**: `(-5)`, `(5 + 3) * 2` +- ✅ **Use spaces around comparison operators**: `5 = 3`, `5 < 3` +- ✅ **Use spaces around logical operators**: `true and false` + +### Don'ts + +- ❌ **Don't omit spaces around binary operators**: `5-3`, `5+3` (legacy fallback) +- ❌ **Don't add spaces after unary minus**: `- 5` (legacy fallback) +- ❌ **Don't use inconsistent spacing**: `5- 3`, `5 -3` (legacy fallback) + +### When in Doubt + +- **Use spaces around binary operators** - it's always correct and more readable +- **Unary minus works without parentheses** - `-5` is the preferred syntax +- **Use parentheses for explicit grouping** - when you need to control precedence +- **Follow functional language conventions** - spaces around operators are standard + +## Examples in Context + +### Data Processing + +```plaintext +/* Process data with proper spacing */ +data : {-5, 0, 5, 10, 15}; +is_positive : x -> x > 0; +double : x -> x * 2; +sum : x -> reduce add 0 x; + +/* Pipeline with proper spacing */ +result : sum map double filter is_positive data; +/* Reads: sum (map double (filter is_positive data)) */ +/* Result: 60 (positive: {5,10,15}, doubled: {10,20,30}, sum: 60) */ +``` + +### Validation Logic + +```plaintext +/* Validation with proper spacing */ +validate_age : age -> (age >= 0) and (age <= 120); +validate_salary : salary -> (salary >= 0) and (salary <= 1000000); + +/* Test validation */ +test1 : validate_age -5; /* false */ +test2 : validate_age 25; /* true */ +test3 : validate_salary 50000; /* true */ +``` + +### Mathematical Expressions + +```plaintext +/* Mathematical expressions with proper spacing */ +calculate_discount : price discount_rate -> + price - (price * discount_rate); + +apply_tax : price tax_rate -> + price + (price * tax_rate); + +/* Use the functions */ +final_price : apply_tax (calculate_discount 100 0.1) 0.08; +/* Result: 97.2 (discount: 90, tax: 7.2) */ +``` + +## Key Takeaways + +1. **Spacing distinguishes operators** - unary vs binary minus +2. **Unary minus works without parentheses** - `-5` is preferred +3. **Binary operators need spaces** - `5 - 3`, `5 + 3`, `5 * 3` +4. **Legacy syntax still works** - but spaces are recommended +5. **Parentheses for explicit grouping** - when you need control +6. **Follow functional conventions** - spaces around operators are standard + +**Remember**: Proper spacing makes your code more readable and follows functional language conventions! 🚀 \ No newline at end of file diff --git a/js/scripting-lang/tutorials/README.md b/js/scripting-lang/tutorials/README.md new file mode 100644 index 0000000..30c03dd --- /dev/null +++ b/js/scripting-lang/tutorials/README.md @@ -0,0 +1,128 @@ +# Baba Yaga Tutorials + +Welcome to the Baba Yaga tutorials! These tutorials will guide you through learning this functional programming language step by step. + +## Getting Started + +Start with the **Introduction** tutorial to learn the basics, then follow the numbered sequence for a complete learning path. + +## Tutorial Sequence + +### 🚀 **Beginner Level** + +1. **[00_Introduction.md](00_Introduction.md)** - Basic concepts, functions, and pattern matching +2. **[01_Function_Calls.md](01_Function_Calls.md)** - Function calls without parentheses (juxtaposition) +3. **[02_Function_Composition.md](02_Function_Composition.md)** - Function composition with `via`, `compose`, and `pipe` +4. **[03_Table_Operations.md](03_Table_Operations.md)** - Working with tables and element-wise operations +5. **[04_Currying.md](04_Currying.md)** - Partial function application by default +6. **[05_Pattern_Matching.md](05_Pattern_Matching.md)** - Pattern matching with `when` expressions +7. **[06_Immutable_Tables.md](06_Immutable_Tables.md)** - Immutable table operations and functional programming +8. **[07_Function_References.md](07_Function_References.md)** - Function references with `@` symbol + +### 🔧 **Intermediate Level** + +9. **[08_Combinators.md](08_Combinators.md)** - Understanding the combinator-based architecture +10. **[09_Expression_Based.md](09_Expression_Based.md)** - Expression-based programming without explicit returns +11. **[10_Tables_Deep_Dive.md](10_Tables_Deep_Dive.md)** - Advanced table usage and data structures +12. **[11_Standard_Library.md](11_Standard_Library.md)** - Overview of available functions and combinators +13. **[12_IO_Operations.md](12_IO_Operations.md)** - Input/output operations and assertions +14. **[13_Error_Handling.md](13_Error_Handling.md)** - Error handling patterns and validation + +### 🎯 **Advanced Level** + +15. **[14_Advanced_Combinators.md](14_Advanced_Combinators.md)** - Advanced combinator patterns and optimization +16. **[15_Integration_Patterns.md](15_Integration_Patterns.md)** - External system integration and APIs +17. **[16_Best_Practices.md](16_Best_Practices.md)** - Best practices and coding guidelines + +## Key Concepts Covered + +- **Functional Programming**: Pure functions, immutability, composition +- **Pattern Matching**: `when` expressions for conditional logic +- **Tables**: Immutable data structures with functional operations +- **Combinators**: Higher-order functions for data transformation +- **IO Operations**: Input/output, assertions, and event handling +- **Error Handling**: Functional error patterns and validation +- **Integration**: External system integration patterns +- **Best Practices**: Operator spacing, syntax guidelines, and code organization + +## REPL Integration Documentation + +For comprehensive integration patterns and harness architecture documentation, see the **[REPL Documentation](../docs/repl/scripting-lang/0.0.1/repl.js.html)** which is generated directly from the REPL source code and contains extensive JSDoc comments about: + +- Architecture overview and TEA-inspired patterns +- Harness integration examples +- Adapter pattern implementation +- State management and versioning +- Error handling and recovery +- Command routing strategies +- Complete integration examples + +## Quick Reference + +### Essential Syntax + +```plaintext +/* Function definition */ +function_name : param1 param2 -> expression; + +/* Function application */ +function_name arg1 arg2; + +/* Pattern matching */ +when value is + pattern1 then result1 + pattern2 then result2 + _ then default_result; + +/* Table literals */ +{key1: value1, key2: value2}; + +/* Function references */ +map @function_name collection; + +/* IO operations */ +..out "Hello, World!"; +..assert "test" 5 = 5; +..emit "event" data; +..listen "event" handler; +``` + +### Best Practices + +- ✅ **Use spaces around binary operators**: `5 - 3`, `5 + 3`, `5 * 3` +- ✅ **Unary minus works without parentheses**: `-5`, `f -5` +- ✅ **Use parentheses for explicit grouping**: `(-5)`, `(5 + 3) * 2` +- ✅ **Follow functional conventions**: Immutable data, pure functions +- ✅ **Keep functions focused**: Single responsibility principle +- ✅ **Use descriptive names**: Clear intent and purpose +- ✅ **Handle errors explicitly**: Pattern matching over exceptions + +## Running Examples + +To run examples from these tutorials: + +1. Create a `.txt` or `.baba` file with the example code +2. Run: `node lang.js your_file.txt` + +Example: +```bash +# Create test.txt with tutorial code +echo "result : 5 - 3;" > test.txt + +# Run the example +node lang.js test.txt +``` + +## File Extensions + +Baba Yaga files should use either the `.txt` file extension, or the `.baba` extension. + +## Need Help? + +- Check the [main README](../README.md) for language overview +- Review [Best Practices](16_Best_Practices.md) for syntax guidelines +- Run the test suite: `./run_tests.sh` to see working examples +- Explore [Advanced Combinators](14_Advanced_Combinators.md) for complex patterns +- Check [Integration Patterns](15_Integration_Patterns.md) for external system integration + +Happy learning! 🚀 \ No newline at end of file |