undies 2.2.1 → 3.0.0.rc.1

data/ARCH.md

@@ -0,0 +1,116 @@
+# Undies Models
+
+## `IO`
+
+Used internally to handle generated output streaming.  An instance of this class is required when defining Template objects.
+
+```ruby
+output = ""
+templ  = Undies::Template.new(Undies::IO.new(output, :pp => 2))
+```
+
+Create IO objects by passing two arguments:
+
+* *stream*: a stream for writing generated output to.  the only requirement is it must respond to `<<`.
+* *options hash*: a hash of output options:
+** `:pp`: (pretty print) indent size.  an integer specifying how many spaces each level of indent should be.  is `nil` by default and implies no pretty printed output
+** `:pp_level`: the starting level for pretty printing.  is zero by default.
+
+### API
+
+#### Attributes
+
+* `stream`: the io steam being written to
+* `newline`: the newline character for this IO.  set to `"\n"` if `:pp` option is not nil, `""` otherwise
+* `level`: the current pp level
+* `indent`: the amount of spaces in each indent level
+* `node_stack`: the stack of nodes being written on
+* `current`: the current node being written (`node_stack.last`)
+
+#### Methods
+
+* `write`: write the given text to the io stream.  aliased as `<<`.
+* `push`: given a node object, pushes it onto the node stack and increments the level
+* `push!`: given a node object, pushes it onto the node stack - no level changes
+* `pop`: pops the current node from the node stack and decrements the level
+* `options=`: pass a hash to reset (no merge) the IO options
+
+
+## `Template`
+
+Build with an IO object to generate tempalated markup.  Can supply a data hash to render on.  Can either supply Source templates that are evaluated in the Template scope, or you can build the template object and drive using a more builder like render approach.  See the README for more details on building templates and rendering.
+
+### API
+
+#### Markup methods
+
+* `_`:  pass a string to insert escaped markup or text
+* `__`: pass a string to insert unescaped markup or text
+* `_<element>`: any method prefixed with an '_' will define an element with that name.  Aliased as `tag` and `element`.
+* `__attrs`: pass a Hash to modify parent element attributes within the build.  Merges with current attributes.
+* `__yield`: render nested content (ie from a layout) when rendering using nested Source objects.
+* `__partial`: insert markup generated with its own source/data/scope into the template.
+
+#### Flow Control methods
+
+* `__push`: used to change the template scope to modify on the latest child element.  Needed in manual render approach.
+* `__pop`:  used to change the template scope back to modify on the parent element.
+* `__flush`: used to flush any cached markup to the IO.  You must call this after rendering is complete if using the builder or manual render approaches.  Can call using the singleton Template variant: `Undies::Template.flush(my_template_obj)`
+
+
+## `RootNode`
+
+Used internally to implement the markup tree nodes.  Each node caches and processes nested markup and elements.  At each node level in the markup tree, nodes/markup are cached until the next sibling node or raw markup is defined, or until the node is flushed.  This keeps nodes from bloating memory on large documents and allows for output streaming.
+
+### API
+
+#### Attributes
+
+* `__cached`: the currently cached markup/element
+* `__builds`: the builds that should be run in the root scope
+
+#### Methods
+
+* `__attrs`: does nothing.  If called on the root of a document it has no effect.
+* `__flush`: flush any cached markup to the IO
+* `__markup`: pass raw markup.  will write any cached markup and cache this new markup.
+* `__element`: pass an element node.  will write any cached markup and cache the new element.
+* `__partial`: insert raw markup (just calls __markup, needed by Template API)
+* `__push`: will clear and push the cached node/markup to the IO handler, changing the Template API scope to that node/markup.
+* `__pop`: flush.  should have no effect on the IO handler if called.
+
+
+## `Element`
+
+Handles tag element markup and the scope for building and nesting markup.
+
+### API
+
+#### Singleton Methods
+
+* `Element#hash_attrs`: given a nested hash, serialize to markup tag attribute string
+* `Element#escape_attr_value`: given a value, escape it for attribute string use
+
+#### Attributes
+
+* `__cached`: the currently cached child markup/element
+* `__builds`: any builds should be run against the Element
+
+#### Methods
+
+* `__attrs`: pass a hash.  merges given hash with element attrbutes.  only has an effect if called before the start tag is written (before any child elements or markup is defined).
+* `__flush`: flush any cached markup to the IO
+* `__markup`: pass raw markup.  will write any cached markup and cache this new markup.  writes the start tag appropriately if not already written.
+* `__element`: pass an element node.  will write any cached markup and cache the new element.  writes the start tag appropriately if not already written.
+* `__partial`: insert raw markup as child element markup (just calls __element, needed by Template API)
+* `__push`: will clear and push the cached node/markup to the IO handler, changing the Template API scope to that node/markup.
+* `__pop`: flushes any cached markup and will pop the current node/markup from the IO handler.  changes the Template API scope to that parent node/markup.  finally writes the end tag appropriately.
+* `to_s`: pushes itself to the IO handler, changing the Template API scope to operate on itself.  calls any builds for the element.  calls `__pop` once builds have run.
+
+## `Source`
+
+TODO
+
+## `SourceStack`
+
+TODO

data/Gemfile

@@ -6,4 +6,7 @@ gemspec
 gem 'rake', '~>0.9.2'
 gem 'ruby-prof'
 gem 'erubis'
+gem 'haml'
+gem 'markaby'
+gem 'erector'
 gem 'ansi'

data/Gemfile.lock

@@ -1,20 +1,32 @@
 PATH
   remote: .
   specs:
-    undies (2.2.1)
+    undies (3.0.0.rc.1)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    ansi (1.4.1)
+    ansi (1.4.2)
     assert (0.7.3)
       assert-view (~> 0.5)
-    assert-view (0.5.0)
+    assert-view (0.6.0)
       ansi (~> 1.3)
-      undies (~> 2.0)
+    builder (3.0.0)
+    erector (0.8.3)
+      rake
+      rake
+      treetop
+      treetop (>= 1.2.3)
     erubis (2.7.0)
+    haml (3.1.4)
+    markaby (0.7.2)
+      builder (>= 2.0.0)
+    polyglot (0.3.3)
     rake (0.9.2)
     ruby-prof (0.10.8)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
     whysoslow (0.0.2)
       ansi (~> 1.4)
 
@@ -24,8 +36,12 @@ PLATFORMS
 DEPENDENCIES
   ansi
   assert (~> 0.7.3)
+  assert-view (~> 0.6)
   bundler (~> 1.0)
+  erector
   erubis
+  haml
+  markaby
   rake (~> 0.9.2)
   ruby-prof
   undies!

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011-Present Kelly Redding
+
+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.

data/README.md

@@ -0,0 +1,343 @@
+# Undies
+A pure-Ruby DSL for streaming templated HTML, XML, or plain text.  Named for its gratuitous use of the underscore.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'undies'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install undies
+
+## Usage
+
+```ruby
+_html {
+  _head {
+    _title "Hello World"
+  }
+  body {
+    _h1.main!.big "Hi There!"
+    _p "this is an ", em("Undies"), " usage example."
+  }
+}
+```
+
+Will stream out
+
+```
+<html>
+  <head>
+    <title>Hello World</title>
+  </head>
+  <body>
+    <h1 class="big" id="main">Hi There!</h1>
+    <p>this is an <em>Undies</em> usage example.</p>
+  </body>
+</html>
+```
+
+## DSL
+
+### Plain text
+
+All text is escaped by default.
+
+```ruby
+    Undies::Template.escape_html("ab&<>'\"/yz")
+    # => "ab&amp;&lt;&gt;&#x27;&quot;&#x2F;yz"
+```
+
+Capture raw (un-escaped) text using the `raw` method
+
+```ruby
+    raw "this will <em>not</em> be escaped"
+    # => "this will <em>not</em> be escaped"
+```
+
+### XML
+
+Capture an empty element:
+
+```ruby
+    element(:thing) # => "<thing />"
+    tag('ns:thing') # => "<ns:thing />"
+```
+
+Capture an element with content:
+
+```ruby
+    # basic content
+
+    element(:thing, "some content")
+    # => "<thing>some content</thing>"
+
+    # all content is escaped by default
+
+    element(:thing, "&<>")
+    # => "<thing>&amp;&lt;&gt;</thing>"
+
+    # you can force raw content using the `raw` method
+
+    element(:thing, raw("<raw>text</raw>"))
+    # => "<thing><raw>text</raw></thing>"
+
+    # you can pass in as many pieces of content as you like
+
+    element(:thing, "1 < 2", raw("<raw>text</raw>"), " & 4 > 3")
+    # => "<thing>1 &lt; 2<raw>text</raw>&amp; 4 &gt; 3</thing>"
+```
+
+Capture an element with attributes:
+
+```ruby
+    element(:thing, "some content", :one => 1, 'a' => "Aye")
+    # => "<thing one=\"1\" a=\"Aye\">some content</thing>"
+```
+
+Capture nested elements:
+
+```ruby
+    element(:thing) {
+      element('Something', "Some Content")
+      element('AnotherThing', "more content")
+    } # => "<thing><Something>Some Content</Something><AnotherThing>more content</AnotherThing></thing>"
+```
+
+### HTML
+
+In general, all the same stuff applies.  However, you can call specific methods for all non-deprecated elements from the HTML 4.0.1 spec.
+
+```ruby
+    br
+    # => "<br />"
+
+    span "something"
+    # => "<span>something</span>"
+
+    div "something", :style => "color: red"
+    # => "<div style=\"color: red\">somthing</div"
+
+    html {
+      head { title "Hello World" }
+      body {
+        h1 "Hi There!"
+      }
+    } # => "<html><head><title>Hello World</title></head><body<h1>Hi There!</h1></body></html>"
+```
+
+You can't mix content and nested elements.  If you specify content in the element arguments, any nested element blocks will be ignored
+
+```ruby
+    div("contents") {
+      span "more content"
+    }
+    # => "<div>contents</div>"
+```
+
+Use bang (!) method calls to set id attributes
+
+```ruby
+    h1.header!
+    # => "<h1 id=\"header\" />"
+
+    h1.header!.title!
+    # => "<h1 id=\"title\" />"
+```
+
+Use general method calls to add class attributes
+
+```ruby
+    _h1.header.awesome
+    # => "<h1 class=\"header awesome\" />"
+```
+
+Use both in combination
+
+```ruby
+    h1.header!.awesome
+    # => "<h1 class=\"awesome\" id=\"header\" />
+```
+
+## Streamed Output
+
+Up to this point we've just looked at 'capture methods' - the generated output is just returned as a string.  Undies, however, is designed to stream generated content to a given IO.  This has a number of advantages:
+
+* content is written out immediately
+* maintain a relatively low memory profile while rendering
+* can process large templates with linear performance impact
+
+### Plain text
+
+Stream plain text
+*note*: this is only valid at the root of the view.  to add plain text to an element, pass it in as an argument.  it will get streamed out as the element is streamed.
+
+```ruby
+    _ "this will be escaped"
+
+    _ raw("this will not be escaped")
+    ```
+
+### XML
+
+Stream xml element markup.  Call the element and tag methods with two leading underscores.
+
+```ruby
+    __element(:thing)
+
+    __tag('ns:thing')
+```
+
+All other element handling is the same.
+
+### HTML
+
+Stream html markup.  Call the html element methods with a leading underscore.
+
+```ruby
+    _br
+
+    _span "something"
+
+    _div "something", :style => "color: red"
+
+    _html {
+      _head { _title "Hello World" }
+      _body {
+        _h1 "Hi There!"
+      }
+    }
+```
+
+All other element handling is the same.
+
+### Notes on streamed output
+
+* because content is streamed then forgotten as it is being rendered, streamed elements cannot be self-referrential.  No one element may refer to other previously rendered elements.
+* streamed output will honor pretty printing settings - captured output is never pretty printed
+* elements specified with content are printed on a single line
+* elements specified with nested elements are always printed on multiple lines
+* in general, define markup using streaming method calls for the main markup and add inline elements to content using the capture methods
+* captured element output is always handled as raw markup and won't be escaped
+
+## Rendering
+
+To render using Undies, create a Template instance, providing the template source, data, and io information.
+
+    source = Undies::Source.new("/path/to/sourcefile")
+    data   = { :two_plus_two => 4 }
+    io     = Undies::IO.new(@some_io_stream)
+
+    Undies::Template.new(source, {}, io)
+
+### Source
+
+You specify Undies source using the Undies::Source object.  You can create source either form a block or a file.  Source content (either block or file) will be evaluated in context of the template.
+
+### Data
+
+Undies renders source content in the isolated scope of the Template.  This means that content has access to only the data it is given or the Undies API itself.  When you define a template for rendering, you provide not only the template source, but any data that source should be rendered with.  Data is given in the form of a Hash.  The string form of the hash keys are exposed as local instance variables assigned their corresponding values.
+
+### IO
+
+As said before, Undies streams to a given io stream.  You specify a Template's io by creating an Undies::IO object.  These objects take a stream and a hash of options:
+
+* :pp (pretty-print) : set to a Fixnum to space-indent pretty print the streamed output.
+* :level : the starting level to render pretty printed output at, default is zero
+
+### Examples
+
+file source, no local data, no pretty printing
+
+```ruby
+    source = Undies::Source.new("/path/to/source")
+    Undies::Template.new(source, {}, Undies::IO.new(@io))
+```
+
+proc source, simple local data, no pretty printing
+
+```ruby
+    source = Undies::Source.new(Proc.new do
+      _div {
+        _ @content.to_s
+      }
+    end)
+    Undies::Template.new(source, {:content => "Some Content!!" }, Undies::IO.new(@io))
+```
+
+pretty printing (4 space tab indentation)
+
+```ruby
+    source = Undies::Source.new("/path/to/source")
+    Undies::Template.new(source, {}, Undies::IO.new(@io, :pp => 4))
+```
+
+### Builder approach
+
+The above examples use the "source rendering" approach.  This works great when you know your source content before render time and create a source object from it (ie rendering a view template).  However, in some cases, you may not know the source until render time and/or want to use a more declarative style to specify render output.  Undies content can be specified programmatically using the "builder rendering" approach.
+
+To render using this approach, create a Template instance passing it data and io info as above.  However, don't pass in any source info, only pass in any local data if you like, and save off the created template:
+
+```ruby
+    # choosing not to use any local data in this example
+    template = Undies::Template.new(Undies::IO.new(@io))
+```
+
+Now just interact with the Undies API directly.
+
+```ruby
+    # notice that it becomes less important to bind any local data to the Template using this approach
+    something = "Some Thing!"
+    template._div.something! template._ something.to_s
+
+    template._div {
+      template._span "hi"
+    }
+```
+
+*Note:* there is one extra caveat to be aware of using this approach.  You need to be sure and flush the template when content processing is complete.  Just pass the template to the Undies::Template#flush method:
+
+```ruby
+    # ensures all content is streamed to the template's io stream
+    # this is necessary when not using the source approach above
+    Undies::Template.flush(template)
+```
+
+### Manual approach
+
+There is another method you can use to render output: the manual approach.  Like the builder approach, this method is ideal when you don't know the source until render time.  The key difference is that blocks are not used to imply nesting relationships.  Using this approach, you manually 'push' and 'pop' to move up and down nesting relationship contexts.  So a push on an element would move the template context to the element pushed.  A pop would move back to the current context's parent element.  As you would expect, pop'ing on the root of a template has no effect on the context and pushing a non-element node has no effect on the context.
+
+To render using this approach, create a Template as you would with the Builder approach.  Interact with the Undies API directly.  Use the Template#__push and Template#__pop methods to change the template scope.
+
+```ruby
+    # this is the equivalent to the Builder approach example above
+
+    template = Undies::Template.new(Undies::IO.new(@io))
+
+    something = "Some Thing!"
+    template._div.something! something.to_s
+
+    template._div
+    template.__push
+    template._span "hi"
+    template.__pop
+
+    # alternate method for flushing a template
+    template.__flush
+```
+
+*Note:* as with the Builder approach, you must flush the template when content processing is complete.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -4,26 +4,34 @@ Assert::RakeTasks.for(:test)
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
-task :default => :run_all
+task :default => :build
 
-desc "Run the profiler on the large bench template."
-task :run_profiler do
-  require 'bench/profiler_runner'
-  UndiesProfilerRunner.new('large').print_flat(STDOUT, :min_percent => 3)
-end
+namespace :bench do
+
+  desc "Run the bench script."
+  task :run do
+    require 'bench/bench_runner'
+    UndiesBenchRunner.new
+  end
+
+  desc "Run the profiler on 1000 rows."
+  task :profiler do
+    require 'bench/profiler_runner'
+    UndiesProfilerRunner.new('verylarge').print_flat(STDOUT, :min_percent => 1)
+  end
+
+  desc "Run all the tests, then the profiler, then the bench."
+  task :all do
+    Rake::Task['test'].invoke
+    puts
+    Rake::Task['run_profiler'].invoke
+    puts
+    Rake::Task['run_bench'].invoke
+  end
 
-desc "Run the benchmark script."
-task :run_bench do
-  require 'bench/bench_runner'
-  UndiesBenchRunner.new
 end
 
-desc "Run all the tests, then the profiler, then the bench."
-task :run_all do
-  Rake::Task['test'].invoke
-  puts
-  Rake::Task['run_profiler'].invoke
-  puts
-  Rake::Task['run_bench'].invoke
+task :bench do
+  Rake::Task['bench:run'].invoke
 end