shift 0.1.0 → 0.4.0

data/CHANGELOG

@@ -0,0 +1,20 @@
+
+
+HEAD
+  Interface defaults
+
+0.4.0
+  Major restructuring
+  Shift::String for method chaning
+  Gzip support
+
+0.3.0
+  Shell command
+
+0.2.0
+  Shift.inspect_mappings
+  Named actions
+
+0.1.0
+  Working Rubygem with support for some formats.
+

data/README.md

@@ -1,99 +1,167 @@
 
-Shift (draft)
+Shift
 =====
 
-**State and logic-less compiler and compressor interface**
+**Compiler and compressor interface**
 
 ---
 
-Shift is a generic Ruby interface to different compilers, compressors, transformers and so on. What the [Tilt](https://github.com/rtomayko/tilt) gem does for template languages, Shift does for stuff that compiles in one step, without stateful template logic.
+Shift is a generic Ruby interface to different compilers, compressors, transformers and so on. It is also an easy way to chain actions that transform something and build compiler chains.
 
-* [Documentation](http://rubydoc.info/github/jbe/shift/master/frames)
-* [File type mappings](http://rubydoc.info/github/jbe/shift/master/Shift)
+* Installation: `gem install shift`
+* API Documentation
+  * [Latest Gem](http://rubydoc.info/gems/shift/frames)
+  * [Github master](http://rubydoc.info/github/jbe/shift/master/frames)
+* [Default mappings](https://github.com/jbe/shift/blob/master/lib/shift/mappings.rb)
 
-### Installation
+Shift contains:
 
-  gem install tilt
+* A convention for compiler interfaces
+* A collection of such interfaces for common compilers, compressors etc.
+* A way to describe actions that can be performed on a given format (such as `:render` for `markdown` files)
+  * A way to map such format actions to lists of compilers performing that action
+  * A way to return the best available compiler from such a list
+* Default mappings for all of the above
 
 
-### Usage
-
-To read and process a file, using the preferred available default component for that filetype:
+This means you can do things like
 
 ```ruby
 
-  Shift.read('thefile.js') # => minified js string
+(Shift.read('cup.coffee').compile.compress << '/* pidgeon */'
+  ).gzip.write
 
 ```
 
-Or to read, process, and then write:
+This reads `cup.coffee`, compiles it using coffeescript, compresses it using UglifyJS, appends the pidgeon comment to the minified javascript, gzips all of that, and then saves it as `cup.min.js.gz`. Since no file name was given, it is determined automatically.
+
+The aim is to include a large library of interfaces, which are lazy loaded on demand, to allow a huge variety of operations.
+
+
+### Examples
 
 ```ruby
 
-  Shift.read('canopy.sass').write('canopy.css')
+  str = Shift("hello", "hi.markdown") # => "hello"
+  str.class # => Shift::String
+  str.name # => "hi.markdown"
+  
+  result = str.render # => "<p>hello</p>"
+  result.name # => "hi.html"
 
 ```
 
-The components can also be used directly:
+The `Shift::String` works like a normal string, except that it has an associated name, and that it can be transformed like we just did. The string name is theoretical only; it does not necessarily exist as a file. Therefore, it can also simply represent the format. There are methods to read and write from file paths however:
 
 ```ruby
 
-  cc = Shift::ClosureCompiler.new(:compilation_level => 'ADVANCED_OPTIMIZATIONS')
-  minified_js_string  = cc.read(path)
+  str_a = Shift.read('script.js') # => "var hello; hello = 31;"
+  str_a.class # => Shift::String
+
+  str_b = Shift('hello', 'message.txt')
+  str_b.write
+  str_b.write('message_copy.txt')
 
 ```
 
-To simply process a string, or to process and save a string:
+Pretty handy. It can automatically write the string to the path that it automatically figured out.
+
+Now, in the first example, how did it know how to render markdown? Because i have RDiscount installed and it is the preferred default interface for doing `:render` to `.markdown` files.
 
 ```ruby
 
-  md = Shift::RDiscount.new
-  md.process("hello *there*") # => "<p>hello <em>there</em></p>"
-  md.process("hello *there*").write('message.html')
+  str = Shift("hello", "hi.markdown") # => "hello"
+  str.render # => "<p>hello</p>"
+  str.interface # => #<Shift::RDiscount:0xa0ad818>
+
+  Shift[:markdown] # => Shift::RDiscount
+  Shift[:md] # => Shift::RDiscount
+  Shift['somefile.js'] # => Shift::UglifyJS
+
+  Shift[:js, :compress] # => Shift::UglifyJS
+  Shift[:js, :gzip]     # => Shift::ZlibCompressor
+
+  puts Shift.inspect_actions
+  # =>
+  # GLOBAL: gzip
+  # echo: default
+  # coffee: compile
+  # gzip, gz: inflate
+  # js: compress
+  # md, markdown: render
+  # sass: compile
 
 ```
-To see if a component is available (check if the gem is installed and so on):
+If i tried to look up a format, and it had mappings, but none of the underlying handlers were available, Shift would raise a `Shift::DependencyError` including installation instructions.
+
+What if i want to work with the interfaces without any magic?
 
 ```ruby
 
-  Shift::YUICompressor.available?.
+  Shift::ClosureCompiler.available? # => true
+
+  iface = Shift::ClosureCompiler.new(
+    :compilation_level => 'ADVANCED_OPTIMIZATIONS')
+  iface.process(str)
+  iface.rename(file_path)
 
 ```
 
-To get the first available preferred default component class for a file:
+Being interfaces, they all work the same way.
+
+
+### Defining new mappings
 
 ```ruby
 
-  Shift['somefile.js'] # => Shift::UglifyJS
+  Shift.map('myformat', 'myaliasformat',
+    :default => :crush,
+    :crush => 'MyFormatCrusher',
+    :stabilize => %w{MyFormatStabilizer AlternativeMyFormatStabilizer}
+    )
 
 ```
 
-You can also do:
+Or globally, for all formats:
 
 ```ruby
+  Shift.global.map(
+    :mix_up => 'Mixuper'
+    )
+```
 
-  Shift[:md] # => Shift::RDiscount
+To reset all mappings:
+
+```ruby
+
+  Shift::MAP = {}
 
 ```
 
-### Available engines
+* [Default mappings](https://github.com/jbe/shift/blob/master/lib/shift/mappings.rb)
+
+
+### Shifter command line tool
 
-* UglifyJS
-* ClosureCompiler
-* YUICompressor
-* CoffeeScript
-* Sass
-* RDiscount
-* Redcarpet
+There is also a command line tool called `shifter`.
 
+```bash
 
-### Why not use or extend Tilt instead?
+  shifter
+
+  shifter sheet.sass
+  shifter file.js compress
+  shifter style.s compile sass
+  
+  some-tool | shifter - js > myfile.min.js
+  some-tool | shifter - js compress > myfile.min.js
+
+```
 
-I am making a separate library for this rather than extending Tilt, because i would usually only need one of the two in a given context. One and two step compilation are somewhat different things. Shift is more on the build side. Tilt is more on the dynamic side.
 
 ### Bye
 
-Bye Bye, see you. There are proper [docs](http://rubydoc.info/github/jbe/shift/master/frames) if you want more. And once again, [the mappings are there too](http://rubydoc.info/github/jbe/shift/master/Shift). Contributions and feedback is welcome, of course.
+Bye Bye, see you. Contribute some interfaces and mappings if you want to.
 
 ---
 

data/Rakefile

@@ -8,7 +8,7 @@ task :test do
 end
 
 task :shell do
-  system 'pry -I lib -r shift'
+  system 'pry -I lib -r shift --trace'
 end
 
 task :default => :test

data/TODO

@@ -0,0 +1,3 @@
+
+- Support IO streams?
+- Shift::Array which delegates methods to its members

data/bin/shifter

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'shift/cli'
+
+Shift::CLI.new.run!

data/lib/shift.rb

@@ -2,59 +2,65 @@
 
 #  SHIFT
 #
-#  State and logic-less compiler and compressor interface
+#  Compiler and compressor interface framework
 #
 #  (c) 2011 Jostein Berre Eliassen - MIT licence
 
 
 module Shift
 
-  VERSION = '0.1.0'
+  VERSION = '0.4.0'
 
   require 'shift/errors'
+  require 'shift/mapper'
+  require 'shift/interfaces'
   require 'shift/mappings'
 
+  autoload :String,   'shift/string'
 
-  # components
-
-  autoload :Identity,         'shift/c/identity'
-  autoload :UglifyJS,         'shift/c/uglify_js'
-  autoload :ClosureCompiler,  'shift/c/closure_compiler'
-  autoload :YUICompressor,    'shift/c/yui_compressor'
-  autoload :CoffeeScript,     'shift/c/coffee_script'
-  autoload :Sass,             'shift/c/sass'
-  autoload :RDiscount,        'shift/c/rdiscount'
-  autoload :Redcarpet,        'shift/c/redcarpet'
-  autoload :RedCarpet,        'shift/c/redcarpet'
 
+  class << self
+  
+    # (see Shift::String.new)
+    #
+    def new(*args)
+      Shift::String.new(*args)
+    end
 
-  # Read and process a file with the mapped component.
-  #
-  # @see Shift.[]
-  #
-  # (see Identity#read)
-  #
-  def self.read(path, opts={})
-    self[path].new(opts).read(path)
-  end
+    # Read a file, returning a Shift string.
+    # @param [String] path the file to read from.
+    # @param [String] new_path treat the shift string as if it came
+    #   from this path. Can be used to override file type behavior.
+    #
+    # (see Shift.new)
+    #
+    def read(path, new_path=nil)
+      new(File.read(path), new_path || path)
+    end
 
-  # Get the preferred available class mapped to match the
-  # given filename or extension.
-  #
-  # @raise [UnknownFormatError] when none of the mappings match.
-  #
-  # (see Shift.best_available_mapping_for)
-  #
-  def self.[](file)
-    pattern = File.basename(file.to_s.downcase)
-    until pattern.empty?
-      if MAPPINGS[pattern]
-        return best_available_mapping_for(pattern)
+    # Read and concatenate several files.
+    # (see Shift.read)
+    #
+    # TODO: glob
+    #
+    def concat(*globs)
+      buf = new('', File.extname(globs.first))
+      globs.each do |glob|
+        Dir[glob].each do |file|
+          buf.read_append(file)
+        end
       end
-      pattern.sub!(/^[^.]*\.?/, '')
+      buf
     end
-    raise UnknownFormatError, "no mapping matches #{file}"
+    alias :cat :concat
+
   end
+end
 
+# (see Shift.new)
+#
+def Shift(*args)
+  Shift.new(*args)
 end
 
+

data/lib/shift/action_map.rb

@@ -0,0 +1,106 @@
+
+module Shift
+
+  # A mapping of actions to interfaces. Handles validation,
+  # lookup, updates, link walking etc.
+  #
+  class ActionMap
+
+    def initialize(fallback, actions={})
+      @actions  = {}
+      @fallback = fallback
+      map(actions)
+    end
+
+    attr_reader :fallback
+
+    # Return a duplicate ActionHash without fallback,
+    # to be used for local queries.
+    def local
+      self.class.new(nil).map(@actions)
+    end
+
+    def map(actions)
+      begin
+        original = @actions.dup
+        parse(actions)
+        validate
+      rescue Shift::Error
+        @actions = original
+        raise
+      end; self
+    end
+
+    def to_hash(inherit=true)
+      (inherit && @fallback) ?
+        @actions.merge(@fallback) : @actions.dup
+    end
+
+    # Return a hash of mappings that are not links
+    def atoms(inherit=false)
+      to_hash(inherit).delete_if {|k,v| v.is_a?(Symbol) }
+    end
+
+    def eql?(other)
+      (eql_id.eql? other.eql_id) &&
+      (@fallback.eql? other.fallback)
+    end
+    alias :== :eql?
+
+    def eql_id
+      [to_hash(false), @fallback]
+    end
+    def hash; eql_id.hash; end
+
+    # Look up an action
+    def [](action)
+      action = action.to_sym
+      item = @actions[action] || (@fallback[action] if @fallback)
+      item.is_a?(Symbol) ? self[item] : item
+    end
+
+    def inspect
+      'ActionMap' + @actions.inspect
+    end
+
+    def dup
+      self.class.new(fallback ? @fallback.dup : @fallback, @actions)
+    end
+    
+  private
+
+    def parse(hsh)
+      hsh = {:default => hsh} unless hsh.is_a?(Hash)
+
+      hsh.each do |name, handler|
+        h = case handler
+          when Symbol, InterfaceList then handler
+          when Array  then handler.map {|cls| cls.to_s }
+          else [handler.to_s]
+        end
+        @actions[name] = h.is_a?(Array) ? InterfaceList.new(h) : h
+      end
+    end
+
+
+    def validate
+      @actions.each do |name, handler|
+        cycle_search(handler) if handler.is_a?(Symbol)
+      end
+    end
+
+    def cycle_search(action, visited=[])
+      visited << action
+      item    =  @actions[action]
+
+      raise(MappingError, "bad link #{action.inspect}") unless item
+
+      if visited.include?(item)
+        raise MappingError, 'cycle detected ' + visited.inspect
+      end
+      
+      cycle_search(item, visited) if item.is_a?(Symbol)
+    end
+
+  end
+end