frausto 0.2.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c1ff4be227078cbc60a23393acb8fc563c0175e5fbffe921864275d2bf50337
-  data.tar.gz: 6333880ae0f3c7bf85530a2c5cc8c1d44f7041f2358f04283efff77ccf4d828f
+  metadata.gz: '093f5e9746f4614c8b4085708ccd9b2bf092d06c3a50f5ff08fec837a86ff978'
+  data.tar.gz: 4f1262a4cf6d6e9357f9315729b9628b123034c5092867b9a48f78850acef31f
 SHA512:
-  metadata.gz: 0f6c2e262a74d874be53a627c09d5ec01f12d5d31bc078654c153034ec1588a1de07ddcfc69a0c386c83c582e16cdacb24fe6e6d383c0ca320853c34c2ec6f06
-  data.tar.gz: 06b09d654d37583068304b2743b9cb14baa7f11b712d8748f9686639c016f8b6d322708d1a77cf4499f70fc2d155f43306fea716c621f3759b150e4e54fd9ee3
+  metadata.gz: f2b150ac6dfedb611dd4e924b0497f6c9170122593401d13eff0e8771effc241f3512227fd592d2df6f49278c870015c6c3b7221fd9010e035a1635a4bf1464b
+  data.tar.gz: 7bffe90c34b3ba5a7576044fe6d2f5c0768dbffdf893ded31fb10bfb9425e57b99e1028fb2e5c37ee4eb2d6d5c28c70672b06c76cc19916a0f42a39f6f14e6f9

data/README.md

@@ -24,25 +24,31 @@ gem 'frausto'
 - **[ruby2faust](ruby2faust.md)** - Ruby DSL that generates Faust DSP code
 - **[faust2ruby](faust2ruby.md)** - Convert Faust DSP code to Ruby DSL
 
-## Quick Example
+## Quick Examples
 
 ```ruby
 require 'ruby2faust'
 
 code = Ruby2Faust.generate do
-  osc(440) >> lp(800) >> gain(0.3)
+  freq = hslider("freq", init: 48, min: 20, max: 100, step: 1) >> midi2hz >> smoo
+  amp = hslider("amp", init: -12, min: -60, max: 0, step: 1) >> db2linear >> smoo
+  osc(freq) >> lp(2000) >> gain(amp)
 end
 
 puts code
-# => import("stdfaust.lib");
-#    process = (os.osc(440) : fi.lowpass(1, 800) : *(0.3));
+# import("stdfaust.lib");
+#
+# process =
+#   os.osc(hslider("freq", 48, 20, 100, 1) : ba.midikey2hz : si.smoo)
+#   : fi.lowpass(1, 2000)
+#   : *(hslider("amp", -12, -60, 0, 1) : ba.db2linear : si.smoo);
 ```
 
 ```ruby
 require 'faust2ruby'
 
 ruby_code = Faust2Ruby.to_ruby('process = os.osc(440) : *(0.5);')
-# => "osc(440) >> gain(0.5)"
+# => "0.5 * osc(440)"
 ```
 
 ## License

data/bin/faust2ruby

@@ -18,7 +18,7 @@ parser = OptionParser.new do |opts|
   opts.separator ""
   opts.separator "Options:"
 
-  opts.on("-o", "--output FILE", "Output Ruby file (default: stdout)") do |file|
+  opts.on("-o", "--output FILE", "Output Ruby file (default: <input>.rb)") do |file|
     options[:output] = file
   end
 
@@ -74,6 +74,8 @@ else
   end
   source = File.read(input_path)
   input_name = input_path
+  # Default output to input.dsp.rb (unless expression-only mode or explicit -o)
+  options[:output] ||= "#{input_path}.rb" unless options[:expression_only]
 end
 
 begin

data/faust2ruby.md

@@ -4,8 +4,6 @@ Convert Faust DSP code to Ruby DSL code compatible with ruby2faust.
 
 ## Installation
 
-faust2ruby is included with the frausto gem:
-
 ```bash
 gem install frausto
 ```
@@ -15,29 +13,19 @@ gem install frausto
 ### Command Line
 
 ```bash
-# Convert a Faust file to Ruby
-faust2ruby input.dsp -o output.rb
+# Convert a Faust file to Ruby (writes to file.dsp.rb)
+faust2ruby file.dsp
+
+# Specify output file
+faust2ruby file.dsp -o other.rb
 
-# Output only the process expression (no boilerplate)
-faust2ruby -e input.dsp
+# Output only the process expression (no boilerplate, to stdout)
+faust2ruby -e file.dsp
 
 # Read from stdin
 echo 'process = os.osc(440) : *(0.5);' | faust2ruby -e
 ```
 
-### Options
-
-```
-Usage: faust2ruby [options] <input.dsp>
-  -o, --output FILE    Output Ruby file (default: stdout)
-  -e, --expression     Output only process expression (no boilerplate)
-  -v, --verbose        Verbose output (show parsing info)
-  -t, --tokens         Show lexer tokens (debug mode)
-  -a, --ast            Show AST (debug mode)
-  --version            Show version
-  -h, --help           Show help
-```
-
 ### Ruby API
 
 ```ruby
@@ -46,106 +34,67 @@ require 'faust2ruby'
 # Convert Faust to Ruby code
 faust_code = 'process = os.osc(440) : *(0.5);'
 ruby_code = Faust2Ruby.to_ruby(faust_code)
-puts ruby_code
 
 # Expression only
 ruby_expr = Faust2Ruby.to_ruby(faust_code, expression_only: true)
-# => "(osc(440) >> gain(0.5))"
-
-# Parse to AST
-program = Faust2Ruby.parse(faust_code)
-
-# Tokenize
-tokens = Faust2Ruby.tokenize(faust_code)
+# => "0.5 * osc(440)"
 ```
 
 ## Examples
 
 ### Simple Oscillator
 
-**Input (Faust):**
 ```faust
 process = os.osc(440) : *(0.5);
 ```
-
-**Output (Ruby):**
 ```ruby
-require 'ruby2faust'
-include Ruby2Faust::DSL
-
-process = (osc(440) >> gain(0.5))
-
-puts Ruby2Faust::Emitter.program(process)
+0.5 * osc(440)
 ```
 
 ### Synthesizer with Controls
 
-**Input (Faust):**
 ```faust
 import("stdfaust.lib");
-declare name "synth";
-
 freq = hslider("freq", 440, 20, 20000, 1);
-gain = hslider("gain", 0.5, 0, 1, 0.01);
-
-process = os.osc(freq) : *(gain);
+amp = hslider("amp", 0.5, 0, 1, 0.01);
+process = os.osc(freq) : *(amp);
 ```
-
-**Output (Ruby):**
 ```ruby
-require 'ruby2faust'
-include Ruby2Faust::DSL
-
-# declare name "synth"
-
-freq = slider("freq", init: 440, min: 20, max: 20000, step: 1)
-
-gain = slider("gain", init: 0.5, min: 0, max: 1, step: 0.01)
-
-process = (osc(freq) >> gain(gain))
-
-puts Ruby2Faust::Emitter.program(process)
+freq = hslider("freq", init: 440, min: 20, max: 20000, step: 1)
+amp = hslider("amp", init: 0.5, min: 0, max: 1, step: 0.01)
+process = amp * osc(freq)
 ```
 
-### Parallel Composition
+### Stereo Output
 
-**Input (Faust):**
 ```faust
 process = os.osc(440) , os.osc(880);
 ```
-
-**Output (Ruby):**
 ```ruby
-(osc(440) | osc(880))
+osc(440) | osc(880)
 ```
 
-### Feedback Loop
+### Feedback Delay
 
-**Input (Faust):**
 ```faust
 process = _ ~ (de.delay(44100, 22050) : *(0.5));
 ```
-
-**Output (Ruby):**
 ```ruby
-(wire ~ (delay(44100, 22050) >> gain(0.5)))
+wire ~ (0.5 * delay(44100, 22050))
 ```
 
 ### Iteration
 
-**Input (Faust):**
 ```faust
 process = par(i, 4, os.osc(i * 100));
 ```
-
-**Output (Ruby):**
 ```ruby
-fpar(4) { |i| osc((i * 100)) }
+fpar(4) { |i| osc(i * 100) }
 ```
 
-## Supported Faust Constructs
+## Mapping Overview
 
-### Composition Operators
+### Composition
 
 | Faust | Ruby |
 |-------|------|
@@ -154,88 +103,27 @@ fpar(4) { |i| osc((i * 100)) }
 | `a <: b` | `a.split(b)` |
 | `a :> b` | `a.merge(b)` |
 | `a ~ b` | `a ~ b` |
+| `*(x)` | `x *` (idiomatic) or `gain(x)` |
 
-### Arithmetic
+### Numeric Extensions
 
-| Faust | Ruby |
-|-------|------|
-| `a + b` | `a + b` |
-| `a - b` | `a - b` |
-| `a * b` | `a * b` |
-| `a / b` | `a / b` |
-| `a % b` | `a % b` |
-| `*(x)` | `gain(x)` |
-
-### Comparison
+When arguments are numeric literals, faust2ruby emits idiomatic Ruby:
 
 | Faust | Ruby |
 |-------|------|
-| `a < b` | `a < b` |
-| `a > b` | `a > b` |
-| `a <= b` | `a <= b` |
-| `a >= b` | `a >= b` |
-| `a == b` | `a.eq(b)` |
-| `a != b` | `a.neq(b)` |
-
-Note: `eq()` and `neq()` are methods because Ruby's `==` must return boolean.
-
-### Bitwise
-
-| Faust | Ruby |
-|-------|------|
-| `a & b` | `a & b` |
-| `a \| b` (bitwise) | `a.bor(b)` |
-| `xor(a, b)` | `a ^ b` |
-
-Note: `bor()` is a method because `\|` is used for parallel composition in the DSL.
+| `ba.db2linear(-6)` | `-6.db` |
+| `ba.midikey2hz(60)` | `60.midi` |
+| `ba.sec2samp(0.1)` | `0.1.sec` |
 
 ### Library Functions
 
-| Faust | Ruby |
-|-------|------|
-| `os.osc(f)` | `osc(f)` |
-| `os.sawtooth(f)` | `saw(f)` |
-| `os.square(f)` | `square(f)` |
-| `os.triangle(f)` | `triangle(f)` |
-| `no.noise` | `noise` |
-| `fi.lowpass(n, f)` | `lp(f, order: n)` |
-| `fi.highpass(n, f)` | `hp(f, order: n)` |
-| `fi.resonlp(f, q, g)` | `resonlp(f, q, g)` |
-| `de.delay(m, d)` | `delay(m, d)` |
-| `de.fdelay(m, d)` | `fdelay(m, d)` |
-| `en.adsr(a,d,s,r,g)` | `adsr(a, d, s, r, g)` |
-| `ba.db2linear(x)` | `db2linear(x)` |
-| `si.smoo` | `smoo` |
-| `sp.panner(p)` | `panner(p)` |
-
-### UI Elements
-
-| Faust | Ruby |
-|-------|------|
-| `hslider("n", i, mn, mx, s)` | `slider("n", init: i, min: mn, max: mx, step: s)` |
-| `vslider(...)` | `vslider(...)` |
-| `nentry(...)` | `nentry(...)` |
-| `button("n")` | `button("n")` |
-| `checkbox("n")` | `checkbox("n")` |
-| `hgroup("n", e)` | `hgroup("n") { e }` |
-| `vgroup("n", e)` | `vgroup("n") { e }` |
+Most `os.*`, `fi.*`, `de.*`, `en.*`, `ba.*`, `si.*`, `re.*`, `co.*`, `sp.*`, `aa.*`, `an.*`, `ef.*` functions are mapped. Examples:
 
-### Iteration
-
-| Faust | Ruby |
-|-------|------|
-| `par(i, n, e)` | `fpar(n) { \|i\| e }` |
-| `seq(i, n, e)` | `fseq(n) { \|i\| e }` |
-| `sum(i, n, e)` | `fsum(n) { \|i\| e }` |
-| `prod(i, n, e)` | `fprod(n) { \|i\| e }` |
-
-### Tables
-
-| Faust | Ruby |
-|-------|------|
-| `waveform{v1, v2, ...}` | `waveform(v1, v2, ...)` |
-| `rdtable(n, i, r)` | `rdtable(n, i, r)` |
-| `rwtable(n, i, w, s, r)` | `rwtable(n, i, w, s, r)` |
+- `os.osc(f)` → `osc(f)`
+- `fi.lowpass(n, f)` → `lp(f, order: n)`
+- `de.delay(m, d)` → `delay(m, d)`
+- `en.adsr(a,d,s,r,g)` → `adsr(a, d, s, r, g)`
+- `si.smoo` → `smoo`
 
 ### Primitives
 
@@ -245,164 +133,43 @@ Note: `bor()` is a method because `\|` is used for parallel composition in the D
 | `!` | `cut` |
 | `mem` | `mem` |
 | `ma.SR` | `sr` |
-| `ma.PI` | `pi` |
 
 ## Round-trip Conversion
 
-faust2ruby is designed to work with ruby2faust for round-trip conversion:
-
 ```ruby
-require 'faust2ruby'
-require 'ruby2faust'
+require 'frausto'
 
-# Faust → Ruby
+# Faust → Ruby → Faust
 faust_input = 'process = os.osc(440) : *(0.5);'
-ruby_code = Faust2Ruby.to_ruby(faust_input, expression_only: true)
+ruby_expr = Faust2Ruby.to_ruby(faust_input, expression_only: true)
 
-# Ruby → Faust
 include Ruby2Faust::DSL
-process = eval(ruby_code)
+process = eval(ruby_expr)
 faust_output = Ruby2Faust::Emitter.program(process)
 ```
 
-## With Clauses
+## Advanced Features
 
-`with` clauses are converted to Ruby lambdas for proper scoping:
+### With Clauses
+
+Local definitions are converted to Ruby lambdas:
 
-**Input (Faust):**
 ```faust
-myDSP = result with {
+myDSP = _ * gain with {
     gain = 0.5;
-    result = _ * gain;
 };
 ```
-
-**Output (Ruby):**
 ```ruby
 myDSP = -> {
   gain = 0.5
-  result = (wire * gain)
-  result
+  (wire * gain)
 }.call
 ```
 
-Function-style local definitions use `flambda`:
-```ruby
-adaa = flambda(:x0, :x1) { |x0, x1| select2(...) }
-```
-
-## Partial Application
-
-Faust's partial application creates reusable signal processors by providing some arguments upfront.
-
-### Clipping / Limiting
-
-**Input (Faust):**
-```faust
-// Clip signal to [-1, 1] range
-safetyLimit = min(1) : max(-1);
-process = osc(440) : safetyLimit;
-```
-
-**Output (Ruby):**
-```ruby
-safetyLimit = (flambda(:x) { |x| min_(x, 1) } >> flambda(:x) { |x| max_(x, (-1)) })
-process = (osc(440) >> safetyLimit)
-```
-
-### Conditional Routing
-
-**Input (Faust):**
-```faust
-// Switch between two signals based on condition
-useWet = checkbox("wet");
-effect = _ <: _, reverb : select2(useWet);
-```
-
-**Output (Ruby):**
-```ruby
-useWet = checkbox("wet")
-effect = wire.split(wire, reverb) >> flambda(:x, :y) { |x, y| select2(useWet, x, y) }
-```
-
-### Gain Stages
-
-**Input (Faust):**
-```faust
-// Partial application of multiplication
-halfGain = *(0.5);
-quarterGain = *(0.25);
-process = osc(440) : halfGain;
-```
-
-**Output (Ruby):**
-```ruby
-halfGain = gain(0.5)
-quarterGain = gain(0.25)
-process = (osc(440) >> halfGain)
-```
-
-### Filter Configuration
-
-**Input (Faust):**
-```faust
-// Second-order lowpass waiting for cutoff frequency
-smoothFilter = fi.lowpass(2);
-process = _ : smoothFilter(1000);
-```
-
-**Output (Ruby):**
-```ruby
-smoothFilter = flambda(:x) { |x| lp(x, order: 2) }
-process = (wire >> smoothFilter.call(1000))  # Note: needs .call in Ruby
-```
-
-### Math Functions as Processors
-
-**Input (Faust):**
-```faust
-// 0-arg functions applied to signals
-softclip(x) = tanh(x);
-process = osc(440) * 2 : softclip;
-```
-
-**Output (Ruby):**
-```ruby
-def softclip(x)
-  (x >> tanh_)
-end
-process = ((osc(440) * 2) >> softclip(wire))
-```
-
-## What Uses `literal()`
-
-Some Faust constructs are emitted as `literal()` calls to preserve semantics:
-
-| Construct | Example | Reason |
-|-----------|---------|--------|
-| Letrec blocks | `letrec { 'x = ... }` | Complex state semantics |
-| Unmapped library functions | `an.amp_follower(t)` | Not in library mapper |
-| Partial app (4+ args) | `route(4, 4, ...)` | Requires complex curry |
-
-Most common Faust library functions are mapped, including `fi.*`, `os.*`, `de.*`, `en.*`, `ba.*`, `si.*`, `aa.*`, and math primitives.
-
-## Limitations
-
-**Supported with limitations:**
-- `with` clauses: Local definitions work, scoped via Ruby lambda
-- Partial application: Works for 1-3 missing arguments
-- Forward references: Functions defined later in `with` blocks are resolved
-
-**Not supported:**
-- Pattern matching on function arguments (see below)
-- Foreign functions (`ffunction`)
-- Component/library imports beyond path tracking
-
 ### Case Expressions
 
-Case expressions with integer patterns are converted to `select2` chains:
+Faust's `case` creates a pattern-matching function—the `(n)` pattern binds the input signal to variable `n`:
 
-**Input (Faust):**
 ```faust
 process = case {
   (0) => 1;
@@ -410,114 +177,35 @@ process = case {
   (n) => n * 2;
 };
 ```
-
-**Output (Ruby):**
 ```ruby
-flambda(:n) { |n| select2(n.eq(0), select2(n.eq(1), (n * 2), 2), 1) }
+fcase(0 => 1, 1 => 2) { |n| (n * 2) }
 ```
 
-The variable pattern `(n)` becomes the default/else case, and integer patterns are checked in order.
-
-**Limitations:**
-- Only integer patterns are converted to `select2` (variable patterns become default)
-- Complex patterns (tuples, nested expressions) fall back to `literal()`
-- Recursive functions like `fact(0) = 1; fact(n) = n * fact(n-1)` require compile-time evaluation not available at runtime
+The `fcase` DSL method handles integer patterns as a hash, with the block as the default case.
 
-### Pattern Matching on Function Arguments
+### Partial Application
 
-Multi-rule function definitions with single-parameter pattern matching are now supported:
-
-**Input (Faust):**
 ```faust
-fact(0) = 1;
-fact(n) = n * fact(n - 1);
+halfGain = *(0.5);
+process = osc(440) : halfGain;
 ```
-
-**Output (Ruby):**
 ```ruby
-fact = flambda(:n) { |n| select2(n.eq(0), (n * fact((n - 1))), 1) }
+halfGain = gain(0.5)
+process = osc(440) >> halfGain
 ```
 
-Multiple definitions with the same name are automatically merged into a case expression, then converted to `select2` chains.
-
-**Limitations:**
-- Only single-parameter pattern matching is supported
-- Multi-parameter patterns (e.g., `foo(0, 0) = a; foo(x, y) = b;`) are not merged
-- Recursive functions like factorial require compile-time evaluation (the Ruby output is syntactically correct but may not produce the same runtime behavior)
-
-## Known Issues
-
-### letrec Blocks
-
-`letrec` blocks are emitted as `literal()` calls because they implement complex recursive state semantics that don't have a direct Ruby DSL equivalent.
-
-**Example Faust:**
-```faust
-// Spring-damper physics simulation
-follower(input) = pos letrec {
-    'v = v + step * (-damping * v - stiffness * (pos - input));
-    'pos = pos + step * v;
-};
-```
+## Limitations
 
-**Generated Ruby:**
-```ruby
-literal("letrec { 'v = (v + (step * ...)); 'pos = (pos + (step * v)) } pos")
-```
+**Not fully supported:**
+- `letrec` blocks (emitted as `literal()`)
+- Foreign functions (`ffunction`)
+- Multi-parameter pattern matching
+- Some library namespaces: `ve.*`, `pm.*`, `sy.*`, `dx.*`
 
-**Why this happens:**
-- `'v` means "next value of v" (sample n+1)
-- `v` means "current value of v" (sample n)
-- This creates mutually recursive signals with feedback
-- Ruby lacks native syntax for this pattern
-
-**Workarounds:**
-1. **Accept the literal** - Round-trip conversion still works; the Faust code is preserved
-2. **Use simple feedback** - For single-variable recursion, use `wire ~ expr` instead
-3. **Refactor in Faust** - Sometimes letrec can be rewritten using standard feedback
-
-**Impact:** In practice, letrec is rare. Complex DSP files like triode.lib (500+ lines) convert with only 1 literal remaining (the letrec block).
-
-### Unmapped Library Functions
-
-The following Faust library namespaces are not yet mapped and will emit `literal()`:
-
-| Namespace | Description | Status |
-|-----------|-------------|--------|
-| `ve.*` | Virtual analog (Moog filters, etc.) | Not mapped |
-| `pm.*` | Physical modeling | Not mapped |
-| `sy.*` | Synthesizers | Not mapped |
-| `dx.*` | DX7 emulation | Not mapped |
-| `pf.*` | Phaflangers | Not mapped |
-| `dm.*` | Demos | Not mapped |
-
-**Currently mapped:**
-- `os.*` - Oscillators (osc, saw, square, triangle, phasor, lf_*)
-- `no.*` - Noise (noise, pink_noise)
-- `fi.*` - Filters (lowpass, highpass, resonlp, svf.*, allpass, dcblocker, peak_eq, tf1/tf2, etc.)
-- `de.*` - Delays (delay, fdelay, sdelay)
-- `en.*` - Envelopes (ar, asr, adsr, adsre)
-- `ba.*` - Basics (db2linear, linear2db, tau2pole, midikey2hz, selectn, if, take)
-- `si.*` - Signals (smooth, smoo, bus, block)
-- `ma.*` - Math (SR, PI, tempo, tanh)
-- `re.*` - Reverbs (mono_freeverb, zita_rev1_stereo, jpverb)
-- `co.*` - Compressors (compressor_mono, limiter_1176_R4_mono)
-- `sp.*` - Spatial (panner)
-- `aa.*` - Antialiasing (tanh1, tanh2, arctan, softclip, hardclip, etc.)
-- `an.*` - Analyzers (amp_follower, amp_follower_ar, rms_envelope_*, abs_envelope_*, peak_envelope)
-- `ef.*` - Effects (gate_mono/stereo, flanger_mono/stereo, phaser2_mono/stereo, wah4, auto_wah, crybaby, echo, transpose, vocoder, speakerbp, cubicnl, dryWetMixer)
-- Math primitives (sin, cos, tan, tanh, sinh, cosh, abs, min, max, pow, sqrt, exp, log, floor, ceil, etc.)
-
-**Contributing:** To add support for unmapped functions, edit `lib/faust2ruby/library_mapper.rb` and add corresponding entries to `lib/ruby2faust/ir.rb`, `lib/ruby2faust/dsl.rb`, and `lib/ruby2faust/emitter.rb`.
+Unmapped functions are preserved as `literal("...")` for round-trip compatibility.
 
 ## Architecture
 
 ```
 Faust Source → Lexer → Parser → AST → Ruby Generator → Ruby DSL
 ```
-
-- **Lexer** (`lexer.rb`): StringScanner-based tokenizer
-- **Parser** (`parser.rb`): Recursive descent parser
-- **AST** (`ast.rb`): Abstract syntax tree nodes
-- **Generator** (`ruby_generator.rb`): Produces Ruby DSL code
-- **Library Mapper** (`library_mapper.rb`): Maps Faust functions to Ruby methods