shlisp_tools 0.0.1 → 0.0.2

data/README.md

@@ -1,6 +1,8 @@
 # ShlispTools
 
-Tools for shlisp/shnth developers. If you don't recognize both of words starting with "sh", this is probably not for you.
+[![Gem Version](https://badge.fury.io/rb/shlisp_tools.png)](http://badge.fury.io/rb/shlisp_tools)
+
+Tools for shlisp/shnth developers. If you don't recognize both words starting with "sh", this is probably not for you.
 
 Executables:
 * shlerb (a templating and uploading tool for txts; an ERB wrapper for shlisp)
@@ -110,6 +112,16 @@ You can also define your own scales and add a scaling factor to bring them into
 
     %>
 
+## Caveats
+
+* Ratio, Scale, and the Scales collection all assume "arab" mode.
+
+##  TODO
+
+* write tests
+* write more complete documentation
+* allow Ratio and Scale classes to work in "dirac" mode as well as "arab" mode
+
 ## Contributing
 
 1. Fork it

data/bin/shlerb

@@ -1,36 +1,36 @@
 #!/usr/bin/env ruby
 
 require 'erb'
-
 require 'shlisp_tools'
 
-# for the binding
+#:nodoc: all
 Scales = ShlispTools::Scales
 Shnth  = ShlispTools::Shnth
 
-def error(s)
+def error(s) #:nodoc:
   puts s
   exit 1
 end
 
-class Shlerb
-
+class Shlerb #:nodoc: all
   TEMP_FILE = "_shlerb_temp"
   
   def self.perform(infile)
     template_file = File.open(infile, 'r').read
     out = nil
 
+    puts "Generating shlisp..."
     begin
       out = herb(template_file)
     rescue Exception => e
-      # do again and show verbos output
+      # do again and show verbose output
       $VERBOSE = true
       puts herb(template_file)
       exit 1
     end
 
     if out
+      puts "Compiling generated shlisp (#{TEMP_FILE}) and sending to shnth..."
       File.open(TEMP_FILE, 'w+') { |f| f.write(out) }
       system("shlisp #{TEMP_FILE}")
     end

data/bin/shtool

@@ -4,7 +4,7 @@
 # ops
 #------------------------------------------------------------------------------
 
-class OpResult
+class OpResult #:nodoc: all
   attr_reader :args, :result
 
   def initialize(args=nil, result=nil)
@@ -18,7 +18,7 @@ class OpResult
 end
 
 # base class for operations
-class Op
+class Op #:nodoc: all
   def self.name
     ""
   end
@@ -49,7 +49,7 @@ end
 
 # operations
 
-class OpSr < Op
+class OpSr < Op #:nodoc: all
   CLOCK = 72000000.0
 
   def self.name
@@ -82,7 +82,7 @@ class OpSr < Op
     end
 end
 
-class OpRatMul < Op
+class OpRatMul < Op #:nodoc: all
   def self.name
     "mul"
   end
@@ -118,7 +118,7 @@ class OpRatMul < Op
     end
 end
 
-class OpRange < Op
+class OpRange < Op #:nodoc: all
   Min = -128
   Max = 128
 
@@ -154,7 +154,7 @@ class OpRange < Op
     end
 end
 
-class OpReduce < Op
+class OpReduce < Op #:nodoc: all
   def self.name
     "reduce"
   end
@@ -192,20 +192,20 @@ class OpReduce < Op
 end
 
 # known operations
-Ops = [ OpSr, OpRatMul, OpRange, OpReduce ]
+Ops = [ OpSr, OpRatMul, OpRange, OpReduce ] #:nodoc:
 
 #------------------------------------------------------------------------------
 # mainline code
 #------------------------------------------------------------------------------
 
-def usage
+def usage #:nodoc:
   puts "usage: 'shtool OP [args ...]'"
   puts "where OP is one of: #{Ops.collect{ |op| op.name}.join(" ") }"
   puts "or try 'shtool help'"
   exit 1
 end
 
-def main(argv)
+def main(argv) #:nodoc:
   if argv.length < 1
     usage
   else

data/examples/hexanies.txt.erb

@@ -3,7 +3,7 @@
   Slew_add = 5
   Modo_mul = 2
 %>
-<% s = Scales::Hexany1357.scale(127) %>
+<% s = Scales::Hexany1357.mul(127) %>
 {
   <%= Shnth::Situation_1 %>
 

data/examples/metaslendro.txt.erb

@@ -3,7 +3,7 @@
   Slew_add = 5
   Modo_mul = 2
 %>
-<% s1 = Scales::MetaSlendro_1.scale(120) %> 
+<% s1 = Scales::MetaSlendro_1.mul(120) %> 
 {
   <%= Shnth::Situation_1 %>
 
@@ -32,7 +32,7 @@
 
   )
 }
-<% s2 = Scales::MetaSlendro_2.scale(120) %>
+<% s2 = Scales::MetaSlendro_2.mul(120) %>
 {
   <%= Shnth::Situation_2 %>
 

data/lib/shlisp_tools/ratio.rb

@@ -1,81 +1,95 @@
 module ShlispTools
+
+  # A Shlisp-oriented representation of a pitch in just/rational intonation.
+  # Numerators are "numes" and denoninators are "denos" as is customary for
+  # Shlisp. All terms 0 < n < 256 ("arab" mode in Shlisp).
   class Ratio
     include Enumerable
 
-    attr_reader :nume, :deno, :rat
+    # numerator
+    attr_reader :nume
+    # denominator
+    attr_reader :deno
+    # rational form
+    attr_reader :rat
 
-    def initialize(nume, deno, scale=nil)
+    def initialize(nume, deno, _mul=nil)
       @nume = nume
       @deno = deno
       _set_rat
-      scale(scale)
-    end
-
-    # pos: scale up (multiply)
-    # neg: scale down (divide)
-    def scale(mul)
-      if mul
-        if mul >= 0
-          @nume *= mul
-          @deno *= mul
-          @nume = 255 if @nume > 255
-          @deno = 255 if @deno > 255
-        else
-          mul = mul.abs
-          @nume /= mul
-          @deno /= mul
-          @nume = 1 if @nume <= 0
-          @deno = 1 if @deno <= 0
-        end
-      end
+      mul(_mul)
     end
 
+    # Get the nume(rator).
     def n
       @nume
     end
 
+    # Set the nume(rator).
     def n=(nume)
       @nume = nume
       _set_rat
+      n
     end
 
+    # Get the deno(minator).
     def d
       @deno
     end
 
+    # Set the deno(minator).
     def d=(deno)
       @deno = deno
       _set_rat
+      d
     end
 
-    def reduce
-      Ratio.new(@rat.numerator, @rat.denominator)
+    # Multiply both nume and deno by same factor for Shnth amplitude scaling.
+    def mul(factor)
+      if factor
+        factor = factor.abs
+        @nume = (@nume * factor) % LIMIT
+        @deno = (@deno * factor) % LIMIT
+      end
+      self
     end
 
-    def reduce!
+     def scale(factor) #:nodoc:
+      mul(factor)
+    end
+
+   # Return to the canonical (reduced) value.
+    def reset!
       @nume = @rat.numerator
       @deno = @rat.denominator
     end
 
+    # String representation
     def to_s
       "#{@nume}/#{@deno}"
     end
 
+    # Rational representation
     def to_r
       @rat
     end
 
-    def each
+    # Iterator
+    def each #:nodoc:
       yield @rat
     end
 
-    def <=>(other)
+    # Comparator, for sorting
+    def <=>(other) #:nodoc:
       @rat <=> other.rat
     end
 
     private
-      def _set_rat
+      LIMIT = 256 #:nodoc:
+
+      def _set_rat #:nodoc:
         @rat = Rational(@nume, @deno)
       end
   end
+
 end

data/lib/shlisp_tools/scale.rb

@@ -1,9 +1,15 @@
 module ShlispTools
+
+  # A scale is a series of Ratio instances, always maintained in canonical
+  # (reduced) form and ascending order, but available with amplitude scaling
+  # for use in a Shlisp/Shnth context.
   class Scale
     include Enumerable
 
+    # The default separator (' ') between scale degrees when scale is printed.
     DEF_SEP = ' '
 
+    # Arg: either nothing, or an array of Ratios
     def initialize(degrees=nil)
       @degrees = []
       if degrees && !degrees.empty?
@@ -12,72 +18,103 @@ module ShlispTools
       end
     end
 
+    # Add a new scale degree (Ratio).
     def add(degree)
       @degrees << degree
       _sort
+      self
     end
 
-    def remove(idx)
-      @degrees.delete_at(idx) rescue nil
+    # Add a new scal degree (Ratio) using string/array notation; i.e., myScale << Ratio.new(5,4)/
+    def <<(degree)
+      add(degree)
+      self
     end
 
-    def scale(mul)
-      unless empty?
-        @degrees.each_with_index do |note,i|
-          if i == 0
-            note.scale(mul)
-          else
-            tmp = ((mul > note.deno) ? mul : mul*2)
-            note.scale((tmp / note.deno).to_i)
-          end
-        end
-      end
+    # Remove the scale degree at the specified position (0-based).
+    def remove(idx)
+      @degrees.delete_at(idx) rescue nil
       self
     end
 
+    # Return the scale degree at a specified postion (0-based).
     def [](idx)
       @degrees[idx] rescue nil
     end
 
+    # Return the number of degrees (notes) in the scale.
     def length
       @degrees.length
     end
 
+    # Return true if scale is empty, false otherwise.
     def empty?
       @degrees.empty?
     end
 
-    def <<(degree)
-      add(degree)
+    # Apply a multiplicative factor to every ratio for Shnth amplitude scaling.
+    # For example, myScale.scale(100) transforms 1/1 to 100/100. Other notes are brought into
+    # as close a range as possible while keeping all terms in the 1..255 range.
+    def mul(factor)
+      unless empty?
+        @degrees.each_with_index do |note,i|
+          if i == 0
+            note.mul(factor)
+          else
+            tmp = ((factor > note.deno) ? factor : factor*2)
+            note.mul((tmp / note.deno).to_i)
+          end
+        end
+      end
+      self
     end
 
-    def each(&block)
-      @degrees.each(&block)
+    def scale(factor) #:nodoc:
+      mul(factor)
     end
 
+    # Print the scale (multipied).
     def to_s
-      scaled
+      multiplied
     end
 
-    def scaled(sep=DEF_SEP)
+    # Print out the scale (multiplied).
+    def multiplied(sep=DEF_SEP)
       @degrees.inject([]) { |out,d| out << d.to_s; out }.join(sep)
     end
 
-    def reduced(sep=DEF_SEP)
+    def scaled(sep=DEF_SEP) #:nodoc:
+      multiplied(sep)
+    end
+
+    # Print out the scale in canonical form (reduced rations).
+    def canonical(sep=DEF_SEP)
       @degrees.inject([]) { |out,d| out << d.to_r.to_s; out }.join(sep)
     end
 
+    def reduced(sep=DEF_SEP) #:nodoc:
+      canonical(sep)
+    end
+
+    # Print out all the nume(rator)s, multiplied.
     def numes(sep=DEF_SEP)
       @degrees.inject([]) { |out,d| out << d.n; out }.join(sep)
     end
 
+    # Print out all the deno(minators), multiplied.
     def denos(sep=DEF_SEP)
       @degrees.inject([]) { |out,d| out << d.d; out }.join(sep)
     end
 
+    # iterator
+    def each(&block) #:nodoc
+      @degrees.each(&block)
+    end
+
     private
       def _sort
         @degrees.sort!
       end
   end
+
 end

data/lib/shlisp_tools/scales.rb

@@ -1,10 +1,13 @@
 require 'shlisp_tools/scale'
 
 module ShlispTools
+
+  # Predefined scales.
   module Scales
 
     # 1-3-5-7 hexany, utonal stellated
     # second degree (49/48) and 2/1 removed to fit eight buttons
+    # 1/1 25/24 7/6 5/4 35/24 3/2 5/3 7/4
     Hexany1357 = Scale.new([
       Ratio.new( 1,  1),
       Ratio.new(25, 24),
@@ -16,6 +19,7 @@ module ShlispTools
       Ratio.new( 7,  4)
     ])
 
+    # 1/1 37/32 21/16 49/32 7/4 2/1
     MetaSlendro_1 = Scale.new([
       Ratio.new( 1,  1),
       Ratio.new(37, 32),
@@ -25,6 +29,7 @@ module ShlispTools
       Ratio.new( 2,  1)
     ])
 
+    # 1/1 9/8 151/128 3/2 25/16 2/1
     MetaSlendro_2 = Scale.new([
       Ratio.new(  1,   1),
       Ratio.new(  9,   8),
@@ -34,6 +39,7 @@ module ShlispTools
       Ratio.new(  2,   1)
     ])
 
+    # 1/1 21/20 7/6 3/2 14/9 2/1
     CentaurPelog = Scale.new([
       Ratio.new( 1,   1),
       Ratio.new(21,  20),
@@ -44,4 +50,5 @@ module ShlispTools
     ])
 
   end
+
 end

data/lib/shlisp_tools/shnth.rb

@@ -1,5 +1,24 @@
 module ShlispTools
+
+=begin
+Macros and constants for use with the shlerb tool.
+
+*Light_\**: simple light values, 1-8 across
+
+*Situation_\**: macros representing stevek's idiom for switching through situations using the tar button, using the lights from left to right
+to show which situation is running:
+- <tt>\<%= Situation_1 %></tt> emits <tt>(jump (tar 1)) (lights 1)</tt>
+- <tt>\<%= Situation_2 %></tt> emits <tt>(jump (tar 1)) (lights 4)</tt>
+- etc.
+
+*Bar_\**: scale indexes by bar (Uppercase=major, lowercase=minor), using stevek's arrangement:
+- <tt>Bar_A = 0</tt>
+- <tt>Bar_B = 1</tt>
+- etc.
+=end
+    
   module Shnth
+
     Light_1 = 1
     Light_2 = Light_1 * 4
     Light_3 = Light_2 * 4
@@ -17,8 +36,7 @@ module ShlispTools
     Situation_6 = "(jump (tar 1)) (lights #{Light_6})"
     Situation_7 = "(jump (tar 1)) (lights #{Light_7})"
     Situation_8 = "(jump (tar 1)) (lights #{Light_8})"
-
-    # scale indexes by bar (A=major, a=minora), using stevek's arrangement
+    
     Bar_A = 0
     Bar_B = 1
     Bar_C = 2
@@ -27,5 +45,7 @@ module ShlispTools
     Bar_c = 5
     Bar_b = 6
     Bar_a = 7
+
   end
+
 end

data/lib/shlisp_tools/version.rb

@@ -1,3 +1,3 @@
 module ShlispTools
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shlisp_tools
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-12 00:00:00.000000000 Z
+date: 2013-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler