haml 5.2.2 → 6.1.1

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,50 +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:
 
 ```ruby
 # config/initializers/haml.rb
-Haml::Template.options[:format] = :html5
-
-# Avoid escaping attributes which are already escaped
-Haml::Template.options[:escape_attrs] = :once
+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`:
 
 ```ruby
-Haml::Options.defaults[:format] = :html5
+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
 
@@ -325,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`
@@ -404,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`](lib/haml/attribute_builder.rb),
+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:
 
@@ -993,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>"
@@ -1154,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.
@@ -1271,43 +1197,48 @@ default. This filter is implemented using Tilt.
 
 ### Custom Filters
 
-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.
+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).
 
-### surround {#surround}
+The simplest example of a filter might be something like:
 
-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}
+```ruby
+class HelloFilter < Haml::Filters::Base
+  def compile(_node)
+    [:static, "hello world"]
+  end
+end
 
-Prepends a Haml block with text. Expects 1 argument.
+Haml::Filters.registered[:hello] ||= HelloFilter
+```
 
-    = precede "*" do
-      %span Required
+A more complex complex example
 
-### succeed {#succeed}
+```ruby
+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}
 
@@ -1367,14 +1298,7 @@ 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
-
-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.

data/Rakefile

@@ -1,36 +1,57 @@
-require "rake/clean"
-require "rake/testtask"
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+
+#
+# Prepend DevKit into compilation phase
+#
+if Gem.win_platform?
+  desc 'Activates DevKit'
+  task :devkit do
+    begin
+      require 'devkit'
+    rescue LoadError
+      abort 'Failed to load DevKit required for compilation'
+    end
+  end
+  task compile: :devkit
+end
 
-task :default => :test
+require 'rake/testtask'
+if /java/ === RUBY_PLATFORM
+  # require 'rake/javaextensiontask'
+  # Rake::JavaExtensionTask.new(:haml) do |ext|
+  #   ext.ext_dir = 'ext/java'
+  #   ext.lib_dir = 'lib/haml'
+  # end
 
-# 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'] + Dir['test/cases/*_test.rb'] - isolated_test.file_list
-  t.warning = true
-  t.verbose = true
+  task :compile do
+    # dummy for now
+  end
+else
+  require 'rake/extensiontask'
+  Rake::ExtensionTask.new(:haml) do |ext|
+    ext.lib_dir = 'lib/haml'
+  end
 end
 
-CLEAN.replace %w(pkg doc coverage .yardoc test/haml vendor)
+Dir['benchmark/*.rake'].each { |b| import(b) }
 
-desc "Benchmark Haml against ERB. TIMES=n sets the number of runs, default is 1000."
-task :benchmark do
-  sh "ruby benchmark.rb #{ENV['TIMES']}"
+Rake::TestTask.new do |t|
+  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 :submodules do
-  if File.exist?(File.dirname(__FILE__) + "/.git")
-    sh %{git submodule sync}
-    sh %{git submodule update --init --recursive}
+task test: :compile
+
+desc 'bench task for CI'
+task bench: :compile 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
@@ -58,58 +79,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: %w[compile 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

data/bin/stackprof

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'hamlit'
+require 'stackprof'
+
+def open_flamegraph(report)
+  temp = `mktemp /tmp/stackflame-XXXXXXXX`.strip
+  data_path = "#{temp}.js"
+  system("mv #{temp} #{data_path}")
+
+  File.open(data_path, 'w') do |f|
+    report.print_flamegraph(f)
+  end
+
+  viewer_path = File.join(`bundle show stackprof`.strip, 'lib/stackprof/flamegraph/viewer.html')
+  url = "file://#{viewer_path}?data=#{data_path}"
+  system(%Q[osascript -e 'open location "#{url}"'])
+end
+
+haml = File.read(ARGV.first)
+StackProf.start(mode: :wall, interval: 1, raw: false)
+Hamlit::Engine.new.call(haml)
+StackProf.stop
+
+report = StackProf::Report.new(StackProf.results)
+report.print_text(false)

data/bin/test

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+VERSIONS=(
+  2.1.10
+  2.2.5
+  2.3.1
+)
+
+set -e
+trap 'echo "${VERSIONS[2]}" > .ruby-version' 0
+
+function test_with() {
+  version=$1
+  rbenv local $version
+  if ! bundle check > /dev/null; then
+    bundle install
+  fi
+  ruby -v
+  bundle exec rake test
+}
+
+for version in ${VERSIONS[@]}; do
+  test_with $version
+done

data/exe/haml

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path('../lib', __dir__)
+require 'haml/cli'
+
+Haml::CLI.start(ARGV)

data/ext/haml/extconf.rb

@@ -0,0 +1,10 @@
+require 'mkmf'
+
+$CFLAGS << ' -Wall -Wextra'
+
+$srcs = %w[
+  haml.c
+  hescape.c
+]
+
+create_makefile('haml/haml')