tilt 1.4.1 → 2.0.11

data/TEMPLATES.md

@@ -1,516 +0,0 @@
-Tilt Templates
-==============
-
-(See <https://github.com/rtomayko/tilt/blob/master/TEMPLATES.md> for a rendered,
-HTML-version of this file).
-
-While all Tilt templates use the same basic interface for template loading and
-evaluation, each varies in its capabilities and available options. Detailed
-documentation on each supported template engine is provided below.
-
-There are also some file extensions that have several implementations
-(currently ERB and Markdown). These template classes have certain features
-which are guaranteed to work across all the implementations. If you wish to be
-compatible with all of these template classes, you should only depend on the
-cross-implementation features.
-
- * [ERB](#erb) - Generic ERB implementation (backed by erb.rb or Erubis)
- * [erb.rb](#erbrb) - `Tilt::ERBTemplate`
- * [Erubis](#erubis) - `Tilt::ErubisTemplate`
- * [Haml](#haml) - `Tilt::HamlTemplate`
- * [Liquid](#liquid) - `Tilt::LiquidTemplate`
- * Nokogiri - `Tilt::NokogiriTemplate`
- * Builder - `Tilt::BuilderTemplate`
- * Markaby - `Tilt::MarkabyTemplate`
- * [Radius](#radius) - `Tilt::RadiusTemplate`
-
-Tilt also includes support for CSS processors like [LessCSS][lesscss] and
-[Sass][sass], [CoffeeScript][coffee-script] and some simple text formats.
-
- * Less - `Tilt::LessTemplate`
- * Sass - `Tilt::SassTemplate`
- * Scss - `Tilt::ScssTemplate`
- * CoffeeScript - `Tilt::CoffeeScriptTemplate`
- * [Textile](#redcloth) - `Tilt::RedClothTemplate`
- * Creole - `Tilt::CreoleTemplate`
- * [RDoc](#rdoc) - `Tilt::RDocTemplate`
-
-Tilt has extensive support for Markdown, backed by one of four different
-implementations (depending on which are available on your system):
-
- * [Markdown](#markdown) - Generic Markdown implementation
- * [RDiscount](#rdiscount) - `Tilt::RDiscountTemplate`
- * Redcarpet - `Tilt::RedcarpetTemplate`
- * BlueCloth - `Tilt::BlueClothTemplate`
- * Kramdown - `Tilt::KramdownTemplate`
- * Maruku - `Tilt::MarukuTemplate`
-
-<a name='erb'></a>
-ERB (`erb`, `rhtml`)
---------------------
-
-ERB is a simple but powerful template languge for Ruby. In Tilt it's backed by
-[Erubis](#erubis) (if installed on your system) or by [erb.rb](#erbrb) (which
-is included in Ruby's standard library). This documentation applies to both
-implementations.
-
-### Example
-
-    Hello <%= world %>!
-
-### Usage
-
-ERB templates support custom evaluation scopes and locals:
-
-    >> require 'erb'
-    >> template = Tilt.new('hello.html.erb')
-    >> template.render(self, :world => 'World!')
-    => "Hello World!"
-
-Or, use `Tilt['erb']` directly to process strings:
-
-    template = Tilt['erb'].new { "Hello <%= world %>!" }
-    template.render(self, :world => 'World!')
-
-### Options
-
-#### `:trim => trim`
-
-Omits newlines and spaces around certain lines (usually those that starts with
-`<%` and ends with `%>`). There isn't a specification for how trimming in ERB
-should work, so if you need more control over the whitespace, you should use
-[erb.rb](#erbrb) or [Erubis](#erubis) directly.
-
-
-#### `:outvar => '_erbout'`
-
-The name of the variable used to accumulate template output. This can be
-any valid Ruby expression but must be assignable. By default a local
-variable named `_erbout` is used.
-
-<a name='erbrb'></a>
-erb.rb (`erb`, `rhtml`)
------------------------
-
-[ERB](#erb) implementation available in Ruby's standard library.
-
-All the documentation of [ERB](#erb) applies in addition to the following:
-
-### Usage
-
-The `Tilt::ERBTemplate` class is registered for all files ending in `.erb` or
-`.rhtml` by default, but with a *lower* priority than ErubisTemplate. If you
-specifically want to use ERB, it's recommended to use `#prefer`:
-
-    Tilt.prefer Tilt::ERBTemplate
-
-__NOTE:__ It's suggested that your program `require 'erb'` at load time when
-using this template engine within a threaded environment.
-
-### Options
-
-#### `:trim => true`
-
-The ERB trim mode flags. This is a string consisting of any combination of the
-following characters:
-
-  * `'>'`  omits newlines for lines ending in `>`
-  * `'<>'` omits newlines for lines starting with `<%` and ending in `%>`
-  * `'%'`  enables processing of lines beginning with `%`
-  * `true` is an alias of `<>`
-
-#### `:safe => nil`
-
-The `$SAFE` level; when set, ERB code will be run in a
-separate thread with `$SAFE` set to the provided level.
-
-#### `:outvar => '_erbout'`
-
-The name of the variable used to accumulate template output. This can be
-any valid Ruby expression but must be assignable. By default a local
-variable named `_erbout` is used.
-
-### See also
-
-  * [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html)
-
-
-<a name='erubis'></a>
-Erubis (`erb`, `rhtml`, `erubis`)
----------------------------------
-
-[Erubis][erubis] is a fast, secure, and very extensible implementation of [ERB](#erb).
-
-All the documentation of [ERB](#erb) applies in addition to the following:
-
-### Usage
-
-The `Tilt::ErubisTemplate` class is registered for all files ending in `.erb` or
-`.rhtml` by default, but with a *higher* priority than `ERBTemplate`. If you
-specifically want to use Erubis, it's recommended to use `#prefer`:
-
-    Tilt.prefer Tilt::ErubisTemplate
-
-__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
-using this template engine within a threaded environment.
-
-### Options
-
-#### `:engine_class => Erubis::Eruby`
-
-Allows you to specify a custom engine class to use instead of the
-default which is `Erubis::Eruby`.
-
-#### `:escape_html => false`
-
-When `true`, `Erubis::EscapedEruby` will be used as the engine class
-instead of the default. All content within `<%= %>` blocks will be
-automatically html escaped.
-
-#### `:outvar => '_erbout'`
-
-The name of the variable used to accumulate template output. This can be
-any valid Ruby expression but must be assignable. By default a local
-variable named `_erbout` is used.
-
-#### `:pattern => '<% %>'`
-
-Set pattern for embedded Ruby code.
-
-#### `:trim => true`
-
-Delete spaces around `<% %>`. (But, spaces around `<%= %>` are preserved.)
-
-### See also
-
-  * [Erubis Home][erubis]
-  * [Erubis User's Guide](http://www.kuwata-lab.com/erubis/users-guide.html)
-
-
-<a name='haml'></a>
-Haml (`haml`)
--------------
-
-[Haml][haml] is a markup language that’s used to cleanly and simply describe
-the HTML of any web document without the use of inline code. Haml functions as
-a replacement for inline page templating systems such as PHP, ASP, and ERB, the
-templating language used in most Ruby on Rails applications. However, Haml
-avoids the need for explicitly coding HTML into the template, because it itself
-is a description of the HTML, with some code to generate dynamic content.
-([more](http://haml.info/about.html))
-
-
-### Example
-
-    %html
-      %head
-        %title= @title
-      %body
-        %h1
-          Hello
-          = world + '!'
-
-### Usage
-
-The `Tilt::HamlTemplate` class is registered for all files ending in `.haml`
-by default. Haml templates support custom evaluation scopes and locals:
-
-    >> require 'haml'
-    >> template = Tilt.new('hello.haml')
-    => #<Tilt::HamlTemplate @file='hello.haml'>
-    >> @title = "Hello Haml!"
-    >> template.render(self, :world => 'Haml!')
-    => "
-    <html>
-      <head>
-        <title>Hello Haml!</title>
-      </head>
-      <body>
-        <h1>Hello Haml!</h1>
-      </body>
-    </html>"
-
-Or, use the `Tilt::HamlTemplate` class directly to process strings:
-
-    >> require 'haml'
-    >> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
-    => #<Tilt::HamlTemplate @file=nil ...>
-    >> template.render
-    => "<h1>Hello Haml!</h1>"
-
-__NOTE:__ It's suggested that your program `require 'haml'` at load time when
-using this template engine within a threaded environment.
-
-### Options
-
-Please see the [Haml Reference](http://haml.info/docs/yardoc/file.HAML_REFERENCE.html#options) for all available options.
-
-### See also
-
-  * [#haml.docs](http://haml.info/docs.html)
-  * [Haml Tutorial](http://haml.info/tutorial.html)
-  * [Haml Reference](http://haml.info/docs/yardoc/file.HAML_REFERENCE.html)
-
-
-<a name='liquid'></a>
-Liquid (`liquid`)
------------------
-
-[Liquid][liquid] is for rendering safe templates which cannot affect the
-security of the server they are rendered on.
-
-### Example
-
-    <html>
-      <head>
-        <title>{{ title }}</title>
-      </head>
-      <body>
-        <h1>Hello {{ world }}!</h1>
-      </body>
-    </html>
-
-### Usage
-
-`Tilt::LiquidTemplate` is registered for all files ending in `.liquid` by
-default. Liquid templates support locals and objects that respond to
-`#to_h` as scopes:
-
-    >> require 'liquid'
-    >> require 'tilt'
-    >> template = Tilt.new('hello.liquid')
-    => #<Tilt::LiquidTemplate @file='hello.liquid'>
-    >> scope = { :title => "Hello Liquid Templates" }
-    >> template.render(nil, :world => "Liquid")
-    => "
-    <html>
-      <head>
-        <title>Hello Liquid Templates</title>
-      </head>
-      <body>
-        <h1>Hello Liquid!</h1>
-      </body>
-    </html>"
-
-Or, use `Tilt::LiquidTemplate` directly to process strings:
-
-    >> require 'liquid'
-    >> template = Tilt::LiquidTemplate.new { "<h1>Hello Liquid!</h1>" }
-    => #<Tilt::LiquidTemplate @file=nil ...>
-    >> template.render
-    => "<h1>Hello Liquid!</h1>"
-
-__NOTE:__ It's suggested that your program `require 'liquid'` at load
-time when using this template engine within a threaded environment.
-
-### See also
-
-  * [Liquid for Programmers](https://wiki.github.com/Shopify/liquid/liquid-for-programmers)
-  * [Liquid Docs](http://liquid.rubyforge.org/)
-  * GitHub: [Shopify/liquid](https://github.com/Shopify/liquid/)
-
-
-<a name='radius'></a>
-Radius (`radius`)
------------------
-
-[Radius][radius] is the template language used by [Radiant CMS][radiant]. It is
-a tag language designed to be valid XML/HTML.
-
-### Example
-
-    <html>
-    <body>
-      <h1><r:title /></h1>
-      <ul class="<r:type />">
-      <r:repeat times="3">
-        <li><r:hello />!</li>
-      </r:repeat>
-      </ul>
-      <r:yield />
-    </body>
-    </html>
-
-### Usage
-
-To render a template such as the one above.
-
-    scope = OpenStruct.new
-    scope.title = "Radius Example"
-    scope.hello = "Hello, World!"
-
-    require 'radius'
-    template = Tilt::RadiusTemplate.new('example.radius', :tag_prefix=>'r')
-    template.render(scope, :type=>'hlist'){ "Jackpot!" }
-
-The result will be:
-
-    <html>
-    <body>
-      <h1>Radius Example</h1>
-      <ul class="hlist">
-        <li>Hello, World!</li>
-        <li>Hello, World!</li>
-        <li>Hello, World!</li>
-      </ul>
-      Jackpot!
-    </body>
-    </html>
-
-### See also
-
-  * [Radius][radius]
-  * [Radiant CMS][radiant]
-
-
-<a name='textile'></a>
-Textile (`textile`)
--------------------
-
-Textile is a lightweight markup language originally developed by Dean Allen and
-billed as a "humane Web text generator". Textile converts its marked-up text
-input to valid, well-formed XHTML and also inserts character entity references
-for apostrophes, opening and closing single and double quotation marks,
-ellipses and em dashes.
-
-Textile formatted texts are converted to HTML with the [RedCloth][redcloth]
-engine, which is a Ruby extension written in C.
-
-### Example
-
-    h1. Hello Textile Templates
-
-    Hello World. This is a paragraph.
-
-### Usage
-
-__NOTE:__ It's suggested that your program `require 'redcloth'` at load time
-when using this template engine in a threaded environment.
-
-### See Also
-
-  * [RedCloth][redcloth]
-
-
-<a name='rdoc'></a>
-RDoc (`rdoc`)
--------------
-
-[RDoc][rdoc] is the simple text markup system that comes with Ruby's standard
-library.
-
-### Example
-
-    = Hello RDoc Templates
-
-    Hello World. This is a paragraph.
-
-### Usage
-
-__NOTE:__ It's suggested that your program `require 'rdoc'`,
-`require 'rdoc/markup'`, and `require 'rdoc/markup/to_html'` at load time
-when using this template engine in a threaded environment.
-
-### See also
-
- * [RDoc][rdoc]
-
-
-<a name='markdown'></a>
-Markdown (`markdown`, `md`, `mkd`)
-----------------------------------
-
-[Markdown][markdown] is a lightweight markup language, created by John Gruber
-and Aaron Swartz. For any markup that is not covered by Markdown’s syntax, HTML
-is used.  Marking up plain text with Markdown markup is easy and Markdown
-formatted texts are readable.
-
-Markdown formatted texts are converted to HTML with one of these libraries:
-
-  * [RDiscount](#rdiscount) - `Tilt::RDiscountTemplate`
-  * Redcarpet - `Tilt::RedcarpetTemplate`
-  * BlueCloth - `Tilt::BlueClothTemplate`
-  * Kramdown - `Tilt::KramdownTemplate`
-  * Maruku - `Tilt::MarukuTemplate`
-
-Tilt will use fallback mode (as documented in the README) for determining which
-library to use. RDiscount has highest priority - Maruku has lowest.
-
-### Example
-
-    Hello Markdown Templates
-    ========================
-
-    Hello World. This is a paragraph.
-
-### Usage
-
-To wrap a Markdown formatted document with a layout:
-
-    layout = Tilt['erb'].new do
-      "<!doctype html><title></title><%= yield %>"
-    end
-    data = Tilt['md'].new { "# hello tilt" }
-    layout.render { data.render }
-    # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
-
-### Options
-
-Every implementation of Markdown *should* support these options, but there are
-some known problems with the Kramdown and Maruku engines.
-
-#### `:smartypants => true|false`
-
-Set `true` to enable [Smarty Pants][smartypants]
-style punctuation replacement.
-
-#### `:escape_html => true|false`
-
-Set `true` disallow raw HTML in Markdown contents. HTML is converted to
-literal text by escaping `<` characters.
-
-### See also
-
- * [Markdown Syntax Documentation](http://daringfireball.net/projects/markdown/syntax/)
-
-<a name='rdiscount'></a>
-RDiscount (`markdown`, `md`, `mkd`)
------------------------------------
-
-[Discount][discount] is an implementation of the Markdown markup language in C.
-[RDiscount][rdiscount] is a Ruby wrapper around Discount.
-
-All the documentation of [Markdown](#markdown) applies in addition to the following:
-
-### Usage
-
-The `Tilt::RDiscountTemplate` class is registered for all files ending in
-`.markdown`, `.md` or `.mkd` by default with the highest priority. If you
-specifically want to use RDiscount, it's recommended to use `#prefer`:
-
-    Tilt.prefer Tilt::RDiscountTemplate
-
-__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
-using this template engine within a threaded environment.
-
-### See also
-
-  * [Discount][discount]
-  * [RDiscount][rdiscount]
-  * GitHub: [rtomayko/rdiscount][rdiscount]
-
-
-[lesscss]: http://lesscss.org/ "Less CSS"
-[sass]: http://sass-lang.com/ "Sass"
-[coffee-script]: http://jashkenas.github.com/coffee-script/ "Coffee Script"
-[erubis]: http://www.kuwata-lab.com/erubis/ "Erubis"
-[haml]: http://haml.info/ "Haml"
-[liquid]: http://www.liquidmarkup.org/ "Liquid"
-[radius]: http://radius.rubyforge.org/ "Radius"
-[radiant]: http://radiantcms.org/ "Radiant CMS"
-[redcloth]: http://redcloth.org/ "RedCloth"
-[rdoc]: http://rdoc.rubyforge.org/ "RDoc"
-[discount]: http://www.pell.portland.or.us/~orc/Code/discount/ "Discount"
-[rdiscount]: http://github.com/rtomayko/rdiscount/ "RDiscount"
-[smartypants]: http://daringfireball.net/projects/smartypants/ "Smarty Pants"
-

data/lib/tilt/css.rb

@@ -1,80 +0,0 @@
-require 'tilt/template'
-
-module Tilt
-  # Sass template implementation. See:
-  # http://haml.hamptoncatlin.com/
-  #
-  # Sass templates do not support object scopes, locals, or yield.
-  class SassTemplate < Template
-    self.default_mime_type = 'text/css'
-
-    def self.engine_initialized?
-      defined? ::Sass::Engine
-    end
-
-    def initialize_engine
-      require_template_library 'sass'
-    end
-
-    def prepare
-      @engine = ::Sass::Engine.new(data, sass_options)
-    end
-
-    def evaluate(scope, locals, &block)
-      @output ||= @engine.render
-    end
-
-    def allows_script?
-      false
-    end
-
-  private
-    def sass_options
-      options.merge(:filename => eval_file, :line => line, :syntax => :sass)
-    end
-  end
-
-  # Sass's new .scss type template implementation.
-  class ScssTemplate < SassTemplate
-    self.default_mime_type = 'text/css'
-
-  private
-    def sass_options
-      options.merge(:filename => eval_file, :line => line, :syntax => :scss)
-    end
-  end
-
-   # Lessscss template implementation. See:
-  # http://lesscss.org/
-  #
-  # Less templates do not support object scopes, locals, or yield.
-  class LessTemplate < Template
-    self.default_mime_type = 'text/css'
-
-    def self.engine_initialized?
-      defined? ::Less
-    end
-
-    def initialize_engine
-      require_template_library 'less'
-    end
-
-    def prepare
-      if ::Less.const_defined? :Engine
-        @engine = ::Less::Engine.new(data)
-      else
-        parser  = ::Less::Parser.new(options.merge :filename => eval_file, :line => line)
-        @engine = parser.parse(data)
-      end
-    end
-
-    def evaluate(scope, locals, &block)
-      @output ||= @engine.to_css(options)
-    end
-
-    def allows_script?
-      false
-    end
-  end
-end
-