rip-lang 3.6.2 → 3.7.3

package/docs/RIP-LANG.md

@@ -2,7 +2,7 @@
 
 # Rip Language Reference
 
-Rip is a modern reactive language that compiles to ES2022 JavaScript. It combines CoffeeScript's elegant syntax with built-in reactivity primitives. Zero dependencies, self-hosting, ~10,300 LOC.
+Rip is a modern reactive language that compiles to ES2022 JavaScript. It combines CoffeeScript's elegant syntax with built-in reactivity primitives. Zero dependencies, self-hosting, ~10,800 LOC.
 
 ---
 
@@ -121,6 +121,10 @@ else
 status = active ? "on" : "off"
 result = x > 5 ? "big" : "small"
 
+# Ternary (Python-style postfix)
+status = "active" if online else "offline"
+label = "big" if x > 5 else "small"
+
 # NOTE: Subscript in ternary true-branch needs parentheses
 item = found ? (arr[0]) : default
 
@@ -227,6 +231,15 @@ until done
 loop
   data = fetch()
   break if data.complete
+
+# Loop N times
+loop 5
+  console.log "hi"
+# Compiles to: for (let _i = 0; _i < 5; _i++) { ... }
+
+# Loop with variable or expression
+loop retries
+  attempt!
 ```
 
 ## Comprehensions
@@ -275,6 +288,7 @@ Multiple lines
 | `of` | `k of obj` | Object key existence |
 | `?` (postfix) | `a?` | Existence check (`a != null`) |
 | `?` (ternary) | `a ? b : c` | Ternary conditional |
+| `if...else` (postfix) | `b if a else c` | Python-style ternary |
 | `?.` `?.[]` `?.()` | `a?.b` `a?.[0]` `a?.()` | Optional chaining (ES6) |
 | `?[]` `?()` | `a?[0]` `a?(x)` | Optional chaining shorthand |
 | `??` | `a ?? b` | Nullish coalescing |
@@ -293,6 +307,15 @@ Multiple lines
 | `!` | Void | `def process!` | Suppresses implicit return |
 | `!?` | Otherwise | `val !? 5` | Default if undefined or throws |
 | `=~` | Match | `str =~ /pat/` | Ruby-style regex match, captures in `_` |
+| `::` | Prototype | `String::trim` | `String.prototype.trim` |
+| `[-n]` | Negative index | `arr[-1]` | `arr.at(-1)` |
+| `*` | String repeat | `"-" * 40` | `"-".repeat(40)` |
+| `<` `<=` | Chained comparison | `1 < x < 10` | `(1 < x) && (x < 10)` |
+| `\|>` | Pipe | `x \|> fn` or `x \|> fn(y)` | `fn(x)` or `fn(x, y)` |
+| `.=` | Method assign | `x .= trim()` | `x = x.trim()` |
+| `*` | Merge assign | `*obj = {a: 1}` | `Object.assign(obj, {a: 1})` |
+| `not in` | Not in | `x not in arr` | Negated membership test |
+| `not of` | Not of | `k not of obj` | Negated key existence |
 
 ## Assignment Operators
 
@@ -333,6 +356,10 @@ status = active ? 'on' : 'off'
 result = valid ? obj.field : null
 output = ready ? compute() : fallback
 
+# Python-style postfix ternary
+status = "active" if online else "offline"
+label = "big" if x > 5 else "small"
+
 # Nested
 level = score > 90 ? 'A' : score > 80 ? 'B' : score > 70 ? 'C' : 'F'
 
@@ -349,6 +376,162 @@ result = riskyOperation() !? "default"
 # If riskyOperation() throws or returns null/undefined, result = "default"
 ```
 
+## Method Assignment (`.=`)
+
+A Rip original. Compound assignment for method calls — apply a method to a
+variable and assign the result back in one step:
+
+```coffee
+# Without .= — repeat the variable name every time
+items = items.filter -> it.active
+items = items.map -> it.name
+items = items.sort (a, b) -> a.localeCompare b
+str = str.trim()
+str = str.toLowerCase()
+
+# With .= — name it once, transform in place
+items .= filter -> it.active
+items .= map -> it.name
+items .= sort (a, b) -> a.localeCompare b
+str .= trim()
+str .= toLowerCase()
+```
+
+`x .= method(args)` compiles to `x = x.method(args)`. It's the method-call
+equivalent of `+=` — just as `x += 5` means `x = x + 5`, `x .= trim()`
+means `x = x.trim()`.
+
+This operator is unique to Rip. Other languages have `+=`, `-=`, `*=`, and
+other arithmetic compound assignments, but none extend the concept to method
+calls. Combined with implicit `it`, this enables remarkably concise data
+transformation pipelines:
+
+```coffee
+users .= filter -> it.active
+users .= map -> it.name
+users .= sort()
+```
+
+Works with any method — built-in or custom, with or without arguments. Spacing
+is flexible — all of these are equivalent:
+
+```coffee
+str .= trim()          # canonical (spaced)
+str.=trim()            # compact (no spaces)
+str .=trim()           # mixed
+```
+
+## Merge Assignment (`*`)
+
+A Rip original. Merge properties into an existing object without repeating
+its name:
+
+```coffee
+# Without * — repeat the object name or use verbose Object.assign
+Object.assign config,
+  host: "localhost"
+  port: 3000
+  debug: true
+
+# With * — clean and direct
+*config =
+  host: "localhost"
+  port: 3000
+  debug: true
+
+# Single line
+*opts = {method: "POST", body: data}
+
+# Dotted paths
+*el.style =
+  color: "red"
+  fontSize: "14px"
+
+# Merge user overrides into defaults
+*defaults = userConfig
+```
+
+`*target = value` compiles to `Object.assign(target, value)`. The `*` reads
+as "spread these into" — the same concept as `...` spread but as an
+assignment. This is unique to Rip.
+
+Common use cases: config objects, options bags, state initialization, DOM
+styling, merging defaults with overrides — anywhere you're setting multiple
+properties on an existing object.
+
+## Prototype Operator (`::`)
+
+Access `.prototype` with `::` (CoffeeScript-style). Disambiguated from type annotations by spacing:
+
+```coffee
+# Prototype access (no space after ::)
+String::starts = String::startsWith
+String::ends   = String::endsWith
+String::has    = String::includes
+
+# Now you can use them
+"hello".starts "he"        # true
+"hello.rip".ends ".rip"    # true
+"error: bad".has "error"   # true
+
+# Define new prototype methods
+String::shout = -> @toUpperCase() + "!"
+"hello".shout()            # "HELLO!"
+
+# Type annotations (space after ::) — unaffected
+name:: string = "Alice"
+def greet(name:: string):: string
+  "Hello, #{name}!"
+```
+
+The rule is simple: `::` with **no space** before an identifier is prototype access. `::` with a **space** is a type annotation.
+
+## Negative Indexing
+
+Literal negative indexes compile to `.at()` for Python-style access from the end:
+
+```coffee
+arr = [10, 20, 30, 40, 50]
+
+arr[-1]          # → arr.at(-1)  — 50 (last)
+arr[-2]          # → arr.at(-2)  — 40 (second to last)
+str[-1]          # works on strings too
+
+arr?[-1]         # → arr?.at(-1) — optional variant
+
+# Positive and variable indexes are unchanged
+arr[0]           # → arr[0]      — normal access
+arr[i]           # → arr[i]      — variable index
+```
+
+Only literal negative numbers trigger the `.at()` transform. Variable indexes pass through as-is.
+
+## Pipe Operator (`|>`)
+
+Pipes a value into a function as its first argument. Chains left-to-right:
+
+```coffee
+# Simple reference — value becomes the sole argument
+5 |> double                      # → double(5)
+10 |> Math.sqrt                  # → Math.sqrt(10)
+"hello" |> console.log           # → console.log("hello")
+
+# Multi-arg — value is inserted as the FIRST argument
+5 |> add(3)                      # → add(5, 3)
+data |> filter(isActive)         # → filter(data, isActive)
+"World" |> greet("!")            # → greet("World", "!")
+
+# Chaining — reads left-to-right like a pipeline
+5 |> double |> add(1) |> console.log
+# → console.log(add(double(5), 1))
+
+# Works with dotted methods
+users |> Array.from              # → Array.from(users)
+data |> JSON.stringify(null, 2)  # → JSON.stringify(data, null, 2)
+```
+
+This is the **Elixir-style** pipe — strictly better than F#'s (which only supports bare function references) and cleaner than Hack's (which requires a `%` placeholder). No special syntax to learn; if the right side is a call, the left value goes first.
+
 ---
 
 # 4. Functions
@@ -420,6 +603,41 @@ def findUser(id)
   null
 ```
 
+## Implicit `it` Parameter
+
+Arrow functions with no explicit parameters that reference `it` in the body automatically inject `it` as the parameter:
+
+```coffee
+# Without `it` — must name a throwaway variable
+users.filter (u) -> u.active
+names = users.map (u) -> u.name
+
+# With `it` — cleaner
+users.filter -> it.active
+names = users.map -> it.name
+orders.filter -> it.total > 100
+
+# Works with fat arrows too
+items.map => it.toUpperCase()
+
+# Nested arrows — each level gets its own `it`
+# Only the innermost param-less arrow with `it` is affected
+groups.map -> it.items.filter -> it.active
+
+# Explicit params still work normally
+items.sort (a, b) -> a - b
+```
+
+Compiles to standard JavaScript — `it` becomes a regular function parameter:
+
+```coffee
+arr.filter -> it > 5
+# → arr.filter(function(it) { return (it > 5); })
+
+arr.map => it.name
+# → arr.map(it => it.name)
+```
+
 ## Calling Functions
 
 ```coffee
@@ -1165,4 +1383,4 @@ count = 10  # Logs: "Count: 10, Doubled: 20"
 
 ---
 
-*Rip 3.4 — 1,140 tests passing — Zero dependencies — Self-hosting — ~10,300 LOC*
+*Rip 3.7 — 1,219 tests passing — Zero dependencies — Self-hosting — ~10,800 LOC*