micromidi 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f2f1df337f1568e1e5b327664ee14734eae8095a
-  data.tar.gz: 45fa44750f71f646414883b7103ccadf9162c7d6
+  metadata.gz: d899af108dba8fc0eb7b830cdc53ecf65f8a9946
+  data.tar.gz: 947eb84dfbba8084a55359b460effd7da0bfa881
 SHA512:
-  metadata.gz: 9afb9c4ef330f7cb29b9baf02d37371055487f27f6833f46d99dc46c81161fe0dba982f27572f00422b8dfa20566d6901fbd34069df83ac65399c9e9e38e3a8d
-  data.tar.gz: fa2eb27bdb3162c12a8fac1f6ba72edba97e5e1e6891a43df5c7ca20afe8f006b64ebb41239e544d15bc6495c5fafb9f0e896060b6ab7015c3ebfdc206899e25
+  metadata.gz: 738e6469b03feff4fdf5f64027ca32f2d6341c18f0f2767b0dcc810b265c16cf4290fc13ac862ec0eeedc339ef43d6379ba590c93612fccce2d68e15450a697e
+  data.tar.gz: c9b87df40f972394d975d23d3ba35de7b8bf145efce20857504f069d02857e4c53401ce9358a7e88d1b401c09d1d536734a7f5efc84360db143ad0c4430586a4

data/lib/micromidi.rb

@@ -3,8 +3,8 @@
 #
 # A Ruby DSL for MIDI
 #
-# (c)2011-2014 Ari Russo 
-# licensed under the Apache 2.0 License
+# (c)2011-2014 Ari Russo
+# Apache 2.0 License
 #
 
 # libs
@@ -15,6 +15,7 @@ require "midi-message"
 require "unimidi"
 
 # modules
+require "micromidi/device"
 require "micromidi/instructions/composite"
 require "micromidi/module_methods"
 
@@ -32,9 +33,8 @@ require "micromidi/instructions/sysex"
 require "micromidi/instructions/shorthand"
 
 module MicroMIDI
-  
-  VERSION = "0.1.3"
+
+  VERSION = "0.1.4"
 
 end
 MIDI = MicroMIDI
-

data/lib/micromidi/context.rb

@@ -1,41 +1,54 @@
 module MicroMIDI
-  
+
+  # The DSL context
   class Context
-    
+
     include Instructions::Composite
     extend Forwardable
-    
+
     attr_reader :state
-    
+
     def_delegator :state, :output_cache, :cache
-            
-    def initialize(ins, outs, &block)
-      
-      @state = State.new(ins, outs)
-      
+
+    # @param [Array<UniMIDI::Input>, UniMIDI::Input] inputs
+    # @param [Array<UniMIDI::Output, IO>, IO, UniMIDI::Output] outputs
+    # @param [Proc] block
+    def initialize(inputs, outputs, &block)
+
+      @state = State.new(inputs, outputs)
+
       @instructions = {
         :process => Instructions::Process.new(@state),
-        :input => Instructions::Input.new(@state),      
+        :input => Instructions::Input.new(@state),
         :message => Instructions::Message.new(@state),
         :output => Instructions::Output.new(@state),
         :sticky => Instructions::Sticky.new(@state),
         :sysex => Instructions::SysEx.new(@state)
       }
-       
-      edit(&block) unless block.nil?
+
+      edit(&block) if block_given?
     end
-    
-    # Open a block for editing/live coding in this Context
+
+    # Eval a block for editing/live coding in this context
+    # @param [Proc] block
+    # @return [Object]
     def edit(&block)
       instance_eval(&block)
     end
-    
+
     # Repeat the last instruction in the history
+    # @return [Object]
     def repeat
-      send(@state.last_command[:method], *@state.last_command[:args]) unless @state.last_command.nil?
+      unless @state.last_command.nil?
+        send(@state.last_command[:method], *@state.last_command[:args])
+      end
     end
-    
+
     # Delegates a command to one of the instruction classes
+    # @param [Symbol] method
+    # @param [*Object] args
+    # @param [Proc] block
+    # @return [Object]
     def method_missing(method, *args, &block)
       results = delegate(method, args, &block)
       if results.empty?
@@ -53,11 +66,17 @@ module MicroMIDI
     private
 
     # Should a message that resulted from the given instruction type be outputted?
+    # @param [Symbol] instruction_type
+    # @return [Boolean]
     def output?(instruction_type)
       @state.auto_output && [:sysex, :message, :process].include?(instruction_type)
     end
 
-    # Delegate a command 
+    # Delegate a command
+    # @param [Symbol] method
+    # @param [*Object] args
+    # @param [Proc] block
+    # @return [Object]
     def delegate(method, args, &block)
       results = @instructions.map do |key, instruction|
         if instruction.respond_to?(method)
@@ -70,6 +89,6 @@ module MicroMIDI
       end
       results.compact
     end
-        
+
   end
 end

data/lib/micromidi/device.rb

@@ -0,0 +1,37 @@
+module MicroMIDI
+
+  # Deal with MIDI devices
+  module Device
+
+    extend self
+
+    # Is the given device a MIDI input?
+    # @param [Object] device
+    # @return [Boolean]
+    def input?(device)
+      device.respond_to?(:type) && device.type == :input && device.respond_to?(:gets)
+    end
+
+    # Is the given device a MIDI output?
+    # @param [Object] device
+    # @return [Boolean]
+    def output?(device)
+      device.respond_to?(:puts)
+    end
+
+    # Select the MIDI inputs from the given objects
+    # @params [*Object] args
+    # @return [Array<UniMIDI::Input>]
+    def get_inputs(*args)
+      [args].flatten.select { |device| input?(device) }
+    end
+
+    # Select the MIDI outputs from the given objects
+    # @params [*Object] args
+    # @return [Array<UniMIDI::Output, IO>]
+    def get_outputs(*args)
+      [args].flatten.select { |device| output?(device) }
+    end
+
+  end
+end

data/lib/micromidi/instructions/composite.rb

@@ -1,31 +1,35 @@
 module MicroMIDI
 
   module Instructions
-    
+
+    # Commands that are composites of other commands
     module Composite
-      
+
       #
-      # Plays a note or notes, for a certain duration.
+      # Play a note or notes, for the given duration.
       #
-      # The first argument must be a note name (String), MIDIMessage::NoteOn object, or array of either
-      # the last argument must be a Numeric (representing the duration)
+      # The first argument must be: [Array<String>, Array<MIDIMessage::NoteOn>, String, MIDIMessage::NoteOn]
+      # The last argument must be [Numeric] representing the duration
       #
-      # Additional arguments should be note names or MIDIMessage::NoteOn objects and will 
-      # be played as a chord with the first argument.
+      # Additional arguments can be [Array<String>, Array<MIDIMessage::NoteOn>, String, MIDIMessage::NoteOn] and will
+      # be played as a chord simultaneously with the first argument.
       #
+      # @param [*Object] args
+      # @return [Array<MIDIMessage::NoteOn>, MIDIMessage::NoteOn]
       def play(*args)
         raise "Last argument must be a Numeric duration" unless args.last.kind_of?(Numeric)
-        
+        args = args.dup
         duration = args.pop
         note_or_notes = [args].flatten
         messages = as_note_messages(note_or_notes)
         sleep(duration)
         send_note_offs(messages)
-        
+
         messages.count > 1 ? messages : messages.first
       end
-      
-      # sends a note off message for every note on every channel
+
+      # Send a note off message for every note on every channel
+      # @return [Boolean]
       def all_off
         (0..15).each do |channel|
           (0..127).each do |note_num|
@@ -38,21 +42,28 @@ module MicroMIDI
 
       private
 
+      # Send note off messages for the given note messages
+      # @param [Array<MIDIMessage::NoteOn, MIDIMessage::NoteOff>] messages
+      # @return [Boolean]
       def send_note_offs(messages)
-        messages.each do |message| 
+        messages.each do |message|
           note_off(message.note, :channel => message.channel, :velocity => message.velocity)
         end
+        true
       end
 
+      # MIDI note message objects for the given arguments
+      # @param [Array<MIDIMessage::NoteOn, MIDIMessage::NoteOff, Fixnum, String>] note_or_notes
+      # @return [Array<MIDIMessage::NoteOn>]
       def as_note_messages(note_or_notes)
-        note_or_notes.map do |note|
-          case note
-            when Numeric, String then note(note)
-            when MIDIMessage then note 
+        note_or_notes.map do |item|
+          case item
+          when Fixnum, String then note(item)
+          when MIDIMessage then item
           end
         end
       end
-      
+
     end
 
   end

data/lib/micromidi/instructions/input.rb

@@ -1,23 +1,29 @@
 module MicroMIDI
 
   module Instructions
-    
+
+    # Commands dealing with MIDI input
     class Input
-   
+
+      # @param [State] state
       def initialize(state)
         @state = state
       end
 
-      # bind an event that will be called every time a message is received
-      def receive(*args, &block)
-        message_options = args.dup
-        options = message_options.last.kind_of?(Hash) ? message_options.pop : {}
-        unless message_options.empty?
-          match = { :class => message_classes(message_options) }
+      # Bind an event that will be fired when a message is received
+      # @param [*Object] args Types of messages to filter on eg :note_on, :control_change
+      # @param [Proc] callback The event callback
+      # @return [Boolean]
+      def receive(*args, &callback)
+        args = args.dup
+        options = args.last.kind_of?(Hash) ? args.pop : {}
+        unless args.empty?
+          match = { :class => message_classes(args) }
         end
-        listener(match, options) do |event| 
+        listener(match, options) do |event|
           yield(event[:message], event[:timestamp])
         end
+        true
       end
       alias_method :gets, :receive
       alias_method :handle, :receive
@@ -25,11 +31,15 @@ module MicroMIDI
       alias_method :listen_for, :receive
       alias_method :when_receive, :receive
 
-      def receive_unless(*args, &block)
-        message_options = args.dup
-        options = message_options.last.kind_of?(Hash) ? message_options.pop : {}
-        match = message_classes(message_options)
-        listener(nil, options) do |event| 
+      # Bind an event that will be fired when a message is received
+      # @param [*Object] args Types of messages to filter out eg :note_on, :control_change
+      # @param [Proc] callback The event callback
+      # @return [Boolean]
+      def receive_unless(*args, &callback)
+        args = args.dup
+        options = args.last.kind_of?(Hash) ? args.pop : {}
+        match = message_classes(args)
+        listener(nil, options) do |event|
           yield(event[:message], event[:timestamp]) unless match.include?(event[:message].class)
         end
       end
@@ -38,45 +48,66 @@ module MicroMIDI
       alias_method :listen_for_unless, :receive_unless
       alias_method :unless_receive, :receive_unless
 
-      # send input messages thru to the outputs
+      # Send input messages thru to the outputs
       def thru
         thru_if
       end
 
-      # send input messages thru to the outputs if it has a specific class
+      # Send input messages thru to the outputs if they have a specified class
+      # @param [*Object] args
+      # @return [Boolean]
       def thru_if(*args)
-        receive_options = thru_options(args)
+        receive_options = thru_arguments(args)
         receive(*receive_options) { |message, timestamp| output(message) }
+        true
       end
 
-      # send input messages thru to the outputs unless of a specific class
+      # Send input messages thru to the outputs unless they're of the specified class
+      # @param [*Object] args
+      # @return [Boolean]
       def thru_unless(*args)
-        receive_options = thru_options(args)
+        receive_options = thru_arguments(args)
         receive_unless(*receive_options) { |message, timestamp| output(message) }
       end
-      
-      # like <em>thru_unless</em> except a block can be passed that will be called when
-      # notes specified as the <em>unless</em> arrive
-      def thru_except(*args, &block)
+
+      # Similar to Input#thru_unless except a callback can be passed that will be fired when notes specified arrive
+      # @param [*Object] args
+      # @param [Proc] callback
+      # @return [Boolean]
+      def thru_except(*args, &callback)
         thru_unless(*args)
-        receive(*args, &block)        
+        receive(*args, &callback)
       end
-            
-      # wait for input on the last input passed in
-      # can pass the option :from => [an input] to specify which one to wait on
+
+      # Wait for input on the last input passed in (blocking)
+      # Can pass the option :from => [an input] to specify which one to wait on
+      # @param [Hash] options
+      # @option options [UniMIDI::Input] :from
+      # @return [Boolean]
       def wait_for_input(options = {})
         listener = options[:from] || @state.listeners.last || @state.thru_listeners.last
         listener.join
+        true
       end
-      
+
+      # Join the listener thread
+      # @return [Boolean]
       def join
         loop { wait_for_input }
+        true
       end
 
       protected
 
+      # Initialize input event listeners for the given inputs and options
+      # @param [Hash] match
+      # @param [Hash] options
+      # option options [Array<UniMIDI::Input>, UniMIDI::Input] :from
+      # option options [Boolean] :start
+      # option options [Boolean] :thru
       def listener(match, options = {}, &block)
         inputs = options[:from] || @state.inputs
+        inputs = [inputs].flatten
         do_thru = options.fetch(:thru, false)
         should_start = options.fetch(:start, true)
         match ||= {}
@@ -89,21 +120,29 @@ module MicroMIDI
 
       private
 
-      def initialize_listener(input, match, do_thru, &block)
+      # Initialize an input event listener
+      # @param [UniMIDI::Input] input
+      # @param [Hash] match
+      # @param [Boolean] do_thru
+      # @param [Proc] callback
+      # @return [MIDIEye::Listener]
+      def initialize_listener(input, match, do_thru, &callback)
         listener = MIDIEye::Listener.new(input)
-        listener.listen_for(match, &block)
+        listener.listen_for(match, &callback)
         if do_thru
           @state.thru_listeners.each(&:stop)
           @state.thru_listeners.clear
           @state.thru_listeners << listener
-        else 
+        else
           @state.listeners << listener
-        end 
+        end
         listener
       end
 
-      # The options for using thru
-      def thru_options(args)
+      # The arguments for using thru
+      # @param [Array<Object>] args
+      # @return [Array<Object, Hash>]
+      def thru_arguments(args)
         receive_options = args.dup
         if receive_options.last.kind_of?(Hash)
           receive_options.last[:thru] = true
@@ -113,9 +152,12 @@ module MicroMIDI
         receive_options
       end
 
-      def message_classes(list)
-        list.map do |type|
-          case type
+      # Get the MIDIMessage class for the given note name
+      # @param [Array<String, Symbol>] type_list
+      # @return [Array<Class>]
+      def message_classes(type_list)
+        classes = type_list.map do |type|
+          case type.to_sym
           when :aftertouch, :pressure, :aft then [MIDIMessage::ChannelAftertouch, MIDIMessage::PolyphonicAftertouch]
           when :channel_aftertouch, :channel_pressure, :ca, :cp then MIDIMessage::ChannelAftertouch
           when :control_change, :cc, :c then MIDIMessage::ControlChange
@@ -126,7 +168,8 @@ module MicroMIDI
           when :polyphonic_aftertouch, :poly_aftertouch, :poly_pressure, :polyphonic_pressure, :pa, :pp then MIDIMessage::PolyphonicAftertouch
           when :program_change, :pc, :p then MIDIMessage::ProgramChange
           end
-        end.flatten.compact
+        end
+        classes.flatten.compact
       end
 
     end