malt 0.2.0 → 0.3.0

data/History.rdoc

@@ -1,5 +1,24 @@
 = Release History
 
+
+== 0.3.0 | 2010-11-04
+
+New release adds a Malt::Machine class that encapsulates all
+Malt's class level functionality. This allow Malt to be 
+be more finaly controlled. For example an instance of 
+Malt::Machine can be used to limit rendering to a select
+set of formats.
+
+Changes:
+
+* Add Machine class to ecapsulate toplevel functions.
+* Add feature via Machine options to select available formats.
+* Add `#to_default` to for converting to default format.
+* Add `Malt.engine?` to test for supported engine types.
+* Rename `Malt.support?` to `Malt.format?`.
+* Rename `Malt.main` to `Malt.cli`.
+
+
 == 0.2.0 | 2010-10-22
 
 Malt now support Erector, Markaby, Builder and Mustache templates.

data/License.txt

@@ -1,4 +1,5 @@
 .
+
                              Apache License
                         Version 2.0, January 2004
                      http://www.apache.org/licenses/
@@ -201,4 +202,4 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 
-
+.

data/README.rdoc

@@ -18,7 +18,7 @@ very easy to implement thanks to it's clean design.
 
 === Functional API
 
-  Malt.render(:file=>'foo.erb', :format=>:html, :data=>data)
+  Malt.render(:file=>'foo.erb', :to=>:html, :data=>data)
 
 Where +data+ is a data source of some type. Malt will see
 that the file is an ERB template and render it accordingly.

data/bin/malt

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
 require 'malt'
-Malt.main(*ARGV)
+Malt.cli(*ARGV)
 

data/lib/malt.rb

@@ -1,5 +1,7 @@
+require 'malt/meta/data'
 require 'malt/kernel'
-require 'malt/render'
+require 'malt/machine'
+require 'malt/core_ext'
 
 module Malt
 
@@ -8,60 +10,42 @@ module Malt
   end
 
   #
-  def self.register(malt_class, *exts)
-    exts.each do |ext|
-      type = ext_to_type(ext)
-      registry[type] = malt_class
-    end
+  def self.machine
+    @machine ||= Machine.new
   end
 
   #
-  def self.registry
-    @registry ||= {}
+  def self.file(file, options={})
+    machine.file(file, options)
   end
 
   #
-  def self.support?(ext)
-    ext  = ext.to_s
-    type = ext.sub(/^\./, '').strip
-    return false if type.empty?
-    #@registry.key?(ext.to_sym)
-    #Engine.registry[type.to_sym]
-    Engine.registry.key?(type.to_sym)
+  def self.text(text, options={})
+    machine.text(text, options)
   end
 
   #
-  def self.file(file, options={})
-    type = options[:type] || options[:format] || File.extname(file)
-    type = ext_to_type(type)
-    malt_class = registry[type]
-    raise "unkown type -- #{type}" unless malt_class
-    malt_class.new(options.merge(:file=>file,:type=>type))
+  def self.open(url, options={})
+    machine.open(url, options)
   end
 
   #
-  def self.text(text, options={})
-    if file = options[:file]
-      ext = File.extname(file)
-      ext = nil if ext.empty?
-    end
-    type = options[:type] || options[:format] || ext
-    type = ext_to_type(type)
-    malt_class = registry[type] || Format::Text
-    #raise "unkown type -- #{type}" unless malt_class
-    malt_class.new(options.merge(:text=>text,:file=>file,:type=>type))
+  def self.render(params, &body)
+    machine.render(params, &body)
   end
 
   #
-  def self.open(url, options={})
-    require 'open-uri'
-    text = open(url).read
-    file = File.basename(url) # parse better with URI.parse
-    text(text, :file=>file)
+  def self.format?(ext)
+    machine.format?(ext)
+  end
+
+  # Returns true if the extension given is renderable.
+  def self.engine?(ext)
+    machine.engine?(ext)
   end
 
   #
-  def self.main(*args)
+  def self.cli(*args)
     require 'optparse'
     itype, otype = nil, nil
     OptionParser.new{|o|

data/lib/malt/engines/abstract.rb

@@ -22,6 +22,10 @@ module Engine
     @registry ||= {}
   end
 
+  #
+  def self.defaults
+    @defaults ||= {}
+  end
 
   # Abstract Template class serves as the base
   # class for all other Template classes.
@@ -38,10 +42,15 @@ module Engine
     def self.default(*exts)
       register(*exts)
       exts.each do |ext|
-        Malt.config.engine[ext.to_sym] = self
+        Engine.defaults[ext.to_sym] = self
       end
     end
 
+    #
+    def self.type
+      basename.downcase.to_sym
+    end
+
     #
     def initialize(settings={})
       @settings = settings.rekey

data/lib/malt/formats/abstract.rb

@@ -3,6 +3,23 @@ require 'malt/kernel'
 module Malt
 module Format
 
+  class << self
+    include Malt::Kernel
+  end
+
+  #
+  def self.register(malt_class, *exts)
+    exts.each do |ext|
+      type = ext_to_type(ext)
+      registry[type] = malt_class
+    end
+  end
+
+  #
+  def self.registry
+    @registry ||= {}
+  end
+
   # Abstract format class serves as the base
   # class for all other format classes.
   #
@@ -12,7 +29,7 @@ module Format
     # Register the class to an extension type.
     def self.register(*exts)
       @extensions = exts
-      Malt.register(self, *exts)
+      Malt::Format.register(self, *exts)
 
       #exts.each do |ext|
       #  Abstract.module_eval %{

data/lib/malt/formats/abstract_template.rb

@@ -10,7 +10,7 @@ module Format
 
     #
     def to(type, data=nil, &yld)
-      new_class   = Malt.registry[type.to_sym]
+      new_class   = Malt::Format.registry[type.to_sym]  # TODO: Malt.machine.format?
       new_text    = render(type, data, &yld)
       new_file    = refile(type)
       new_options = options.merge(:text=>new_text, :file=>new_file, :type=>type)
@@ -28,11 +28,11 @@ module Format
 
     # ERB templates can be any type.
     def method_missing(sym, *args, &yld)
-      if Malt.registry.key?(sym)
+      if Malt::Format.registry.key?(sym)  # TODO: Malt.machine.format?
         return render(sym, *args, &yld).to_s
       elsif md = /^to_/.match(sym.to_s)
         type = md.post_match.to_sym
-        if Malt.registry.key?(type)
+        if Malt::Format.registry.key?(type)  # TODO: Malt.machine.format?
           return to(type, *args, &yld)
         end
       end

data/lib/malt/formats/ruby.rb

@@ -29,7 +29,7 @@ module Malt::Format
 
     #
     def to(type, data=nil, &yld)
-      new_class   = Malt.registry[type.to_sym]
+      new_class   = Malt::Format.registry[type.to_sym]  # TODO: Malt.machine.format?
       new_text    = render(data, &yld)
       new_file    = refile(type)
       new_options = options.merge(:text=>new_text, :file=>new_file)
@@ -38,11 +38,11 @@ module Malt::Format
 
     # Ruby templates can be any type.
     def method_missing(sym, *args, &yld)
-      if Malt.registry.key?(sym)
+      if Malt::Format.registry.key?(sym)
         return to(sym, *args, &yld).to_s
       elsif md = /^to_/.match(sym.to_s)
         type = md.post_match.to_sym
-        if Malt.registry.key?(type)
+        if Malt::Format.registry.key?(type)  # TODO: Malt.machine.format?
           return to(type, *args, &yld)
         end
       end

data/lib/malt/machine.rb

@@ -0,0 +1,227 @@
+module Malt
+
+  # The Machine class encapsulates Malt's main methods
+  # along with configuratable settings to control
+  # which engines and formats are used for rendering.
+  #--
+  # TODO: Can we dynamically generate the MARKUP and TEMPLATE constants
+  # from the format classes? In anycase, the still need tweaking.
+  #++
+  class Machine
+
+    # List of markup types. These are formats that just allow markup transformations
+    # and do not provide for data injection.
+    MARKUP = [:rdoc, :markdown, :textile, :scss, :sass, :less, :css, :html, :xml]
+
+    # List of template types. These are template formats that provide data injection.
+    TEMPLATES = [:ruby, :erb, :liquid, :mustache, :tenjin, :ragtag, :radius, :erector, :builder, :markaby]
+
+    # Template types that prevent arbitrary Ruby code execution.
+    TEMPLATES_SAFE = [:liquid, :mustache]
+
+    # New Malt Machine.
+    #
+    # * config[:types]    - list of formats to handle
+    # * config[:priority] - list of prioritized engines
+    #
+    def initialize(config={})
+      if priority = config[:priority]
+        priority.map!{ |e| e.to_sym }
+      else
+        priority = []
+      end
+      if types = config[:types] || config[:type]
+        formats = {}
+        engines = {}
+        types.each do |type|
+          k = ext_to_type(type)
+          formats[k] = Malt::Format.registry[k]
+          engines[k] = Malt::Engine.registry[k]
+        end
+      else
+        formats = Malt::Format.registry #.dup
+        engines = Malt::Engine.registry #.dup
+      end
+      @formats  = formats
+      @engines  = engines
+      @priority = priority
+    end
+
+    #
+    def formats
+      @formats
+    end
+
+    #
+    def engines
+      @engines
+    end
+
+    # Engine priorities.
+    #
+    # Returns an Array of symbolic engine names.
+    def priority(type=nil)
+      if type
+        type = type.to_s.downcase.to_sym
+        @priority.unshift(type)
+        @priority.uniq!  # assuming first are kept
+      end
+      @priority
+    end
+
+    #
+    def engine?(ext)
+      type = ext_to_type(ext)
+      engines.key?(type)
+      ##ext  = ext.to_s
+      ##type = ext.sub(/^\./, '').strip
+      ##return false if type.empty?
+      ###@registry.key?(ext.to_sym)
+      ###Engine.registry[type.to_sym]
+      ##Engine.registry.key?(type.to_sym)
+    end
+
+    #
+    def format?(ext)
+      type = ext_to_type(ext)
+      formats.key?(type)
+    end
+
+    #
+    def file(file, options={})
+      type = options[:type] || options[:format] || File.extname(file)
+      type = ext_to_type(type)
+      malt_class = formats[type]
+      raise "unkown type -- #{type}" unless malt_class
+      malt_class.new(options.merge(:file=>file,:type=>type))
+    end
+
+    #
+    def text(text, options={})
+      if file = options[:file]
+        ext = File.extname(file)
+        ext = nil if ext.empty?
+      end
+      type = options[:type] || options[:format] || ext
+      type = ext_to_type(type)
+      malt_class = formats[type] || Format::Text  # :pass ?
+      #raise "unkown type -- #{type}" unless malt_class
+      malt_class.new(options.merge(:text=>text,:file=>file,:type=>type))
+    end
+
+    # Open a URL as a Malt Format object.
+    def open(url, options={})
+      require 'open-uri'
+      text = open(url).read
+      file = File.basename(url) # parse better with URI.parse
+      text(text, :file=>file)
+    end
+
+    # Render template directly.
+    #
+    # parameters[:file]   - File name of template. Used to read text.
+    # parameters[:text]   - Text of template document.
+    # parameters[:type]   - File type/extension used to look up engine.
+    # parameters[:pass]   - If not a supported type return text rather than raise an error.
+    # parameters[:engine] - Force the use of a this specific engine.
+    # parameters[:to]     - Format to convert to (usual default is `html`).
+    #
+    def render(parameters={}, &body)
+      type   = parameters[:type]
+      file   = parameters[:file]
+      text   = parameters[:text]
+      engine = parameters[:engine]
+
+      type   = file_type(file, type)
+      text   = file_read(file) unless text
+
+      engine_class = engine(type, engine)
+
+      if engine_class
+        parameters[:type] = type
+        parameters[:text] = text
+
+        engine = engine_class.new
+        engine.render(parameters, &body)
+      else
+        if parameters[:pass]
+          text
+        else
+          raise NoEngineError, "no engine to handle `#{type}' format"      
+        end
+      end
+    end
+
+    private
+
+    #
+    def engine(type, engine=nil)
+      type = ext_to_type(type)
+      #engine = engine || Malt.config.engine[type]  # FIXME
+      case engine
+      when Class
+        #raise unless Engine.registry[type].include?(engine)
+        engine
+      when String, Symbol
+        match = engine.to_s.downcase.to_sym
+        #Engine.registry[type].find{ |e| e.basename.downcase == match }
+        #engines[type].find{ |e| e.basename.downcase == match }
+        engines[type].find{ |e| match == e.type }
+      else
+        if engines[type]
+          #Engine.registry[type].first
+          types = engines[type]
+          if prior = types.find{ |e| priority.include?(e.type) }
+            return prior
+          end
+          if default = Engine.defaults[type]           
+            return default #if engine?(default.type)
+          end
+          types.first
+        else
+          nil
+        end
+      end
+    end
+
+    #
+    def file_type(file, type=nil)
+      ext = type || File.extname(file)
+      ext = ext.to_s.downcase
+      if ext.empty?
+        nil
+      elsif ext[0,1] == '.'
+        ext[1..-1].to_sym
+      else
+        ext.to_sym
+      end
+    end
+
+    #
+    #def ext_type(type)
+    #  type.to_s.downcase.sub(/^\./,'').to_sym
+    #end
+
+    # TODO: Handle File objects and URLs.
+    def file_read(file)
+      File.read(file)
+    end
+
+    # Normal file extension to a symbol type reference.
+    def ext_to_type(ext)
+      ext = ext.to_s.downcase
+      return nil if ext.empty?
+      if ext[0,1] == '.'
+        ext[1..-1].to_sym
+      else
+        ext.to_sym
+      end
+    end
+
+  end
+
+  #
+  class NoEngineError < ArgumentError
+  end
+
+end

data/lib/malt/meta/package

@@ -1,6 +1,6 @@
 name    : malt
-date    : 2010-10-22
-version : 0.2.0
+date    : 2010-11-04
+version : 0.3.0
 
 requires:
   - syckle   (build)

data/meta/package

@@ -1,6 +1,6 @@
 name    : malt
-date    : 2010-10-22
-version : 0.2.0
+date    : 2010-11-04
+version : 0.3.0
 
 requires:
   - syckle   (build)

data/qed/05_machine/01_limited_formats.rdoc

@@ -0,0 +1,29 @@
+== Limited Formats
+
+The Machine class makes it possible to control which formats
+are available for rendering.
+
+For example, let's make a Machine that only support RDoc format
+and no others.
+
+  malt = Malt::Machine.new(:types=>[:rdoc])
+
+Now we use the `malt` machine object to handle rendering. First let's
+make sure that the machine is infact setup to limit formats to just RDoc.
+
+  malt.formats.keys.assert = [:rdoc]
+
+  malt.assert.format?('.rdoc')
+  malt.refute.format?('.markdown')
+
+This being the case we should be able to render an RDoc file without issue.
+
+  malt.render(:file=>'qed/samples/sample.rdoc')
+
+Where as another format type, though usually supported, but excluded in this
+case, will fail.
+
+  expect Malt::NoEngineError do
+    malt.render(:file=>'qed/samples/sample.markdown')
+  end
+

data/qed/05_machine/02_prioritized_engines.rdoc

@@ -0,0 +1,34 @@
+== Prioritized Engines
+
+The Malt Machine class can also be used to prioritize engines.
+For instance, by default markdown documents are handled by
+the RDiscount library. 
+
+  malt = Malt::Machine.new
+
+  engine = malt.pry.engine(:markdown)
+  engine.assert == Malt::Engine::RDiscount
+
+To use Kramdown instead, we can specify
+it as a priority when initilizeing a new Machine.
+
+  malt = Malt::Machine.new(:priority=>[:kramdown])
+
+Lets check to make sure.
+
+  engine = malt.pry.engine(:markdown)
+  engine.assert == Malt::Engine::Kramdown
+
+To change the engine priorities of the master Malt Machine, provide 
+the #priority method with the type and it will put it at the top of
+the priority list.
+
+  Malt.machine.priority :kramdown
+
+Lets check to make sure.
+
+  engine = Malt.machine.pry.engine(:markdown)
+  engine.assert == Malt::Engine::Kramdown
+
+(If you are wondering, #pry is simply used to call a private method.)
+

data/qed/applique/malt.rb

@@ -1,4 +1,5 @@
 require 'malt'
+require 'ae/pry'
 
 When "say we have a (((\\w+))) document called '(((\\S+)))' containing" do |type, fname, text|
   file = File.join('tmp',fname)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: malt
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Thomas Sawyer
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-28 00:00:00 -04:00
+date: 2010-11-04 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -247,7 +247,6 @@ files:
 - features/step_definitions/engine_steps.rb
 - features/support/loadpath.rb
 - features/support/sample_class.rb
-- lib/malt/config.rb
 - lib/malt/core_ext.rb
 - lib/malt/engines/abstract.rb
 - lib/malt/engines/bluecloth.rb
@@ -300,11 +299,11 @@ files:
 - lib/malt/formats/yaml.rb
 - lib/malt/formats.rb
 - lib/malt/kernel.rb
+- lib/malt/machine.rb
 - lib/malt/markup.rb
 - lib/malt/meta/data.rb
 - lib/malt/meta/package
 - lib/malt/meta/profile
-- lib/malt/render.rb
 - lib/malt/template.rb
 - lib/malt.rb
 - meta/data.rb
@@ -331,6 +330,8 @@ files:
 - qed/03_formats/18_builder.rb
 - qed/03_formats/19_erector.rb
 - qed/03_formats/20_mustache.rdoc
+- qed/05_machine/01_limited_formats.rdoc
+- qed/05_machine/02_prioritized_engines.rdoc
 - qed/applique/malt.rb
 - qed/samples/data.yml
 - qed/samples/output-erb.txt

data/lib/malt/config.rb

@@ -1,12 +0,0 @@
-module Malt
-
-  class Config
-
-    #
-    def engine
-      @engine ||= {}
-    end
-
-  end
-
-end

data/lib/malt/render.rb

@@ -1,93 +0,0 @@
-require 'malt/kernel'
-require 'malt/config'
-require 'malt/core_ext'
-
-module Malt
-
-  extend Kernel
-
-  # 
-  def self.config
-    @config ||= Config.new
-  end
-
-  # Render template.
-  #
-  # parameters[:file]   - File name of template. Used to read text.
-  # parameters[:text]   - Text of template document.
-  # parameters[:type]   - File type/extension used to look up engine.
-  # parameters[:pass]   - If not a supported type return text rather than raise an error.
-  # parameters[:engine] - Force the use of a this specific engine.
-  # parameters[:to]     - Format to convert to (usual default is `html`).
-  #
-  def self.render(parameters={}, &body)
-    type   = parameters[:type]
-    file   = parameters[:file]
-    text   = parameters[:text]
-    engine = parameters[:engine]
-
-    type   = file_type(file, type)
-    text   = file_read(file) unless text
-
-    engine_class = engine(type, engine)
-
-    if engine_class
-      parameters[:type] = type
-      parameters[:text] = text
-
-      engine = engine_class.new
-      engine.render(parameters, &body)
-    else
-      if parameters[:pass]
-        text
-      else
-        raise "no engine to handle `#{type}' format"      
-      end
-    end
-  end
-
-  #
-  def self.engine(type, engine=nil)
-    type   = ext_to_type(type)
-    engine = engine || config.engine[type]
-    case engine
-    when Class
-      #raise unless Engine.registry[type].include?(engine)
-      engine
-    when String, Symbol
-      match = engine.to_s.downcase
-      Engine.registry[type].find{ |e| e.basename.downcase == match }
-    else
-      if Engine.registry[type]
-        Engine.registry[type].first
-      else
-        nil
-      end
-    end
-  end
-
-  #
-  def self.file_type(file, type=nil)
-    ext = type || File.extname(file)
-    ext = ext.to_s.downcase
-    if ext.empty?
-      nil
-    elsif ext[0,1] == '.'
-      ext[1..-1].to_sym
-    else
-      ext.to_sym
-    end
-  end
-
-  #
-  #def self.ext_type(type)
-  #  type.to_s.downcase.sub(/^\./,'').to_sym
-  #end
-
-  # TODO: Handle File objects and URLs.
-  def self.file_read(file)
-    File.read(file)
-  end
-
-end
-