malt 0.3.0 → 0.4.0

data/.ruby

@@ -0,0 +1,156 @@
+---
+source:
+- var
+authors:
+- name: trans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2010'
+  license: BSD-2-Clause
+replacements: []
+alternatives: []
+requirements:
+- name: blankslate
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: qed
+  groups:
+  - test
+  development: true
+- name: test
+  groups:
+  - test
+  development: true
+- name: lemon
+  groups:
+  - test
+  development: true
+- name: ae
+  groups:
+  - test
+  development: true
+- name: rdoc
+  version: 3+
+  groups:
+  - test
+  development: true
+- name: RedCloth
+  groups:
+  - test
+  development: true
+- name: bluecloth
+  groups:
+  - test
+  development: true
+- name: kramdown
+  groups:
+  - test
+  development: true
+- name: rdiscount
+  groups:
+  - test
+  development: true
+- name: haml
+  groups:
+  - test
+  development: true
+- name: sass
+  groups:
+  - test
+  development: true
+- name: less
+  groups:
+  - test
+  development: true
+- name: tenjin
+  groups:
+  - test
+  development: true
+- name: rtals
+  groups:
+  - test
+  development: true
+- name: liquid
+  groups:
+  - test
+  development: true
+- name: erubis
+  groups:
+  - test
+  development: true
+- name: mustache
+  groups:
+  - test
+  development: true
+- name: markaby
+  groups:
+  - test
+  development: true
+- name: builder
+  groups:
+  - test
+  development: true
+- name: radius
+  groups:
+  - test
+  development: true
+- name: ragtag
+  groups:
+  - test
+  development: true
+- name: redcarpet
+  groups:
+  - test
+  development: true
+- name: wikicloth
+  groups:
+  - test
+  development: true
+- name: maruku
+  groups:
+  - test
+  development: true
+- name: creole
+  groups:
+  - test
+  development: true
+- name: erector
+  groups:
+  - test
+  development: true
+- name: active_support
+  groups:
+  - test
+  development: true
+- name: coffee-script
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git@github.com:rubyworks/malt.git
+  scm: git
+  name: upstream
+resources:
+  home: http://rubyworks.github.com/malt
+  code: http://github.com/rubyworks/malt
+  wiki: http://wiki.github.com/rubyworks/malt
+  docs: http://rubyworks.github.com/malt/docs/api
+  bugs: http://github.com/rubyworks/malt/issues
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2010-06-22'
+summary: Multi-template/multi-markup rendering engine
+title: Malt
+version: 0.4.0
+name: malt
+description: Malt provides a factory framework for rendering a variety of template
+  and markup document formats.
+organization: rubyworks
+date: '2011-11-26'

data/Assembly

@@ -0,0 +1,28 @@
+---
+gem:
+  active: true
+
+github:
+  gh_pages: web
+
+dnote:
+  labels: ~
+  output: log/notes.html
+
+qedoc:
+  title: Malt Demonstrandum
+  output: web/qed.html
+
+email:
+  mailto:
+    - ruby-talk@ruby-lang.org
+    - rubyworks-mailinglist@googlegroups.com
+
+locat:
+  output: log/locat.html
+
+vclog:
+  output:
+    - log/changes.html
+    - log/history.html
+

data/COPYING.rdoc

@@ -0,0 +1,33 @@
+= COPYRIGHT NOTICES
+
+== Malt
+
+Copyright:: (c) 2010 Rubyworks
+License:: BSD-2-Clause
+Website:: http://rubyworks.github.com/malt
+
+    Malt - Multi-Template
+
+    Copyright 2010 Rubyworks. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+    AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/Gemfile

@@ -0,0 +1,10 @@
+source :rubygems
+gemspec
+
+## JRuby can't compile libv8 which both less and coffee-script gems depend.
+#if defined?(RUBY_ENGINE)
+#  if RUBY_ENGINE == 'jruby'
+#    @dependencies.reject!{ |d| d.name == 'less' or d.name == 'coffee-script' }
+#  end
+#end
+

data/HISTORY.rdoc

@@ -0,0 +1,102 @@
+= Release History
+
+== 0.4.0 | 2011-11-27
+
+This release of Malt is a major improvement over the previous release.
+Where as before not all formats behaved consistently --for instance,
+not all templating engines handled block yielding, this release has
+ensured consistent functionality across all engines. A couple of
+significant changes were made to do this.
+
+Most important to the end user, templating formats can no longer
+use `yield` to insert block content, but rather must use `content`.
+This was done to avoid unnecessary implementation complexity due
+to Ruby's limitation on the use of yield within Proc objects.
+The code is much cleaner and subsequently more robust thanks to 
+this change.
+
+The builder-style engines (Builder, Markaby, Erector and Nokogiri)
+have all been united under a single `Builder` format class. The
+common extension for such files is `.rbml`. These engines have been
+tweaked to behave uniformly, supporting explicit and implicit
+evaluation modes and using instance variables and externalized
+scope.
+
+In addition to these changes, a few new formats/engines have been
+added, including Creole, Maruku, WikiCloth, CoffeeScript and
+Nokogiri Builder.
+
+Changes:
+
+* Add Creole, Maruku and WikiCloth markup engine/formats.
+* Add CoffeeScript transpiler engine/formats.
+* Add Nokogiri Builder format.
+* Support `scope and `locals` style data, as well as `data` option.
+* Unified builder engines under one .rbml/.builder format.
+* Use #content instead of #yield for block content!
+* Add :multi option for multi-format rendering.
+* Overhaul internal engine API, for better overall design.
+* Formats delegate to master Malt.render method.
+
+
+== 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 finally 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 encapsulate 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.
+Erector, Markaby and Builder are Ruby-based formats --templates
+are simply Ruby code. This requires them to use instance variables
+in templates rather than local variables/methods. Something to keep
+in mind.
+
+Changes:
+
+* Add support for Erector templates.
+* Add support for Markaby templates.
+* Add support for Builder templates.
+* Add support for Mustache templates.
+* Add `:pass` option to render method.
+* Rename `:format` option to `:to` for render method.
+
+
+== 0.1.1 | 2010-09-21
+
+This release simple fixes two bugs. One to handle variant arity
+in format class #render methods. Currently the interface can vary
+dependent on whether they accept interpolation data or not (this will
+probably be uniform in the future). The other fix raises an error if
+no engine exists to handle a given format.
+
+Changes:
+
+* Bug fix to raise error if format not handled by any engine.
+* Bug fix to underlying #render calls to handle variant arities. 
+
+
+== 0.1.0 | 2010-08-23
+
+This if the initial release of Malt. I have no doubt the code base
+still needs some fine-tuning --hence the 0.1 version, but I have put
+it to good use with the latest version of Brite, my static website
+generator, so I know that it is at least is a working state.
+
+Changes:
+
+* Initial release.
+

data/README.rdoc

@@ -1,7 +1,10 @@
 = Malt
 
-* home: http://rubyworks.github.com/malt
-* code: http://github.com/rubyworks/malt
+{Homepage}[http://rubyworks.github.com/malt] |
+{Development}[http://github.com/rubyworks/malt] |
+{Mailing List}[http://groups.google.com/group/rubyworks-mailinglist]
+
+{<img src="http://travis-ci.org/rubyworks/malt.png" />}[http://travis-ci.org/rubyworks/malt]
 
 
 == DESCRIPTION
@@ -41,11 +44,13 @@ Notice the #to_s. This is needed because #to_html returns an
 Malt::Format::HTML object.
 
 
-== COMING SOON
-
-Malt can also "multi-render".
+== LIMITATIONS
 
-  Malt.file('foo.rdoc.erb').to_html(data)   # ~> foo.html
+*JRuby* and *Rubinus* users: Not all template systems work with your Ruby.
+Consequently not all of Malt will work either. Thankfully Malt only
+requires template engines as they are needed, so it will work fine
+in most cases. But, you will need to avoid engines that depend on compiled
+code, such as +less+ and +coffee-script+.
 
 
 == INSTALATION
@@ -63,10 +68,11 @@ cd into it and run setup.rb, e.g.
   $ sudo setup.rb
 
 
-== COPYING
 
-Copyright (c) 2010 Thomas Sawyer
+== COPYRIGHTS
+
+Copyright (c) 2010 Rubyworks
 
-This program is ditributed under the terms of the Apache 2.0 license.
+This program is ditributed under the terms of the *BSD-2-Clause* license.
 
-See the LICENSE.txt file for details.
+See the COPYING.rdoc file for details.

data/Reapfile

@@ -0,0 +1,4 @@
+desc "ruby unit tests"
+task :test do
+  sh "ruby-test -r./test/helper.rb test/"
+end

data/lib/malt.rb

@@ -1,10 +1,9 @@
-require 'malt/meta/data'
+require 'malt/core_ext'
+require 'malt/version'
 require 'malt/kernel'
 require 'malt/machine'
-require 'malt/core_ext'
 
 module Malt
-
   class << self
     include Malt::Kernel
   end
@@ -14,32 +13,61 @@ module Malt
     @machine ||= Machine.new
   end
 
-  #
+  # Render a file.
   def self.file(file, options={})
     machine.file(file, options)
   end
 
-  #
+  # Render text string.
   def self.text(text, options={})
     machine.text(text, options)
   end
 
-  #
+  # Render a URL.
   def self.open(url, options={})
     machine.open(url, options)
   end
 
+  # Render a document.
+  #
+  # param [Hash] params
+  #   Rendering parameters.
+  #
+  # option params [Symbol] :to
+  #   The format to which the file/text is to be rendered.
+  #
+  # option params [String] :file
+  #   The file to be rendered. If `:text` is not given, this file must exist on disk
+  #   so it can be read-in to fill in the `:text` option. If text is given, the file
+  #   is only used to help determine type and clarify error messages.
+  #
+  # option params [String] :text
+  #   The text to render. This option is required unless `:file` is given.
+  #
+  # option params [Symbol] :type
+  #   The format of the text. This will be determined automatically by the `:file`
+  #    option if it is given and has a recognized extension. Otherwise it needs
+  #    be explicitly provided.
+  #
+  # option params [Hash,Object,Binding,Array] :data
+  #   The data source used for evaluation. This can be a locals hash, a scope
+  #   object or binding, or an array of a scope object/binding and locals hash.
+  #   This option is split-up into :scope and :locals before passing on to 
+  #   the redering engine.
+  #
+  # option params [Boolean] :pass
+  #   If not a supported type return text rather than raise an error.
   #
   def self.render(params, &body)
     machine.render(params, &body)
   end
 
-  #
+  # Returns `true` if the extension given is a recognized format.
   def self.format?(ext)
     machine.format?(ext)
   end
 
-  # Returns true if the extension given is renderable.
+  # Returns `true` if the extension given is renderable.
   def self.engine?(ext)
     machine.engine?(ext)
   end