ruck 0.2.0 → 0.3.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2010 Tom Lieber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,146 @@
+# ruck: a port of ChucK's strong timing to Ruby!
+
+ruck lets you create virtual timelines on which you can
+precisely time the execution of events.
+
+This is accomplished using Shred, Clock, and Shreduler:
+
+- Shred: a resumable Proc
+- Clock: manages occurrences on a timeline
+- Shreduler: executes shreds on time
+
+Here's an example of how to use Shred:
+
+    shred = Ruck::Shred.new do
+      puts "A"
+      Ruck::Shred.current.pause
+      puts "B"
+      Ruck::Shred.current.pause
+      puts "C"
+    end
+    
+    shred.call
+    shred.call
+    shred.call
+    
+    # prints:
+    # A
+    # B
+    # C
+
+Here's how Clock works:
+
+    clock = Ruck::Clock.new
+    
+    clock.schedule("C", 3)
+    clock.schedule("B", 2)
+    clock.schedule("A", 1)
+    
+    3.times do
+      letter, time = clock.unschedule_next
+      puts "#{letter} @ #{time}"
+    end
+    
+    # prints:
+    # A @ 1.0
+    # B @ 2.0
+    # C @ 3.0
+
+Here's how these two are combined with Shreduler:
+
+    @shreduler = Ruck::Shreduler.new
+    
+    @shreduler.shredule(Ruck::Shred.new do
+      %w{ A B C D E }.each do |letter|
+        puts "#{letter}"
+        @shreduler.shredule(Ruck::Shred.current, @shreduler.now + 1)
+        Ruck::Shred.current.pause
+      end
+    end)
+    
+    @shreduler.shredule(Ruck::Shred.new do
+      %w{ 1 2 3 4 5 }.each do |number|
+        puts "#{number}"
+        @shreduler.shredule(Ruck::Shred.current, @shreduler.now + 1)
+        Ruck::Shred.current.pause
+      end
+    end)
+    
+    @shreduler.run
+    
+    # prints
+    # A
+    # 1
+    # B
+    # 2
+    # C
+    # 3
+    # D
+    # 4
+    # E
+    # 5
+
+Though this is somewhat inconvenient to use, so when you're
+using just one global Shreduler, you can call
+Shreduler#make_convenient, which adds useful methods to Object
+and Shred so that you can write the above example more
+concisely:
+
+    @shreduler = Ruck::Shreduler.new
+    @shreduler.make_convenient
+
+    spork do
+      %w{ A B C D E }.each do |letter|
+        puts "#{letter}"
+        Ruck::Shred.yield(1)
+      end
+    end
+
+    spork do
+      %w{ 1 2 3 4 5 }.each do |number|
+        puts "#{number}"
+        Ruck::Shred.yield(1)
+      end
+    end
+
+    @shreduler.run
+
+## Shredulers and time
+
+ruck doesn't specify any behavior for when time passes,
+so by default all shreds are executed as fast as possible
+as they're drained from the queue. In other words, there's
+no mapping from virtual time to anything else, so Shreduler
+only really cares about order.
+
+You change this by sub-classing Shreduler and overriding its
+methods. For example, an easy modification is to map the
+time units to seconds:
+
+    class RealTimeShreduler < Ruck::Shreduler
+      def fast_forward(dt)
+        super
+        sleep(dt)
+      end
+    end
+
+## Useful Shredulers
+
+These gems provide shredulers with other interesting mappings,
+as well as defining convenient DSLs to make shreduling less
+verbose:
+
+<dl>
+<dt>ruck-realtime</dt>
+<dd>the above example</dd>
+
+<dt>ruck-midi</dt>
+<dd>maps to quarter notes in a MIDI file, quarter
+notes in real-time, or both simultaneously (playing back,
+then saving to disk)</dd>
+
+<dt>ruck-ugen</dt>
+<dd>maps to samples in an audio stream, providing a
+simple unit generator framework for reading and writing WAV
+files with effects</dd>
+</dl>

data/Rakefile

@@ -15,11 +15,22 @@ begin
       to its virtual clock. Schedulers can map virtual time to samples
       in a WAV file, real time, time in a MIDI file, or anything else
       by overriding "sim_to" in the Shreduler class.
+      
+      A small library of useful unit generators and plenty of examples
+      are provided. See the README or the web page for details.
     EOF
     gem.has_rdoc = false
+    gem.add_dependency "PriorityQueue", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
   puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
 end
+
+if require "spec/rake/spectask"
+  desc "Run all specs"
+  Spec::Rake::SpecTask.new("spec") do |t|
+    t.spec_files = FileList["spec/**/*.rb"]
+  end
+end

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/examples/ex01.rb

@@ -0,0 +1,27 @@
+
+require "ruck"
+
+include Ruck
+
+shred1 = Shred.new do |shred|
+  puts "A"
+  Shred.current.pause
+  puts "B"
+  Shred.current.pause
+  puts "C"
+end
+
+shred2 = Shred.new do |shred|
+  puts "1"
+  Shred.current.pause
+  puts "2"
+  Shred.current.pause
+  puts "3"
+end
+
+shred1.call
+shred2.call
+shred1.call
+shred2.call
+shred1.call
+shred2.call

data/examples/ex02.rb

@@ -0,0 +1,31 @@
+
+require "ruck"
+
+include Ruck
+
+class RealTimeShreduler < Shreduler
+  def fast_forward(dt)
+    super
+    sleep(dt)
+  end
+end
+
+@shreduler = RealTimeShreduler.new
+
+@shreduler.shredule(Shred.new do
+  %w{ A B C D E }.each do |letter|
+    puts "#{letter}"
+    @shreduler.shredule(Shred.current, @shreduler.now + 1)
+    Shred.current.pause
+  end
+end)
+
+@shreduler.shredule(Shred.new do
+  %w{ 1 2 3 4 5 }.each do |number|
+    puts "#{number}"
+    @shreduler.shredule(Shred.current, @shreduler.now + 1)
+    Shred.current.pause
+  end
+end)
+
+@shreduler.run

data/examples/ex03.rb

@@ -0,0 +1,75 @@
+
+require "rubygems"
+require "midiator"
+require "ruck"
+
+include Ruck
+
+def setup_midi
+  midi = MIDIator::Interface.new
+  # midi.autodetect_driver
+  midi.use :dls_synth # OS X built-in synth
+
+  midi.control_change 32, 10, 1 # TR-808 is Program 26 in LSB bank 1
+  midi.program_change 10, 26
+  
+  include MIDIator::Drums
+  
+  midi
+end
+
+class RealTimeShreduler < Shreduler
+  def fast_forward(dt)
+    super
+    sleep(dt)
+  end
+end
+
+
+
+@midi = setup_midi
+@shreduler = RealTimeShreduler.new
+
+@warped_clock = @shreduler.clock.add_child_clock(Clock.new)
+
+
+# warped bass drum player
+@shreduler.shredule(Shred.new do
+  loop do
+    @midi.note_on(BassDrum1, 10, 127)
+    @midi.note_on(BassDrum1, 10, 127)
+    
+    @shreduler.shredule(Shred.current, @warped_clock.now + 1, @warped_clock)
+    Shred.current.pause
+  end
+end, nil, @warped_clock)
+
+
+# normal crash cymbal player
+@shreduler.shredule(Shred.new do
+  loop do
+    @midi.note_on(CrashCymbal1, 10, 127)
+    @midi.note_on(CrashCymbal1, 10, 127)
+    
+    @shreduler.shredule(Shred.current, @shreduler.now + 1)
+    Shred.current.pause
+  end
+end)
+
+
+# time warper
+@shreduler.shredule(Shred.new do |shred|
+  p = 0.0
+  
+  loop do
+    bpm = Math.sin(p += 0.1) * 270.0 + 300.0
+    @warped_clock.relative_rate = bpm / 60.0
+    puts "#{bpm} bpm"
+    
+    @shreduler.shredule(Shred.current, @shreduler.now + 0.1)
+    Shred.current.pause
+  end
+end)
+
+
+@shreduler.run

data/examples/ex04.rb

@@ -0,0 +1,33 @@
+
+# this example demonstrates Shreduler#make_convenient,
+# which adds Object#spork and Shred#yield
+
+require "ruck"
+
+include Ruck
+
+class RealTimeShreduler < Shreduler
+  def fast_forward(dt)
+    super
+    sleep(dt)
+  end
+end
+
+@shreduler = RealTimeShreduler.new
+@shreduler.make_convenient
+
+spork do
+  %w{ A B C D E }.each do |letter|
+    puts "#{letter}"
+    Shred.yield(1)
+  end
+end
+
+spork do
+  %w{ 1 2 3 4 5 }.each do |number|
+    puts "#{number}"
+    Shred.yield(1)
+  end
+end
+
+@shreduler.run

data/examples/ex05.rb

@@ -0,0 +1,33 @@
+
+require "ruck"
+
+include Ruck
+
+class RealTimeShreduler < Shreduler
+  def fast_forward(dt)
+    super
+    sleep(dt)
+  end
+end
+
+@shreduler = RealTimeShreduler.new
+@shreduler.make_convenient
+
+spork_loop(:gogogo) do
+  puts "YEE HAW!"
+  puts
+end
+
+spork do
+  loop do
+    Shred.yield(1)
+    puts "not yet"
+    Shred.yield(1)
+    puts "still not yet"
+    Shred.yield(1)
+    puts "okay now!"
+    raise_event(:gogogo)
+  end
+end
+
+@shreduler.run

data/examples/ex06.rb

@@ -0,0 +1,110 @@
+
+require "rubygems"
+require "midiator"
+require "ruck"
+
+include Ruck
+
+def setup_midi
+  midi = MIDIator::Interface.new
+  # midi.autodetect_driver
+  midi.use :dls_synth # OS X built-in synth
+  
+  include MIDIator::Drums
+  
+  midi
+end
+
+class RealTimeShreduler < Ruck::Shreduler
+  def run
+    @start_time = Time.now
+    @simulated_now = 0
+    super
+  end
+  
+  def fast_forward(dt)
+    super
+    
+    actual_now = Time.now - @start_time
+    @simulated_now += dt
+    if @simulated_now > actual_now
+      sleep(@simulated_now - actual_now)
+    end
+  end
+end
+
+
+@midi = setup_midi
+@shreduler = RealTimeShreduler.new
+@shreduler.make_convenient
+
+@scale = [0, 2, 4, 5, 7, 9, 11]
+@base = 30
+def to_scale(note)
+  @base + @scale[note % @scale.length] + 12 * (note / @scale.length).to_i
+end
+
+spork_loop(0.2) do
+  @midi.play([to_scale((rand * 21).to_i), to_scale((rand * 21).to_i)])
+end
+
+spork_loop do
+  puts "major"
+  # @base = 30
+  @scale = [0, 2, 4, 5, 7, 9, 11]
+  Shred.yield 5
+  
+  puts "minor"
+  # @base = 32
+  @scale = [0, 2, 3, 5, 7, 8, 11]
+  Shred.yield 5
+end
+
+@shreduler.run
+
+exit
+
+
+@warped_clock = @shreduler.clock.add_child_clock(Clock.new)
+
+
+# warped bass drum player
+@shreduler.shredule(Shred.new do
+  loop do
+    @midi.note_on(BassDrum1, 10, 127)
+    @midi.note_on(BassDrum1, 10, 127)
+    
+    @shreduler.shredule(Shred.current, @warped_clock.now + 1, @warped_clock)
+    Shred.current.pause
+  end
+end, nil, @warped_clock)
+
+
+# normal crash cymbal player
+@shreduler.shredule(Shred.new do
+  loop do
+    @midi.note_on(CrashCymbal1, 10, 127)
+    @midi.note_on(CrashCymbal1, 10, 127)
+    
+    @shreduler.shredule(Shred.current, @shreduler.now + 1)
+    Shred.current.pause
+  end
+end)
+
+
+# time warper
+@shreduler.shredule(Shred.new do |shred|
+  p = 0.0
+  
+  loop do
+    bpm = Math.sin(p += 0.1) * 270.0 + 300.0
+    @warped_clock.relative_rate = bpm / 60.0
+    puts "#{bpm} bpm"
+    
+    @shreduler.shredule(Shred.current, @shreduler.now + 0.1)
+    Shred.current.pause
+  end
+end)
+
+
+@shreduler.run