hexp 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e1f3d62af18c9ae3a5a4c28fdb30e44a082e58f4
-  data.tar.gz: 4379e67e153aca5cb338f3b1f002c871b8f71010
+  metadata.gz: fe165e0149eb663683b10c6bbea75d2e594171c2
+  data.tar.gz: d0678b856d53b37e98652d7a987ced5be71ae220
 SHA512:
-  metadata.gz: 8c0244e52ce84768cb92828ecdfb0021ebd6a62ae0c72ad3beaeb801f2386f5177f61008055d528b91444896aa26a47baa705269e04cc6baa2939d4c19fabc83
-  data.tar.gz: db32b6b92696bd5953c666d5fcbaeb9190b9d87dac0320487eeade385d92536b98067373aeb3ffad753eb0cff9ee5c2ef25e67f77d71fe730da8b8c8a483627a
+  metadata.gz: 19bf3b836ac3a73e7b033d9e75c3323f85813660d56624b9f704b3d60c0ae74563c95ad6a64d77f6419330ce2592e4cecae4981e713e740ccb5e70545d37dc40
+  data.tar.gz: 7188623fe858bfe9c84f1c6c4c83061e6535cfae4bcd1558b7296d489116e4190f4a93ab5745b12fc24e18e45e48a98bbfb19749ef60a7978b3bd0ffb168899e

data/.travis.yml

@@ -8,6 +8,9 @@ rvm:
   - 2.0.0
   - 2.1.1
   - 2.1.2
+  - 2.1.3
+  - 2.1
+  - rbx
   - jruby
   - jruby-head
   - ruby-head

data/Changelog.md

@@ -1,6 +1,15 @@
 ### Development
 
-[full diff](http://github.com/plexus/hexp/compare/v0.4.1...master)
+[full diff](http://github.com/plexus/hexp/compare/v0.4.2...master)
+
+### v0.4.2
+
+* Added Hexp::List#append
+* set_attr now simply replaces the full attribute hash, use
+  merge_attr for "smart" behavior. % is now an alias of merge_attr,
+  not set_attr
+* Make the unparser aware of HTML "void" tags (tags that should not
+  have a closing tag)
 
 ### v0.4.1
 
@@ -8,7 +17,7 @@
 * Add Hexp::Node#append as a convenient API for adding child nodes
 * Make Unparser Adamantium-immutable so instances can be included in
   Adamantiumized objects
-* Skip escaping inside <script> tags
+* Skip escaping inside `<script>` tags
 * Add a "rails integration" (ugh) to play nice with
   ActiveSupport::SafeBuffer. use `gem 'hexp', require: 'hexp-rails'`
   in your Gemfile

data/README.md

@@ -12,114 +12,220 @@
 
 # Hexp
 
-**Hexp** (pronounced [ˈɦækspi:]) is a Ruby API for creating and manipulating HTML syntax trees. It enables a web application architecture where HTML is only ever represented as structured data, rather than as plain text.
+**Hexp** (pronounced [ˈɦækspi:]) is a DOM API for Ruby. It lets you treat HTML in your applications as objects, instead of strings. It is a standalone, framework independent library. You can use it to build full web pages, or to clean up your helpers and presenters.
 
-Only when the data needs to be serialized and sent over the network is it converted to a string representation. This has a number of advantages.
+## Fundamentals
 
-* Single responsibility : HTML generation is not mixed with business logic
-* Security : Protection from XSS (cross-site scripting)
-* Productivity : components that create or alter fragments of a HTML become generic, reusable parts
+The three central classes are `Hexp::Node`, `Hexp::TextNode`, and `Hexp::List`. Instances of these classes are immutable. You can mostly treat `TextNode` as a `String` and `List` as an `Array`, except that they're immutable, and come with some extra convenience functions.
 
-For a more in-depth explanation please see the slides of talk [Web Linguistics, Towards Higher Fluency](http://arnebrasseur.net/talks/eurucamp2013/presentation.html) given at Eurucamp 2013. (the video is not available yet.)
+Take this bit of HTML
 
-**Creating Hexps**
+``` html
+<nav id="menu">
+  <ul>
+    <li>Home</li>
+    <li>Lolcats</li>
+    <li>Games</li>
+  </ul>
+</nav>
+```
 
-Hexps are basically snippets of HTML written in nothing but Ruby, here's an example.
+If we would spell out all the objects, it would be represented as
 
-````ruby
-@message = "Hexps are fun for the whole family, from 9 to 99 years old."
-@hexp = H[:div, {class: 'hexp-intro'}, [
-    [:p, @message]
-  ]
-]
-````
+``` ruby
+include Hexp
 
-For more info to get you up and running have a look at the API documentation for [Hexp::Node](http://plexus.github.io/hexp/Hexp/Node.html).
+Node.new(:nav, {"id"=>"menu"},
+  List.new([
+    Node.new(:ul, {},
+      List.new([
+        Node.new(:li, {}, List.new([TextNode.new("Home")])),
+        Node.new(:li, {}, List.new([TextNode.new("lolcats")])),
+        Node.new(:li, {}, List.new([TextNode.new("Games")]))
+      ])
+    )
+  ])
+)
+```
 
-**Don't people use templates for this kind of thing?**
+The `Hexp::Node` constructor is lenient though. It knows how to wrap things in `TextNode` and `List` instances, and it will let you omit the attributes Hash if it's empty, so you never actually type all of that out.
 
-They do, this is an alternative approach. With templates you need to think about which parts need to be HTML-escaped, or you can make errors like forgetting a closing tag. With hexps you no longer need to think about escaping.
+The above simplifies to:
+
+``` ruby
+Node.new(:nav, {"id"=>"menu"},
+  Node.new(:ul,
+    Node.new(:li, "Home"),
+    Node.new(:li, "lolcats"),
+    Node.new(:li, "Games")
+  )
+)
+```
 
-**Wait how is that?**
+There's also a shorthand syntax:
 
-With traditional approaches you can insert plain text in your template, or snippets of HTML. The first must be escaped, the second should not. For your template they are all just strings, so you, the programmer, need to distinguish between the two in a way. For example by using `html_escape` on one (explicit escaping), or `html_safe` on the other (implicit escaping).
+``` ruby
+node = H[:nav, {"id"=>"menu"},
+         H[:ul,
+           H[:li, "Home"],
+           H[:li, "Lolcats"],
+           H[:li, "Games"]]]
 
-When using hexps you never deal with strings that actually contain HTML. Helper methods would return hexps instead, and you can combine those into bigger hexps. Strings inside a hexp are always just that, so they will always be escaped without you thinking about it.
+puts node.to_html
+```
 
-**So that's it, easier escaping?**
+If the first argument to `H[...]` is a Symbol, then the result is a `Node`, otherwise it's a `List`.
 
-Well that's not all, by having a simple lightweight representation of HTML that is _a real data structure_, you can really start programming your HTML. If you have an object that responds to `to_hexp`, you can use that object inside a hexp, so you can use Object Orientation for your user interface. Like so
+You can parse exisiting HTML to Hexp with `Hexp.parse(...)`.
 
-````ruby
-class ProfileLink < Struct.new(:user)
-  def to_hexp
-    H[:a, {class: "profile-link", href: "/user/#{user.id}"}, user.name]
-  end
-end
+### Hexp::Node
 
-class Layout < Struct.new(:content)
-  def to_hexp
-    H[:html, [
-      [:body, [content]]
-    ]
-  end
-end
+A `Node` has a `#tag`, `#attrs` and `#children`. The methods `#set_tag`, `#set_attrs` and `#set_children` return a new updated instance.
+
+``` ruby
+node = H[:p, { class: 'bold' }, "A lovely paragraph"]
+node.tag      # => :p
+node.attrs    # => {"class"=>"bold"}
+node.children # => ["A lovely paragraph"]
+
+node.set_tag(:div)
+# => H[:div, {"class"=>"bold"}, ["A lovely paragraph"]]
+
+node.set_attrs({id: 'para-1'})
+# => H[:p, {"id"=>"para-1"}, ["A lovely paragraph"]]
+
+node.set_children(H[:em, "Ginsberg said:"], "The starry dynamo in the machinery of night")
+# => H[:p, {"class"=>"bold"}, [H[:em, ["Ginsberg said:"]], "The starry dynamo in the machinery of night"]]
+```
+
+#### Predicates
+
+``` ruby
+node.tag?(:p) # => true
+node.text? # => false
+node.children.first.text? # => true
+```
 
-render inline: Layout.new(ProfileLink.new(@user)).to_html
-````
+#### Attributes
 
-**Does it get any better?**
+``` ruby
+# [] : As in Nokogiri/Hpricot, attributes can be accessed with hash syntax
+node['class'] # => "bold"
 
-It does! The really neat part is having filters that process this HTML tree before it gets serialized to text. This could be good for
+# attr : Analogues to jQuery's `attr`, read-write based on arity
+node.attr('class') # => "bold"
+node.attr('class', 'bourgeois') # => H[:p, {"class"=>"bourgeois"}, ["A lovely paragraph"]]
 
-- populating form fields
-- adding extra admin buttons when logged in
-- cleanly separate aspects of your app (e.g. discount codes) from 'core' implementation
-- becoming filthy rich and/or ridiculously happy
+node.has_attr?('class') # => true
+node.class?('bold') # => true
+node.add_class('daring') # => H[:p, {"class"=>"bold daring"}, ["A lovely paragraph"]]
+node.class_list # => ["bold"]
+node.remove_class('bold') # => H[:p, ["A lovely paragraph"]]
+node.remove_attr('class') # => H[:p, ["A lovely paragraph"]]
 
-**What's up with the funny name?**
+# merge_attrs : Does a Hash#merge on the attributes, but the class
+# attribute is treated special. aliased to %
+node.merge_attrs(class: 'daring', id: 'poem')
+# => H[:p, {"class"=>"bold daring", "id"=>"poem"}, ["A lovely paragraph"]]
+```
 
-Hexp stands for HTML expressions. It's a reference to s-expressions as they are known in LISP languages, a simple way to represent data as nested lists.
+#### Children
 
-How to use it
--------------
+``` ruby
+node.empty? # => false
+node.append(H[:blink, "ARRSOME"], H[:p, "bye"]) # => H[:p, {"class"=>"bold"}, ["A lovely paragraph", H[:blink, ["ARRSOME"]], H[:p, ["bye"]]]]
+node.text # => "A lovely paragraph"
+node.map_children { |ch| ch.text? ? ch.upcase : ch } # => H[:p, {"class"=>"bold"}, ["A LOVELY PARAGRAPH"]]
+```
 
-Hexp objects come in two flavors : `Hexp::Node` and `Hexp::List`. A `Node` consists of three parts : its `tag`, `attributes` and `children`. A `List` is just that, a list (of nodes).
+#### CSS Selectors
 
-To construct a `Node` use `H[tag, attributes, children]`. Use a `Symbol` for the `tag`, a `Hash` for the `attributes`, and an `Array` for the `children`. Attributes or children can be omitted when they are empty.
+``` ruby
+node.select('p')
+# => #<Enumerator: #<Hexp::Node::CssSelection @node=H[:p, {"class"=>"bold"}, ["A lovely paragraph"]] @css_selector="p" matches=true>:each>
+node.replace('.warn') {|warning| warning.add_class('bold') }
+```
 
-The list of children will automatically be converted to `Hexp::List`, similarly for any nested nodes you can simply use `[tag, attributes, children]` without the `H`, all nodes in the tree will be converted to proper `Hexp::Node` objects.
+#### The rest
 
-The entire API is centered around these two classes, and one of them you can think of as essentially just an `Array`, in other words Hexp is super easy to learn. Try it out in `irb`, have a look at the examples, and *build cool stuff*!
+``` ruby
+puts node.pp
+node.to_html
+node.to_dom # => Convert to Nokogiri
+```
 
-A note on immutability
-----------------------
+### Hexp::List
 
-All Hexp objects are frozen on creation, you can never alter them afterwards. Operations always return a new `Hexp::Node` rather than working in place.
+A `Hexp::List` wraps and delegates to a Ruby Array, so it has the same
+API as Array. Methods which mutate the Array will raise an exception.
 
-This might seem stringent when you are not used to this style of coding, but it's a pattern that generally promotes good code.
+Additionally `Hexp::List` implements `to_html`, `append`, and `+`. Just like built-in collections, the class implements `[]` as an alternative constructor.
 
-Can I already use it
---------------------
+Equality checks with `==` only compare value equality, so comparing to an Array with the same content returns true. Use `eql?` for a stronger "type and value" equality.
 
-Yes, but there are some things to keep in mind.
+``` ruby
+list = Hexp::List[H[:p, "hello, world!"]]
+list.append("what", "a", "nice", "day")
+#=> [H[:p, ["hello, world!"]], "what", "a", "nice", "day"]
+```
 
-For the 0.x line of versions Hexp is not restricted to [semantic versioning](http://semver.org). We are still designing the API, and small backwards incompatible changes may occur. However given that the project's aim is to only provide the lowest level of DOM manipulation upon which others can built, it is already quite feature complete. It shouldn't be too long before we release a 1.0.0, after which we will commit to semantic versioning.
+## hexp-rails
 
-Another thing is that Hexp is young. It hasn't been battle tested yet, and the ecosystem which will make this approach truly attractive is yet to emerge. Therefore better try it out on smaller, non-critical projects first, and give us your feedback.
+There is a thin layer of Rails integration included. This makes Hexp aware of the `html_safe` / `html_safe?` convention used to distinguish text from markup. It also aliases `to_html` to `to_s`, so Hexp nodes and lists can be used transparently in templates.
 
-Is it any good?
----------------
+``` erb
+<%= H[:p, legacy_helper] %>
+```
 
-Yes
+You need to explicitly opt-in to this behaviour. The easiest is to add a 'require' to your Gemfile
 
-How to install
---------------
+``` ruby
+gem 'hexp', require: 'hexp-rails'
+```
+
+## Builder
+
+If you like the Builder syntax available in other gems like Builder and Hpricot, you can use `Hexp.build` to achieve the same
+
+``` ruby
+Hexp.build do
+  div id: 'warning-sign' do
+    span "It's happening!"
+    ul.warn_list do
+      li "Cats are taking over the world"
+      li "The price of lasagne has continued to rise"
+    end
+  end
+end
+
+# H[:div, {"id"=>"warning-sign"}, [
+#   H[:span, [
+#     "It's happening!"]],
+#   H[:ul, {"class"=>"warn_list"}],
+#   H[:li, [
+#     "Cats are taking over the world"]],
+#   H[:li, [
+#     "The price of lasagne has continued to rise"]]]]
+```
+
+## to_hexp
+
+When an object implements `to_hexp` it can be used where you would otherwise use a node. This can be useful for instance to create components that know how to render themselves.
+
+Yaks does not contain any core extensions, but there is an optional, opt-in, implementation of `to_hexp` for NilClass, so nils in a list of nodes won't raise an error. This lets you write things like
+
+``` ruby
+H[:p,
+  some_node if some_condition?,
+  other_node if other_condition?
+]
+```
 
-At this point you're best off grabbing the Git repo, e.g. with bundler
+You can use it with `require 'hexp/core_ext/nil'`. Loading `hexp-rails` will automatically include this because, let's be honest, if you're using Rails a single monkey patch won't make the difference.
 
-````sh
-# Gemfile
+## Related projects
 
-gem 'hexp', github: 'plexus/hexp'
-````
+* [Hexp-Kramdown](https://github.com/plexus/hexp-kramdown) Convert Markdown documents of various flavors to Hexp
+* [Slippery](https://github.com/plexus/slippery) Generate HTML/JS slides from Markdown. Supports backends for Reveal.js, Deck.js, and Impress.js.
+* [Yaks-HTML](https://github.com/plexus/slippery) Uses Hexp to render hypermedia API resources to HTML
+* [AssetPacker](https://github.com/plexus/asset_packer) Find all images, stylesheets, and javascript references in a HTML file, save them to local files, and return an updated HTML file pointing to the local resources.

data/hexp.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency 'nokogiri', '~> 1.6'
   gem.add_runtime_dependency 'adamantium', '~> 0.2'
   gem.add_runtime_dependency 'equalizer', '~> 0.0'
+  gem.add_runtime_dependency 'concord', '~> 0.0'
 
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'rspec'

data/lib/hexp.rb

@@ -2,10 +2,11 @@ require 'delegate'
 require 'forwardable'
 require 'pathname'
 
-require 'nokogiri' # TODO => replace with Builder
+require 'nokogiri'
 require 'sass'
 require 'adamantium'
 require 'equalizer'
+require 'concord'
 
 module Hexp
   ROOT = Pathname(__FILE__).dirname.parent

data/lib/hexp/list.rb

@@ -91,5 +91,9 @@ module Hexp
     def +(other)
       self.class[*to_ary, *other.to_ary]
     end
+
+    def append(*args)
+      self + args
+    end
   end
 end

data/lib/hexp/node.rb

@@ -52,13 +52,14 @@ module Hexp
   # {Hexp::Node#select}.
   #
   class Node
-    include Equalizer.new(:tag, :attributes, :children)
+    include Concord::Public.new(:tag, :attributes, :children)
     include Adamantium
     extend Forwardable
 
     include Hexp::Node::Attributes
     include Hexp::Node::Children
 
+    alias attrs attributes
     memoize :class_list
 
     # The HTML tag of this node
@@ -69,7 +70,7 @@ module Hexp
     # @return [Symbol]
     # @api public
     #
-    attr_reader :tag
+    #attr_reader :tag
 
     # The attributes of this node
     #
@@ -79,7 +80,7 @@ module Hexp
     # @return [Hash<String, String>]
     # @api public
     #
-    attr_reader :attributes
+    #attr_reader :attributes
 
     # The child nodes of this node
     #
@@ -90,7 +91,7 @@ module Hexp
     # @return [Hexp::List]
     # @api public
     #
-    attr_reader :children
+    #attr_reader :children
 
     # Main entry point for creating literal hexps
     #
@@ -124,7 +125,7 @@ module Hexp
     # @api public
     #
     def initialize(*args)
-      @tag, @attributes, @children = Normalize.new(args).call
+      super(*Normalize.new(args).call)
     end
 
     # Standard hexp coercion protocol, return self

data/lib/hexp/node/attributes.rb

@@ -124,12 +124,10 @@ module Hexp
       def set_attrs(attrs)
         H[
           self.tag,
-          self.attributes.merge(Hash[*attrs.flat_map{|k,v| [k.to_s, v]}]),
+          Hash[*attrs.flat_map{|k,v| [k.to_s, v]}],
           self.children
         ]
       end
-      alias :% :set_attrs
-      alias :add_attributes :set_attrs
 
       # Remove an attribute by name
       #
@@ -188,6 +186,8 @@ module Hexp
         end
         result
       end
+      alias :% :merge_attrs
+
     end
   end
 end

data/lib/hexp/unparser.rb

@@ -27,7 +27,9 @@ module Hexp
 
     DEFAULT_OPTIONS = {
       encoding: Encoding.default_external,
-      no_escape: [:script]
+      no_escape: [:script],
+      void: [ :area, :base, :br, :col, :command, :embed, :hr, :img, :input,
+              :keygen, :link, :meta, :param, :source, :track, :wbr ]
     }
 
     attr_reader :options
@@ -59,7 +61,7 @@ module Hexp
       end
       buffer << GT
       add_child_nodes(buffer, tag, children)
-      buffer << LT << FSLASH << tag.to_s << GT
+      buffer << LT << FSLASH << tag.to_s << GT unless void?(tag)
     end
 
     def add_child_nodes(buffer, tag, children)
@@ -84,5 +86,9 @@ module Hexp
     def escape_text(text)
       text.gsub(ESCAPE_TEXT_REGEX, ESCAPE_TEXT)
     end
+
+    def void?(tag)
+      options[:void].include?(tag)
+    end
   end
 end

data/lib/hexp/version.rb

@@ -1,3 +1,3 @@
 module Hexp
-  VERSION = '0.4.1'
+  VERSION = '0.4.2'
 end

data/spec/unit/hexp/node/attributes_spec.rb

@@ -91,10 +91,6 @@ describe Hexp::Node::Attributes do
     it 'should override attributes' do
       expect(H[:foo, class: 'baz'].set_attrs(class: 'bar')).to eq H[:foo, class: 'bar']
     end
-
-    it 'should merge keep both old and new attributes' do
-      expect(H[:foo, class: 'baz'].set_attrs(src: 'bar')).to eq H[:foo, class: 'baz', src: 'bar']
-    end
   end
 
   describe 'merge_attrs' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hexp
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Arne Brasseur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-30 00:00:00.000000000 Z
+date: 2014-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sass
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: concord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement