hamlit 1.7.2 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 97c6e8e207573918bcdc35f2d9c5092221906577
-  data.tar.gz: 466188f7c1a06f359f33b85406263b8fc697b77b
+  metadata.gz: 28a84db73fc904f991af638d917007332547d58d
+  data.tar.gz: f1d1b3f015fb126cb5b4f17bbe98ed9d544e93a1
 SHA512:
-  metadata.gz: 324a94fe243be2497ef6d0ab786386b6f281d2ab990396863e90cdad800f815578c2228bf6df3f2a85de7034e3621394456f6b20235701c70538e3f90ebc9c42
-  data.tar.gz: c69e5ed58abd2d603b54cd4915ffc90c00242f6fa9225b6db7be726c6f7aec01a2a2348c267dd2b1c3f3c0a2cc87700350286a4deebd237845ed56dea2e83170
+  metadata.gz: 03d00832e894a37163e28f1ff2f635d9c77cc456be27b335b653a2367e3fe2cb5804524a7db955f564612ff5453b0b900751ed9c815a7342e303180312f47ae8
+  data.tar.gz: 4aecd7d189befada1018c846c0059ff093d84fa03c414840e8454add6888725039eebd76035cec8b5d65716c5123baf528fb80bea113538b337d78d535c8c212

data/.gitignore

@@ -3,13 +3,14 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
+/doc/
 /pkg/
 /spec/reports/
 /tmp/
+.sass-cache
+/hamlit1
+.ruby-version
 *.bundle
 *.so
 *.o
 *.a
-*.cache
-mkmf.log
-.sass-cache/

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ext/hamlit/houdini"]
+	path = ext/hamlit/houdini
+	url = https://github.com/vmg/houdini

data/.travis.yml

@@ -1,42 +1,30 @@
 language: ruby
-rvm:
-  - 2.0.0
-  - 2.1
-  - 2.2
-sudo: false
-cache: bundler
+branches:
+  only:
+    - master
 script:
   - "bundle exec rake $TASK"
-gemfile:
-  - Gemfile
-  - spec/rails/Gemfile
-env:
-  - TASK=spec
-  - TASK=rails:spec
-  - TASK=bench TIME=20
-  - TASK=bench TIME=20 HTML_ESCAPE=1
 matrix:
-  allow_failures:
-    - env: TASK=bench TIME=20
-    - env: TASK=bench TIME=20 HTML_ESCAPE=1
-  exclude:
-    - env: TASK=spec
-      gemfile: spec/rails/Gemfile
-    - env: TASK=rails:spec
-      gemfile: Gemfile
-    - env: TASK=bench TIME=20
-      gemfile: spec/rails/Gemfile
-    - env: TASK=bench TIME=20 HTML_ESCAPE=1
-      gemfile: spec/rails/Gemfile
-    - rvm: 2.1
-      env: TASK=rails:spec
-    - rvm: 2.1
-      env: TASK=bench TIME=20
-    - rvm: 2.1
-      env: TASK=bench TIME=20 HTML_ESCAPE=1
+  include:
     - rvm: 2.0.0
-      env: TASK=rails:spec
-    - rvm: 2.0.0
-      env: TASK=bench TIME=20
-    - rvm: 2.0.0
-      env: TASK=bench TIME=20 HTML_ESCAPE=1
+      env: TASK=test
+    - rvm: 2.1
+      env: TASK=test
+    - rvm: 2.2
+      env: TASK=test
+    - rvm: 2.2
+      env: TASK=bench TEMPLATE=benchmark/boolean_attribute.haml,benchmark/class_attribute.haml,benchmark/id_attribute.haml,benchmark/data_attribute.haml,benchmark/common_attribute.haml
+    - rvm: 2.2
+      env: TASK=bench TEMPLATE=benchmark/dynamic_attributes/boolean_attribute.haml,benchmark/dynamic_attributes/class_attribute.haml,benchmark/dynamic_attributes/id_attribute.haml,benchmark/dynamic_attributes/data_attribute.haml,benchmark/dynamic_attributes/common_attribute.haml
+    - rvm: 2.2
+      env: TASK=bench TEMPLATE=benchmark/etc/attribute_builder.haml
+    - rvm: 2.2
+      env: TASK=bench SLIM_BENCH=1
+    - rvm: 2.2
+      env: TASK=bench TEMPLATE=test/haml/templates/standard.haml COMPILE=1
+  allow_failures:
+    - env: TASK=bench TEMPLATE=benchmark/boolean_attribute.haml,benchmark/class_attribute.haml,benchmark/id_attribute.haml,benchmark/data_attribute.haml,benchmark/common_attribute.haml
+    - env: TASK=bench TEMPLATE=benchmark/dynamic_attributes/boolean_attribute.haml,benchmark/dynamic_attributes/class_attribute.haml,benchmark/dynamic_attributes/id_attribute.haml,benchmark/dynamic_attributes/data_attribute.haml,benchmark/dynamic_attributes/common_attribute.haml
+    - env: TASK=bench TEMPLATE=benchmark/etc/attribute_builder.haml
+    - env: TASK=bench SLIM_BENCH=1
+    - env: TASK=bench TEMPLATE=test/haml/templates/standard.haml COMPILE=1

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## v2.0.0
+
+- Full scratch of internal implementation
+  - Rendering is strongly optimized
+     - Static analyzer is introduced
+     - Built with C extension for runtime rendering
+     - Optimized compilation for 5 types of attributes
+  - Compilation became faster too
+  - Many rendering incompatibilities are resolved
+  - Object reference support
+  - Breaking changes:
+     - Replaced parser with original Haml's one
+         - Incompatible parsing error will never happen, but we can no longer parse attributes with Ripper
+     - Unified behavior for both static and dynamic attributes, see [5 types of attributes](REFERENCE.md#5-types-of-attributes)
+         - Though inconsistent behavior is removed, we can no longer rely on completely-Haml-compatible behavior of static attributes and pass haml-spec
+     - Added :escape\_attrs option
+         - You should specify HTML-escaping availability for script and attrs separately.
+
 ## v1.7.2
 
 - Bugfix about parsing a content of tag

data/Gemfile

@@ -2,3 +2,19 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in hamlit.gemspec
 gemspec
+
+# maintain compatibility against master
+gem 'haml', github: 'haml/haml'
+
+gem 'benchmark-ips', '2.3.0'
+gem 'minitest-line'
+gem 'pry-byebug'
+
+if File.exist?('hamlit1')
+  gem 'hamlit1', path: 'hamlit1'
+end
+
+if RUBY_VERSION >= '2.1.0'
+  gem 'lineprof'
+  gem 'stackprof'
+end

data/LICENSE.txt

@@ -1,7 +1,28 @@
+The MIT License (MIT)
+
 Copyright (c) 2015 Takashi Kokubun
-Copyright (c) 2006-2009 Hampton Catlin and Natalie Weizenbaum
 
-MIT License
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+lib/hamlit/parser/*.rb and test/haml/* are:
+
+Copyright (c) 2006-2009 Hampton Catlin and Natalie Weizenbaum
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -2,27 +2,18 @@
 
 [![Gem Version](https://badge.fury.io/rb/hamlit.svg)](http://badge.fury.io/rb/hamlit)
 [![Build Status](https://travis-ci.org/k0kubun/hamlit.svg?branch=master)](https://travis-ci.org/k0kubun/hamlit)
-[![Coverage Status](https://coveralls.io/repos/k0kubun/hamlit/badge.svg?branch=master)](https://coveralls.io/r/k0kubun/hamlit?branch=master)
-[![Code Climate](https://codeclimate.com/github/k0kubun/hamlit/badges/gpa.svg)](https://codeclimate.com/github/k0kubun/hamlit)
 
-Hamlit is a high performance [haml](https://github.com/haml/haml) implementation.
+Hamlit is a high performance [Haml](https://github.com/haml/haml) implementation.
 
-## Installation
+## Introduction
 
-Add this line to your application's Gemfile:
+### What is Hamlit?
+Hamlit is another implementation of [Haml](https://github.com/haml/haml).
+With some [limitations](REFERENCE.md#limitations) by design for performance,
+Hamlit is **7.16x times faster** than original haml gem in [this benchmark](benchmark/slim/run-benchmarks.rb),
+which is an HTML-escaped version of [slim-template/slim's one](https://github.com/slim-template/slim/blob/v3.0.6/benchmarks/run-benchmarks.rb) for fairness.
 
-```ruby
-gem 'hamlit'
-```
-
-or just replace `gem "haml"` with `gem "hamlit"`.
-
-## Features
-### Fast rendering
-
-![](http://i.gyazo.com/4fe00ff2ac2fa959dfcf86a5e27dc914.png)
-
-Hamlit's rendering is **7.16x times faster** than original haml.
+![Hamlit Benchmark](http://i.gyazo.com/4fe00ff2ac2fa959dfcf86a5e27dc914.png)
 
 ```
     erubis:   114501.6 i/s
@@ -32,56 +23,123 @@ Hamlit's rendering is **7.16x times faster** than original haml.
       haml:    15750.6 i/s - 7.27x slower
 ```
 
-[This benchmark](https://github.com/k0kubun/hamlit/blob/4e5655c4ba1d51c85b4551c3b22baa6d7780d208/benchmarks/benchmark.rb)
-is the same as [slim-template/slim](https://github.com/slim-template/slim)'s one for fairness.
-([The result on travis CI](https://travis-ci.org/k0kubun/hamlit/jobs/58162910))
+### Why is Hamlit faster?
 
-### Better parser
+#### Less string concatenation by design
+As written in [limitations](REFERENCE.md#limitations), Hamlit drops some not-so-important features which require
+works on runtime. With the optimized language design, we can reduce the string concatenation
+to build attributes.
 
-Haml's attribute parser is not so good. For example, raises syntax error for `%a{ b: '}' }`.
-Hamlit's attribute parser is implemented with Ripper, which is an official lexer for Ruby,
-so it is able to parse such an attribute.
+#### Temple optimizers
+Hamlit is built with [Temple](https://github.com/judofyr/temple), which is a framework to build
+template engines and also used in Slim. By using the framework and its optimizers, Hamlit can
+reduce string allocation and concatenation easily.
 
-### Passing haml-spec
+#### Static analyzer
+Hamlit analyzes Ruby expressions with Ripper and render it on compilation if the expression
+is static. And Hamlit can also compile string literal with string interpolation to reduce
+string allocation and concatenation on runtime.
 
-[haml/haml-spec](https://github.com/haml/haml-spec) is a basic suite of tests for Haml interpreters.
-For all test cases in haml-spec, Hamlit behaves the same as Haml (ugly and escape\_html mode only, which is used on production).
-
-Hamlit is used on [githubranking.com](http://githubranking.com/).
+#### C extension to build attributes
+While Hamlit has static analyzer and static attributes are rendered on compilation,
+dynamic attributes must be rendered on runtime. So Hamlit optimizes rendering on runtime
+with C extension.
 
 ## Usage
 
-Basically the same as [haml](https://github.com/haml/haml).
-Check out the [reference documentation](http://haml.info/docs/yardoc/file.REFERENCE.html) for details.
+See [REFERENCE.md](REFERENCE.md) for detail features of Hamlit.
 
 ### Rails
-Just update Gemfile.
+
+Add this line to your application's Gemfile or just replace `gem "haml"` with `gem "hamlit"`.
+It enables rendering by Hamlit for \*.haml automatically.
+
+```rb
+gem 'hamlit'
+```
+
+If you want to use view generator, consider using [hamlit-rails](https://github.com/mfung/hamlit-rails).
 
 ### Sinatra
-Update Gemfile. Html escaping is enabled by default.
-If you want to disable it, add following code.
+
+Replace `gem "haml"` with `gem "hamlit"` in Gemfile, and require "hamlit".
+See [sample/sinatra](sample/sinatra) for working sample.
+
+While Haml disables `escape_html` option by default, Hamlit enables it for security.
+If you want to disable it, please write:
 
 ```rb
 set :haml, { escape_html: false }
 ```
 
-## Why high performance?
-### Less work on runtime
-Haml's rendering is very slow because generated code by haml runs many operations on runtime.
-For example, Haml::Util is extended on view, attribute rendering runs even if it is a
-static value and the values in attribute is sorted. All of them is achieved on runtime.
 
-Hamlit extends ActionView beforehand, attribute rendering is done when compiled if it
-is a static hash and no unnecessary operation is done on runtime.
+## Command line interface
+
+You can see compiled code or rendering result with "hamlit" command.
+
+```bash
+$ gem install hamlit
+$ hamlit --help
+Commands:
+  hamlit compile HAML    # Show compile result
+  hamlit help [COMMAND]  # Describe available commands or one specific command
+  hamlit parse HAML      # Show parse result
+  hamlit render HAML     # Render haml template
+  hamlit temple HAML     # Show temple intermediate expression
+
+$ cat in.haml
+- user_id = 123
+%a{ href: "/users/#{user_id}" }
+
+# Show compiled code
+$ hamlit compile in.haml
+_buf = [];  user_id = 123;
+; _buf << ("<a href='/users/".freeze); _buf << (::Hamlit::Utils.escape_html((user_id))); _buf << ("'></a>\n".freeze); _buf = _buf.join
+
+# Render html
+$ hamlit render in.haml
+<a href='/users/123'></a>
+```
+
+## Contributing
+
+### Development
+
+Contributions are welcomed. It'd be good to see
+[Temple's EXPRESSIONS.md](https://github.com/judofyr/temple/blob/v0.7.6/EXPRESSIONS.md)
+to learn Temple which is a template engine framework used in Hamlit.
+
+```bash
+$ git clone https://github.com/k0kubun/hamlit
+$ cd hamlit
+$ bundle install
+
+# Run all tests
+$ bundle exec rake test
+
+# Run one test
+$ bundle exec ruby -Ilib:test -rtest_helper test/hamlit/line_number_test.rb -l 12
+
+# Show compiling/rendering result of some template
+$ bundle exec exe/hamlit compile in.haml
+$ bundle exec exe/hamlit render in.haml
+
+# Use rails app to debug Hamlit
+$ cd sample/rails
+$ bundle install
+$ bundle exec rails s
+```
+
+### Reporting an issue
 
-### Temple optimizers
-Hamlit is implemented with [temple](https://github.com/judofyr/temple), which is a template
-engine framework for Ruby. Temple has some great optimizers for generated code. Thus generated
-code by Hamlit is very fast.
+Please report an issue with following information:
 
-Not only relying on temple optimizers, but also Hamlit's compiler cares about many cases
-to optimize performance such as string interpolation.
+- Full error backtrace
+- Haml template
+- Ruby version
+- Hamlit version
+- Rails/Sinatra version
 
 ## License
 
-MIT License
+Copyright (c) 2015 Takashi Kokubun

data/REFERENCE.md

@@ -0,0 +1,222 @@
+# Hamlit
+
+Basically Hamlit is the same as Haml.
+See [Haml's tutorial](http://haml.info/tutorial.html) if you are not familiar with Haml's syntax.
+
+[REFERENCE - Haml Documentation](http://haml.info/docs/yardoc/file.REFERENCE.html)
+
+## Supported features
+
+See [Haml's reference](http://haml.info/docs/yardoc/file.REFERENCE.html)
+for full features in original implementation.
+
+- [x] Using Haml
+  - [x] Rails XSS Protection
+  - [x] Ruby Module
+  - [x] Options
+  - [ ] Encodings
+- [x] Plain Text
+  - [x] Escaping: \
+- [x] HTML Elements
+  - [x] Element Name: %
+  - [x] Attributes: `
+     - [x] :class and :id Attributes
+     - [x] HTML-style Attributes: ()
+     - [x] Ruby 1.9-style Hashes
+     - [ ] Attribute Methods
+     - [x] Boolean Attributes
+     - [x] HTML5 Custom Data Attributes
+  - [x] Class and ID: . and #
+     - Implicit Div Elements
+  - [x] Empty (void) Tags: /
+  - [x] Whitespace Removal: > and <
+  - [x] Object Reference: []
+- [x] Doctype: !!!
+- [x] Comments
+  - [x] HTML Comments: /
+     - [x] Conditional Comments: /[]
+  - [x] Haml Comments: -#
+- [x] Ruby Evaluation
+  - [x] Inserting Ruby: =
+  - [x] Running Ruby: -
+     - [x] Ruby Blocks
+  - [x] Whitespace Preservation: ~
+  - [x] Ruby Interpolation: #{}
+  - [x] Escaping HTML: &=
+  - [x] Unescaping HTML: !=
+- [x] Filters
+  - [ ] :cdata
+  - [x] :coffee
+  - [x] :css
+  - [x] :erb
+  - [x] :escaped
+  - [x] :javascript
+  - [x] :less
+  - [x] :markdown
+  - [ ] :maruku
+  - [x] :plain
+  - [x] :preserve
+  - [x] :ruby
+  - [x] :sass
+  - [x] :scss
+  - [ ] :textile
+  - [ ] Custom Filters
+- [ ] Helper Methods
+  - [x] surround
+  - [x] precede
+  - [x] succeed
+- [x] Multiline: |
+- [x] Whitespace Preservation
+- [ ] Helpers
+
+
+## Limitations
+
+### No pretty mode
+Haml has :pretty mode and :ugly mode. :pretty mode is used on development and indented beautifully.
+On production environemnt, :ugly mode is used and Hamlit currently supports only this mode.
+
+So you'll see difference rendering result on development environment, but it'll be the same on production.
+
+### No Haml buffer
+Hamlit uses `Array` as buffer for performance. So you can't touch Haml::Buffer from template when using Hamlit.
+
+### Haml helpers are still in development
+At the same time, because some methods in `Haml::Helpers` require `Haml::Buffer`, they are not supported now.
+But some helpers are supported on Rails. Some of not-implemented methods are planned to be supported.
+
+### Limited attributes hyphenation
+In Haml, `%a{ foo: { bar: 'baz' } }` is rendered as `<a foo-bar='baz'></a>`, whatever foo is.
+In Hamlit, this feature is supported only for data attribute. Hamlit renders `%a{ data: { foo: 'bar' } }`
+as `<a data-foo='bar'></a>` because it's data attribute. This design allows us to reduce work on runtime
+and the idea is originally in [Faml](https://github.com/eagletmt/faml).
+
+### Limited boolean attributes
+In Haml, `%a{ foo: false }` is rendered as `<a></a>`, whatever `foo` is.
+In Hamlit, this feature is supported for only boolean attributes, which are defined by
+http://www.w3.org/TR/xhtml1/guidelines.html or https://html.spec.whatwg.org/.
+The list is the same as `ActionView::Helpers::TagHelper::BOOLEAN_ATTRIBUTES`.
+In addition, data-\* is also regarded as boolean.
+
+Since `foo` is not boolean attribute, `%a{ foo: false }` is rendered as `<a foo='false'></a>`
+This is the same behavior as Rails helpers. Also for `%a{ foo: nil }`,
+Hamlit does not remove non-boolean attributes and render `<a foo=''></a>`
+(`foo` is not removed). This design allows us to reduce string concatenation and
+is the only difference between Faml and Hamlit.
+
+## 5 Types of Attributes
+
+Haml has 3 types of attributes: id, class and others.
+In addition, Hamlit treats data and boolean attributes specially.
+So there are 5 types of attributes in Hamlit.
+
+### id attribute
+Almost the same behavior as Haml, except no hyphenation and boolean support.
+Arrays are flattened, falsey values are removed (but attribute itself is not removed)
+and merging multiple ids results in concatenation by "\_".
+
+```rb
+# Input
+#foo{ id: 'bar' }
+%div{ id: %w[foo bar] }
+%div{ id: ['foo', false, ['bar', nil]] }
+%div{ id: false }
+
+# Output
+<div id='foo_bar'></span>
+<div id='foo_bar'></span>
+<div id='foo_bar'></span>
+<div id=''></span>
+```
+
+### class attribute
+Almost the same behavior as Haml, except no hyphenation and boolean support.
+Arrays are flattened, falsey values are removed (but attribute itself is not removed)
+and merging multiple classes results in unique alphabetical sort.
+
+```rb
+# Input
+.d.a(class='b c'){ class: 'c a' }
+%div{ class: 'd c b a' }
+%div{ class: ['d', nil, 'c', [false, 'b', 'a']] }
+%div{ class: false }
+
+# Output
+<div class='a b c d'></div>
+<div class='d c b a'></div>
+<div class='d c b a'></div>
+<div class=''></div>
+```
+
+### data attribute
+Completely compatible with Haml, hyphenation and boolean are supported.
+
+```rb
+# Input
+%div{ data: { disabled: true } }
+%div{ data: { foo: 'bar' } }
+
+# Output
+<div data-disabled></div>
+<div data-foo='bar'></div>
+```
+
+### boolean attributes
+No hyphenation but complete boolean support.
+
+```rb
+# Input
+%div{ disabled: 'foo' }
+%div{ disabled: true }
+%div{ disabled: false }
+
+# Output
+<div disabled='foo'></div>
+<div disabled></div>
+<div></div>
+```
+
+List of boolean attributes is:
+
+```
+disabled readonly multiple checked autobuffer autoplay controls loop selected hidden scoped async
+defer reversed ismap seamless muted required autofocus novalidate formnovalidate open pubdate
+itemscope allowfullscreen default inert sortable truespeed typemustmatch
+```
+
+"data-\*" is also regarded as boolean.
+
+### other attributes
+No hyphenation and boolean support. `false` is rendered as "false" (like Rails helpers).
+
+```rb
+# Input
+%input{ value: true }
+%input{ value: false }
+
+# Output
+<input value='true'>
+<input value='false'>
+```
+
+## Engine options
+
+| Option | Default | Feature |
+|:-------|:--------|:--------|
+| escape\_html | true | HTML-escape for Ruby script and interpolation. This is false in Haml. |
+| escape\_attrs | true | HTML-escape for Html attributes. |
+| format | :html | You can set :xhtml to change boolean attribute's format. |
+| attr\_quote | `'` | You can change attribute's wrapper to `"` or something. |
+
+### Set options for Rails
+
+```rb
+# config/initializers/hamlit.rb or somewhere
+Hamlit::RailsTemplate.set_options attr_quote: '"'
+```
+
+### Set options for Sinatra
+
+```rb
+set :haml, { attr_quote: '"' }
+```