haml 6.0.1 → 6.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 909d5636fba736ef06747221b4d0ff34a8c5b850f2c8d4cc60ac27843e914e94
-  data.tar.gz: 478fd2cce0e05e386690aa83fa41132da006cb02437ec43a0b4882842a2e973c
+  metadata.gz: 5154c2aa8152311d83ac1c3acb9123d31b3b24af570334c2b9786bc8c057b5b7
+  data.tar.gz: 55cf78c93ff92aea7794b8f12a96bdff471759d072d1b5c0689c8dc9ee4fee5b
 SHA512:
-  metadata.gz: 268bfdc33ba76950ab553692c5ff1c45b84a3f3b4185248a19c6a3a74f4b47cd46527d279ed3782f9b7fd6bba6be889a531b7e6c133a4f00ac7e3e06d61a464c
-  data.tar.gz: 1b4f559abe65e3c39627d87b6cc2da894ca67514f62d702ff0920d9d974dda49d4ab7b49e465157622b31a9c3ad5b1925e5e4aa2b1360640d784a7a6f537178a
+  metadata.gz: ef8aa686f64c59b24b72c907a8dafb6cad0c060000094c74c2db73c1d7155a412937d64f6d377b1fa66eaa5126f694a40e7222593da8c71de360a4f2025098bc
+  data.tar.gz: 1d3c797b5925f1b1b3721b4f14c4756ba102042079b8c091a8b079e9f3ea7de8b1fefd8d5d724f5f111f1d7b9e77cbac77280cf9abc78782ce600549e35389ec

data/.yardopts

@@ -0,0 +1,19 @@
+--charset          utf-8
+--readme           README.md
+--markup           markdown
+--markup-provider  kramdown
+--template-path    yard
+--default-return   ""
+--title            "Haml Documentation"
+--query            'object.type != :classvariable'
+--query            'object.type != :constant || @api && @api.text == "public"'
+--exclude          lib/haml/railtie.rb
+--hide-void-return
+--protected
+--no-private
+--no-highlight
+-
+FAQ.md
+CHANGELOG.md
+REFERENCE.md
+MIT-LICENSE

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Haml Changelog
 
+## 6.0.2
+
+Released on September 28, 2022
+([diff](https://github.com/haml/haml/compare/v6.0.1...v6.0.2)).
+
+* Unescape HTML-safe arguments for `surround`, `succeed`, and `precede` on Rails
+  [#1088](https://github.com/haml/haml/issues/1088)
+
 ## 6.0.1
 
 Released on September 23, 2022
@@ -17,7 +25,12 @@ Released on September 21, 2022
   * Haml 6 is about 1.7x faster than Haml 5 in [this benchmark](benchmark/slim/run-benchmarks.rb).
   * The parser is kept as is, but everything else is replaced.
   * The `haml` CLI interface was also replaced.
-  * All Haml helpers except for `preserve` are removed.
+  * The interface of `Haml::Engine` is changed. `Haml::Template` is most likely what you need now.
+  * Most Haml helpers are removed.
+     * On Rails, only `find_and_reserve`, `preserve`, `surround`, `precede`, `succeed`, and `capture_haml` are left.
+     * On Tilt, only `preserve` is left.
+  * Only the attributes in [`Haml::AttributeBuilder::BOOLEAN_ATTRIBUTES`](lib/haml/attribute_builder.rb)
+    are handled as boolean attributes.
   * Some legacy Rails integration is removed.
 
 ## 5.2.2

data/README.md

@@ -22,7 +22,7 @@ gem install haml
 After you write some Haml, you can run
 
 ~~~sh
-haml document.haml
+haml render document.haml
 ~~~
 
 to compile it to HTML. For more information on these commands, check out
@@ -41,8 +41,8 @@ To use Haml with Rails, simply add Haml to your Gemfile and run `bundle`.
 gem 'haml'
 ~~~
 
-If you'd like to replace Rails's Erb-based generators with Haml, add
-[haml-rails](https://github.com/indirect/haml-rails) to your Gemfile as well.
+If you'd like to replace Rails's ERB-based generators with Haml, add
+[haml-rails](https://github.com/haml/haml-rails) to your Gemfile as well.
 
 ## Formatting
 

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,62 +75,12 @@ 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
-
-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:
-
-```ruby
-# config/initializers/haml.rb
-Haml::Template.options[:format] = :html5
-
-# Avoid escaping attributes which are already escaped
-Haml::Template.options[:escape_attrs] = :once
-```
-
-Outside Rails, you can set them by configuring them globally in
-Haml::Options.defaults:
-
-```ruby
-Haml::Options.defaults[:format] = :html5
-```
-
-In sinatra specifically, you can set them in global config with:
-```ruby
-set :haml, { escape_html: true }
-```
-
-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.
-
 ## Plain Text
 
 A substantial portion of any HTML document is its content, which is plain old
@@ -325,49 +257,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,6 +293,9 @@ 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).
+
 <!-- 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>
@@ -993,7 +885,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 +1046,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 +1160,10 @@ 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.
-
-### 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", "#"
+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).
+See {Haml::Filters} for examples.
 
 ## Multiline: `|` {#multiline}
 
@@ -1367,14 +1223,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

@@ -112,5 +112,30 @@ task bench: :compile do
   exit system(*cmd)
 end
 
+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 "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"
+task(:doc => 'doc:sass') {sh "yard"}
+
+desc "Generate documentation incrementally"
+task(:redoc) {sh "yard -c"}
+
 task default: %w[compile hamlit:test]
 task test: %w[compile test:all]

data/lib/haml/rails_helpers.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: false
 require 'haml/helpers'
 
-# Currently this Haml::Helpers depends on
-# ActionView internal implementation. (not desired)
+# There are only helpers that depend on ActionView internals.
 module Haml
   module RailsHelpers
     include Helpers
@@ -32,16 +31,19 @@ module Haml
 
     def surround(front, back = front, &block)
       output = capture_haml(&block)
-
-      "#{escape_once(front)}#{output.chomp}#{escape_once(back)}\n".html_safe
+      front  = escape_once(front) unless front.html_safe?
+      back   = escape_once(back)  unless back.html_safe?
+      "#{front}#{output.chomp}#{back}\n".html_safe
     end
 
     def precede(str, &block)
-      "#{escape_once(str)}#{capture_haml(&block).chomp}\n".html_safe
+      str = escape_once(str) unless str.html_safe?
+      "#{str}#{capture_haml(&block).chomp}\n".html_safe
     end
 
     def succeed(str, &block)
-      "#{capture_haml(&block).chomp}#{escape_once(str)}\n".html_safe
+      str = escape_once(str) unless str.html_safe?
+      "#{capture_haml(&block).chomp}#{str}\n".html_safe
     end
 
     def capture_haml(*args, &block)

data/lib/haml/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Haml
-  VERSION = '6.0.1'
+  VERSION = '6.0.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haml
 version: !ruby/object:Gem::Version
-  version: 6.0.1
+  version: 6.0.2
 platform: ruby
 authors:
 - Natalie Weizenbaum
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-23 00:00:00.000000000 Z
+date: 2022-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: temple
@@ -265,6 +265,7 @@ files:
 - ".github/FUNDING.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
+- ".yardopts"
 - CHANGELOG.md
 - FAQ.md
 - Gemfile