haml 5.1.2 → 6.3.0

data/REFERENCE.md

@@ -30,7 +30,7 @@ The first step for all of these is to install the Haml gem:
 
 To run Haml from the command line, just use
 
-    haml input.haml output.html
+    haml render input.haml > output.html
 
 Use `haml --help` for full documentation.
 
@@ -68,24 +68,6 @@ may be compiled to:
       </div>
     </div>
 
-### Rails XSS Protection
-
-Haml supports Rails' XSS protection scheme, which was introduced in Rails 2.3.5+
-and is enabled by default in 3.0.0+. If it's enabled, Haml's
-{Haml::Options#escape_html `:escape_html`} option is set to `true` by default -
-like in ERB, all strings printed to a Haml template are escaped by default. Also
-like ERB, strings marked as HTML safe are not escaped. Haml also has [its own
-syntax for printing a raw string to the template](#unescaping_html).
-
-If the `:escape_html` option is set to false when XSS protection is enabled,
-Haml doesn't escape Ruby strings by default. However, if a string marked
-HTML-safe is passed to [Haml's escaping syntax](#escaping_html), it won't be
-escaped.
-
-Finally, all the {Haml::Helpers Haml helpers} that return strings that are known
-to be HTML safe are marked as such. In addition, string input is escaped unless
-it's HTML safe.
-
 ### Ruby Module
 
 Haml can also be used completely separately from Rails and ActionView. To do
@@ -93,10 +75,10 @@ this, install the gem with RubyGems:
 
     gem install haml
 
-You can then use it by including the "haml" gem in Ruby code, and using
-{Haml::Engine} like so:
+You can then use it by including the `haml` gem in Ruby code, and using
+{Haml::Template} like so:
 
-    engine = Haml::Engine.new("%p Haml code!")
+    engine = Haml::Template.new { "%p Haml code!" }
     engine.render #=> "<p>Haml code!</p>\n"
 
 ### Options
@@ -104,43 +86,26 @@ You can then use it by including the "haml" gem in Ruby code, and using
 Haml understands various configuration options that affect its performance and
 output.
 
-In Rails, options can be set by setting the {Haml::Template#options Haml::Template.options}
-hash in an initializer:
+In Rails, options can be set by using `Haml::RailsTemplate.set_options` in an initializer:
 
-    # config/initializers/haml.rb
-    Haml::Template.options[:format] = :html5
+```ruby
+# config/initializers/haml.rb
+Haml::RailsTemplate.set_options(escape_html: false)
+```
 
-Outside Rails, you can set them by configuring them globally in
-Haml::Options.defaults:
+Outside Rails, you can set them by configuring them globally in `Haml::Template.options`:
 
-    Haml::Options.defaults[:format] = :html5
+```ruby
+Haml::Template.options[:escape_html] = false
+```
 
 In sinatra specifically, you can set them in global config with:
 ```ruby
-set :haml, { escape_html: true }
+set :haml, { escape_html: false }
 ```
 
-Finally, you can also set them by passing an options hash to
-{Haml::Engine#initialize}. For the complete list of available options, please
-see {Haml::Options}.
-
-### Encodings
-
-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
-other lines). This will tell Haml that the template is encoded using the named
-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 {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
-use these as the output encoding, though.
+Finally, you can also set them by passing an options hash to `Haml::Engine.new` or `Haml::Template.new`.
+For the complete list of available options, please see `Haml::Engine`.
 
 ## Plain Text
 
@@ -215,10 +180,10 @@ closing tags for any element.
 
 ### Attributes: `{}` or `()` {#attributes}
 
-Brackets represent a Ruby hash that is used for specifying the attributes of an
+Braces represent a Ruby hash that is used for specifying the attributes of an
 element. It is literally evaluated as a Ruby hash, so logic will work in it and
 local variables may be used. Quote characters within the attribute will be
-replaced by appropriate escape sequences. The hash is placed after the tag is
+replaced with appropriate escape sequences. The hash is placed after the tag is
 defined. For example:
 
     %html{:xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en"}
@@ -228,15 +193,19 @@ is compiled to:
     <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'></html>
 
 Attribute hashes can also be stretched out over multiple lines to accommodate
-many attributes. However, newlines may only be placed immediately after commas.
-For example:
+many attributes.
 
-    %script{:type => "text/javascript",
-            :src  => "javascripts/script_#{2 + 7}"}
+    %script{
+      "type": text/javascript",
+      "src": javascripts/script_#{2 + 7}",
+      "data": {
+        "controller": "reporter",
+      },
+    }
 
 is compiled to:
 
-    <script src='javascripts/script_9' type='text/javascript'></script>
+    <script src='javascripts/script_9' type='text/javascript' data-controller='reporter'></script>
 
 #### `:class` and `:id` Attributes {#class-and-id-attributes}
 
@@ -278,7 +247,7 @@ could render as either of:
 #### HTML-style Attributes: `()`
 
 Haml also supports a terser, less Ruby-specific attribute syntax based on HTML's
-attributes. These are used with parentheses instead of brackets, like so:
+attributes. These are used with parentheses instead of braces, like so:
 
     %html(xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en")
 
@@ -314,49 +283,6 @@ Haml also supports Ruby's new hash syntax:
 
     %a{title: @title, href: href} Stuff
 
-#### Attribute Methods
-
-A Ruby method call that returns a hash can be substituted for the hash contents.
-For example, {Haml::Helpers} defines the following method:
-
-    def html_attrs(lang = 'en-US')
-      {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
-    end
-
-This can then be used in Haml, like so:
-
-    %html{html_attrs('fr-fr')}
-
-This is compiled to:
-
-    <html lang='fr-fr' xml:lang='fr-fr' xmlns='http://www.w3.org/1999/xhtml'>
-    </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 be merged together, from
-left to right. For example, if you defined
-
-    def hash1
-      {:bread => 'white', :filling => 'peanut butter and jelly'}
-    end
-
-    def hash2
-      {:bread => 'whole wheat'}
-    end
-
-then
-
-    %sandwich{hash1, hash2, :delicious => 'true'}/
-
-would compile to:
-
-    <sandwich bread='whole wheat' delicious='true' filling='peanut butter and jelly' />
-
-Note that the Haml attributes list has the same syntax as a Ruby method call.
-This means that any attribute methods must come before the hash literal.
-
-Attribute methods aren't supported for HTML-style attributes.
-
 #### Boolean Attributes
 
 Some attributes, such as "checked" for `input` tags or "selected" for `option`
@@ -393,24 +319,38 @@ or using `true` and `false`:
 
     %input(selected=true)
 
+This feature works only for attributes that are included in
+[`Haml::AttributeBuilder::BOOLEAN_ATTRIBUTES`](https://github.com/haml/haml/blob/main/lib/haml/attribute_builder.rb#L5),
+as well as `data-` and `aria-` attributes.
+
+    %input{'data-hidden' => false}
+    %input{'aria-hidden' => false}
+    %input{'xyz-hidden' => false}
+
+will render as:
+
+    <input>
+    <input>
+    <input xyz-hidden='false'>
+
+
 <!-- 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
+#### Data 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-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.
+specification makes use of attributes beginning with `aria-`.
 
 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.
+these. Any entry in an `data` or `aria` 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. This works only for `data` or `aria`.
 
 For example:
 
@@ -420,7 +360,7 @@ will render as:
 
     <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
+Notice that the underscore in `author_id` was replaced with a hyphen. If you wish
 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:
@@ -517,6 +457,24 @@ and is compiled to:
       </div>
     </div>
 
+#### Class Name Merging and Ordering
+
+Class names are ordered in the following way:
+
+1) Tag identifiers in order (aka, ".alert.me" => "alert me")
+2) Classes appearing in HTML-style attributes
+3) Classes appearing in Hash-style attributes
+
+For instance, this is a complicated and unintuitive test case illustrating the ordering
+
+    .foo.moo{:class => ['bar', 'alpha']}(class='baz')
+
+The resulting HTML would be as follows:
+
+    <div class='foo moo baz bar alpha'></div>
+
+*Versions of Haml prior to 5.0 would alphabetically sort class names.*
+
 ### Empty (void) Tags: `/`
 
 The forward slash character, when placed at the end of a tag definition, causes
@@ -853,7 +811,7 @@ is compiled to:
 
 ## Ruby Evaluation
 
-### Inserting Ruby: `=`
+### Inserting Ruby: `=` {#inserting_ruby}
 
 The equals character is followed by Ruby code. This code is evaluated and the
 output is inserted into the document. For example:
@@ -964,7 +922,7 @@ is compiled to:
 
 ### Whitespace Preservation: `~` {#tilde}
 
-`~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve}
+`~` works just like `=`, except that it runs {Haml::Helpers.preserve}
 on its input. For example,
 
     ~ "Foo\n<pre>Bar\nBaz</pre>"
@@ -1034,7 +992,7 @@ most code but you may have errors with code like the following:
 
     %span #{'{'}
 
-This code will generate a syntax error, complaining about unbalanced brackets.
+This code will generate a syntax error, complaining about unbalanced braces.
 In cases like this, the recommended workaround is output the code as a Ruby
 string to force Haml to parse the code with Ruby.
 
@@ -1125,9 +1083,6 @@ is compiled to
       <p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
     </div>
 
-Note that `#{}` interpolation within filters is HTML-escaped if you specify true to
-{Haml::Options#escape_filter_interpolations `:escape_filter_interpolations`} option.
-
 The functionality of some filters such as Markdown can be provided by many
 different libraries. Usually you don't have to worry about this - you can just
 load the gem of your choice and Haml will automatically use it.
@@ -1138,7 +1093,7 @@ uses to implement many of its filters:
 
     Tilt.prefer Tilt::RedCarpetTemplate
 
-See the [Tilt documentation](https://github.com/rtomayko/tilt#fallback-mode) for
+See the [Tilt documentation](https://github.com/rtomayko/tilt) for
 more info.
 
 Haml comes with the following filters defined:
@@ -1190,7 +1145,7 @@ implemented using Tilt.
 
 ### `:maruku` {#maruku-filter}
 
-Parses the filtered text with [Maruku](https://github.com/nex3/maruku), which
+Parses the filtered text with [Maruku](https://github.com/bhollis/maruku), which
 has some non-standard extensions to Markdown.
 
 As of Haml 4.0, this filter is defined in [Haml
@@ -1213,11 +1168,8 @@ HTML escape code for newlines, to preserve nice-looking output. See also
 
 ### `: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.
+Parses the filtered text with the normal Ruby interpreter.
+The Ruby code is evaluated in the same context as the Haml template.
 
 ### `:sass` {#sass-filter}
 
@@ -1242,43 +1194,44 @@ default. This filter is implemented using Tilt.
 
 ### Custom Filters
 
-You can also define your own filters. See {Haml::Filters} for details.
+You can also define your own filters.
+`Haml::Filters::YourCustomFilter#compile` should return
+[a Temple expression](https://github.com/judofyr/temple/blob/master/EXPRESSIONS.md).
 
-## Helper Methods {#helper-methods}
+The simplest example of a filter might be something like:
 
-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}
+    class HelloFilter < Haml::Filters::Base
+      def compile(_node)
+        [:static, "hello world"]
+      end
+    end
+    
+    Haml::Filters.registered[:hello] ||= HelloFilter
+
+A more complex example:
+
+    class BetterFilter < Haml::Filters::Base
+      def compile(node)
+        temple = [:multi]
+        temple << [:static, "hello "]
+        temple << compile_text(node.value[:text])
+        temple << [:static, " world"]
+        temple
+      end
+    
+      private
+      def compile_text(text)
+        if ::Haml::Util.contains_interpolation?(text)
+          [:dynamic, ::Haml::Util.unescape_interpolation(text)]
+        else
+          [:static, text]
+        end
+      end
+    end
 
-Appends a Haml block with text. Expects 1 argument.
+    Haml::Filters.registered[:better] ||= BetterFilter
 
-    Begin by
-    = succeed "," do
-      = link_to "filling out your profile", "#"
-    = succeed "," do
-      = link_to "adding a bio", "#"
-    and
-    = succeed "." do
-      = link_to "inviting friends", "#"
+See {Haml::Filters} for examples.
 
 ## Multiline: `|` {#multiline}
 
@@ -1323,9 +1276,9 @@ that just need a lot of template information.
 So data structures and  functions that require lots of arguments
 can be wrapped over multiple lines,
 as long as each line but the last ends in a comma
-(see [Inserting Ruby](#inserting_ruby_)).
+(see [Inserting Ruby](#inserting_ruby)).
 
-## Whitespace Preservation
+## Whitespace Preservation {#whitespace_preservation}
 
 Sometimes you don't want Haml to indent all your text.
 For example, tags like `pre` and `textarea` are whitespace-sensitive;
@@ -1338,14 +1291,26 @@ 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
+{Haml::Helpers.preserve} or the [`~` command](#tilde), which has the
 same effect.
 
 Blocks of literal text can be preserved using the [`:preserve` filter](#preserve-filter).
 
-## Helpers
+## Turbo
 
-Haml offers a bunch of helpers that are useful for doing stuff like preserving
-whitespace, creating nicely indented output for user-defined helpers, and other
-useful things. The helpers are all documented in the {Haml::Helpers} and
-{Haml::Helpers::ActionViewExtensions} modules.
+For people using Turbo-rails and Haml 6+ need to either:
+*  follow the naming convention with the html format (ie. ensure any `.haml` files end `.html.haml`), or
+*  add a monkey patch as follows:
+
+```rb
+# config/initializers/haml.rb
+require "haml/rails_template"
+
+module Haml
+  class RailsTemplate
+    def default_format
+      :html
+    end
+  end
+end
+```

data/Rakefile

@@ -1,43 +1,23 @@
-require "rake/clean"
-require "rake/testtask"
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
-task :default => :test
-
-# 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.libs << 'lib' << 'test'
+  files = Dir['test/haml/**/*_test.rb']
+  t.ruby_opts = %w[-rtest_helper]
+  t.test_files = files
   t.verbose = true
 end
+task :test
 
-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
-
-task :set_coverage_env do
-  ENV["COVERAGE"] = "true"
-end
-
-desc "Run Simplecov"
-task :coverage => [:set_coverage_env, :test]
-
-task :submodules do
-  if File.exist?(File.dirname(__FILE__) + "/.git")
-    sh %{git submodule sync}
-    sh %{git submodule update --init --recursive}
+desc 'bench task for CI'
+task :bench do
+  if ENV['SLIM_BENCH'] == '1'
+    cmd = %w[bundle exec ruby benchmark/slim/run-benchmarks.rb]
+  else
+    cmd = ['bin/bench', 'bench', ('-c' if ENV['COMPILE'] == '1'), *ENV['TEMPLATE'].split(',')].compact
   end
+  exit system(*cmd)
 end
 
 namespace :doc do
@@ -65,58 +45,4 @@ task(:doc => 'doc:sass') {sh "yard"}
 desc "Generate documentation incrementally"
 task(:redoc) {sh "yard -c"}
 
-desc <<END
-Profile Haml.
-  TIMES=n sets the number of runs. Defaults to 1000.
-  FILE=str sets the file to profile. Defaults to 'standard'
-  OUTPUT=str sets the ruby-prof output format.
-    Can be Flat, CallInfo, or Graph. Defaults to Flat. Defaults to Flat.
-END
-task :profile do
-  times  = (ENV['TIMES'] || '1000').to_i
-  file   = ENV['FILE'] || 'test/templates/standard.haml'
-
-  require 'bundler/setup'
-  require 'ruby-prof'
-  require 'haml'
-  file = File.read(File.expand_path("../#{file}", __FILE__))
-  obj = Object.new
-  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
-end
-
-def gemfiles
-  @gemfiles ||= Dir[File.dirname(__FILE__) + '/test/gemfiles/Gemfile.*'].reject {|f| f =~ /\.lock$/}
-end
-
-def with_each_gemfile
-  gemfiles.each do |gemfile|
-    Bundler.with_clean_env do
-      puts "Using gemfile: #{gemfile}"
-      ENV['BUNDLE_GEMFILE'] = gemfile
-      yield
-    end
-  end
-end
-
-namespace :test do
-  namespace :bundles do
-    desc "Install all dependencies necessary to test Haml."
-    task :install do
-      with_each_gemfile {sh "bundle"}
-    end
-
-    desc "Update all dependencies for testing Haml."
-    task :update do
-      with_each_gemfile {sh "bundle update"}
-    end
-  end
-
-  desc "Test all supported versions of rails. This takes a while."
-  task :rails_compatibility => 'test:bundles:install' do
-    with_each_gemfile {sh "bundle exec rake test"}
-  end
-  task :rc => :rails_compatibility
-end
+task default: :test

data/bin/bench

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'haml'
+require 'thor'
+require 'benchmark/ips'
+require_relative '../benchmark/utils/benchmark_ips_extension'
+
+class Bench < Thor
+  class_option :show_template, type: :boolean, aliases: ['-t']
+
+  desc 'bench HAML', 'Benchmark haml template'
+  option :compile, type: :boolean, aliases: ['-c']
+  option :show_code, type: :boolean, aliases: ['-s']
+  def bench(*files)
+    files.each { |file| render(file) }
+    files.each { |file| compile(file) if options[:compile] }
+    files.each { |file| code(file) if options[:show_code] }
+  end
+
+  desc 'compile HAML', 'Benchmark compilation'
+  def compile(file)
+    puts "#{?= * 49}\n Compilation: #{file}\n#{?= * 49}"
+    haml = File.read(file)
+
+    Benchmark.ips do |x|
+      x.report("haml v#{Haml::VERSION}") { Haml::Engine.new.call(haml) }
+      x.compare!
+    end
+  end
+
+  desc 'render HAML', 'Benchmark rendering'
+  def render(file)
+    puts "#{?= * 49}\n Rendering: #{file}\n#{?= * 49}"
+    haml = File.read(file)
+    puts haml + "\n" if options[:show_template]
+    object = Object.new
+    ruby_file = file.gsub(/\.haml\z/, '.rb')
+    if File.exist?(ruby_file)
+      object.instance_eval(File.read(ruby_file))
+    end
+
+    object.instance_eval "def haml; #{Haml::Engine.new.call(haml)}; end"
+
+    Benchmark.ips do |x|
+      x.report("haml v#{Haml::VERSION}") { object.haml }
+      x.compare!
+    end
+  end
+
+  desc 'code HAML', 'Show compiled code'
+  def code(file)
+    haml = File.read(file)
+    puts "\n#{?= * 49}\n Haml Source: #{file}\n#{?= * 49}"
+    puts Haml::Engine.new.call(haml)
+  end
+
+  private
+
+  def method_missing(*args)
+    return super if args.length > 1
+    render(args.first.to_s)
+  end
+end
+
+Bench.start

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'hamlit'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require 'pry'
+Pry.start

data/bin/ruby

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+bundle exec ruby -Ilib:test -rtest_helper $@

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here