rip-lang 2.9.1 → 3.0.0

package/docs/RATIONALE.md

@@ -1,180 +0,0 @@
-<p><img src="rip.svg" alt="Rip Logo" width="100"></p>
-
-# Why Rip Exists
-
-> Philosophy, design decisions, and the case for a modern CoffeeScript successor.
-
----
-
-## The Short Version
-
-Rip exists because:
-
-1. **Simplicity scales** — S-expressions make compilers 50% smaller and 10x easier to maintain
-2. **Zero dependencies** — True autonomy from the npm ecosystem
-3. **Modern output** — ES2022 everywhere, no legacy baggage
-4. **Unique features** — 10+ innovations CoffeeScript never had
-5. **Reactivity as operators** — `:=`, `~=`, `~>` are language syntax, not library imports
-6. **Self-hosting** — Rip compiles itself, including its own parser generator
-
----
-
-## 1. Why S-Expressions
-
-Most compilers use complex AST node classes. Rip uses **simple arrays**:
-
-```javascript
-// Traditional AST (CoffeeScript, TypeScript, Babel)
-class BinaryOp {
-  constructor(op, left, right) { ... }
-  compile() { /* 50+ lines */ }
-}
-
-// Rip's S-Expression
-["+", left, right]  // That's it!
-```
-
-**Result:** CoffeeScript's compiler is 17,760 LOC. Rip's is ~11,000 LOC — smaller, yet includes a complete reactive runtime.
-
-### The Fundamental Rule
-
-> **Transform the IR (s-expressions), not the output (strings)**
-
-This single principle eliminates entire categories of bugs. When your IR is simple data (arrays), transformations are trivial and debuggable:
-
-```javascript
-// Debugging: inspect the data directly
-console.log(sexpr);
-// ["comprehension", ["*", "x", 2], [["for-in", ["x"], ["array", 1, 2, 3]]], []]
-// Clear structure, 2-3 minutes to debug
-
-// vs. string manipulation
-console.log(code);
-// "(() => {\n  const result = [];\n  for (const x of arr) {\n..."
-// Blob of text, 20-30 minutes to debug
-```
-
-**Lisp got this right 60 years ago.** Code is data, data is code.
-
----
-
-## 2. Rip vs CoffeeScript
-
-| Metric | CoffeeScript | Rip |
-|--------|--------------|-----|
-| **Feature Parity** | Baseline | ~99% |
-| **Unique Features** | 0 | 10+ innovations |
-| **Dependencies** | Multiple | **ZERO** |
-| **Self-Hosting** | No | **YES** |
-| **Total LOC** | 17,760 | ~11,000 |
-| **Output** | ES6 (2017) | ES2022 |
-| **Reactivity** | None | Built-in |
-
-### What Rip Adds
-
-1. **Reactivity as operators** — `:=` state, `~=` computed, `~>` effects
-2. **Ternary operator** — `x ? a : b` (freed by using `??` for nullish)
-3. **Dammit operator** — `fetchData!` calls AND awaits
-4. **Ruby-style regex** — `str =~ /pattern/` with captures in `_`
-5. **Dual optional syntax** — Both CoffeeScript soak AND ES6 optional chaining
-6. **Void functions** — `def process!` suppresses implicit returns
-7. **Smart comprehensions** — Context-aware (loop vs. array building)
-8. **`__DATA__` marker** — Ruby-style inline data sections
-9. **Heregex** — Extended regex with comments and whitespace
-10. **Zero dependencies** — Everything included, even the parser generator
-
-### The Complete Feature Table
-
-| Feature | CoffeeScript | Rip | Winner |
-|---------|-------------|------|--------|
-| Optional operators | 4 soak | 10 (5 soak + 5 ES6) | Rip |
-| Ternary | No | Yes | Rip |
-| Regex features | Basic | Ruby-style (`=~`, indexing) | Rip |
-| Async shorthand | No | Dammit operator (`!`) | Rip |
-| Void functions | No | `def fn!` | Rip |
-| Reactivity | None | `:=`, `~=`, `~>` | Rip |
-| Comprehension optimization | Always IIFE | Context-aware | Rip |
-| Modules | CommonJS | ES6 | Rip |
-| Classes | ES5 | ES6 | Rip |
-| Dependencies | Multiple | **ZERO** | Rip |
-| Parser generator | External (Jison) | **Built-in (solar.rip)** | Rip |
-| Self-hosting | No | **Yes** | Rip |
-
----
-
-## 3. The Case Against CoffeeScript (And Why Rip Is Different)
-
-The strongest argument against CoffeeScript in 2026:
-
-- **Ecosystem abandoned** — Hiring, tooling, community all gone
-- **TypeScript won** — Type safety became the standard
-- **JavaScript absorbed it** — `?.`, `??`, `=>`, classes, destructuring all native now
-- **Tooling rotted** — IDE support deprecated, build plugins unmaintained
-
-**These are valid criticisms.** Rip addresses every one:
-
-| Criticism | CoffeeScript's Problem | Rip's Answer |
-|-----------|----------------------|--------------|
-| No ecosystem | Dead community | Zero dependencies — doesn't need one |
-| No types | Can't integrate with TS tooling | ES2022 output works with any JS toolchain |
-| Tooling rot | Plugins unmaintained | Self-contained — nothing to maintain |
-| No innovation | Frozen since 2017 | 10+ unique features, active development |
-| No corporate backing | Abandoned | Self-hosting — depends on nothing |
-
-**The key insight:** CoffeeScript failed because it depended on an ecosystem that moved on. Rip succeeds by depending on nothing.
-
----
-
-## 4. Reactivity as a Language Feature
-
-This is Rip's signature innovation. While React, Vue, and Solid provide reactivity through library imports, Rip provides it as **language operators**:
-
-```coffee
-count := 0                    # State — reactive container
-doubled ~= count * 2          # Computed — auto-updates when count changes
-~> console.log count           # Effect — runs when dependencies change
-```
-
-Compare to React:
-```javascript
-import { useState, useMemo, useEffect } from 'react';
-const [count, setCount] = useState(0);
-const doubled = useMemo(() => count * 2, [count]);
-useEffect(() => { console.log(count); }, [count]);
-```
-
-**No imports. No hooks. No dependency arrays. Just operators.**
-
-The reactive runtime is ~200 lines, embedded in the compiler, and only included when reactive operators are used.
-
----
-
-## 5. Design Principles
-
-### Simplicity Scales
-
-Simple IR (s-expressions), clear pipeline (lex → parse → generate), minimal code, comprehensive tests. Every design decision optimizes for **long-term maintainability**, not short-term cleverness.
-
-### Zero Dependencies Is a Feature
-
-```json
-{ "dependencies": {} }
-```
-
-Everything included: compiler, parser generator, REPL, browser bundle, test framework. No supply chain attacks. No version conflicts. No `node_modules` bloat.
-
-### Self-Hosting Proves Quality
-
-Rip compiles its own parser generator (`solar.rip` → `parser.js`). If the compiler can compile itself, it works.
-
----
-
-**See Also:**
-- [GUIDE.md](GUIDE.md) — Complete language reference
-- [REACTIVITY.md](REACTIVITY.md) — Reactivity deep dive
-- [INTERNALS.md](INTERNALS.md) — Compiler architecture
-- [BROWSER.md](BROWSER.md) — Browser usage and REPL
-
----
-
-*Version 2.9.0 — 1115/1115 tests passing — Zero dependencies — Self-hosting*

package/docs/examples/README.md

@@ -1,33 +0,0 @@
-# Rip Examples
-
-Focused examples demonstrating Rip's key features. Each file is self-contained
-and can be compiled with `rip -c <file>` to see the generated JavaScript.
-
-## Core Language
-
-| Example | Demonstrates |
-|---------|-------------|
-| [fibonacci.rip](fibonacci.rip) | Functions, implicit returns, recursion |
-| [arrows.rip](arrows.rip) | Arrow functions, callbacks, implicit object returns |
-| [switch.rip](switch.rip) | Switch/when patterns (value and condition based) |
-| [ternary.rip](ternary.rip) | JS-style ternary operator (`? :`) |
-| [ranges.rip](ranges.rip) | Inclusive (`..`) and exclusive (`...`) ranges |
-
-## Advanced Features
-
-| Example | Demonstrates |
-|---------|-------------|
-| [reactivity.rip](reactivity.rip) | State (`:=`), computed (`~=`), effects (`~>`) |
-| [async-await.rip](async-await.rip) | Dammit operator (`!`), auto-async detection |
-| [existential.rip](existential.rip) | Null coalescing (`??`), optional chaining (`?.`) |
-| [module.rip](module.rip) | Imports, exports, module patterns |
-
-## Quick Start
-
-```bash
-# See what Rip generates
-rip -c docs/examples/fibonacci.rip
-
-# Run an example
-rip docs/examples/reactivity.rip
-```

package/docs/examples/arrows.rip

@@ -1,74 +0,0 @@
-# Arrow Function Examples
-
-# =============================================================================
-# Basic Arrow Functions (=> binds 'this', -> does not)
-# =============================================================================
-
-# Simple arrows
-add = (a, b) => a + b
-square = (x) => x * x
-greet = (name) => "Hello, #{name}!"    # CoffeeScript-style interpolation
-farewell = (name) => "Goodbye, ${name}!" # JavaScript-style also works
-
-# Arrow functions in objects (methods!)
-math = {
-  add: (a, b) => a + b
-  subtract: (a, b) => a - b
-  multiply: (a, b) => a * b
-  divide: (a, b) => a / b
-}
-
-# Arrow functions as callbacks
-numbers = [1, 2, 3, 4, 5]
-doubled = numbers.map((x) => x * 2)
-evens = numbers.filter((x) => x % 2 == 0)
-sum = numbers.reduce((acc, x) => acc + x, 0)
-
-# Arrow functions with object methods
-users = [
-  {name: "Alice", age: 30}
-  {name: "Bob", age: 25}
-]
-
-names = users.map((u) => u.name)
-adults = users.filter((u) => u.age >= 18)
-
-# Composing arrows
-pipeline = {
-  transform: (data) => data.map((x) => x * 2)
-  filter: (data) => data.filter((x) => x > 5)
-  process: (data) => data.reduce((sum, x) => sum + x, 0)
-}
-
-# =============================================================================
-# Implicit Object Returns (CoffeeScript-style elegance!)
-# =============================================================================
-
-# Simple implicit object (no braces needed!)
-makePoint = (x, y) =>
-  x: x
-  y: y
-
-# With shorthand (use explicit braces)
-makePoint2 = (x, y) => {x, y}
-
-# Data transformation
-enrichUser = (user) =>
-  id: user.id
-  name: user.name
-  email: user.email
-  active: true
-  joined: Date.now()
-
-# Simple API methods
-api = {
-  getUser: (id) =>
-    id: id
-    name: "User #{id}"
-    timestamp: Date.now()
-
-  createResponse: (data, status) =>
-    data: data
-    status: status
-    success: status == 200
-}

package/docs/examples/async-await.rip

@@ -1,59 +0,0 @@
-# Async/Await with the "Dammit Operator" (!)
-# Clean, visual async syntax
-
-# Simple async function
-def loadUser(id)
-  user = Db.findOne!(id)
-  user
-
-# Multiple awaits (auto-detected as async!)
-def getUserProfile(id)
-  user = Db.getUser!(id)
-  posts = Db.getPosts!(user.id)
-  friends = Db.getFriends!(user.id)
-
-  {user, posts, friends}
-
-# No arguments - auto-calls!
-def refreshCache()
-  data = fetchLatest!
-  cache = getCache!
-  cache.set!(data)
-  data
-
-# Await in conditionals
-def checkStatus(id)
-  user = Db.getUser!(id)
-
-  if user.active
-    status = Api.getStatus!(user.id)
-    {user, status, active: true}
-  else
-    {user, active: false}
-
-# Arrow functions with await
-fetchAndProcess = (id) => Api.fetch!(id).then!(processData)
-
-# Await in object methods
-api = {
-  loadData: (key) =>
-    data: Cache.get!(key)
-    timestamp: Date.now()
-
-  saveData: (key, value) =>
-    result = Cache.set!(key, value)
-    success: result.ok
-}
-
-# Complex async flow
-def processUserData(userId)
-  user = Db.getUser!(userId)
-  settings = Db.getSettings!(userId)
-  activity = Api.getActivity!(userId)
-
-  {
-    user
-    settings
-    activity
-    fetchedAt: Date.now()
-  }

package/docs/examples/existential.rip

@@ -1,86 +0,0 @@
-# Existential and Logical Assignment Operators
-# Demonstrates the difference between nullish and falsy checks
-
-# Binary Nullish Coalescing (??)
-# Only replaces null/undefined
-def getPort(config)
-  config.port ?? 8080
-
-# Preserves 0, false, empty string
-port1 = getPort({port: 0})        # → 0 (not replaced!)
-port2 = getPort({port: null})     # → 8080 (replaced)
-port3 = getPort({})               # → 8080 (undefined)
-
-# Binary Logical OR (||)
-# Replaces ALL falsy values
-def getPortFalsy(config)
-  config.port || 8080
-
-portA = getPortFalsy({port: 0})   # → 8080 (0 is falsy)
-portB = getPortFalsy({port: null}) # → 8080 (null is falsy)
-
-# Existential Assignment (?=)
-# Assign only if null/undefined
-def initializeConfig()
-  config = {}
-  config.port ?= 8080      # Sets to 8080 (undefined)
-  config.debug ?= false    # Sets to false (undefined)
-  config.timeout ?= 0      # Sets to 0 (undefined)
-
-  # These won't change existing values
-  config.port ?= 9000      # Stays 8080
-  config.debug ?= true     # Stays false (preserves false!)
-  config.timeout ?= 5000   # Stays 0 (preserves 0!)
-
-  config
-
-# Logical OR Assignment (||=)
-# Assign if falsy
-def setDefaults(options)
-  options.name ||= "guest"     # Replaces empty string
-  options.count ||= 10         # Replaces 0
-  options.enabled ||= true     # Replaces false
-  options
-
-# Logical AND Assignment (&&=)
-# Update only if truthy
-def processIfValid(data)
-  data.value &&= data.value * 2  # Only process if exists
-  data
-
-# Real-world example: User preferences
-def getUserPreferences(user)
-  prefs = user?.preferences ?? {}
-
-  # Set defaults for missing values (existential)
-  prefs.theme ?= "dark"
-  prefs.fontSize ?= 14
-  prefs.notifications ?= true
-
-  # But replace falsy user inputs (logical)
-  prefs.username ||= "anonymous"
-
-  prefs
-
-# Chained nullish coalescing
-def getConfigValue(primary, secondary, tertiary)
-  primary ?? secondary ?? tertiary ?? "default"
-
-# Comparison table
-def demonstrateDifference()
-  testValues = [null, undefined, false, 0, "", "text", 42]
-
-  # For each value, show behavior of ?? vs ||
-  results = []
-
-  testValues.forEach((val) => {
-    nullish = val ?? "default"
-    logical = val || "default"
-    results.push({
-      value: val
-      nullish: nullish
-      logical: logical
-    })
-  })
-
-  results

package/docs/examples/fibonacci.rip

@@ -1,12 +0,0 @@
-# Fibonacci example in Rip
-# Whitespace-sensitive s-expression syntax
-# No let/const needed, no return needed!
-
-def fibonacci(n)
-  if n <= 1
-    n
-  else
-    fibonacci(n - 1) + fibonacci(n - 2)
-
-# Test it
-result = fibonacci(10)

package/docs/examples/module.rip

@@ -1,48 +0,0 @@
-# Modules — Imports, Exports, and Module Patterns
-
-# =============================================================================
-# Importing
-# =============================================================================
-
-# Named imports
-import { readFileSync, writeFileSync } from "fs"
-import { join, resolve } from "path"
-
-# Namespace import
-import * as os from "os"
-
-# Default import
-# import express from "express"
-
-# =============================================================================
-# Exporting Functions
-# =============================================================================
-
-# Named function export
-export def greet(name)
-  "Hello, #{name}!"
-
-# Arrow function export
-export double = (x) -> x * 2
-export format = (obj) -> JSON.stringify(obj, null, 2)
-
-# =============================================================================
-# Exporting Values
-# =============================================================================
-
-export config =
-  timeout: 5000
-  retries: 3
-  verbose: false
-
-export AUTHOR =! "Rip"    # const export
-
-# =============================================================================
-# Default Export
-# =============================================================================
-
-export default
-  greet: greet
-  double: double
-  format: format
-  config: config

package/docs/examples/ranges.rip

@@ -1,45 +0,0 @@
-# Range Examples
-# Smart compilation: small ranges = inline, large ranges = IIFE
-
-# Inclusive ranges (..)
-def demoInclusive()
-  nums = 1..5
-  console.log("1..5 =", nums)     # [1, 2, 3, 4, 5]
-
-# Exclusive ranges (...)
-def demoExclusive()
-  nums = 1...5
-  console.log("1...5 =", nums)    # [1, 2, 3, 4]
-
-# Descending ranges
-def demoDescending()
-  nums = 10..1
-  console.log("10..1 =", nums.slice(0, 5))  # [10, 9, 8, 7, 6, ...]
-
-# Large ranges (generates IIFE, not inline)
-def demoLarge()
-  nums = 1..100
-  console.log("1..100 length =", nums.length)  # 100
-  console.log("First 5:", nums.slice(0, 5))    # [1, 2, 3, 4, 5]
-
-# Dynamic ranges (runtime values)
-def rangeBetween(start, end)
-  start..end
-
-# Using ranges
-def sumRange(n)
-  nums = 1..n
-  sum = 0
-  nums.forEach((x) => sum = sum + x)
-  sum
-
-# Range in array
-def mixedArray()
-  arr = [0, 1..3, 10, 20..22]
-  console.log("Mixed:", arr)  # [0, [1,2,3], 10, [20,21,22]]
-
-# Practical: Generate test data
-def generateIds(count)
-  ids = 1..count
-  ids.map((id) => id)
-

package/docs/examples/reactivity.rip

@@ -1,48 +0,0 @@
-# Reactivity — Rip's signature feature
-# Language-level operators for reactive state, computed values, and effects.
-# No imports. No hooks. No dependency arrays. Just operators.
-
-# =============================================================================
-# State (:= creates reactive state)
-# =============================================================================
-
-count := 0                    # Reactive state variable
-name := "Alice"               # Works with any type
-items := [1, 2, 3]            # Arrays too
-
-# =============================================================================
-# Computed (~= auto-updates when dependencies change)
-# =============================================================================
-
-doubled ~= count * 2          # Always equals count * 2
-greeting ~= "Hello, #{name}!" # Recomputes when name changes
-total ~= items.reduce((a, b) -> a + b, 0)
-
-# =============================================================================
-# Effects (~> runs automatically when dependencies change)
-# =============================================================================
-
-# Anonymous effect (runs whenever count changes)
-~> console.log "Count is now: #{count}"
-
-# Named effect (can be controlled/disposed)
-logger ~> console.log "#{name} has #{count} items"
-
-# =============================================================================
-# Const (=! for values that never change)
-# =============================================================================
-
-MAX_RETRIES =! 10             # const — "equals, dammit!"
-API_URL =! "https://api.example.com"
-
-# =============================================================================
-# How it works
-# =============================================================================
-
-# The operators compile to a tiny reactive runtime:
-#   count := 0        →  const count = __state(0)
-#   doubled ~= count  →  const doubled = __computed(() => count * 2)
-#   ~> console.log    →  __effect(() => console.log(...))
-#
-# The runtime is embedded in the compiler (~100 lines) and only
-# included in the output when reactive operators are used.

package/docs/examples/switch.rip

@@ -1,50 +0,0 @@
-# Switch/When/Else Examples
-# Two modes: value-based and condition-based
-
-# Value-based switch (matches against a value)
-def getDayType(day)
-  switch day
-    when "Mon", "Tue", "Wed", "Thu", "Fri" then "weekday"
-    when "Sat", "Sun" then "weekend"
-    else "unknown"
-
-# Condition-based switch (evaluates conditions)
-def getGrade(score)
-  switch
-    when score < 60 then "F"
-    when score < 70 then "D"
-    when score < 80 then "C"
-    when score < 90 then "B"
-    else "A"
-
-# With block syntax
-def processDay(day)
-  switch day
-    when "Mon"
-      console.log("Start of week")
-      "work mode"
-    when "Fri"
-      console.log("Almost weekend!")
-      "party mode"
-    when "Sat", "Sun"
-      console.log("Weekend!")
-      "relax mode"
-    else
-      "default mode"
-
-# Switch as expression (gets wrapped in IIFE)
-def categorize(value)
-  category = switch value
-    when 1, 2, 3 then "low"
-    when 4, 5, 6 then "medium"
-    when 7, 8, 9 then "high"
-    else "out of range"
-  category
-
-# Condition-based for complex logic
-def classify(x, y)
-  switch
-    when x > 100 && y > 100 then "both large"
-    when x > 100 || y > 100 then "one large"
-    when x > 0 && y > 0 then "both positive"
-    else "other"

package/docs/examples/ternary.rip

@@ -1,36 +0,0 @@
-# Ternary Operator Examples
-# Both ? : and if/then/else syntaxes supported!
-
-# Basic ternary
-def abs(x)
-  result = x < 0 ? (0 - x) : x
-  result
-
-# Nested ternary for classification
-def classify(n)
-  n > 0 ? "positive" : n < 0 ? "negative" : "zero"
-
-# Ternary in expressions
-def max(a, b)
-  a > b ? a : b
-
-# Ternary with objects
-def makePoint(x, y)
-  x > 0 && y > 0 ? {x: x, y: y, quadrant: 1} : {x: x, y: y, quadrant: 0}
-
-# CoffeeScript-style inline if/then/else
-def greeting(isMorning)
-  if isMorning then "Good morning!" else "Good evening!"
-
-def compare(a, b)
-  if a > b then "greater" else if a < b then "less" else "equal"
-
-# Real-world example: validation
-def validateAge(age)
-  message = age >= 18 ? "Adult" : age >= 13 ? "Teen" : "Child"
-  valid = age >= 0 && age <= 120
-  {
-    age: age
-    category: message
-    valid: valid ? "yes" : "no"
-  }