@mojir/lits 2.1.33 → 2.1.35

package/README.md

@@ -1,6 +1,6 @@
 # Lits
 
-Lits is a lexically scoped pure functional language with algebraic notation. It combines the power of functional programming with an intuitive, readable syntax.
+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.
 
 Try it in the [Lits Playground](https://mojir.github.io/lits/).
 
@@ -13,18 +13,51 @@ Try it in the [Lits Playground](https://mojir.github.io/lits/).
 - **Comprehensive standard library** - Rich set of functions for collections, math, strings, and more
 - **Structural equality** - Objects are compared by value, not by reference
 - **Destructuring** - Extract values from complex data structures with ease
+- **Lexical scoping** - Variables are scoped to their defining context
 
 ## Installation
 
-*[Add installation instructions here]*
+### As a Library
+
+```bash
+npm install @mojir/lits
+```
+
+### CLI Tool
+
+Install globally to use the Lits command-line interface:
+
+```bash
+npm install --global @mojir/lits
+```
+
+#### CLI Usage
+
+```bash
+# Start an interactive REPL session
+$ lits
+
+# Evaluate Lits code directly
+$ lits -e "5 + 3"
+$ lits -e "[1, 2, 3, 4] filter odd? map inc"
+
+# Run a Lits file
+$ lits -f script.lits
+$ lits -f examples/factorial.lits
+
+# Get help
+$ lits --help
+```
+
+The REPL provides an interactive environment where you can experiment with Lits code, test functions, and explore the language features in real-time.
 
 ## Quick Start
 
 Here's a simple example to get you started:
 
-```
+```lits
 // Defining a function
-square = x -> x * x;
+let square = x -> x * x;
 
 // Using the function
 let result = square(5);
@@ -39,351 +72,697 @@ let sum = +([1, 2, 3, 4, 5]);
 // => 15
 ```
 
-## Syntax
+## Basic Syntax
 
-### Basic Data Types
+### Data Types
 
-```
+```lits
 // Numbers
-42       // integer
-3.14     // float
-0xFFFF   // hexadecimal
-0b1100   // binary
-0o77     // octal
--2.3e-2  // scientific notation
+42;          // integer
+3.14;        // float
+0xFFFF;      // hexadecimal
+0b1100;      // binary
+0o77;        // octal
+-2.3e-2;     // scientific notation
 
 // Strings
-"Hello, world!"
+"Hello, world!";
 
 // Booleans
-true
-false
+true;
+false;
 
 // Null
-null
+null;
 
 // Arrays
-[1, 2, 3, 4]
+[1, 2, 3, 4];
 
 // Objects
-{ name: "John", age: 30 }
-```
-
-### Builtin Number Symbols
-
-Lits provides a set of predefined mathematical constants that can be used directly in your code:
+{ name: "John", age: 30 };
 
+// Regular expressions
+#"pattern";
 ```
-// Mathematical constants
-PI    // => 3.141592653589793
-π     // => 3.141592653589793 (Unicode alternative)
--PI   // => -3.141592653589793
--π    // => -3.141592653589793
-
-E     // => 2.718281828459045 (Euler's number)
-ε     // => 2.718281828459045 (Unicode alternative)
--E    // => -2.718281828459045
--ε    // => -2.718281828459045
 
-PHI   // => 1.618033988749895 (Golden ratio)
-φ     // => 1.618033988749895 (Unicode alternative)
--PHI  // => -1.618033988749895
--φ    // => -1.618033988749895
+### Mathematical Constants
 
-// Infinity values
-POSITIVE_INFINITY // => Infinity
-∞     // => Infinity (Unicode alternative)
-NEGATIVE_INFINITY // => -Infinity
--∞    // => -Infinity (Unicode alternative)
+Lits provides predefined mathematical constants:
 
-// Integer limits
-MAX_SAFE_INTEGER  // => 9007199254740991
-MIN_SAFE_INTEGER  // => -9007199254740991
+```lits
+PI;    // => 3.141592653589793
+π;     // => 3.141592653589793 (Unicode alternative)
+E;     // => 2.718281828459045 (Euler's number)
+ε;     // => 2.718281828459045 (Unicode alternative)
+PHI;   // => 1.618033988749895 (Golden ratio)
+φ;     // => 1.618033988749895 (Unicode alternative)
 
-// Floating point limits
-MAX_VALUE  // => 1.7976931348623157e+308
-MIN_VALUE  // => 5e-324
+// Infinity values
+POSITIVE_INFINITY; // => Infinity
+∞;                 // => Infinity (Unicode alternative)
+NEGATIVE_INFINITY; // => -Infinity
 
-// Not a Number
-NaN  // => NaN
+// Integer and float limits
+MAX_SAFE_INTEGER;  // => 9007199254740991
+MIN_SAFE_INTEGER;  // => -9007199254740991
+MAX_VALUE;         // => 1.7976931348623157e+308
+MIN_VALUE;         // => 5e-324
 ```
 
-These constants can be used anywhere a number value is expected and help make mathematical code more readable and elegant.
+## Special Expressions
 
 ### Variable Binding
 
-```
-// Let expression
+#### Let
+
+```lits
+// Simple binding
 let x = 10;
 // => 10
 
 // Variables are immutable
-let x = 20; // Error: x is already defined
+// let x = 20; // Error: x is already defined
 
-// But can be shadowed in inner scopes
-let y = do
+// Shadowing in inner scopes
+let y = {
   let x = 20;
   x
-end;
+};
 // => 20, outer x is still 10
 ```
 
-### Functions
+#### Destructuring
+
+```lits
+// Object destructuring
+let { name, age } = { name: "John", age: 30 };
+// name => "John", age => 30
+```
+
+```lits
+// Array destructuring
+let [a, b] = [1, 2, 3, 4];
+// a => 1, b => 2
+```
+
+```lits
+// With default values
+let { name = "Unknown", age = 0 } = { name: "John" };
+// name => "John", age => 0
+```
 
+```lits
+// Rest patterns
+let [head, ...tail] = [1, 2, 3, 4];
+// head => 1, tail => [2, 3, 4]
 ```
-// Lambda functions
+
+```lits
+// Destructuring in function parameters
+let displayPerson = ({name, age}) ->
+  name ++ " is " ++ str(age) ++ " years old";
+
+displayPerson({ name: "John", age: 30 });
+// => "John is 30 years old"
+```
+
+### Functions
+
+#### Lambda Functions
+
+```lits
+// Multi-parameter lambda
 let add = (a, b) -> a + b;
 
-// Short form with positional arguments
-let add = -> $1 + $2;
+// Single parameter (parentheses optional)
+let square = x -> x * x;
+
+// No parameters
+let constant = () -> 42;
 
-// Single argument short form
-let cube = x -> x ** 3;
-let fourth = -> $ ** 4;
+// Positional arguments
+let add-v2 = -> $1 + $2;
+
+// Single positional argument
+let square-v2 = -> $ * $;
+
+// Self-reference for recursion
+let factorial = n ->
+  if n <= 1 then
+    1
+  else
+    n * self(n - 1)
+  end;
 ```
 
 ### Control Flow
 
-```
+#### If/Unless
+
+```lits
 // If expression
+let x = !:random-int(0, 20); // Random number between 0 and 19
+
 if x > 10 then
   "large"
 else
   "small"
+end;
 // => "large" (if x > 10) or "small" (if x <= 10)
 
-// Unless expression (reversed if)
+// If without else returns null
+if false then "never" end;
+// => null
+
+// Unless (inverted if)
 unless x > 10 then
   "small"
 else
   "large"
+end;
 // => "small" (if x <= 10) or "large" (if x > 10)
+```
+
+#### Cond
+
+```lits
+let x = !:random-int(0, 20); // Random number between 0 and 19
+
+// 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
+```
+
+#### Switch
+
+```lits
+let x = !:random-int(0, 3); // Random number between 0 and 2
 
-// Switch expression
+// Switch on value
 switch x
   case 0 then "zero"
   case 1 then "one"
   case 2 then "two"
-end;
-// => "zero" (if x = 0), "one" (if x = 1), "two" (if x = 2), or null (otherwise)
+end
+// => "zero" (if x = 0), "one" (if x = 1), etc., or null if no match
+```
 
-// Cond expression
-cond
-  case val < 5 then "S"
-  case val < 10 then "M"
-  case val < 15 then "L"
-end ?? "No match";
-// => "S" (if val < 5), "M" (if 5 <= val < 10), "L" (if 10 <= val < 15), or "No match" (otherwise)
+### Loops and Iteration
+
+#### For Comprehensions
+
+```lits
+// Simple iteration
+for (x in [1, 2, 3, 4]) -> x * 2;
+// => [2, 4, 6, 8]
+
+// With filtering
+for (x in [1, 2, 3, 4] when odd?(x)) -> x * 2;
+// => [2, 6]
+
+// With while condition
+for (x in [1, 2, 3, 4] while x < 3) -> x * 2;
+// => [2, 4]
+
+// With let bindings
+for (x in [1, 2, 3] let doubled = x * 2) -> doubled + 1;
+// => [3, 5, 7]
+
+// Multiple iterators
+for (x in [1, 2], y in [10, 20]) -> x + y;
+// => [11, 21, 12, 22]
+
+// Object iteration
+for (entry in { a: 1, b: 2 } let [key, value] = entry) -> key ++ ":" ++ str(value);
+// => ["a:1", "b:2"]
+```
+
+#### Doseq (Side Effects)
+
+```lits
+// For side effects only (returns null)
+doseq (x in [1, 2, 3]) -> write!(x)
+// Prints: 1 2 3, returns null
+```
+
+#### Loop (Tail Recursion)
+
+```lits
+// Loop with recur for tail recursion
+loop (n = 5, acc = 1) -> {
+  if zero?(n) then
+    acc
+  else
+    recur(n - 1, acc * n)
+  end
+}
+// => 120 (factorial of 5)
+```
+
+### Error Handling
+
+#### Try/Catch
 
-// Try/catch
+```lits
+// Basic try/catch
+try
+  riskyOperation()
+catch
+  "Something went wrong"
+end;
+
+// With error binding
 try
   riskyOperation()
 catch (error)
   "Error: " ++ error.message
-// => result of riskyOperation() or error message if an exception occurs
+end;
 ```
 
-### List Comprehension
+#### Throw
 
+```lits
+// Throwing errors
+try
+  throw("Custom error message");
+catch
+  "Caught an error"
+end;
+
+// In context
+let divide = (a, b) ->
+  if zero?(b) then
+    throw("Division by zero")
+  else
+    a / b
+  end;
 ```
-// Simple for comprehension
-TODO
+
+### Logical Operators
+
+#### And/Or
+
+```lits
+// Logical AND (short-circuit)
+true && "second value";   // => "second value"
+false && "never reached"; // => false
+
+// Logical OR (short-circuit)
+false || "default value"; // => "default value"
+true || "never reached";  // => true
+
+// Multiple arguments
+&&(true, true, "all true"); // => "all true"
+||(false, false, "found");  // => "found"
 ```
 
-### Destructuring
+#### Null Coalescing
 
+```lits
+// Null coalescing operator
+null ?? "default";     // => "default"
+undefined ?? "default"; // => "default"
+0 ?? "default";        // => 0 (only null/undefined are coalesced)
+false ?? "default";    // => false
+"" ?? "default";       // => ""
 ```
-// Object destructuring
-let { name, age } = { name: "John", age: 30 };
-// name => "John"
-// age => 30
 
-// Array destructuring
-let [nbr1, nbr2] = [1, 2, 3, 4];
-// nbr1 => 1
-// nbr2 => 2
+### Blocks
 
-// Destructuring in function parameters
-let displayPerson = ({name, age}) ->
-  name ++ " is " ++ str(age) ++ " years old";
+```lits
+// Block expressions
+{
+  let a = 1 + 2 + 3;
+  let b = x -> x * x;
+  b(a)
+}
+// => 36 (returns value of last expression)
+```
 
-displayPerson({ name: "John", age: 30 });
-// => "John is 30 years old"
+### Arrays and Objects
+
+#### 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];
+```
+
+#### Object Construction
+
+```lits
+// Object literal
+{ name: "John", age: 30 };
+
+// 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 }
+```
+
+### Recursion
+
+#### Recur
+
+```lits
+// Tail recursion with recur
+let countdown = n -> {
+  write!(n);
+  if pos?(n) then
+    recur(n - 1)
+  end
+};
+
+countdown(3)
+// Prints: 3 2 1 0
 ```
 
 ## Operators and Functions
 
-### Function Usage vs Operator Usage
+### Algebraic Notation
 
 All functions that take two parameters can be used as operators:
 
-```
+```lits
 // As a function
-max(5, 10);
-// => 10
+max(5, 10);    // => 10
 
 // As an operator
-5 max 10;
-// => 10
+5 max 10;      // => 10
 ```
 
 All operators can be used as functions:
 
-```
+```lits
 // As an operator
-5 + 3;
-// => 8
+5 + 3;         // => 8
 
 // As a function
-+(5, 3);
-// => 8
-```
++(5, 3);       // => 8
 
-### Parameter Order
+// Partial application with underscore placeholder
+let add5 = +(5, _);
+add5(3);       // => 8
 
-Lits favors subject-first parameter order:
+// Multiple placeholders
+let subtractTwoValues = -(100, _, _);
+subtractTwoValues(4, 3);  // => 93
 
-```
-// Lits
-filter([1, 2, 3, 4], odd?);
-// => [1, 3]
+// Single placeholder in different positions
+let subtract = -(_, 2);
+subtract(10);  // => 8
 
-// Unlike for example Clojure
-// (filter odd? [1 2 3 4])
+let divide = /(10, _);
+divide(2);     // => 5
 ```
 
-This makes operator usage more readable:
+### Parameter Order
 
-```
-[1, 2, 3, 4] filter odd?;
-// => [1, 3]
-```
+Lits favors subject-first parameter order for better operator chaining:
 
-## Built-in Functions
+```lits
+// Function style
+filter([1, 2, 3, 4], odd?);  // => [1, 3]
 
-Lits comes with a comprehensive standard library of functions organized into categories:
+// Operator style (more readable)
+[1, 2, 3, 4] filter odd?;    // => [1, 3]
+```
 
-### Collection Functions
-`count`, `get`, `get-in`, `contains?`, `assoc`, `assoc-in`, `++`, `not-empty`, `every?`, `not-every?`, `any?`, `not-any?`, `update`, `update-in`
+### Pipe Operator
 
-### Array Functions
-`array`, `range`, `repeat`, `flatten`, `mapcat`
+The pipe operator `|>` passes the result of the left expression as the first argument to the right function:
 
-### Sequence Functions
-`nth`, `push`, `pop`, `unshift`, `shift`, `slice`, `splice`, `reductions`, `reduce`, `reduce-right`, `map`, `filter`, `position`, `index-of`, `last-index-of`, `some`, `reverse`, `first`, `second`, `last`, `rest`, `next`, `take`, `take-last`, `take-while`, `drop`, `drop-last`, `drop-while`, `sort`, `sort-by`, `distinct`, `remove`, `remove-at`, `split-at`, `split-with`, `frequencies`, `group-by`, `partition`, `partition-all`, `partition-by`, `starts-with?`, `ends-with?`, `interleave`, `interpose`
+```lits
+// Without pipe operator
+reduce(map(filter([1, 2, 3, 4, 5, 6], odd?), -> $ + $), +, 0);
 
-### Math Functions
-`+`, `-`, `*`, `/`, `mod`, `%`, `quot`, `inc`, `dec`, `√`, `∛`, `**`, `round`, `trunc`, `floor`, `ceil`, `min`, `max`, `abs`, `sign`, `log`, `log2`, `log10`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh`
+// With pipe operator (much more readable)
+[1, 2, 3, 4, 5, 6]
+  |> filter(_, odd?)
+  |> map(_, -> $ * $)
+  |> reduce(_, +, 0);
+// => 35
 
-### Functional Programming
-`apply`, `identity`, `partial`, `comp`, `constantly`, `juxt`, `complement`, `every-pred`, `some-pred`, `fnull`
+// Simple transformations
+"hello world"
+  |> upper-case
+  |> split(_, " ")
+  |> reverse
+  |> join(_, "-");
+// => "WORLD-HELLO"
 
-### Object Functions
-`dissoc`, `object`, `keys`, `vals`, `entries`, `find`, `merge`, `merge-with`, `zipmap`, `select-keys`
+// Mathematical operations
+10
+  |> +(_, 5)
+  |> *(_, 2)
+  |> /(_, 3);
+// => 10 (10 + 5 = 15, 15 * 2 = 30, 30 / 3 = 10)
 
-### String Functions
-`string-repeat`, `str`, `number`, `lower-case`, `upper-case`, `trim`, `trim-left`, `trim-right`, `pad-left`, `pad-right`, `split`, `split-lines`, `template`, `to-char-code`, `from-char-code`, `encode-base64`, `decode-base64`, `encode-uri-component`, `decode-uri-component`, `join`, `capitalize`, `blank?`
+// 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)
+```
 
-### Predicates
-`boolean?`, `null?`, `number?`, `string?`, `function?`, `integer?`, `array?`, `object?`, `coll?`, `seq?`, `regexp?`, `zero?`, `pos?`, `neg?`, `even?`, `odd?`, `finite?`, `nan?`, `negative-infinity?`, `positive-infinity?`, `false?`, `true?`, `empty?`, `not-empty?`
+## Built-in Functions
 
-### Regular Expressions
-`regexp`, `match`, `replace`, `replace-all`
+Lits comes with a comprehensive standard library of functions for:
 
-### Bitwise Operations
-`<<`, `>>`, `>>>`, `~`, `&`, `bit-and-not`, `|`, `^`, `bit-flip`, `bit-clear`, `bit-set`, `bit-test`
+- **Arithmetic and Math**: Basic operations, trigonometry, logarithms, rounding
+- **Collections**: Working with arrays and objects (get, assoc, merge, etc.)
+- **Sequences**: Filtering, mapping, reducing, sorting, and transforming data
+- **Strings**: Manipulation, formatting, encoding, and pattern matching
+- **Predicates**: Type checking and condition testing functions
+- **Functional Programming**: Function composition, partial application, and utilities
+- **Regular Expressions**: Pattern matching and text processing
+- **Bitwise Operations**: Low-level bit manipulation
+- **Assertions**: Testing and validation utilities
 
-### Assertions
-`assert`, `assert=`, `assert!=`, `assert-gt`, `assert-lt`, `assert-gte`, `assert-lte`, `assert-true`, `assert-false`, `assert-truthy`, `assert-falsy`, `assert-null`, `assert-throws`, `assert-throws-error`, `assert-not-throws`
+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.
 
 ## Modules and Exports
 
-You can export definitions to make them available to other modules:
-
-```
-// Exporting variables
-export let magic-number = 42;
-// => 42
-
-// Exporting functions
+```lits
+// Export variables and functions
+export let pi = 3.14159;
 export let square = x -> x * x;
-```
-
-## API
-
-Lits provides a JavaScript API for embedding:
 
-```javascript
-interface Lits {
-  getRuntimeInfo: () => LitsRuntimeInfo
-  run: (program: string, params?: ContextParams & FilePathParams) => unknown
-  context: (programOrAst: string | Ast, params?: ContextParams & FilePathParams) => Context
-  getUndefinedSymbols: (programOrAst: string | Ast, params: ContextParams) => Set<string>
-  tokenize: (program: string, tokenizeParams: FilePathParams & MinifyParams) => TokenStream
-  parse: (tokenStream: TokenStream) => Ast
-  evaluate: (ast: Ast, params: ContextParams) => unknown
-  transformSymbols: (tokenStream: TokenStream, transformer: (symbol: string) => string) => TokenStream
-  untokenize: (tokenStream: TokenStream) => string
-  apply: (fn: LitsFunction, fnParams: unknown[], params: ContextParams) => unknown
-}
+// Exported values become available to other modules
 ```
 
 ## Examples
 
-### Factorial Function
+### Factorial
 
-```
-let factorial = (n) ->
+```lits
+let factorial = n ->
   if n <= 1 then
     1
   else
-    n * self(n - 1);
+    n * self(n - 1)
+  end;
 
-factorial(5);
-// => 120
+factorial(5)  // => 120
 ```
 
-### Fibonacci Sequence
+### Array Processing
+
+```lits
+let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+// Get even numbers squared
+let evenSquares = numbers
+  |> filter(_, even?)
+  |> map(_, -> $ * $);
+// => [4, 16, 36, 64, 100]
 
+// Sum of odd numbers
+let oddSum = numbers
+  |> filter(_, odd?)
+  |> reduce(_, +, 0);
+// => 25
 ```
-let fib = n -> 
-  if n < 2 then
-    n
-  else
-    self(n - 1) + fib(n - 2)
 
-// Generate the first 10 Fibonacci numbers
-range(10) map fib;
-// => [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+### Object Manipulation
+
+```lits
+let person = { name: "John", age: 30, city: "New York" };
+
+// Update age
+let older = assoc(person, "age", 31);
+
+// Add new field
+let withJob = assoc(older, "job", "Developer");
+
+// Using pipe operator for chaining
+let updated = person
+  |> assoc(_, "age", 31)
+  |> assoc(_, "job", "Developer");
 ```
 
-### Working with Collections
+### Pattern Matching Examples
+
+#### Switch (for matching against a single value)
+
+```lits
+let gradeToLetter = grade ->
+  switch grade
+    case 90 then "A"
+    case 80 then "B" 
+    case 70 then "C"
+    case 60 then "D"
+  end ?? "F";
 
+gradeToLetter(80);  // => "B"
+gradeToLetter(55);  // => "F"
+
+// HTTP status code handling
+let statusMessage = code ->
+  switch code
+    case 200 then "OK"
+    case 404 then "Not Found"
+    case 500 then "Internal Server Error"
+  end ?? "Unknown Status";
 ```
-let people = [
-  { name: "Alice", age: 25 },
-  { name: "Bob", age: 30 },
-  { name: "Charlie", age: 35 },
-  { name: "Diana", age: 40 }
-];
 
-// Get all names
-people map (p -> p.name);
-// => ["Alice", "Bob", "Charlie", "Diana"]
+#### Cond (for testing different conditions)
+
+```lits
+let describe = x ->
+  cond
+    case null?(x) then "nothing"
+    case number?(x) then "a number: " ++ str(x)
+    case string?(x) then "text: " ++ x
+    case array?(x) then "list of " ++ str(count(x)) ++ " items"
+  end ?? "unknown type";
+
+describe(42);      // => "a number: 42"
+describe([1,2,3]); // => "list of 3 items"
 
-// Get people older than 30
-people filter (p -> p.age > 30);
-// => [{ name: "Charlie", age: 35 }, { name: "Diana", age: 40 }]
+// Grade ranges
+let gradeToLetter = score ->
+  cond
+    case score >= 90 then "A"
+    case score >= 80 then "B"
+    case score >= 70 then "C"
+    case score >= 60 then "D"
+  end ?? "F";
 
-// Calculate average age
-(people map (p -> p.age) reduce +) / count(people);
-// => 32.5
+gradeToLetter(85);  // => "B"
+gradeToLetter(55);  // => "F"
 ```
 
-## Contributing
+## JavaScript Interoperability
+
+Lits provides a comprehensive JavaScript API for embedding and integration:
+
+```javascript
+import { Lits } from 'lits';
+
+// Create a Lits instance
+const lits = new Lits();
+
+// Run Lits code
+const result = lits.run('+(5, 3)');
+console.log(result); // 8
+
+// Pass JavaScript values to Lits
+const result2 = lits.run('name ++ " is " ++ str(age)', {
+  values: {
+    name: "John",
+    age: 30
+  }
+});
+console.log(result2); // "John is 30"
+
+// Expose JavaScript functions to Lits
+const result3 = lits.run('myAlert("Hello from Lits!")', {
+  jsFunctions: {
+    myAlert: {
+      fn: (message) => console.log(`Alert: ${message}`),
+      arity: { min: 1, max: 1 }
+    }
+  }
+});
+
+// Parse and evaluate separately for better performance
+const tokens = lits.tokenize('+(5, 3)');
+const ast = lits.parse(tokens);
+const result4 = lits.evaluate(ast, {});
+```
+
+### Lits Class Methods
+
+```typescript
+interface Lits {
+  // Execute Lits code directly
+  run(program: string, params?: ContextParams & FilePathParams): unknown
+  
+  // Get execution context after running code
+  context(programOrAst: string | Ast, params?: ContextParams & FilePathParams): Context
+  
+  // Find undefined symbols in code
+  getUndefinedSymbols(programOrAst: string | Ast, params?: ContextParams): Set<string>
+  
+  // Parse pipeline
+  tokenize(program: string, params?: FilePathParams & MinifyParams): TokenStream
+  parse(tokenStream: TokenStream): Ast
+  evaluate(ast: Ast, params: ContextParams): unknown
+  
+  // Apply Lits function with JavaScript arguments
+  apply(fn: LitsFunction, fnParams: unknown[], params?: ContextParams): unknown
+  
+  // Utility methods
+  transformSymbols(tokenStream: TokenStream, transformer: (symbol: string) => string): TokenStream
+  untokenize(tokenStream: TokenStream): string
+  getRuntimeInfo(): LitsRuntimeInfo
+}
+```
+
+### Context Parameters
+
+```typescript
+interface ContextParams {
+  globalContext?: Context          // Global variable context
+  contexts?: Context[]             // Additional context layers
+  values?: Record<string, unknown> // JavaScript values to expose
+  jsFunctions?: Record<string, JsFunction> // JavaScript functions to expose
+  globalModuleScope?: boolean      // Module scoping behavior
+}
+
+interface JsFunction {
+  fn: (...args: any[]) => unknown // The JavaScript function
+  arity?: Arity                   // Function arity constraints
+  docString?: string              // Documentation
+}
+```
 
-*[Add contribution guidelines here]*
+## Learn More
 
-## License
+- Try Lits in the [online playground](https://mojir.github.io/lits/)
+- Explore the comprehensive function reference
+- Check out more complex examples in the documentation
 
-*[Add license information here]*
+Lits combines the elegance of functional programming with practical syntax, making it perfect for data transformation, mathematical computation, and any scenario where immutability and expressiveness are valued.