mtk 0.0.2 → 0.0.3

data/.yardopts

@@ -1,9 +1,10 @@
 --readme README.md
---title 'MTK (Music ToolKit for Ruby)'
+--title 'MTK (Music Tool Kit for Ruby)'
 --charset utf-8
 --protected
+--no-private
 lib/**/*.rb
 - *.md
 - examples/*
 - lib/**/*.citrus
-
+- LICENSE.txt

data/DEVELOPMENT_NOTES.md

@@ -0,0 +1,114 @@
+MTK
+===
+
+[![Build Status](https://secure.travis-ci.org/adamjmurray/mtk.png)](http://travis-ci.org/adamjmurray/mtk)
+
+Music Tool Kit for Ruby
+-----------------------
+
+Classes for modeling music with a focus on simplicity. Support for reading/writing MIDI files and realtime MIDI.
+
+
+
+Getting Started
+---------------
+
+    gem install mtk
+
+or download the source from here and add mtk/lib to your $LOAD_PATH. Then...
+
+    require 'mtk'
+
+Some examples are available in the examples folder (more coming soon).
+The specs provide a lot of details of usage...
+
+
+
+Goals
+-----
+
+* Build musical generators to assist with composing music
+* Re-implement Cosy (http://compusition.com/web/software/cosy) using these models as the "backend"
+
+
+
+Status
+------
+
+Alpha phase, API subject to change. Feedback welcome!
+
+
+
+Requirements
+------------
+
+### Ruby Version
+
+Ruby 1.9+ or JRuby 1.6+
+
+
+### Dependencies
+
+MTK's core features should not depend on anything outside of the Ruby standard library.
+
+
+MTK's optional features typically require gems. Currently the following gems are required:
+
+* MIDI file I/O requires the __midilib__ gem
+
+* realtime MIDI I/O with (MRI/YARV) Ruby requires the __unimidi__ and __gamelan__ gems
+
+* realtime MIDI I/O with JRuby require the __jsound__ and __gamelan__ gems
+
+* The custom MTK syntax (work in progress) requires the __citrus__ gem
+
+
+Development requires the gems for optional features, plus the following:
+
+* rake
+* rspec (tests)
+* yard (docs)
+
+You shouldn't need to worry about the dependencies too much. A Gemfile is provided to sort this out for you:
+
+    gem install bundler
+    bundle install
+
+[rvm](https://rvm.beginrescueend.com/) is required for cross version testing (see Development Notes below)
+
+
+
+Documentation
+-------------
+
+Gem 0.0.2: http://rdoc.info/gems/mtk/0.0.2/frames (TODO: update this)
+
+Latest for source: http://rubydoc.info/github/adamjmurray/mtk/master/frames
+
+
+
+Development Notes
+-----------------
+
+### Run Tests ###
+
+Test with current version of Ruby:
+
+     bundle exec rake test
+
+Test with all supported versions of Ruby (requires [rvm](https://rvm.beginrescueend.com/), YARV 1.9.3, and JRuby 1.6.7):
+
+     bundle exec rake test:all
+
+The test:all test must pass for a pull request to be accepted or for a release of the mtk gem.
+
+
+### Generate Docs ###
+
+     bundle exec rake doc
+     open doc/frames.html
+
+or, to automatically refresh the documentation as you work:
+
+     bundle exec yard server -r
+     open http://localhost:8808

data/INTRO.md

@@ -6,21 +6,19 @@ Core Concepts
 ### Core data types
 
 These model the basic properties of musical events:
-* pitch_class (MTK class)
-* pitch (MTK class)
-* intensity (Numeric)
-* duration (Numeric)
+* PitchClass
+* Pitch
+* Duration
+* Intensity
 
-Like Numeric types, PitchClass and Pitch are immutable. This helps avoid confusing bugs.
+These types are all immutable. This helps avoid confusing bugs.
 Mostly you don't need to worry about this. Just remember when you call methods that change the value, like #invert,
 it does not change the value in-place. For example:
 
      p = PitchClass[G]
      p = p.invert(E)  # because p.invert(E) does not change p
 
-For efficiency and convenience, intensity and duration are modeled using Ruby's Numeric types (Fixnum, Float, etc).
-
-Intensity is intended to range from 0.0 (minimum intensity) to 1.0 (maximum intensity).
+Intensity values are intended to range from 0.0 (minimum intensity) to 1.0 (maximum intensity).
 
 A Duration of 1 is one beat (usually a quarter note, depending on the meter). By convention, negative durations
 indicate a rest that lasts for the absolute value duration.
@@ -70,4 +68,62 @@ Future?
 Convert patterns into timelines
 
 
+<br/>
+### Syntax
+
+Basic Tenants
+
+* Minimal syntax: less typing means more music!
+* Be case-insensitive to avoid typos caused by lower vs upper case (there's one notable exception for intervals: m2 vs M2)
+* pitch and duration are the most important properties
+* pitch is more important than rhythm
+
+Because pitch class and duration are such important properties, and we want to minimize typing, we represent these with 1 letter.
+
+**Diatonic Pitch Class: c d e f g a b**
+
+**Chromatic Pitch Class (Sharp/Flat): c c# db d d# eb e e# fb f f# gb g g# ab a a# bb b b#**
+
+Double-sharps (c##) and double-flats (dbb) are also allowed. You may prefer Bb to bb, etc
+
+**Pitch (Pitch Class + Octave Number): c4 db5 c-1 g9**
+
+c-1 (that's octave number: negative 1) is the lowest note. g9 is the highest.
+
+**Duration: w h q i s r x (that's: whole note, half, quarter, eighth, sixteenth, thirty-second, sixty-fourth)**
+
+Why "i", "r", and "x"? We're trying to keep these one letter. 'e', 'r', and 's' were already used,
+so we just move along the letters of the word until we find an unused letter.
+
+For intensity, we'll try to use standard music notation, but 'f' conflicts, so we handle this the same way we did with durations:
+
+**Intensity: ppp pp p mp mf o ff fff**
+
+(You may find it helpful to think "loud" for "o")
+
+
+TODO: keep documenting this...
+
+
+Summary of single-letter assignments:
+```
+a -> pitch class a
+b -> pitch class b, flat modifier on pitch class
+c -> pitch class c
+d -> pitch class d
+e -> pitch class e
+f -> pitch class f
+
+h -> half note duration
+i -> eighth note duration
+
+o -> forte intensity
+p -> piano intensity
+q -> quarter note duration
+r -> thirty-second note duration
+s -> sixteenth note duration
+t -> triplet modifier on durations
 
+w -> whole note duration
+x -> sixty-fourth note duration
+```

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011, Adam Murray (adam@compusition.com).
+Copyright (c) 2011-2013, Adam Murray (adam@compusition.com).
 
 All rights reserved.
 

data/README.md

@@ -1,127 +1,56 @@
-MTK
+MTK: a Music Tool Kit for Ruby
 ===
 
-Music ToolKit for Ruby
-----------------------
+MTK is a Ruby library and custom [domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language) (DSL) for generating musical material.
 
-Classes for modeling music with a focus on simplicity. Support for reading/writing MIDI files and realtime MIDI.
+MTK is flexible: You may use the custom music-generating language without writing any Ruby code, or you may avoid the custom language
+ and only program in Ruby, or anywhere in between.
 
 
+Features
+--------
+* A minimalist syntax (DSL) for generating musical patterns
+* Read and write MIDI files
+* Record and output realtime MIDI signals
+* Sequence MIDI-compatible event streams
+* Manipulate musical objects like pitch, duration, and intensity
+* Generate deterministic and non-deterministic music via flexible patterns such as looping sequences and random choices
 
 Getting Started
 ---------------
 
-    gem install mtk
+# NOTE: This project is not ready yet, these instructions will not work! Please check back in a little while once I have mtk version 0.0.3 released to rubygems.org.
 
-or download the source from here and add mtk/lib to your $LOAD_PATH. Then...
+MTK works with Ruby 1.9, Ruby 2.0, and JRuby
 
-    require 'mtk'
+0. Install
 
-Some examples are available in the examples folder (more coming soon).
-The specs provide a lot of details of usage...
+        gem install mtk
 
+    or if using JRuby:
 
+        jgem install mtk
 
-Goals
------
+0. Learn the command-line interface:
 
-* Build musical generators to assist with composing music
-* Re-implement Cosy (http://compusition.com/web/software/cosy) using these models as the "backend"
+        mtk --help
 
+0. Learn the MTK syntax:
 
+        mtk --tutorial
 
-Status
-------
+0. Check out examples: ... TODO
 
-Alpha phase, API subject to change. Feedback welcome!
+0. Read the [MTK Ruby library documentation](http://rubydoc.info/github/adamjmurray/mtk/master/frames) (TODO: update this 0.0.3 gem version when ready)
 
+TODO: explain how to hear output on different platforms (maybe in the mtk command line help?)
 
 
-Requirements
-------------
+About this project
+------------------
+This project is developed by [Adam Murray (github.com/adamjmurray)](http://github.com/adamjmurray).
 
-### Ruby Version
+It is a free and open source project licensed under [a permissive BSD-style license](https://raw.github.com/adamjmurray/mtk/master/LICENSE.txt).
+I simply ask for credit by including my copyright in derivative works.
 
-Ruby 1.8+ or JRuby 1.5+
-
-
-### Dependencies
-
-MTK's core features should not depend on anything outside of the Ruby standard library.
-
-MTK's optional features typically require gems. Currently the following gems are required:
-
-* midilib: required by MTK::MIDI::File for file I/O
-
-* jsound and gamelan: required by MTK::MIDI::JSoundInput/Output (also requires JRuby)
-
-Development requires all the gems for optional features, plus the following development tools:
-
-* rake
-* rspec (tests)
-* yard (docs)
-* yard-rspec (docs)
-* rdiscount (docs)
-
-[rvm](https://rvm.beginrescueend.com/) is recommended for cross version testing (see Development Notes below)
-
-
-
-Documentation
--------------
-
-Gem: http://rdoc.info/gems/mtk/0.0.2/frames
-
-Latest for source: http://rubydoc.info/github/adamjmurray/mtk/master/frames
-
-
-
-Development Notes
------------------
-
-### Run Tests ###
-
-Test with current version of Ruby:
-
-     rake spec
-
-Test with all supported versions of Ruby (requires [rvm](https://rvm.beginrescueend.com/), MRI 1.8.7, YARV 1.9.2, JRuby 1.5.6, and JRuby 1.6.2):
-
-     rake spec:xversion
-
-The spec:xversion test must pass for a pull request to be accepted or for a release of the mtk gem.
-
-
-### Generate Docs ###
-
-     yard
-     open doc/frames.html
-
-or, to automatically refresh the documentation as you work:
-
-      yard server -r
-      open http://localhost:8808
-
-
-### Project Roadmap ###
-
-https://www.pivotaltracker.com/projects/295419
-
-
-
-Changelog
----------
-
-* July 8, 2011: version 0.0.2
-    - Added a Sequencer module to build Timelines out of Patterns
-    - Overhauled Pattern module: removed type-specific patterns, and added the Palindrome, Lines, and Function patterns
-    - Patterns can now be nested (they can contain other Patterns)
-    - Patterns can now be typed, to distinguish Numeric Patterns as :pitch (i.e. intervals), :intensity, :duration, or :rhythm patterns
-    - Removed auto-sorting behavior from PitchClassSet to support 12-tone rows and atonal composition techniques
-    - Added #quantize and #shift features to Timeline
-    - Got rid of Chord class, model Chords with PitchSets or Arrays of Notes instead
-    - Added support for realtime MIDI I/O with JSound (JRuby only)
-    - various cleanup and reorganization
-
-* June 8, 2011: version 0.0.1
-    - First gem release.
+You can learn more about the development of this project at the [development notes page](https://github.com/adamjmurray/mtk/blob/master/DEVELOPMENT_NOTES.md).

data/Rakefile

@@ -1,13 +1,17 @@
 require 'rspec/core/rake_task'
 require 'rake/clean'
-require 'yard'
 
-task :default => :spec
+MTK_VERSION = '0.0.3'
 
-CLEAN.include('html','doc') # clean and clobber do the same thing for now
+SUPPORTED_RUBIES = %w[ 1.9.3  2.0  jruby-1.7.4 ]
+ENV['JRUBY_OPTS'] = '--1.9'
+
+task :default => :test
+
+CLEAN.include('html','doc','coverage.data','coverage', '*.gem') # clean and clobber do the same thing for now
 
 desc "Run RSpec tests with full output"
-RSpec::Core::RakeTask.new do |spec|
+RSpec::Core::RakeTask.new('test') do |spec|
   spec.rspec_opts = ["--color", "--format", "nested"]
   if ARGV[1]
     # only run specs with filenames starting with the command line argument
@@ -15,29 +19,63 @@ RSpec::Core::RakeTask.new do |spec|
   end
 end
 
-namespace :spec do
+task :spec => :test
+
+
+namespace :gem do
+  desc "Install gems for supported versions of Ruby: #{SUPPORTED_RUBIES.join ', '}"
+  task :install_dependencies do
+    fail unless system("rvm #{SUPPORTED_RUBIES.join ','} do bundle install")
+  end
+
+  desc "Build the gemspec for C-Ruby and JRuby"
+  task :build do
+    ENV['MTK_VERSION'] = MTK_VERSION
+    ENV['MTK_BUILD_FOR_JRUBY'] = 'true'
+    `gem build ./mtk.gemspec`
+    `mv mtk-#{MTK_VERSION}.gem mtk-#{MTK_VERSION}-jruby.gem`
+    puts "Built mtk-#{MTK_VERSION}-jruby.gem"
 
-  desc "Run RSpecs tests with summary output and fast failure"
+    ENV['MTK_BUILD_FOR_JRUBY'] = nil
+    `gem build ./mtk.gemspec`
+    puts "Built mtk-#{MTK_VERSION}.gem"
+  end
+end
+
+
+namespace :test do
+  desc "Run RSpec tests with summary output and fast failure"
   RSpec::Core::RakeTask.new(:fast) do |spec|
     spec.rspec_opts = ["--color", "--fail-fast"]
   end
 
-  desc "Run RSpecs tests on mutiple versions of Ruby: 1.8.7, 1.9.2, JRuby 1.5.6, and JRuby 1.6.2"
-  task :xversion do
-    fail unless system("rvm 1.8.7,1.9.2,jruby-1.5.6,jruby-1.6.2 rake -f #{__FILE__} spec:fast")
+  desc "Run RSpec tests and generate a coverage report"
+  if RUBY_PLATFORM == "java"
+    task :cov do |t|
+      fail "#{t} task is not compatible with JRuby. Use Ruby 1.9 instead."
+    end
+  else
+    RSpec::Core::RakeTask.new(:cov) do |spec|
+      spec.rspec_opts = ["--color", "-r", "#{File.dirname __FILE__}/spec/spec_coverage.rb"]
+    end
   end
 
+  desc "Profile RSpec tests and report 10 slowest"
+  RSpec::Core::RakeTask.new(:prof) do |spec|
+    spec.rspec_opts = ["--color", "-p"]
+  end
+
+  desc "Run RSpec tests on all supported versions of Ruby: #{SUPPORTED_RUBIES.join ', '}"
+  task :all do
+    fail unless system("rvm #{SUPPORTED_RUBIES.join ','} do bundle exec rake -f #{__FILE__} test:fast")
+  end
 end
 
 
-YARD::Rake::YardocTask.new do |yard|
-  yard.files   = ['lib/**/*.rb', 'spec/**/*.rb']
-  yard.options = []
-  if File.exist? '../yard-spec-plugin/lib/yard-rspec.rb'
-    # prefer my local patched copy which can handle my rspec conventions better...
-    yard.options.concat ['-e' '../yard-spec-plugin/lib/yard-rspec.rb']
-  else
-    # use the gem
-    yard.options.concat ['-e' 'yard-rspec']
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new(:doc) do |yard|
+    yard.files   = ['lib/**/*.rb']
   end
+rescue Exception # yard is optional, so don't cause rake to fail if it's missing
 end