malt 0.1.0 → 0.1.1

data/lib/malt/template.rb

@@ -0,0 +1,12 @@
+module Malt
+
+  # Template base case.
+  #
+  class Template < Markup
+
+    def compile(db, &yld)
+    end
+
+  end
+
+end

data/meta/gemfile

@@ -1,6 +1,6 @@
 name    : malt
-date    : 2010-09-07
-version : 0.1.0
+date    : 2010-10-21
+version : 0.1.1
 
 requires:
   - syckle   (build)

data/qed/01_overview.rdoc

@@ -1,44 +1,8 @@
-= Malt
+= Introduction
 
-Malt is a multi-template rendering framework.
-
-  require 'malt'
-
-For example lets say we have a document called 'test.rdoc' containing ...
-
-  = Example
-
-  This is an example of RDOC rendering.
-
-We can convert RDoc documents to html using the universal, functional
-interface easily enough.
-
-  html = Malt.render(:file=>'tmp/test.rdoc')
-
-In this example, Malt recognizes the type of file by the '.rdoc' extension
-and renders it using the default redering engine (in this case RDoc itself).
-By default the engine renders to HTML, so we did not need to specify
-the output :format option to the +render+ method.
-
-Alternately we can use the object-oriented interface.
-
-  rdoc = Malt.file('tmp/test.rdoc')
-
-First we will notice that the output is an instance of Malt::Formats::HTML.
-
-  rdoc.class.assert == Malt::Formats::RDoc
-
-While we could have used `Malt::Formats::RDoc.new` to create the object directly,
-Malt provides the #file, as well as #text, methods for convience. We can convert
-the rdoc to html with the #to_html method.
-
-  html = rdoc.to_html
-
-Again notice that the output is an instance of Malt::Formats::HTML.
-
-  html.class.assert == Malt::Formats::HTML
-
-And that by calling #to_s we can get the rendered HTML document.
-
-  html.to_s.assert.include?('<h1>Example</h1>')
+Malt is a multi-template rendering framework. It provides two convenient
+interfaces for working with backend template systems. The first is 
+a functional interface via `Malt.render` method. And the second is an
+object-oriented interface that can be easily constructed via the 
+`Malt.file` or `Malt.text` methods.
 

data/qed/02_formats.rdoc

@@ -0,0 +1,39 @@
+= Formats
+
+We have created a set of sample documents in the samples directory.
+We will take each format in turn.
+
+  formats = %w{erb liquid}
+
+Included with the format samples are files containing the expected results
+of each rendering.
+
+  expected_output = {}
+
+  formats.each do |format|
+    expected_output[format] = File.read("qed/samples/output-#{format}.txt")
+  end
+
+The data to inject into the formats that interpolate, is also stored in the
+samples folder.
+
+  data = YAML.load(File.new('qed/samples/data.yml'))
+
+Now we can render each of thes formats, and verify we get the expected result.
+
+  formats.each do |format|
+    output = Malt.render(:file=>"qed/samples/sample.#{format}", :format=>format, :data=>data)
+    output.assert == expected_output[format]
+  end
+
+Notice that formats the do not use interpolation data simply ignore it even
+if it is given.
+
+We can also handle the files in a more object-oriented manner.
+
+  formats.each do |format|
+    object = Malt.file("qed/samples/sample.#{format}", :format=>format)
+    output = object.render(data)
+    output.assert == expected_output[format]
+  end
+

data/qed/03_formats/01_overview.rdoc

@@ -0,0 +1,7 @@
+= Formats
+
+Malt support a wide variety of markup and template systems.
+
+Malt provides two distinct APIs for rendering each format --a single-point-of-entry
+functional interface, `Malt.render`, and an object-oriented interface where by
+each format is represented by a document class.

data/qed/03_formats/02_rdoc.rdoc

@@ -0,0 +1,83 @@
+== RDoc
+
+Lets say we have a RDoc document called 'test.rdoc' containing:
+
+  = Example
+
+  This is an example of RDoc rendering.
+
+We can convert rdoc documents to html easily via the univeral +render+ function.
+
+  html = Malt.render(:file=>'tmp/test.rdoc')
+
+  html.assert.include?('<h1>Example</h1>')
+
+Malt recognizes the type of file by the '.rdoc' extension and renders it using
+the default redering engine (in this case RDoc itself). By default the engine
+renders to HTML, so we did not need to specify the output :format option to
+the +render+ method.
+
+If we have a file that has a different extension, but is in fact an RDoc
+document, we can inform Malt.
+
+Lets say we have an RDoc document called 'test.txt' containing:
+
+  = Example
+
+  This is an example of RDoc rendering.
+
+We can inform Malt as the actual type using the `:type` option.
+
+  html = Malt.render(:file=>'tmp/test.txt', :type=>:rdoc)
+
+  html.assert.include?('<h1>Example</h1>')
+
+Alternately we can use the object-oriented interface. Again, lets say we have
+an RDoc document called 'test.rdoc' containing ...
+
+  = Example
+
+  This is an example of RDOC rendering.
+
+Then we can use the `Malt.file` method to instantiate an RDoc object.
+
+  rdoc = Malt.file('tmp/test.rdoc')
+
+We will notice that the output is an instance of Malt::Formats::HTML.
+
+  rdoc.class.assert == Malt::Format::RDoc
+
+While we could have used `Malt::Formats::RDoc.new` to create the object directly,
+Malt provides the #file, as well as #text, methods for convience. We can convert
+the rdoc to html with the #to_html method.
+
+  html = rdoc.to_html
+
+Again notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+And that by calling #to_s we can get the rendered HTML document.
+
+  html.to_s.assert.include?('<h1>Example</h1>')
+
+We can convert rdoc documents to html very easily.
+
+  rdoc = Malt.file('tmp/test.rdoc')
+
+  html = rdoc.to_html
+
+First we will notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+And that by calling #to_s we can get the rendered HTML document.
+
+  html.to_s.assert.include?('<h1>Example</h1>')
+
+Or we can convert the RDoc document directly to HTML via the #html method.
+
+  out = rdoc.html
+
+  out.assert.include?('<h1>Example</h1>')
+

data/qed/03_formats/03_textile.rdoc

@@ -0,0 +1,48 @@
+== Textile
+
+Malt supports Textile via RedCloth.
+
+Lets say we have a Textile document called 'test.tt' containing ...
+
+  h1. Example
+
+  This is an example of Textile rendering.
+
+We can redner the textile document via the universal render function.
+Textile documents are recognized by the +.textile+ or +.tt+ extension.
+
+  html = Malt.render(:file=>'tmp/test.tt')
+
+  html.assert.include?('<h1>Example</h1>')
+
+Malt supports Textile via either the RedCloth or the ___ backend.
+
+Lets say we have an Textile document called 'test.tt' containing ...
+
+  h1. Example
+
+  This is an example of Textile rendering.
+
+We can access the file via the +Malt.file+ method. Textile documents are
+recognized by the +.textile+ or +.tt+ extension.
+
+  tile = Malt.file('tmp/test.tt')
+
+We can the convert the document to a Malt Html object via the #to_html method.
+
+  html = tile.to_html
+
+Notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+And that by calling #to_s we can get the rendered HTML document.
+
+  html.to_s.assert.include?('<h1>Example</h1>')
+
+Or we can convert the document directly to HTML via the #html method.
+
+  out = tile.html
+
+  out.assert.include?('<h1>Example</h1>')
+

data/qed/03_formats/04_markdown.rdoc

@@ -0,0 +1,66 @@
+== Markdown
+
+Malt supports Markdown via either the RDiscount, BlueCloth or Kramdown backends.
+
+Lets say we have a Markdown document called 'test.md' containing ...
+
+  # Example
+
+  This is an example of Markdown rendering.
+
+Markdown documents are recognized by the +.markdown+ or +.md+ file extensions.
+
+  html = Malt.render(:file=>'tmp/test.md')
+
+  html.assert.include?('<h1>Example</h1>')
+
+By default teh RDiscount library is used to render markdown documents, but
+Malt supports BlueCloth and Kramdown as well. These case be used by setting
+the :engine option.
+
+  html = Malt.render(:file=>'tmp/test.md', :engine=>:bluecloth)
+
+And as we can see the document rendered as expected.
+
+  html.assert.include?('<h1>Example</h1>')
+
+And using the Kramdown library,
+
+  html = Malt.render(:file=>'tmp/test.md', :engine=>:kramdown)
+
+We can see the document rendered as well, though notice that Kramdown provides
+some bonus features compared to the other rendering engines.
+
+  html.assert.include?('<h1 id="example">Example</h1>')
+
+Malt supports Markdown via either the RDiscount, BlueCloth or Kramdown backends.
+
+Lets say we have an Markdown document called 'test.md' containing ...
+
+  # Example
+
+  This is an example of Markdown rendering.
+
+We can access the file via the +Malt.file+ method. Markdown documents are
+recognized by the +.markdown+ or +.md+ file extensions.
+
+  mark = Malt.file('tmp/test.md')
+
+We can the convert the document to a Malt Html object via the #to_html method.
+
+  html = mark.to_html
+
+Notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+And that by calling #to_s we can get the rendered HTML document.
+
+  html.to_s.assert.include?('<h1>Example</h1>')
+
+Or we can convert the document directly to HTML via the #html method.
+
+  out = mark.html
+
+  out.assert.include?('<h1>Example</h1>')
+

data/qed/03_formats/05_erb.rdoc

@@ -0,0 +1,65 @@
+== ERB
+
+Malt supports ERB via the ERB and Erubis engines. 
+
+Lets say we have a ERB document called 'test.erb' containing ...
+
+  <h1>Example <%= title %></h1>
+
+  <p>This is an example of ERB template.</p>
+
+We can render erb documents via the +render+ method, as we can any format.
+However, becuase ERB if a template format and not just a markup syntax,
+we need to also provide the +render+ methods with data for interpolation
+into the ERB document. 
+
+  data = { :title=>"Document" }
+
+  html = Malt.render(:file=>'tmp/test.erb', :data=>data)
+
+And as we can see the document rendered as expected.
+
+  html.assert.include?('<h1>Example Document</h1>')
+
+ERB doesn't actually care what format the document is rendered as. The 
+template could have been any text file what so ever, so using the `:format`
+option would have no effect here.
+
+By default the common ERB library is used to render erb documents. By setting
+the :engine option, Erubis can be used instead.
+
+  html = Malt.render(:file=>'tmp/test.erb', :data=>data, :engine=>:erubis)
+
+And as we can see the document rendered as expected.
+
+  html.assert.include?('<h1>Example Document</h1>')
+
+Malt supports template engines as well as formats. 
+
+Lets say we have an ERB document called 'test.erb' containing ...
+
+  <h1>Example <%= title %></h1>
+
+  <p>This is an example of ERB template.</p>
+
+We can render erb documents to any format we wish.
+
+  erb = Malt.file('tmp/test.erb')
+
+  html = erb.to_html(:title=>"Document")
+
+We will notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+And that by calling #to_s we can get the rendered HTML document.
+
+  html.to_s.assert.include?('<h1>Example Document</h1>')
+
+Or we can convert the document directly to HTML via the #html method.
+
+  out = erb.html(:title=>"Alternate")
+
+  out.assert.include?('<h1>Example Alternate</h1>')
+
+ERB doesn't actually care what format the document is rendered as.

data/qed/03_formats/06_liquid.rdoc

@@ -0,0 +1,54 @@
+== Liquid
+
+Lets say we have a Liquid document called 'test.liquid' containing:
+
+  <h1>Example {{ title }}</h1>
+
+  <p>This is an example of a Liquid template.</p>
+
+We can render liquid documents via the +render+ method, as we can any format.
+However, becuase Liquid is a template format and not just a markup syntax,
+we need to also provide the +render+ function with data for interpolation
+into the liquid document. 
+
+  data = { :title=>"Document" }
+
+  html = Malt.render(:file=>'tmp/test.liquid', :data=>data)
+
+  html.assert.include?('<h1>Example Document</h1>')
+
+Liquid doesn't actually care what format the document is rendered as, since it
+is purely a template engine that can be applied to any other format.
+Lets say we have a Liquid document called 'test.liquid' containing ...
+
+  <h1>Example {{ title }}</h1>
+
+  <p>This is an example of a Liquid template.</p>
+
+We can render erb documents to any format we wish.
+
+  liq = Malt.file('tmp/test.liquid')
+
+  html = liq.to_html(:title=>"Document")
+
+We will notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+We will notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+Then by calling #to_s we can get the rendered HTML document.
+
+  html.to_s.assert.include?('<h1>Example Document</h1>')
+
+Or we can convert the document directly to HTML via the #html method.
+
+  out = liq.html(:title=>"Alternate")
+
+  out.assert.include?('<h1>Example Alternate</h1>')
+
+Liquid doesn't actually care what format the document is rendered as, since it
+is purely a template engine that can be applied to any format.
+

data/qed/03_formats/07_haml.rdoc

@@ -0,0 +1,44 @@
+== Haml
+
+Lets say we have a Haml document called 'test.haml' containing:
+
+  %h1== Example #{title}
+  %p This is an example of a Haml template.
+
+We can render Haml documents via the +render+ method, as we can any format.
+While it might not appear as such on first glance, Haml is actually a template
+format and not just a markup language, so we need to also provide the +render+
+function with data for interpolation into the Haml document. 
+
+  data = { :title=>"Document" }
+
+  html = Malt.render(:file=>'tmp/test.haml', :data=>data)
+
+  html.assert.include?('<h1>Example Document</h1>')
+
+We can get a hold of the Haml document via the Malt.file function.
+
+  haml = Malt.file('tmp/test.haml')
+
+  haml.class.assert == Malt::Format::Haml
+
+We can convert Haml documents to html very easily.
+
+  data = {:title => "Document"}
+
+  html = haml.to_html(data)
+
+First we will notice that the output is an instance of Malt::Format::HTML.
+
+  html.class.assert == Malt::Format::HTML
+
+And that by calling #to_s we can get the rendered HTML document.
+
+  html.to_s.assert.include?('<h1>Example Document</h1>')
+
+Or we can convert the Haml document directly to HTML via the #html method.
+
+  out = haml.html(data)
+
+  out.assert.include?('<h1>Example Document</h1>')
+