haml 4.0.0 → 5.0.0

data/REFERENCE.md

@@ -121,7 +121,7 @@ see {Haml::Options}.
 
 ### Encodings
 
-When using Ruby 1.9 or later, Haml supports the same sorts of
+Haml supports the same sorts of
 encoding-declaration comments that Ruby does. Although both Ruby and Haml
 support several different styles, the easiest it just to add `-# coding:
 encoding-name` at the beginning of the Haml template (it must come before all
@@ -130,8 +130,8 @@ encoding.
 
 By default, the HTML generated by Haml has the same encoding as the Haml
 template. However, if `Encoding.default_internal` is set, Haml will attempt to
-use that instead. In addition, the [`:encoding` option](#encoding-option) can be
-used to specify an output encoding manually.
+use that instead. In addition, the {Haml::Options#encoding `:encoding` option}
+can be used to specify an output encoding manually.
 
 Note that, like Ruby, Haml does not support templates encoded in UTF-16 or
 UTF-32, since these encodings are not compatible with ASCII. It is possible to
@@ -186,7 +186,6 @@ is compiled to:
 
 ## HTML Elements
 
-
 ### Element Name: `%`
 
 The percent character is placed at the beginning of a line. It's followed
@@ -234,8 +233,7 @@ is compiled to:
 
     <script src='javascripts/script_9' type='text/javascript'></script>
 
-#### `:class` and `:id` Attributes
-{#class-and-id-attributes}
+#### `:class` and `:id` Attributes {#class-and-id-attributes}
 
 The `:class` and `:id` attributes can also be specified as a Ruby array whose
 elements will be joined together. A `:class` array is joined with `" "` and an
@@ -307,7 +305,7 @@ hash-style attributes:
 
 #### Ruby 1.9-style Hashes
 
-On Ruby 1.9, Haml also supports Ruby's new hash syntax:
+Haml also supports Ruby's new hash syntax:
 
     %a{title: @title, href: href} Stuff
 
@@ -330,7 +328,7 @@ This is compiled to:
     </html>
 
 You can use as many such attribute methods as you want by separating them with
-commas, like a Ruby argument list. All the hashes will me merged together, from
+commas, like a Ruby argument list. All the hashes will be merged together, from
 left to right. For example, if you defined
 
     def hash1
@@ -390,27 +388,49 @@ or using `true` and `false`:
 
     %input(selected=true)
 
-#### HTML5 Custom Data Attributes
+<!-- The title to the next section (Prefixed Attributes) has changed. This
+<a> tag is so old links to here still work. -->
+<a id="html5_custom_data_attributes" style="border:0;"></a>
+
+#### Prefixed Attributes
 
-HTML5 allows for adding [custom non-visible data
-attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data)
-to elements using attribute names beginning with `data-`. Custom data attributes
-can be used in Haml by using the key `:data` with a Hash value in an attribute
-hash. Each of the key/value pairs in the Hash will be transformed into a custom
-data attribute. For example:
+HTML5 allows for adding
+[custom non-visible data attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data-with-the-data-*-attributes)
+to elements using attribute names beginning with `data-`. The
+[Accessible Rich Internet Applications](http://www.w3.org/WAI/intro/aria)
+specification makes use of attributes beginning with `aria-`. There are also
+frameworks that use non-standard attributes with a common prefix.
 
-    %a{:href=>"/posts", :data => {:author_id => 123}} Posts By Author
+Haml can help generate collections of attributes that share a prefix like
+these. Any entry in an attribute hash that has a Hash as its value is expanded
+into a series of attributes, one for each key/value pair in the hash, with the
+attribute name formed by joining the “parent” key name to the key name with a
+hyphen.
+
+For example:
+
+    %a{:href=>"/posts", :data => {:author_id => 123, :category => 7}} Posts By Author
 
 will render as:
 
-    <a data-author-id='123' href='/posts'>Posts By Author</a>
+    <a data-author-id='123' data-category='7' href='/posts'>Posts By Author</a>
 
 Notice that the underscore in `author_id` was replaced by a hyphen. If you wish
-to suppress this behavior, you can set Haml's [`:hyphenate_data_attrs`
-option](#hyphenate_data_attrs-option) to `false`, and the output will be
-rendered as:
+to suppress this behavior, you can set Haml's
+{Haml::Options#hyphenate_data_attrs `:hyphenate_data_attrs` option} to `false`,
+and the output will be rendered as:
+
+    <a data-author_id='123' data-category='7' href='/posts'>Posts By Author</a>
+
+This expansion of hashes is recursive – any value of the child hash that is
+itself a hash will create an attribute for each entry, with the attribute name
+prefixed with all ancestor keys. For example:
 
-    <a data-author_id='123' href='/posts'>Posts By Author</a>
+    .book-info{:data => {:book => {:id => 123, :genre => 'programming'}, :category => 7}}
+
+will render as:
+
+    <div class='book-info' data-book-genre='programming' data-book-id='123' data-category='7'></div>
 
 ### Class and ID: `.` and `#`
 
@@ -492,31 +512,33 @@ and is compiled to:
       </div>
     </div>
 
-### Self-Closing Tags: `/`
+### Empty (void) Tags: `/`
 
 The forward slash character, when placed at the end of a tag definition, causes
-the tag to be self-closed. For example:
+Haml to treat it as being an empty (or void) element. Depending on the format,
+the tag will be rendered either without a closing tag (`:html4` or `:html5`), or
+as a self-closing tag (`:xhtml`).
+
+Taking the following as an example:
 
     %br/
     %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}/
 
-is compiled to:
-
-    <br />
-    <meta http-equiv='Content-Type' content='text/html' />
-
-Some tags are automatically closed, as long as they have no content. `meta`,
-`img`, `link`, `script`, `br`, and `hr` tags are closed by default. This list
-can be customized by setting the [`:autoclose`](#autoclose-option) option. For
-example:
+When the format is `:html4` or `:html5` this is compiled to:
 
-    %br
-    %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}
+    <br>
+    <meta content='text/html' http-equiv='Content-Type'>
 
-is also compiled to:
+and when the format is `:xhtml` it is compiled to:
 
     <br />
-    <meta http-equiv='Content-Type' content='text/html' />
+    <meta content='text/html' http-equiv='Content-Type' />
+
+Some tags are automatically treated as being empty, as long as they have no
+content in the Haml source. `meta`, `img`, `link`, `br`, `hr`, `input`,
+`area`, `param`, `col` and `base` tags are treated as empty by default. This
+list can be customized by setting the {Haml::Options#autoclose `:autoclose`}
+option.
 
 ### Whitespace Removal: `>` and `<`
 
@@ -621,6 +643,12 @@ is compiled to:
       Hello!
     </div>
 
+The `:class` attribute may be used in conjunction with an object
+reference.  The compiled element will have the union of all classes.
+
+    - user = User.find(1)
+    %p[user]{:class => 'alpha bravo'}
+    <p id="user_1" class="alpha bravo user"></p>
 
 ## Doctype: `!!!`
 
@@ -651,7 +679,7 @@ is compiled to:
     </html>
 
 You can also specify the specific doctype after the `!!!` When the
-[`:format`](#format-option) is set to `:xhtml`. The following doctypes are
+{Haml::Options#format `:format`} is set to `:xhtml`. The following doctypes are
 supported:
 
 `!!!`
@@ -686,7 +714,7 @@ supported:
 : XHTML+RDFa 1.0<br/>
  `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">`
 
-When the [`:format`](#format-option) option is set to `:html4`, the following
+When the {Haml::Options#format `:format`} option is set to `:html4`, the following
 doctypes are supported:
 
 `!!!`
@@ -701,7 +729,7 @@ doctypes are supported:
 : HTML 4.01 Frameset<br/>
  `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">`
 
-When the [`:format`](#format-option) option is set to `:html5`,
+When the {Haml::Options#format `:format`} option is set to `:html5`,
 `!!!` is always `<!DOCTYPE html>`.
 
 If you're not using the UTF-8 character set for your document, you can specify
@@ -772,6 +800,21 @@ is compiled to:
       </a>
     <![endif]-->
 
+To generate “downlevel-revealed” conditional comments, where the content is
+hidden from IE but not other browsers,  add a `!` before the brackets: `/![]`.
+Haml will produce valid HTML when generating this kind of conditional comment.
+
+For example:
+
+    /![if !IE]
+      You are not using Internet Explorer, or are using version 10+.
+
+is compiled to:
+
+    <!--[if !IE]><!-->
+      You are not using Internet Explorer, or are using version 10+.
+    <!--<![endif]-->
+
 ### Haml Comments: `-#`
 
 The hyphen followed immediately by the pound sign signifies a silent comment.
@@ -821,7 +864,7 @@ is compiled to:
       yo
     </p>
 
-If the [`:escape_html`](#escape_html-option) option is set, `=` will sanitize
+If the {Haml::Options#escape_html `:escape_html`} option is set, `=` will sanitize
 any HTML-sensitive characters generated by the script. For example:
 
     = '<script>alert("I\'m evil!");</script>'
@@ -941,7 +984,7 @@ Ruby string interpolation. For example,
 
 is the same as
 
-    %p= "This is the #{h quality} cake!"
+    %p= "This is #{h quality} cake!"
 
 and might compile to:
 
@@ -978,6 +1021,21 @@ might compile to:
       //]]>
     </script>
 
+#### Gotchas
+
+Haml uses an overly simplistic regular expression to identify string
+interpolation rather than a full-blown Ruby parser. This is fast and works for
+most code but you may have errors with code like the following:
+
+    %span #{'{'}
+
+This code will generate a syntax error, complaining about unbalanced brackets.
+In cases like this, the recommended workaround is output the code as a Ruby
+string to force Haml to parse the code with Ruby.
+
+    %span= "#{'{'}"
+
+
 ### Escaping HTML: `&=` {#escaping_html}
 
 An ampersand followed by one or two equals characters evaluates Ruby code just
@@ -1080,54 +1138,53 @@ more info.
 
 Haml comes with the following filters defined:
 
-{#cdata-filter}
-### `:cdata`
+### `:cdata` {#cdata-filter}
+
 Surrounds the filtered text with CDATA tags.
 
-{#coffee-filter}
-### `:coffee`
-Compiles the filtered text to Javascript using Cofeescript. You can also
+### `:coffee` {#coffee-filter}
+
+Compiles the filtered text to Javascript using Coffeescript. You can also
 reference this filter as `:coffeescript`. This filter is implemented using
 Tilt.
 
-{#css-filter}
-### `:css`
+### `:css` {#css-filter}
+
 Surrounds the filtered text with `<style>` and (optionally) CDATA tags. Useful
 for including inline CSS. Use the {Haml::Options#cdata `:cdata` option} to
 control when CDATA tags are added.
 
-{#erb-filter}
-### `:erb`
-Parses the filtered text with ERb, like an RHTML template. Not available if the
-[`:suppress_eval`](#suppress_eval-option) option is set to true. Embedded Ruby
-code is evaluated in the same context as the Haml template. This filter is
+### `:erb` {#erb-filter}
+
+Parses the filtered text with ERB, like an RHTML template. Not available if the
+{Haml::Options#suppress_eval `:suppress_eval`} option is set to true. Embedded
+Ruby code is evaluated in the same context as the Haml template. This filter is
 implemented using Tilt.
 
-{#escaped-filter}
-### `:escaped`
+### `:escaped` {#escaped-filter}
+
 Works the same as plain, but HTML-escapes the text
 before placing it in the document.
 
-{#javascript-filter}
-### `:javascript`
+### `:javascript` {#javascript-filter}
+
 Surrounds the filtered text with `<script>` and (optionally) CDATA tags.
 Useful for including inline Javascript. Use the {Haml::Options#cdata `:cdata`
 option} to control when CDATA tags are added.
 
-{#less-filter}
-### `:less`
+### `:less` {#less-filter}
+
 Parses the filtered text with [Less](http://lesscss.org/) to produce CSS output.
 This filter is implemented using Tilt.
 
+### `:markdown` {#markdown-filter}
 
-{#markdown-filter}
-### `:markdown`
 Parses the filtered text with
 [Markdown](http://daringfireball.net/projects/markdown). This filter is
 implemented using Tilt.
 
-{#maruku-filter}
-### `:maruku`
+### `:maruku` {#maruku-filter}
+
 Parses the filtered text with [Maruku](https://github.com/nex3/maruku), which
 has some non-standard extensions to Markdown.
 
@@ -1136,38 +1193,39 @@ contrib](https://github.com/haml/haml-contrib) but is loaded automatically for
 historical reasons. In future versions of Haml it will likely not be loaded by
 default. This filter is implemented using Tilt.
 
-{#plain-filter}
-### `:plain`
+### `:plain` {#plain-filter}
+
 Does not parse the filtered text. This is useful for large blocks of text
 without HTML tags, when you don't want lines starting with `.` or `-` to be
 parsed.
 
-{#preserve-filter}
-### `:preserve`
+### `:preserve` {#preserve-filter}
+
 Inserts the filtered text into the template with whitespace preserved.
 `preserve`d blocks of text aren't indented, and newlines are replaced with the
 HTML escape code for newlines, to preserve nice-looking output. See also
 [Whitespace Preservation](#whitespace_preservation).
 
-{#ruby-filter}
-### `:ruby`
-Parses the filtered text with the normal Ruby interpreter. All output sent to
-`$stdout`, like with `puts`, is output into the Haml document. Not available if
-the [`:suppress_eval`](#suppress_eval-option) option is set to true. The Ruby
-code is evaluated in the same context as the Haml template.
+### `:ruby` {#ruby-filter}
+
+Parses the filtered text with the normal Ruby interpreter. Creates an `IO`
+object named `haml_io`, anything written to it is output into the Haml document.
+Not available if the {Haml::Options#suppress_eval `:suppress_eval`} option is
+set to true. The Ruby code is evaluated in the same context as the Haml
+template.
+
+### `:sass` {#sass-filter}
 
-{#sass-filter}
-### `:sass`
 Parses the filtered text with [Sass](http://sass-lang.com/) to produce CSS
 output. This filter is implemented using Tilt.
 
-{#scss-filter}
-### `:scss`
+### `:scss` {#scss-filter}
+
 Parses the filtered text with Sass like the `:sass` filter, but uses the newer
 SCSS syntax to produce CSS output. This filter is implemented using Tilt.
 
-{#textile-filter}
-### `:textile`
+### `:textile` {#textile-filter}
+
 Parses the filtered text with [Textile](http://www.textism.com/tools/textile).
 Only works if [RedCloth](http://redcloth.org) is installed.
 
@@ -1180,6 +1238,42 @@ default. This filter is implemented using Tilt.
 
 You can also define your own filters. See {Haml::Filters} for details.
 
+## Helper Methods {#helper-methods}
+
+Sometimes you need to manipulate whitespace in a more precise fashion than what
+the whitespace removal methods allow. There are a few helper methods that are
+useful when dealing with inline content. All these methods take a Haml block to
+modify.
+
+### surround {#surround}
+
+Surrounds a Haml block with text. Expects 1 or 2 string arguments used to
+surround the Haml block. If a second argument is not provided, the first
+argument is used as the second.
+
+    = surround "(", ")" do
+      = link_to "learn more", "#"
+
+### precede {#precede}
+
+Prepends a Haml block with text. Expects 1 argument.
+
+    = precede "*" do
+      %span Required
+
+### succeed {#succeed}
+
+Appends a Haml block with text. Expects 1 argument.
+
+    Begin by
+    = succeed "," do
+      = link_to "filling out your profile", "#"
+    = succeed "," do
+      = link_to "adding a bio", "#"
+    and
+    = succeed "." do
+      = link_to "inviting friends", "#"
+
 ## Multiline: `|` {#multiline}
 
 The pipe character designates a multiline string.
@@ -1231,14 +1325,15 @@ Sometimes you don't want Haml to indent all your text.
 For example, tags like `pre` and `textarea` are whitespace-sensitive;
 indenting the text makes them render wrong.
 
-Haml deals with this by "preserving" newlines before they're put into the document --
-converting them to the HTML whitespace escape code, `&#x000A;`.
-Then Haml won't try to re-format the indentation.
+Haml deals with this by "preserving" newlines before they're put into the
+document -- converting them to the HTML whitespace escape code, `&#x000A;`. Then
+Haml won't try to re-format the indentation.
 
-Literal `textarea` and `pre` tags automatically preserve content given through `=`.
-Dynamically-generated `textarea`s and `pre`s can't be preserved automatically,
-and so should be passed through {Haml::Helpers#find\_and\_preserve} or the [`~` command](#tilde),
-which has the same effect.
+Literal `textarea` and `pre` tags automatically preserve content given through
+`=`. Dynamically-generated `textarea`s and `pre`s can't be preserved
+automatically, and so should be passed through
+{Haml::Helpers#find\_and\_preserve} or the [`~` command](#tilde), which has the
+same effect.
 
 Blocks of literal text can be preserved using the [`:preserve` filter](#preserve-filter).
 

data/Rakefile

@@ -1,41 +1,38 @@
 require "rake/clean"
 require "rake/testtask"
-require "rubygems/package_task"
+require "bundler/gem_tasks"
 
 task :default => :test
 
-CLEAN.replace %w(pkg doc coverage .yardoc test/haml vendor)
-
-def silence_warnings
-  the_real_stderr, $stderr = $stderr, StringIO.new
-  yield
-ensure
-  $stderr = the_real_stderr
+# FIXME: Redefining :test task to run test/options_test.rb in isolated process since it depends on whether Rails is loaded or not.
+# Remove this task when we finished changing escape_html option to be true by default.
+isolated_test = Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = %w[test/options_test.rb]
+  t.warning = true
+  t.verbose = true
+end
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = Dir['test/*_test.rb'] + Dir['test/haml-spec/*_test.rb'] - isolated_test.file_list
+  t.warning = true
+  t.verbose = true
 end
 
-desc "Benchmark Haml against ERb. TIMES=n sets the number of runs, default is 1000."
+CLEAN.replace %w(pkg doc coverage .yardoc test/haml vendor)
+
+desc "Benchmark Haml against ERB. TIMES=n sets the number of runs, default is 1000."
 task :benchmark do
   sh "ruby benchmark.rb #{ENV['TIMES']}"
 end
 
-Rake::TestTask.new do |t|
-  t.libs << 'lib' << 'test'
-  t.test_files = Dir["test/**/*_test.rb"]
-  t.verbose = true
-end
-
 task :set_coverage_env do
   ENV["COVERAGE"] = "true"
 end
 
-desc "Run Simplecov (only works on 1.9)"
+desc "Run Simplecov"
 task :coverage => [:set_coverage_env, :test]
 
-gemspec = File.expand_path("../haml.gemspec", __FILE__)
-if File.exist? gemspec
-  Gem::PackageTask.new(eval(File.read(gemspec))) { |pkg| }
-end
-
 task :submodules do
   if File.exist?(File.dirname(__FILE__) + "/.git")
     sh %{git submodule sync}
@@ -43,31 +40,32 @@ task :submodules do
   end
 end
 
-begin
-  silence_warnings do
-    require 'yard'
-  end
-
-  namespace :doc do
-    desc "List all undocumented methods and classes."
-    task :undocumented do
-      command = 'yard --list --query '
-      command << '"object.docstring.blank? && '
-      command << '!(object.type == :method && object.is_alias?)"'
-      sh command
+namespace :doc do
+  task :sass do
+    require 'sass'
+    Dir["yard/default/**/*.sass"].each do |sass|
+      File.open(sass.gsub(/sass$/, 'css'), 'w') do |f|
+        f.write(Sass::Engine.new(File.read(sass)).render)
+      end
     end
   end
 
-  desc "Generate documentation"
-  task(:doc) {sh "yard"}
+  desc "List all undocumented methods and classes."
+  task :undocumented do
+    command = 'yard --list --query '
+    command << '"object.docstring.blank? && '
+    command << '!(object.type == :method && object.is_alias?)"'
+    sh command
+  end
+end
 
-  desc "Generate documentation incrementally"
-  task(:redoc) {sh "yard -c"}
+desc "Generate documentation"
+task(:doc => 'doc:sass') {sh "yard"}
 
-rescue LoadError
-end
+desc "Generate documentation incrementally"
+task(:redoc) {sh "yard -c"}
 
-  desc <<END
+desc <<END
 Profile Haml.
   TIMES=n sets the number of runs. Defaults to 1000.
   FILE=str sets the file to profile. Defaults to 'standard'
@@ -76,15 +74,14 @@ Profile Haml.
 END
 task :profile do
   times  = (ENV['TIMES'] || '1000').to_i
-  file   = ENV['FILE']
+  file   = ENV['FILE'] || 'test/templates/standard.haml'
 
   require 'bundler/setup'
   require 'ruby-prof'
   require 'haml'
-
-  file = File.read(File.expand_path("../test/templates/#{file || 'standard'}.haml", __FILE__))
+  file = File.read(File.expand_path("../#{file}", __FILE__))
   obj = Object.new
-  Haml::Engine.new(file, :ugly => true).def_method(obj, :render)
+  Haml::Engine.new(file).def_method(obj, :render)
   result = RubyProf.profile { times.times { obj.render } }
 
   RubyProf.const_get("#{(ENV['OUTPUT'] || 'Flat').capitalize}Printer").new(result).print
@@ -94,19 +91,18 @@ def gemfiles
   @gemfiles ||= begin
     Dir[File.dirname(__FILE__) + '/test/gemfiles/Gemfile.*'].
       reject {|f| f =~ /\.lock$/}.
-      reject {|f| RUBY_VERSION < '1.9.3' && f =~ /master/}
+      reject {|f| RUBY_VERSION < '1.9.3' && f =~ /Gemfile.rails-(\d+).\d+.x/ && $1.to_i > 3}
   end
 end
 
 def with_each_gemfile
-  old_env = ENV['BUNDLE_GEMFILE']
   gemfiles.each do |gemfile|
-    puts "Using gemfile: #{gemfile}"
-    ENV['BUNDLE_GEMFILE'] = gemfile
-    yield
+    Bundler.with_clean_env do
+      puts "Using gemfile: #{gemfile}"
+      ENV['BUNDLE_GEMFILE'] = gemfile
+      yield
+    end
   end
-ensure
-  ENV['BUNDLE_GEMFILE'] = old_env
 end
 
 namespace :test do