# Hyper RPN Operators Hyper operators operate on **all** values currently on the stack, rather than just the top one or two. They pop every value, reduce them left-associatively, and push a single result back. The syntax uses square brackets: `[+]`, `[*]`, `[-]`, `[/]`, `[^]`, `[%]`, `[lg]`, `[log]`, `[ln]`. ## How Hyper Operators Work ``` Input: 1 2 3 4 5 [+] Step Stack ---- ----- 1 [1] 2 [1, 2] 3 [1, 2, 3] 4 [1, 2, 3, 4] 5 [1, 2, 3, 4, 5] [+] [15] Result: 15 ``` All five values are consumed, summed left-to-right (`((((1 + 2) + 3) + 4) + 5)`), and the single result is pushed back. ### Requirements - At least **two** values must be on the stack, or the operator returns an error. - After execution, exactly one value remains on the stack. ## Arithmetic Hyper Operators ### `[+]` Sum Adds all stack values left-associatively. ``` $ gt '1 2 3 4 5 [+]' 15 ``` Equivalently: `1 + 2 + 3 + 4 + 5` = 15. With two operands, behaves identically to binary `+`: ``` $ gt '10 20 [+]' 30 ``` ### `[*]` Product Multiplies all stack values left-associatively. Result is always unitless. ``` $ gt '2 3 4 [*]' 24 ``` Equivalently: `2 * 3 * 4` = 24. ``` $ gt '1 2 3 [*]' 6 ``` ### `[-]` Subtraction Subtracts all stack values left-associatively from the first. ``` $ gt '10 3 2 [-]' 5 ``` Equivalently: `10 - 3 - 2` = 5. ``` $ gt '100 10 20 30 [-]' 40 ``` Equivalently: `100 - 10 - 20 - 30` = 40. ### `[/]` Division Divides all stack values left-associatively from the first. Result is always unitless. ``` $ gt '100 5 2 [/]' 10 ``` Equivalently: `100 / 5 / 2` = 10. ``` $ gt '1000 10 10 [/]' 10 ``` ### `[^]` Power Raises left-associatively. The first value is the base, subsequent values are successive exponents. Result is always unitless. ``` $ gt '2 3 2 [^]' 64 ``` Equivalently: `(2 ^ 3) ^ 2` = `8 ^ 2` = 64. With two operands, behaves identically to binary `^`: ``` $ gt '2 10 [^]' 1024 ``` ### `[%]` Modulo Computes modulo left-associatively. ``` $ gt '100 7 3 [%]' 2 ``` Equivalently: `100 % 7` = 2, then `2 % 3` = 2. ``` $ gt '10 3 2 2 [%]' 0 ``` Equivalently: `((((10 % 3) % 2) % 2)` = `(1 % 2) % 2` = `1 % 2` = 1. ## Logarithmic Hyper Operators Logarithmic hyper operators compute the **sum** of the log function applied to each stack value. All input values must be positive. ### `[lg]` Base-2 Logarithm Sum ``` $ gt '2 4 8 [lg]' 6 ``` Equivalently: `log2(2) + log2(4) + log2(8)` = `1 + 2 + 3` = 6. ``` $ gt '1 2 3 4 5 [lg]' 6.907 ``` ### `[log]` Base-10 Logarithm Sum ``` $ gt '10 100 [log]' 3 ``` Equivalently: `log10(10) + log10(100)` = `1 + 2` = 3. ### `[ln]` Natural Logarithm Sum ``` $ gt '2.718281828 7.389 [ln]' 2.999992408 ``` Equivalently: `ln(2.718281828) + ln(7.389)` ≈ `1 + 2` ≈ 3. ## Metric-Aware Behavior Some hyper operators are metric-aware, meaning they understand units and can operate on values with compatible units. ### Metric-aware operators: `[+]`, `[-]`, `[%]` These operators: 1. **Validate** that all operands share the same metric category (or are unitless, which is always compatible). 2. **Convert** all values to the result metric's base units before computing. 3. **Push** the result with the first non-unitless metric (or unitless if all inputs are unitless). ``` $ gt '1km 2km 3km [+]' 6 ``` Result is in kilometers: `1 + 2 + 3 = 6 km`. ``` $ gt '1km 500m [+]' 1.5 ``` `500m` is converted to `0.5km`, then `1km + 0.5km = 1.5km`. ``` $ gt '100m 0.005km [+]' 105 ``` `0.005km` is converted to `5m`, then `100m + 5m = 105m`. ``` $ gt '5km 1km 2km [-]' 2 ``` Result is `5 - 1 - 2 = 2 km`. ``` $ gt '10m 3m 2m [%]' 1 ``` `10 % 3 = 1`, then `1 % 2 = 1 m`. ``` $ gt '1km 1000m [+]' 2 ``` `1000m` converts to `1km`, result is `1 + 1 = 2 km`. ### Non-metric operators: `[*]`, `[/]`, `[^]`, `[lg]`, `[log]`, `[ln]` These operators use raw numeric values and always produce unitless (Cool) results, regardless of input units: - `[*]` — multiplying meters by meters would yield square meters, a different category, so the result is unitless. - `[/]` — dividing two like units yields a ratio, which is unitless. - `[^]` — exponents are inherently unitless. - `[lg]`, `[log]`, `[ln]` — logarithms require dimensionless inputs, so the raw numeric value is used and the result is unitless. ### Mixed unitless and unit values Unitless (Cool) values can be combined with any metric category — they "absorb" and take on the category of the other operands: ``` $ gt '0 5km [+]' 5 ``` ## Practical Use Cases ### Batch aggregation Sum a series of readings in one command: ``` $ gt '12 15 18 14 16 [+]' 75 ``` ### Running total with metric conversion Sum distances in different units: ``` $ gt '5km 2km 1000m [+]' 8 ``` Result is in km: `5 + 2 + 1 = 8 km`. ### Compute a product ``` $ gt '2 5 10 [*]' 100 ``` ### Chained reduction with regular operators Compare hyper `[+]` with chained binary `+`: ``` $ gt '1 2 3 4 5 +' + + + +' 15 ``` Equivalent (but much shorter) with hyper: ``` $ gt '1 2 3 4 5 [+]' 15 ``` ### Cascading subtraction ``` $ gt '100 10 20 30 5 [-]' 35 ``` `100 - 10 - 20 - 30 - 5 = 35`. ### Repeated division ``` $ gt '1000 2 2 2 2 [/]' 62.5 ``` `1000 / 2 / 2 / 2 / 2 = 62.5`. ### Log sum for information theory Sum of log2 values for entropy calculations: ``` $ gt '0.25 0.5 0.25 [lg]' -3 ``` `log2(0.25) + log2(0.5) + log2(0.25)` = `-2 + -1 + -2` = -5. ## Edge Cases ### Division by zero ``` $ gt '10 5 0 [/]' Error: division by zero ``` ### Modulo by zero ``` $ gt '100 7 0 [%]' Error: modulo by zero ``` ### Non-positive log inputs ``` $ gt '0 [lg]' Error: log2 undefined for non-positive numbers $ gt '-1 [ln]' Error: ln undefined for non-positive numbers ``` ### Incompatible metrics Mixing different metric categories (e.g., length and weight) in a metric-aware operator returns an error. ### Insufficient operands All hyper operators require at least two values: ``` $ gt '5 [*]' Error: insufficient operands for [*]: need at least 2 values $ gt '[+]' Error: stack is empty ``` ## Summary Table | Operator | Description | Metric-aware | Result metric | |----------|--------------------------------|--------------|---------------| | `[+]` | Sum all values | Yes | First non-Cool| | `[*]` | Multiply all values | No | Cool (unitless)| | `[-]` | Subtract all values | Yes | First non-Cool| | `[/]` | Divide all values | No | Cool (unitless)| | `[^]` | Power (left-associative) | No | Cool (unitless)| | `[%]` | Modulo (left-associative) | Yes | First non-Cool| | `[lg]` | Sum of log2 for all values | No | Cool (unitless)| | `[log]` | Sum of log10 for all values | No | Cool (unitless)| | `[ln]` | Sum of ln for all values | No | Cool (unitless)|