hexp 0.2.0 → 0.3.0

data/SPEC.md

@@ -1,53 +0,0 @@
-# HTML Expressions (hexp) Specification
-
-HTML Expressions, hexps for short, are a subset of s-expressions. They provide a convention for working with HTML data in applications in a structured fashion.
-
-Most languages contain a DOM implementation to work with HTML/XML documents, fragments and nodes. However, generating HTML through the DOM API is verbose and tedious. A hexp implementation SHOULD implement conversions from and to DOM documents. A hexp implementation SHOULD NOT convert directly from or to HTML.
-
-A hexp implementation MUST implement hexp normalization. Several shorthands are provided for the convenience of the programmer when entering literal hexps. These non-strict hexps should be normalized to strict hexps before further manipulation.
-
-## Strict hexps
-
-A strict hexp is a triplet, it represents a single HTML node. The first element is the tag name, the second a dictionary of attributes, the third is a list of child nodes.
-
-If the language implements the concept of a symbol (interned string), the tag name MUST BE a symbol. Otherwise it will be represented as a regular string.
-
-The attributes are represented in a dictionary (hash), with both keys and values being strings.
-
-The list of child nodes is a list (array) of other hexps or strings, the latter representing text nodes in the corresponding DOM.
-
-An example in Ruby of a strict hexp :
-
-````ruby
-[:div, {'class': 'hexp-example'}, [
-    [:p, {}, "Hello, world"]
-  ]
-]
-````
-
-A normalized hexp MUST be made immutable (frozen, persistent) if the runtime supports it. Operations that alter a hexp MUST return a new hexp values, rather than changing the hexp value in-place.
-
-## Non-strict hexps
-
-Following simplifications are allowed for entering literal hexps, the implementation MUST provide a mechanism for converting these to strict hexps.
-
-````ruby
-# non-strict -> strict
-[:p]                            -> [:p, {}, []]
-[:p, {'class' => 'foo'}]        -> [:p, {'class' => 'foo'}, []]
-[:p, ['hello,', [:br], 'world'] -> [:p, {}, ['hello,', [:br, {}, []], 'world']
-````
-
-### Omitting attributes or children
-
-If the dictionary of attributes is empty, it may be omitted.
-
-If the list of children is empty, it may be omitted.
-
-### A single text node as child
-
-If the represented node its only child is a text node, a single string may be given rather than a list of children. An example would be `<p>Hello, world</p>`, this can be represented as `[:p, "Hello, world"]`, which would be normalized to `[:p, {}, ["Hello, world"]]`.
-
-### Standard coercion protocol
-
-In a dynamically typed object-oriented language, a convention may be set for a protocol that objects can implement to return a strict hexp representation of themselves. For Ruby this will be the `to_hexp` method. In the list of children, objects can be added that implement `to_hexp`. The normalization procedure must detect that the object implements this method, and add the resulting hexps to the list of children.

data/notes

@@ -1,34 +0,0 @@
-http://begriffs.github.io/showpiece/
-
-TODO
-====
-* Rename Hexp::Node to Hexp::Element
-* Rename Selector to Selection
-
-Issues
-======
-
-Root elements should not be treated separately
-
-A `rewrite` operation currently yields all nodes except the root node. Rewrite allows you to replace a node with zero, one or more nodes. My thinking at the time was that I wanted to make sure a single Hexp was returned, so if one could rewrite the root node that would be problematic.
-
-This however makes for a special case that is not very intuitive. When implementing `Hexp::Node::Selector` I came across this again. One can use a Selector strictly as an Enumerable
-
-```ruby
-# Find the first child element of all elements with class="strong"
-hexp.select {|el| el.class? 'strong' }.map {|el| el.children.first }
-```
-
-In this case there is no reason why that shouldn't iterate the whole tree, including the node. Other operations on `Selector` however do a Rewrite of the selected elements, and in this case the "all-except-the-root-node" limitation applies.
-
-``` ruby
-# Add class="strong" to all divs
-H[:div, [
-    [:div, 'one'],
-    [:div, 'two']
-  ]
-].select{|node| node.tag==:div}.attr('class', 'strong').to_hexp
-#=> H[:div, [H[:div, {"class"=>"strong"}, ["one"]], H[:div, {"class"=>"strong"}, ["two"]]]]
-```
-
-The top-level node is unaffected. To remove this limitation `Rewriter` will have to return a `Hexp::List` when zero or multiple elements are returned. Hexp::Node and Hexp::List will also have to implement as much as possible the same interface, so they can be largely used intechangably. This should especially be possible for all select/rewrite operations.