micromidi 0.1.3 → 0.1.4

data/lib/micromidi/instructions/message.rb

@@ -1,24 +1,36 @@
 module MicroMIDI
 
   module Instructions
-    
+
+    # Commands that deal with MIDI messages
     class Message
-      
+
+      # @param [State] state
       def initialize(state)
         @state = state
       end
-      
-      # create a control change message
+
+      # Create a MIDI control change message
+      # @param [Fixnum, String] id Control name or index
+      # @param [Fixnum] value
+      # @param [Hash] options
+      # @option options [Fixnum] :channel
+      # @return [MIDIMessage::ControlChange]
       def control_change(id, value, options = {})
         properties = @state.message_properties(options, :channel)
-        if id.kind_of?(Numeric)
+        if id.kind_of?(Fixnum)
           MIDIMessage::ControlChange.new(properties[:channel], id, value)
         else
           MIDIMessage::ControlChange[id].new(properties[:channel], value)
         end
       end
 
-      # create a note message
+      # Create a MIDI note on message
+      # @param [Fixnum, String] id Note name or index
+      # @param [Hash] options
+      # @option options [Fixnum] :channel
+      # @option options [Fixnum] :velocity
+      # @return [MIDIMessage::NoteOn]
       def note(id, options = {})
         properties = @state.message_properties(options, :channel, :velocity)
         note = note_message(MIDIMessage::NoteOn, id, properties)
@@ -26,38 +38,59 @@ module MicroMIDI
         note
       end
 
-      # create a note off message
+      # Create a MIDI note off message
+      # @param [Fixnum, String] id Note name or index
+      # @param [Hash] options
+      # @option options [Fixnum] :channel
+      # @option options [Fixnum] :velocity
+      # @return [MIDIMessage::NoteOff]
       def note_off(id, options = {})
         properties = @state.message_properties(options, :channel, :velocity)
         note_message(MIDIMessage::NoteOff, id, properties)
       end
 
-      # create a MIDI message from a byte string, array of bytes, or list of bytes
+      # Create a MIDI message from raw bytes
+      # @param [Array<Fixnum>, Array<String>, String] message Byte string or array of numeric/string bytes
+      # @return [MIDIMessage]
       def parse(message)
         MIDIMessage.parse(message)
       end
 
-      # create a program change message
+      # Create a MIDI program change message
+      # @param [Fixnum] program
+      # @param [Hash] options
+      # @option options [Fixnum] :channel
+      # @return [MIDIMessage::ProgramChange]
       def program_change(program, options = {})
         properties = @state.message_properties(options, :channel)
         MIDIMessage::ProgramChange.new(properties[:channel], program)
       end
 
-      # create a note-off message from the last note-on message
+      # Create a MIDI note-off message from the last note-on message
+      # @return [MIDIMessage::NoteOff]
       def off
         note_off = @state.last_note.to_note_off unless @state.last_note.nil?
         @state.last_note = nil
         note_off
       end
-      
-      # create a channel pressure message
+
+      # Create a MIDI channel pressure message
+      # @param [Fixnum] value
+      # @param [Hash] options
+      # @option options [Fixnum] :channel
+      # @return [MIDIMessage::ChannelAftertouch]
       def channel_aftertouch(value, options = {})
         properties = @state.message_properties(options, :channel)
         MIDIMessage::ChannelAftertouch.new(properties[:channel], value)
       end
       alias_method :channel_pressure, :channel_aftertouch
-      
-      # create a poly pressure message
+
+      # Create a MIDI poly pressure message
+      # @param [Fixnum, String] note
+      # @param [Fixnum] value
+      # @param [Hash] options
+      # @option options [Fixnum] :channel
+      # @return [MIDIMessage::PolyphonicAftertouch]
       def polyphonic_aftertouch(note, value, options = {})
         properties = @state.message_properties(options, :channel)
         MIDIMessage::PolyphonicAftertouch.new(properties[:channel], note, value)
@@ -65,16 +98,25 @@ module MicroMIDI
       alias_method :poly_aftertouch, :polyphonic_aftertouch
       alias_method :polyphonic_pressure, :polyphonic_aftertouch
       alias_method :poly_pressure, :polyphonic_aftertouch
-      
+
+      # Create a MIDI pitch bend message
+      # @param [Fixnum] low
+      # @param [Fixnum] high
+      # @param [Hash] options
+      # @option options [Fixnum] :channel
+      # @return [MIDIMessage::PitchBend]
       def pitch_bend(low, high, options = {})
         properties = @state.message_properties(options, :channel)
         MIDIMessage::PitchBend.new(properties[:channel], low, high)
       end
       alias_method :bend, :pitch_bend
       alias_method :pitchbend, :pitch_bend
-      
+
       protected
-      
+
+      # Parse a note name string eg "C4"
+      # @param [String] name
+      # @return [String]
       def parse_note_name(name)
         name = name.to_s
         octave = name.scan(/-?\d\z/).first
@@ -86,8 +128,13 @@ module MicroMIDI
 
       private
 
+      # Create a MIDI note on or note off message
+      # @param [Class] klass
+      # @param [Fixnum, String] id
+      # @param [Hash] properties
+      # @return [MIDIMessage::NoteOn, MIDIMessage::NoteOff]
       def note_message(klass, id, properties)
-        if id.kind_of?(Numeric) 
+        if id.kind_of?(Numeric)
           klass.new(properties[:channel], id, properties[:velocity])
         elsif id.kind_of?(String) || id.kind_of?(Symbol)
           note_name = parse_note_name(id)

data/lib/micromidi/instructions/output.rb

@@ -1,9 +1,10 @@
 module MicroMIDI
 
   module Instructions
-    
+
+    # Commands that deal with MIDI output
     class Output
-      
+
       extend Forwardable
 
       def_delegators :@state, :toggle_auto_output
@@ -16,7 +17,7 @@ module MicroMIDI
 
       # Output a message or toggle the auto output mode
       # @param [MIDIMessage, Boolean] message A MIDI message to output, or a boolean to toggle auto-output mode
-      # @return [BIDIMessage]
+      # @return [MIDIMessage]
       def output(message)
         set_auto_output(message) if !!message === message # check for boolean
         unless message.nil?
@@ -24,7 +25,7 @@ module MicroMIDI
         end
         message
       end
-      
+
       # Set mode where messages are automatically outputted
       # @param [Boolean] is_on Whether to set the auto output mode to ON
       # @return [Boolean]

data/lib/micromidi/instructions/process.rb

@@ -1,50 +1,94 @@
 module MicroMIDI
 
   module Instructions
-    
+
+    # Commands that deal with processing MIDI messages
     class Process
-      
+
+      # @param [State] state
       def initialize(state)
         @state = state
       end
-      
+
+      # Transpose a message value
+      # @param [MIDIMessage] message
+      # @param [Symbol, String] property
+      # @param [Fixnum] factor
+      # @param [Hash] options
+      # @return [MIDIMessage]
       def transpose(message, property, factor, options = {})
         MIDIFX.transpose(message, property, factor, options)
       end
-      
+
+      # Limit a message value
+      # @param [MIDIMessage] message
+      # @param [Symbol, String] property
+      # @param [Range] range
+      # @param [Hash] options
+      # @return [MIDIMessage]
       def limit(message, property, range, options = {})
         MIDIFX.limit(message, property, range, options)
       end
-      
+
+      # Filter a message value
+      # @param [MIDIMessage] message
+      # @param [Symbol, String] property
+      # @param [Range] bandwidth
+      # @param [Hash] options
+      # @return [MIDIMessage]
       def filter(message, property, bandwidth, options = {})
         MIDIFX.filter(message, property, bandwidth, options)
       end
-      
+
+      # High pass filter a message value
+      # @param [MIDIMessage] message
+      # @param [Symbol, String] property
+      # @param [Fixnum] min
+      # @param [Hash] options
+      # @return [MIDIMessage]
       def high_pass_filter(message, property, min, options = {})
         MIDIFX.high_pass_filter(message, property, min, options)
       end
       alias_method :only_above, :high_pass_filter
       alias_method :except_below, :high_pass_filter
 
+      # Low pass filter a message value
+      # @param [MIDIMessage] message
+      # @param [Symbol, String] property
+      # @param [Fixnum] max
+      # @param [Hash] options
+      # @return [MIDIMessage]
       def low_pass_filter(message, property, max, options = {})
         MIDIFX.low_pass_filter(message, property, max, options)
       end
       alias_method :only_below, :low_pass_filter
       alias_method :except_above, :low_pass_filter
-      
+
+      # Band pass filter a message value
+      # @param [MIDIMessage] message
+      # @param [Symbol, String] property
+      # @param [Range] bandwidth
+      # @param [Hash] options
+      # @return [MIDIMessage]
       def band_pass_filter(message, property, bandwidth, options = {})
         MIDIFX.band_pass_filter(message, property, bandwidth, options)
       end
       alias_method :only_in, :band_pass_filter
       alias_method :only, :band_pass_filter
-      
+
+      # Band reject filter a message value
+      # @param [MIDIMessage] message
+      # @param [Symbol, String] property
+      # @param [Range] bandwidth
+      # @param [Hash] options
+      # @return [MIDIMessage]
       def notch_filter(message, property, bandwidth, options = {})
         MIDIFX.notch_filter(message, property, bandwidth, options)
       end
       alias_method :band_reject_filter, :notch_filter
       alias_method :except_in, :notch_filter
       alias_method :except, :notch_filter
-      
+
     end
 
   end

data/lib/micromidi/instructions/shorthand.rb

@@ -1,23 +1,24 @@
 module MicroMIDI
-  
+  # Patch shorthand aliases into the MicroMIDI module
+
   alias l loop
- 
+
   def self.m(*args, &block)
     send(:message, *args, &block)
   end
-  
+
   class Context
     alias_method :r, :repeat
   end
-  
-  module Instructions    
-        
+
+  module Instructions
+
     module Composite
       alias_method :p, :play
       alias_method :q!, :all_off
       alias_method :x, :all_off
     end
-        
+
     class Input
       alias_method :j, :join
       alias_method :rc, :receive
@@ -25,9 +26,9 @@ module MicroMIDI
       alias_method :t, :thru
       alias_method :te, :thru_except
       alias_method :tu, :thru_unless
-      alias_method :w, :wait_for_input      
+      alias_method :w, :wait_for_input
     end
-    
+
     class Message
       alias_method :c, :control_change
       alias_method :ca, :channel_aftertouch
@@ -39,11 +40,11 @@ module MicroMIDI
       alias_method :pb, :pitch_bend
       alias_method :pc, :program_change
     end
-    
+
     class Output
       alias_method :out, :output
     end
-    
+
     class Process
       alias_method :bp, :band_pass_filter
       alias_method :bpf, :band_pass_filter
@@ -56,15 +57,15 @@ module MicroMIDI
       alias_method :lpf, :low_pass_filter
       alias_method :mbf, :filter
       alias_method :nf, :notch_filter
-      alias_method :tp, :transpose      
+      alias_method :tp, :transpose
     end
-        
+
     class Sticky
       alias_method :ch, :channel
       alias_method :ss, :super_sticky
       alias_method :v, :velocity
     end
-    
+
     class SysEx
       alias_method :sc, :sysex_command
       alias_method :sr, :sysex_request
@@ -75,5 +76,5 @@ module MicroMIDI
 end
 
 def M(*a, &block)
-  MIDI.message(*a, &block)  
+  MIDI.message(*a, &block)
 end

data/lib/micromidi/instructions/sticky.rb

@@ -1,55 +1,84 @@
 module MicroMIDI
 
   module Instructions
-    
+
+    # Commands that deal with sticky default properties.
+    #
+    # For example, setting a default MIDI channel that persists for the messages to follow it:
+    #
+    # ```ruby
+    # channel 5
+    # note "C4"
+    # note "C3"
+    # ```
+    #
     class Sticky
-      
+
+      # @param [State] state
       def initialize(state)
         @state = state
       end
 
-      # sets the sticky channel for the current block
-      def channel(val = nil)
-        val.nil? ? @state.channel : @state.channel = val
+      # Gets/sets the sticky channel for the current block
+      # @param [*Fixnum] args args[0] is an optional parameter to set the channel: [Fixnum, nil]
+      # @return [Fixnum]
+      def channel(*args)
+        @state.channel = args.first unless args.empty?
+        @state.channel
       end
-      
-      # sets the octave for the current block
-      def octave(val = nil)
-        val.nil? ? @state.octave : @state.octave = val
+
+      # Gets/sets the octave for the current block
+      # @param [*Fixnum] args args[0] is an optional parameter to set the octave: [Fixnum, nil]
+      # @return [Fixnum]
+      def octave(*args)
+        @state.octave = args.first unless args.empty?
+        @state.octave
       end
-      
-      # sets the sysex node for the current block
+
+      # Gets/sets the sysex node for the current block
+      # @param [*Object] args
+      # @return [MIDIMessage::SystemExclusive::Node]
       def sysex_node(*args)
+        args = args.dup
         options = args.last.kind_of?(Hash) ? args.last : {}
-        args.empty? ? @state.sysex_node : @state.sysex_node = MIDIMessage::SystemExclusive::Node.new(args.first, options)
+        @state.sysex_node = MIDIMessage::SystemExclusive::Node.new(args.first, options) unless args.empty?
+        @state.sysex_node
       end
       alias_method :node, :sysex_node
 
-      # sets the sticky velocity for the current block
-      def velocity(val = nil)
-        val.nil? ? @state.velocity : @state.velocity = val
+      # Gets/sets the sticky velocity for the current block
+      # @param [*Fixnum] args args[0] is an optional parameter to set the velocity: [Fixnum, nil]
+      # @return [Fixnum]
+      def velocity(*args)
+        @state.velocity = args.first unless args.empty?
+        @state.velocity
       end
-      
+
       #
-      # toggles super_sticky mode, a mode where any explicit values used to create MIDI messages
-      # automatically become sticky -- whereas normally the explicit value would only be used for 
+      # Toggles super_sticky mode, a mode where any explicit values used to create MIDI messages
+      # automatically become sticky.  Normally the explicit value would only be used for
       # the current message.
       #
-      # e.g.
+      # For example, while in super sticky mode
       #
+      # ```ruby
       # note "C4", :channel => 5
+      # note "C3"
+      # ```
+      #
+      # will have the same results as
       #
-      # will have the exact same effect as
-      # 
+      # ```ruby
       # channel 5
       # note "C4"
+      # note "C3"
+      # ```
       #
-      # while in super sticky mode
-      #
+      # @return [Boolean]
       def super_sticky
         @state.toggle_super_sticky
       end
-      
+
     end
 
   end