@mojir/lits 2.1.36 → 2.1.38

package/README.md

@@ -1,12 +1,14 @@
 # Lits
 
-Lits is a lexically scoped pure functional language with algebraic notation. It combines the power of functional programming with an intuitive, readable syntax that makes complex operations simple and expressive.
+A functional language with algebraic notation and JavaScript interoperability.
 
 Try it in the [Lits Playground](https://mojir.github.io/lits/).
 
 ## Features
 
 - **Pure functional language** - Variables cannot be changed, ensuring predictable behavior and easier reasoning about code
+- **Expression-based syntax** - Everything in Lits is an expression that returns a value; there are no statements, making the language highly composable and consistent
+- **Fully serializable** - Every value returned from Lits evaluation, including functions and regexps, is serializable as JSON
 - **JavaScript interoperability** - JavaScript values and functions can easily be exposed in Lits
 - **First-class functions** - Functions are treated as values that can be passed to other functions
 - **Algebraic notation** - All operators can be used as functions, and functions that take two parameters can be used as operators
@@ -56,7 +58,7 @@ The REPL provides an interactive environment where you can experiment with Lits
 Here's a simple example to get you started:
 
 ```lits
-// Defining a function
+// Defining a function - note that everything returns a value
 let square = x -> x * x;
 
 // Using the function
@@ -68,10 +70,33 @@ let squares = [1, 2, 3, 4, 5] map square;
 // => [1, 4, 9, 16, 25]
 
 // Using operator as a function
-let sum = +(1, 2, 3, 4, 5);
++(1, 2, 3, 4, 5);
 // => 15
 ```
 
+## Expression-Based Language
+
+In Lits, everything is an expression that evaluates to a value. This means:
+
+```lits
+// Conditional expressions always return a value
+let a = 10;
+let result = if a > 0 then "positive" else "non-positive" end;
+
+// Function definitions are expressions that return the function
+let add = (a, b) -> a + b;
+
+// Even variable bindings return the bound value
+let x = let y = 5;  // x becomes 5
+
+// Blocks are expressions - they return the last expression's value
+let value = {
+  let temp = 42;
+  temp * 2 + 1 // => 85
+};
+```
+This expression-based design makes Lits highly composable and eliminates the statement/expression distinction found in many other languages.
+
 ## Basic Syntax
 
 ### Data Types
@@ -87,24 +112,231 @@ let sum = +(1, 2, 3, 4, 5);
 
 // Strings
 "Hello, world!";
+"String with \"escapes\"";
 
 // Booleans
 true;
 false;
 
-// Null
+// Functions
+(x -> x * 2);                  // Anonymous function
+let add = (a, b) -> a + b;     // Named function
+
+// Regular expressions
+#"[a-z]+";
+#"\d{3}-\d{3}-\d{4}";
+
+// null
 null;
+```
 
-// Arrays
-[1, 2, 3, 4];
+#### Arrays (General Collections)
+
+Arrays are the primary collection type in Lits, supporting mixed data types:
+
+```lits
+// Basic arrays
+[1, 2, 3, 4, 5];
+["apple", "banana", "orange"];
+[true, 42, "mixed types"];
+
+// Nested arrays
+[[1, 2], [3, 4], [5, 6]];
+[{name: "Alice"}, {name: "Bob"}];
+
+// Array operations
+let numbers = [1, 2, 3, 4, 5];
+numbers[0];                    // => 1 (indexing)
+count(numbers);                // => 5 (length)
+first(numbers);                // => 1
+last(numbers);                 // => 5
+rest(numbers);                 // => [2, 3, 4, 5]
+
+// Functional array operations
+numbers map -> $ * 2;      // => [2, 4, 6, 8, 10]
+numbers filter odd?;           // => [1, 3, 5]
+```
+
+#### Vectors (Number Arrays)
+
+A vector is simply a non-empty array containing only numbers. The `vec:` namespace provides mathematical operations specifically for these number arrays:
+
+```lits
+// Vectors are just number arrays
+[1, 2, 3, 4, 5];              // This is a vector
+[3.14, 2.71, 1.41];           // This is also a vector
+[1, "hello", 3];               // This is NOT a vector (mixed types)
+[];                            // This is NOT a vector (empty)
+
+// Vector creation functions
+vec:zeros(5);                  // => [0, 0, 0, 0, 0]
+vec:ones(3);                   // => [1, 1, 1]
+vec:linspace(0, 10, 5);        // => [0, 2.5, 5, 7.5, 10]
+vec:fill(4, 3.14);             // => [3.14, 3.14, 3.14, 3.14]
+vec:generate(5, -> $ * 2);     // => [0, 2, 4, 6, 8]
+
+// Vector mathematical operations (use lin: namespace for vector math)
+lin:dot([1, 2, 3], [4, 5, 6]);      // => 32 (dot product)
+lin:euclidean-norm([3, 4]);         // => 5.0 (Euclidean norm/magnitude)
+lin:normalize([3, 4]);              // => [0.6, 0.8] (unit vector)
+lin:euclidean-distance([0, 0], [3, 4]); // => 5.0 (Euclidean distance)
+
+// Vector statistical operations
+vec:sum([1, 2, 3, 4]);         // => 10
+vec:mean([1, 2, 3, 4]);        // => 2.5
+vec:median([1, 2, 3, 4, 5]);   // => 3
+vec:stdev([1, 2, 3, 4]);       // => 1.29... (standard deviation)
+vec:variance([1, 2, 3, 4]);    // => 1.67... (variance)
+
+// Vector analysis
+vec:min([3, 1, 4, 1, 5]);      // => 1
+vec:max([3, 1, 4, 1, 5]);      // => 5
+vec:min-index([3, 1, 4]);      // => 1 (index of minimum)
+vec:max-index([3, 1, 4]);      // => 2 (index of maximum)
+
+// Cumulative operations
+vec:cumsum([1, 2, 3, 4]);      // => [1, 3, 6, 10]
+vec:cumprod([1, 2, 3, 4]);     // => [1, 2, 6, 24]
+
+// Vector predicates
+vec:increasing?([1, 1, 2, 3, 4]);          // => true
+vec:strictly-increasing?([1, 1, 2, 3, 4]); // => true
+
+// Structural equality works with all vectors
+[1, 2, 3] == [1, 2, 3];       // => true
+[1, 2] == [1, 2, 3];          // => false
+```
+
+#### Matrices (2D Vectors)
+
+A matrix is a 2D array where each row is a vector (non-empty array of numbers) and all rows have the same length. The `mat:` namespace provides linear algebra operations for these structures:
+
+```lits
+// Matrices are 2D number arrays with consistent row lengths
+[[1, 2], [3, 4]];              // This is a 2x2 matrix
+[[1, 2, 3], [4, 5, 6]];        // This is a 2x3 matrix
+[[1, 2], [3, 4, 5]];           // This is NOT a matrix (inconsistent row length)
+[[1, "hello"], [3, 4]];        // This is NOT a matrix (contains non-numbers)
+[[]];                          // This is NOT a matrix (contains empty row)
+
+// Basic matrix operations
+let matrixA = [[1, 2], [3, 4]];
+let matrixB = [[5, 6], [7, 8]];
+
+mat:mul(matrixA, matrixB);     // => [[19, 22], [43, 50]] (multiplication)
+mat:det(matrixA);              // => -2 (determinant)
+mat:inv(matrixA);              // => [[-2, 1], [1.5, -0.5]] (inverse)
+mat:trace(matrixA);            // => 5 (trace - sum of diagonal)
+
+// Matrix construction
+mat:hilbert(3);                // => 3x3 Hilbert matrix
+mat:vandermonde([1, 2, 3]);    // => Vandermonde matrix from vector
+mat:band(4, 1, 1);             // => 4x4 band matrix
+
+// Matrix properties and predicates
+mat:symmetric?([[1, 2], [2, 1]]);    // => true
+mat:invertible?([[1, 2], [3, 4]]);   // => true
+mat:square?([[1, 2], [3, 4]]);       // => true
+mat:diagonal?([[1, 0], [0, 2]]);     // => true
+mat:identity?([[1, 0], [0, 1]]);     // => true
+
+// Advanced matrix operations
+mat:adj(matrixA);              // => [[4, -2], [-3, 1]] (adjugate)
+mat:cofactor(matrixA);         // => cofactor matrix
+mat:minor(matrixA, 0, 1);      // => minor by removing row 0, col 1
+mat:frobenius-norm(matrixA);   // => Frobenius norm
+mat:1-norm(matrixA);           // => 1-norm (max column sum)
+mat:inf-norm(matrixA);         // => infinity norm (max row sum)
+mat:max-norm(matrixA);         // => max norm (largest absolute element)
+
+// Matrix analysis
+mat:rank(matrixA);             // => matrix rank
+```
+
+#### Objects (Maps)
 
-// Objects
+Objects store key-value pairs:
+
+```lits
+// Object creation
 { name: "John", age: 30 };
+{ "key with spaces": "value", count: 42 };
 
-// Regular expressions
-#"pattern";
+// Nested objects
+{
+  person: { name: "Alice", age: 25 },
+  scores: [95, 87, 92],
+  active: true
+};
+
+// Object operations
+let user = { name: "Bob", age: 30, city: "NYC" };
+get(user, "name");             // => "Bob"
+assoc(user, "age", 31);        // => new object with age updated
+dissoc(user, "city");          // => new object without city
+keys(user);                    // => ["name", "age", "city"]
+vals(user);                  // => ["Bob", 30, "NYC"]
+```
+
+#### Type Predicates
+
+Lits provides predicate functions to check data types at runtime:
+
+```lits
+// Basic type predicates
+number?(42);                   // => true
+string?("hello");              // => true
+boolean?(true);                // => true
+function?(x -> x * 2);         // => true
+regexp?(#"[a-z]+");            // => true
+array?([1, 2, 3]);             // => true
+object?({name: "Alice"});      // => true
+null?(null);                   // => true
+
+// Specialized array predicates
+vector?([1, 2, 3]);            // => true (non-empty number array)
+vector?([1, "hello", 3]);      // => false (mixed types)
+vector?([]);                   // => false (empty)
+
+matrix?([[1, 2], [3, 4]]);     // => true (2D number array, consistent rows)
+matrix?([[1, 2], [3]]);        // => false (inconsistent row lengths)
+matrix?([[]]);                 // => false (contains empty row)
+
+// Collection predicates
+seq?([1, 2, 3]);               // => true (sequences: strings and arrays)
+seq?("hello");                 // => true
+seq?({a: 1});                  // => false
+
+coll?([1, 2, 3]);              // => true (collections: strings, arrays, objects)
+coll?("hello");                // => true
+coll?({a: 1});                 // => true
+coll?(42);                     // => false
 ```
 
+#### Type Hierarchy
+
+The type predicates follow a logical hierarchy:
+
+```lits
+// If something is a matrix, it's also a vector and an array
+let mat = [[1, 2], [3, 4]];
+matrix?(mat);                  // => true
+vector?(mat);                  // => true (matrix is a special vector)
+array?(mat);                   // => true (vector is a special array)
+
+// If something is a vector, it's also an array
+let vec = [1, 2, 3];
+vector?(vec);                  // => true
+array?(vec);                   // => true
+
+// But not all arrays are vectors
+let arr = [1, "hello", 3];
+array?(arr);                   // => true
+vector?(arr);                  // => false (contains non-numbers)
+```
+
+Each data type is immutable by design - operations return new values rather than modifying existing ones, ensuring predictable behavior and easier reasoning about code.
+
 ### Mathematical Constants
 
 Lits provides predefined mathematical constants:
@@ -192,7 +424,7 @@ let {
   settings = { theme: "light" },
   scores as userScores = [],
   ...others
-} = { name: "Sam", profile: { contact: {} }};
+} = { name: "Sam", profile: { contact: {} } };
 // userName => "Sam", age => 0, userEmail => "none", etc.
 ```
 
@@ -214,11 +446,15 @@ let { name, scores: [one, two] } = { name: "Uma", scores: [85, 92] };
 // Array destructuring
 let [, , a, b] = [1, 2, 3, 4];
 // a => 3, b => 4
+```
 
+```lits
 // Array destructuring with defaults
 let [one, two = 2] = [1];
 // one => 1, two => 2
+```
 
+```lits
 // Skipping elements
 let [x, , z] = [1, 2, 3];
 // x => 1, z => 3
@@ -230,11 +466,15 @@ let [x, , z] = [1, 2, 3];
 // Array rest pattern
 let [head, ...tail] = [1, 2, 3, 4];
 // head => 1, tail => [2, 3, 4]
+```
 
+```lits
 // Object rest pattern  
 let { name, ...otherProps } = { name: "John", age: 30, city: "NYC" };
 // name => "John", otherProps => { age: 30, city: "NYC" }
+```
 
+```lits
 // Empty rest patterns
 let [only, ...empty] = [1];
 // only => 1, empty => []
@@ -247,18 +487,24 @@ let [only, ...empty] = [1];
 let greet = ({ name }) -> "Hello, " ++ name;
 greet({ name: "Pat" });
 // => "Hello, Pat"
+```
 
+```lits
 // With defaults in parameters
 let greet2 = ({ name = "friend" }) -> "Hello, " ++ name;
 greet2({});
 // => "Hello, friend"
+```
 
+```lits
 // Nested parameter destructuring
 let processUser = ({ profile: { name, age }}) -> 
   name ++ " is " ++ str(age);
 processUser({ profile: { name: "Quinn", age: 29 }});
 // => "Quinn is 29"
+```
 
+```lits
 // Array parameter destructuring
 let processCoords = ([x, y]) -> x + y;
 processCoords([3, 4]);
@@ -299,56 +545,59 @@ let factorial = n ->
 #### If/Unless
 
 ```lits
-let x = !:random-int(0, 20); // Random number between 0 and 19
+let x = 15; // Fixed value for compilation
 
 if x > 10 then
   "large"
 else
   "small"
 end;
-// => "large" (if x > 10) or "small" (if x <= 10)
+// => "large"
 
 // If without else returns null
 if false then "never" end;
 // => null
 
 // Unless (inverted if)
-let y = !:random-int(0, 20);
+let y = 8;
 unless y > 10 then
   "small"
 else
   "large"
 end;
-// => "small" (if y <= 10) or "large" (if y > 10)
+// => "small"
 ```
 
 #### Cond
 
 ```lits
-let x = !:random-int(0, 20); // Random number between 0 and 19
+let x = 12;
 
 // Multi-branch conditional
 cond
   case x < 5 then "small"
   case x < 10 then "medium"
   case x < 15 then "large"
-end ?? "extra large";
-// Tests conditions sequentially, returns first truthy match
+  case true then "extra large" // default case
+end;
+// => "large"
 
 // Cond with complex conditions
-let urgent = !:random-int(0, 2) == 1;
-let important = !:random-int(0, 2) == 1;
+let urgent = true;
+let important = false;
 let priority = cond
   case urgent && important then "critical"
   case urgent then "high"
   case important then "medium"
-end ?? "low";
+  case true then "low"
+end;
+// => "high"
 ```
 
 #### Switch
 
 ```lits
-let x = !:random-int(0, 3); // Random number between 0 and 2
+let x = 1;
 
 // Switch on value
 switch x
@@ -356,19 +605,20 @@ switch x
   case 1 then "one"
   case 2 then "two"
 end;
-// => "zero" (if x = 0), "one" (if x = 1), etc., or null if no match
+// => "one"
 
 // Switch with multiple cases
 let userInput = "help";
-let exit = -> "exiting";
-let showHelp = -> "showing help";
-let saveData = -> "saving data";
+let exit = () -> "exiting";
+let showHelp = () -> "showing help";
+let saveData = () -> "saving data";
 
 switch userInput
   case "quit" then exit()
   case "help" then showHelp()
   case "save" then saveData()
 end;
+// => "showing help"
 ```
 
 ### Loops and Iteration
@@ -495,7 +745,7 @@ let parseData = () -> { value: 42 };
 let process = (val) -> val * 2;
 try
   let { value } = parseData();
-  process(value);
+  process(value)
 catch
   "Using default value"
 end;
@@ -553,10 +803,25 @@ let processData = (data) -> data map -> $ * 2;
   let processed = processData(data);
   write!("Process completed");
   processed
-};
+}
 ```
 
-### Array and Object Spread
+### Array and Object Construction
+
+#### Array Construction
+
+```lits
+// Array literal
+[1, 2, 3, 4];
+
+// Array function
+array(1, 2, 3, 4);
+
+// With spread
+let small-set = [3, 4, 5];
+[1, 2, ...small-set, 6];
+// => [1, 2, 3, 4, 5, 6]
+```
 
 #### Array Spread
 
@@ -572,6 +837,39 @@ let stop = [5, 6];
 let result = [...start, ...middle, ...stop];
 ```
 
+#### Object Construction
+
+```lits
+// Object literal with static keys
+{ name: "John", age: 30 };
+
+// Object literal with dynamic keys using bracket notation
+let keyName = "dynamic";
+{ [keyName]: "value", ["computed" ++ "Key"]: 42 };
+// => { dynamic: "value", computedKey: 42 }
+
+// Object function
+object("name", "John", "age", 30);
+
+// With spread
+let defaults = { type: "Person", active: true };
+{
+  ...defaults,
+  name: "John",
+  age: 30
+};
+// => { type: "Person", active: true, name: "John", age: 30 }
+
+// Combining static and dynamic keys
+let propName = "score";
+{
+  id: 123,
+  [propName]: 95,
+  ["level" ++ "Number"]: 5
+};
+// => { id: 123, score: 95, levelNumber: 5 }
+```
+
 #### Object Spread
 
 ```lits
@@ -623,22 +921,21 @@ true || "never reached";  // => true
 
 ```lits
 // Null coalescing operator
-null ?? "default";          // => "default"
-undefined-var ?? "default"; // => "default"
-0 ?? "default";             // => 0 (only null/undefined are coalesced)
-false ?? "default";         // => false
-"" ?? "default";            // => ""
+null ?? "default";     // => "default"
+0 ?? "default";        // => 0 (only null/undefined are coalesced)
+false ?? "default";    // => false
+"" ?? "default";       // => ""
 ```
 
 ### Ternary Operator
 
 ```lits
 // Conditional expression
-let age = !:random-int(10, 60);
+let age = 25;
 let result = age >= 18 ? "adult" : "minor";
 
 // Nested ternary
-let score = !:random-int(0, 100);
+let score = 85;
 let category = score >= 90 ? "A" : score >= 80 ? "B" : "C";
 
 // With complex expressions
@@ -647,36 +944,396 @@ let hasPermission = () -> true;
 let status = isLoggedIn() && hasPermission() ? "authorized" : "unauthorized";
 ```
 
-## Operators and Precedence
+## Variable Names
+
+Lits is generous with variable naming conventions, allowing a wide range of characters that would be invalid in many other programming languages.
+
+### Basic Rules
+
+Variable names in Lits can contain almost any character except for a small set of reserved symbols. The only restrictions are:
+
+**Illegal characters anywhere in a variable name:**
+- Parentheses: `(` `)`
+- Brackets: `[` `]`
+- Braces: `{` `}`
+- Quotes: `'` `"` `` ` ``
+- Punctuation: `,` `.` `;`
+- Whitespace: spaces, newlines, tabs
+
+**Additional restrictions for the first character:**
+- Cannot start with digits `0-9`
+
+### Unicode and Emoji Support
+
+Beyond these minimal restrictions, Lits supports Unicode characters, including emojis, in variable names:
+
+```lits
+// Unicode characters are welcome
+let résultat = 42;
+let naïve = "simple approach";
+let coöperation = "working together";
+
+// Emojis work too!
+let 😅 = "grinning face with sweat";
+let 🚀 = "rocket ship";
+let result = 😅 ++ " " ++ 🚀;
+// => "grinning face with sweat rocket ship"
+```
+
+### Quoted Variable Names
+
+For cases where you need to use the normally illegal characters in variable names, Lits supports quoted variable names using single quotes:
+
+```lits
+// Variables with spaces and special characters
+let 'A strange variable' = 42;
+let 'user.name' = "John Doe";
+let 'data[0]' = "first element";
+let 'function()' = "callable";
+
+// Access them the same way
+'A strange variable' + 8;
+// => 50
+```
+
+### Practical Examples
+
+Here are some examples showcasing the flexibility of Lits variable naming:
+
+```lits
+// Mathematical notation with Greek letters (avoiding reserved symbols)
+let α = 0.5;
+let β = 1.2;
+let γ = 2.0;
+let Δ = β - α;
+
+// Descriptive names with special characters
+let user-name = "alice";
+let is-valid? = true;
+let counter! = 0;
+
+// Mixed styles
+let dataSet₁ = [1, 2, 3];
+let dataSet₂ = [4, 5, 6];
+let 🔧config = { debug: true };
+```
+
+### Important: Operator Spacing
 
-Lits follows a clear operator precedence hierarchy. Understanding precedence helps you write expressions that behave as expected:
+Due to Lits' flexible variable naming, **operators must be separated by whitespace**. This is crucial to understand:
 
-### Precedence Table (Highest to Lowest)
+```lits
+// This is a variable name, NOT addition!
+let x+1 = 42;
+let result1 = x+1;  // => 42
+
+// To perform addition, use spaces
+let x = 5;
+let result2 = x + 1;  // => 6
+
+// More examples of what looks like operations but are actually variable names
+let a-b = "subtraction variable";
+let c*d = "multiplication variable"; 
+let e/f = "division variable";
+let g<h = "comparison variable";
+
+// To use these as actual operations, add spaces
+let a = 10;
+let b = 3;
+let a-sum = a + b;      // Addition
+let a-diff = a - b;     // Subtraction
+let a-prod = a * b;     // Multiplication
+let a-quot = a / b;     // Division
+let a-comp = a < b;     // Comparison
+```
+
+Without whitespace, Lits treats the entire sequence as a single variable identifier. This applies to all operators, including comparison operators, logical operators, and arithmetic operators.
+
+This flexibility allows for expressive and readable code while maintaining the functional programming paradigm that Lits embodies.
+## Operators and Functions
+
+### Algebraic Notation
+
+All functions that take two parameters can be used as operators:
+
+```lits
+// As a function
+max(5, 10);    // => 10
+
+// As an operator
+5 max 10;      // => 10
+```
+
+All operators can be used as functions:
+
+```lits
+// As an operator
+5 + 3;         // => 8
+
+// As a function
++(5, 3);       // => 8
+
+// Partial application with underscore placeholder
+let add5 = +(5, _);
+add5(3);       // => 8
+
+// Multiple placeholders
+let subtractTwoValues = -(100, _, _);
+subtractTwoValues(4, 3);  // => 93
+
+// Single placeholder in different positions
+let subtract = -(_, 2);
+subtract(10);  // => 8
+
+let divide = /(10, _);
+divide(2);     // => 5
+```
+
+### Data Types as Functions
+
+Lits allows arrays, objects, numbers, and strings to be used as functions. This creates elegant, flexible code where data structures become accessors.
+
+#### Arrays and Numbers as Index Accessors
+
+Arrays can be called with an index to get an element, and numbers can be called with collections to access that index:
+
+```lits
+let arr = [10, 20, 30, 40];
+
+// Array as function (accessing by index)
+arr(0);          // => 10
+arr(2);          // => 30
+
+// Number as function (accessing array at that index)
+2(arr);          // => 30 (same as arr(2))
+0(arr);          // => 10 (same as arr(0))
+```
 
-1. **Function calls** - `fn(args)`
-2. **Array/Object access** - `arr[index]`, `obj.property`
-3. **Unary operators** - `not`, `!`, `-` (negation)
-4. **Exponentiation** - `^` (right-associative)
-5. **Multiplication, Division, Modulo** - `*`, `/`, `%`
-6. **Addition, Subtraction** - `+`, `-`
-7. **String concatenation** - `++`
-8. **Comparison operators** - `<`, `>`, `<=`, `>=`
-9. **Equality operators** - `==`, `!=`, `identical?`
-10. **Logical AND** - `&&`
-11. **Logical OR** - `||`
-12. **Null coalescing** - `??`
-13. **Ternary conditional** - `condition ? true-value : false-value`
+#### Strings and Numbers for Character Access
 
-### Examples
+Similar to arrays, strings support indexed access in both directions:
 
 ```lits
-// Comparison and logical operators
-5 > 3 && 2 < 4;          // => true
-5 > 3 || 2 > 4;          // => true
+let name = "Albert";
 
-// Ternary has low precedence
-let x = !:random-int(0, 10);
-x + 3 > 4 ? 1 : 0;       // => (x + 3) > 4 ? 1 : 0
+// String as function (accessing character by index)
+name(0);         // => "A"
+name(2);         // => "b"
+
+// Number as function (accessing string at that index)  
+2(name);         // => "b" (same as name(2))
+4(name);         // => "r" (same as name(4))
+```
+
+#### Objects and Strings as Property Accessors
+
+Objects can be called with property names, and strings can be called with objects to access properties:
+
+```lits
+let person = { foo: 1, bar: 2, name: "John" };
+
+// Object as function (accessing property by key)
+person("foo");   // => 1
+person("name");  // => "John"
+
+// String as function (accessing object property)
+"foo"(person);   // => 1 (same as person("foo"))
+"bar"(person);   // => 2 (same as person("bar"))
+```
+
+#### Powerful Higher-Order Function Applications
+
+This feature makes higher-order functions incredibly flexible. You can pass data directly as accessor functions:
+
+```lits
+let data = [
+  { name: "Alice", score: 95 },
+  { name: "Bob", score: 87 },
+  { name: "Carol", score: 92 }
+];
+
+// Extract names using string as function
+data map "name";
+// => ["Alice", "Bob", "Carol"]
+
+// Extract scores using string as function  
+data map "score";
+// => [95, 87, 92]
+
+// Get second element of multiple arrays using number as function
+let arrays = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+arrays map 1;
+// => [2, 5, 8]
+
+// Access nested data
+let records = [
+  { values: [10, 20, 30] },
+  { values: [40, 50, 60] },
+  { values: [70, 80, 90] }
+];
+
+// Get first value from each record's values array
+records map "values" map 0;
+// => [10, 40, 70]
+```
+
+#### Practical Examples
+
+```lits
+// Matrix column extraction
+let matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+matrix map 1;        // => [2, 5, 8] (second column)
+
+// Object property extraction
+let users = [
+  { id: 1, active: true },
+  { id: 2, active: false },
+  { id: 3, active: true }
+];
+users map "active";  // => [true, false, true]
+
+// String character extraction
+let words = ["hello", "world", "test"];
+words map 0;         // => ["h", "w", "t"] (first characters)
+
+// Complex data navigation
+let sales = [
+  { quarter: "Q1", regions: { north: 100, south: 200 } },
+  { quarter: "Q2", regions: { north: 150, south: 180 } }
+];
+sales map "regions" map "north"; // => [100, 150]
+```
+
+This feature eliminates the need for verbose accessor functions and makes data transformation pipelines more concise and readable.
+
+### Parameter Order
+
+Lits favors subject-first parameter order for better operator chaining:
+
+```lits
+// Function style
+filter([1, 2, 3, 4], odd?);  // => [1, 3]
+
+// Operator style (more readable)
+[1, 2, 3, 4] filter odd?;    // => [1, 3]
+```
+
+### Pipe Operator
+
+The pipe operator `|>` passes the result of the left expression as the first argument to the right function:
+
+```lits
+// Without pipe operator
+reduce(map(filter([1, 2, 3, 4, 5, 6], odd?), -> $ * $), +, 0);
+
+// With pipe operator (much more readable)
+[1, 2, 3, 4, 5, 6]
+  |> filter(_, odd?)
+  |> map(_, -> $ * $)
+  |> reduce(_, +, 0);
+// => 35
+
+// Simple transformations
+"hello world"
+  |> upper-case
+  |> split(_, " ")
+  |> reverse
+  |> join(_, "-");
+// => "WORLD-HELLO"
+
+// Mathematical operations
+10
+  |> +(_, 5)
+  |> *(_, 2)
+  |> /(_, 3);
+// => 10 (10 + 5 = 15, 15 * 2 = 30, 30 / 3 = 10)
+
+// Data processing pipeline
+{ numbers: [1, 2, 3, 4, 5], multiplier: 3 }
+  |> get(_, "numbers")
+  |> filter(_, even?)
+  |> map(_, *(_, 3))
+  |> reduce(_, +, 0);
+// => 18 (even numbers [2, 4] -> [6, 12] -> sum = 18)
+```
+
+### Operator Precedence
+
+Lits follows a specific operator precedence order that determines how expressions are evaluated. Operators with higher precedence are evaluated first. When operators have the same precedence, they are evaluated left-to-right.
+
+Here's the complete precedence table, from highest to lowest:
+
+| Precedence | Operator(s) | Description | Example |
+|------------|-------------|-------------|---------|
+| 12 | `^` | Exponentiation | `2 ^ 3 ^ 2` → `2 ^ (3 ^ 2)` → `512` |
+| 11 | `*` `/` `%` | Multiplication, Division, Remainder | `6 + 4 * 2` → `6 + 8` → `14` |
+| 10 | `+` `-` | Addition, Subtraction | `10 - 3 + 2` → `7 + 2` → `9` |
+| 9 | `<<` `>>` `>>>` | Bit shift operations | `8 >> 1 + 1` → `8 >> 2` → `2` |
+| 8 | `++` | String concatenation | `"a" ++ "b" ++ "c"` → `"abc"` |
+| 7 | `<` `<=` `≤` `>` `>=` `≥` | Comparison operators | `3 + 2 > 4` → `5 > 4` → `true` |
+| 6 | `==` `!=` `≠` | Equality operators | `2 * 3 == 6` → `6 == 6` → `true` |
+| 5 | `&` `xor` `\|` | Bitwise operations | `4 \| 2 & 1` → `4 \| 0` → `4` |
+| 4 | `&&` `\|\|` `??` | Logical operations | `true && false \|\| true` → `false \|\| true` → `true` |
+| 3 | *function operators* | Binary functions used as operators | `5 max 3 + 2` → `5 max 5` → `5` |
+| 2 | `\|>` | Pipe operator | `[1,2] \|> map(_, inc) \|> sum` |
+| 1 | `?` `:` | Conditional (ternary) operator | `true ? 1 + 2 : 3` → `true ? 3 : 3` → `3` |
+
+#### Examples of Precedence in Action
+
+```lits
+// Exponentiation has highest precedence
+2 + 3 ^ 2;           // => 2 + 9 = 11 (not 5^2 = 25)
+
+// Multiplication before addition
+2 + 3 * 4;           // => 2 + 12 = 14 (not 5*4 = 20)
+
+// String concatenation before comparison
+"a" ++ "b" == "ab";  // => "ab" == "ab" = true
+
+// Comparison before logical AND
+3 > 2 && 1 < 2;      // => true && true = true
+
+// Pipe has very low precedence
+[1, 2, 3] |> map(_, inc) |> vec:sum;  // Evaluates left to right
+
+// Conditional has lowest precedence
+true ? 2 + 3 : 4 + 5;             // => true ? 5 : 9 = 5
+```
+
+#### Using Parentheses
+
+When in doubt, or to make your intent clear, use parentheses to override precedence:
+
+```lits
+// Without parentheses (follows precedence)
+2 + 3 * 4;          // => 14
+
+// With parentheses (explicit grouping)
+(2 + 3) * 4;        // => 20
+
+// Complex expression with explicit grouping
+let a = 2;
+let b = 3;
+let c = 4;
+let d = true;
+let e = false;
+let f = 10;
+let g = 5;
+((a + b) * c) > (d && e ? f : g)  // => (5 * 4) > (false ? 10 : 5) = 20 > 5 = true;
+```
+
+#### Associativity
+
+Most operators are left-associative, meaning they evaluate from left to right when they have the same precedence:
+
+```lits
+10 - 5 - 2;         // => (10 - 5) - 2 = 3 (not 10 - (5 - 2) = 7)
+"a" ++ "b" ++ "c";  // => ("a" ++ "b") ++ "c" = "abc"
+```
+
+**Exception**: Exponentiation (`^`) is right-associative:
+```lits
+2 ^ 3 ^ 2           // => 2 ^ (3 ^ 2) = 2 ^ 9 = 512 (not (2 ^ 3) ^ 2 = 64)
 ```
 
 ## Built-in Functions
@@ -695,13 +1352,34 @@ Lits comes with a comprehensive standard library of functions for:
 
 For a complete reference of all available functions with examples, visit the [Lits Playground](https://mojir.github.io/lits/) where you can explore the interactive documentation and try functions in real-time.
 
+## Serialization
+
+A unique feature of Lits is that every result from evaluation is fully serializable as JSON, including functions and regular expressions:
+
+```lits
+// Functions are serializable
+let myFunction = x -> x * 2;
+
+// Regular expressions are serializable  
+let myRegex = #"[a-z]+";
+
+// Complex data structures with functions are serializable
+let config = {
+  transform: x -> x * 3,
+  pattern: #"\d+",
+  data: [1, 2, 3]
+};
+
+// All of these can be serialized to JSON and later deserialized
+// back into working Lits values, preserving their functionality
+```
+
 ## Modules and Exports
 
 ```lits
 // Export variables and functions
 export let pi = 3.14159;
 export let square = x -> x * x;
-
 // Exported values become available to other modules
 ```
 
@@ -712,7 +1390,7 @@ export let square = x -> x * x;
 ```lits
 let factorial = n -> n <= 1 ? 1 : n * self(n - 1);
 
-factorial(5)  // => 120
+factorial(5);  // => 120
 ```
 
 ### Array Processing
@@ -741,7 +1419,7 @@ let text = "Hello, World! How are you today?";
 // Word count
 let wordCount = text
   |> split(_, #"\s+")
-  |> count(_);
+  |> count;
 // => 6
 
 // Uppercase words longer than 4 characters