tagz 1.0.0 → 4.2.0

data/README

@@ -1,240 +1,215 @@
 NAME
+
   tagz.rb
 
 SYNOPSIS
-  object mixin for squeaky clean and super speedy generation of any sgml
-  (html/xml) tags using a private dsl
-
-    + module level interface
-
-        require 'tagz'
-
-        html =
-          Tagz{
-            html_{
-              body_(:class => 'container'){
-                div_{ 'content' }
-              }
-            }
-          }
-
-    + private mixin interface
 
-        require 'tagz'
+  require Tagz
 
-        class Table < ::Array 
-          include Tagz
+  include Tagz.globally
 
-          def initialize width, height
-            @width, @height = width, height
-          end
-
-          def to_row
-            Tagz{
-              table_(:width => @width, :height => @height){
-                each do |row|
-                  tr_{
-                    row.each{|cell| td_{ cell }}
-                  }
-                end
-              }
-            }
-          end
-        end
+  a_(:href => "/foo"){ "bar" }  #=>  <a href="/foo">bar</a> 
 
 DESCRIPTION
-  tagz.rb offers a mixin module which adds four private methods to the calling
-  object:
 
-    tagz
-    tagz__
-    __tagz
-    method_missing
+  tagz.rb is generates html, xml, or any sgml variant like a small ninja
+  running across the backs of a herd of giraffes swatting of heads like a
+  mark-up weedwacker.  weighing in at less than 200 lines of code tagz.rb adds
+  an html syntax to ruby that is both unobtrusive, safe, and available
+  globally to objects without the need for any builder or superfluous objects.
+  tagz.rb is designed for applications that generate html to be able to do so
+  easily in any context without heavyweight syntax or scoping issues, like a
+  ninja sword through butter.
 
-  because the mixing adds only private methods it's safe to use, for instance,
-  in the controller of a web framework which exposes methods to the world as
-  http actions
+INSTALL
 
-  the method_missing tagz.rb adds *only* works from inside a Tagz{}/tagz{}
-  block, for instance
+  gem install tagz
 
-    include Tagz
+HISTORY
 
-    tagz{ h1_{ 'this works' } }
+  4.2.0
+    - general lib cleanup
+    - introduction of dual-mixin technique (Tagz.globally)
+    - few small bug fixes
+    - ninja tales
 
-    h1_{ 'this throws NameError' }
+SAMPLES
 
-  tagz.rb is very non-restrictive, allowing you to generate invalid html,
-  html4, xml, whatever, all using the same simple interface
+  <========< samples/a.rb >========>
 
-  for example
+  ~ > cat samples/a.rb
 
+    #
+    # in the simplest case tagz generates html using a syntax which safely mixes
+    # in to any object
+    #
+    
     require 'tagz'
-    include Tagz
-   
-    tagz{ 
-      div_(:class => 'pinky'){ 'content' }
-    }
-
-    #=> <div class="pinky">content</div>
-
-   
-    tagz{
-      img_(:src => 'foo.png')
-      img_(:src => 'foo.png'){}
-    }
-
-    #=> <img src="foo.png">
-    #=> <img src="foo.png" />
-
-   
-    tagz{
-      br_
-      br_!
-      br_{}
-    }
+    include Tagz.globally
+    
+    class GiraffeModel
+      def link
+        a_(:href => "/giraffe/neck/42"){ "whack!" }
+      end
+    end
+    
+    puts GiraffeModel.new.link
 
-    #=> <br>
-    #=> <br />
-    #=> <br />
+  ~ > ruby samples/a.rb
 
-   
-    tagz{
-      span_('content', :style => 'color:mauve')
-    }
+    <a href="/giraffe/neck/42">whack!</a>
 
-    #=> <span style="color:mauve">content</span>
 
-   
-    tagz{
-      div_(:class => 'container'){
-        span_('content', :style => 'color:mauve')
-      }
-    }
-
-    #=> <div class="container"><span style="color:mauve">content</span></div>
-
-   
-    tagz{
-      div_(:class => 'container')
-        span_('content', :style => 'color:mauve')
-      _div
-    }
+  <========< samples/b.rb >========>
 
-    #=> <div class="container"><span style="color:mauve">content</span></div>
+  ~ > cat samples/b.rb
 
-   
-    tagz{
-      table_(:width => 42{ 
-        %w( 1 2 3 ).each do |row|
-          tr_{
-            row.each{|cell| td_{ cell }}
-          }
-        end
+    #
+    # tagz.rb mixes quite easily with your favourite templating engine, avoiding
+    # the need for '<% rows.each do |row| %> ... <% row.each do |cell| %> '
+    # madness and other types of logic to be coded in the templating language,
+    # leaving templating to template engines and logic and looping to ruby -
+    # unencumbered by extra funky syntax
+    #
+    
+    require 'tagz'
+    include Tagz.globally
+    
+    require 'erb'
+    
+    rows = %w( a b c ), %w( 1 2 3 )
+    
+    template = ERB.new <<-ERB
+      <html>
+        <body>
+          <%=
+    
+            if rows
+    
+              table_{
+                rows.each do |row|
+                  tr_{
+                    row.each do |cell|
+                      td_{ cell }
+                    end
+                  }
+                end
+              }
+    
+            end
+    
+          %>
+        </body>
+      </html>
+    ERB
+    
+    puts template.result(binding)
+    
+
+  ~ > ruby samples/b.rb
+
+      <html>
+        <body>
+          <table><tr><td>a</td><td>b</td><td>c</td></tr><tr><td>1</td><td>2</td><td>3</td></tr></table>
+        </body>
+      </html>
+
+
+  <========< samples/c.rb >========>
+
+  ~ > cat samples/c.rb
+
+    #
+    # once you've learned to generate html using tagz you're primed to generate
+    # xml too
+    #
+    
+    require 'tagz'
+    include Tagz.globally
+    
+    doc =
+      xml_{
+        giraffe_{ 'large' }
+        ninja_{ 'small' }
       }
-    }
+    
+    puts doc
 
-    #=> <table width="42"><tr><td>1</td><td>2</td><td>3</td></tr></table>
+  ~ > ruby samples/c.rb
 
-    # note that the return value of the table block ( the array %w( 1 2 3 )
-    # is *NOT* added to the content.  the rule is: add the return value of
-    # the block if, and only if, the block did not add any content itself
-    # during evaluation
+    <xml><giraffe>large</giraffe><ninja>small</ninja></xml>
 
-   
-    tagz{
-      div_{
-        div_{ 'content' }
-        'this is ignored'
-      }
-    }
 
-    #=> <div><div>content</div></div>
+  <========< samples/d.rb >========>
 
-    # this is a side effect of the above rule
+  ~ > cat samples/d.rb
 
-   
-    tagz{
-      div_{
-        'this is not ignored, see above rule'
+    #
+    # tagz.rb doesn't cramp your style, allowing even invalid html to be
+    # generated.  note the use of the 'tagz' method, which can be used both to
+    # capture output and to append content to the top of the stack.
+    #
+    
+    require 'tagz'
+    include Tagz.globally
+    
+    def header
+      tagz{
+        html_
+          body_(:class => 'ninja-like', :id => 'giraffe-slayer')
+    
+          tagz << "\n<!-- this is the header -->\n"
       }
-    }
-
-    #=> <div>this is not ignored, see above rule</div>
-
-   
-    tagz{
-      div_{
-        div_{ 'content' }
-        tagz << 'this is appended' << ' and so is this'
+    end
+    
+    def footer
+      tagz{
+        tagz << "\n<!-- this is the footer -->\n"
+    
+        body_
+          html_
       }
-    }
+    end
+    
+    puts header, footer
 
-    #=> <div><div>content</div>this is appended and so is this</div>
-
-   
-    tagz{
-      a_
-      b_
-      c_
-        tagz << 'valid html'
-      _a
-      _b
-      _c
-      _invalid
-    }
-
-    #=> <a><b><c>valid html</a></b></c></invalid>
+  ~ > ruby samples/d.rb
 
-   
-    tagz{
-      __
-      a_{ 'content' }
+    <html><body class="ninja-like" id="giraffe-slayer">
+    <!-- this is the header -->
+    
+    <!-- this is the footer -->
+    <body><html>
 
-      __ __
-      b_{ 'content' }
-
-      __ __ __
-      c_{ 'content' }
-    }
 
-    #=> \n<a>content</a>\n\n<b>content</b>\n\n\n<c>content</c>
+  <========< samples/e.rb >========>
 
-    # note that \n is newline.  the html tagz generates is quite compact,
-    # you can do 'tagz << "\n"' or just use the '__' method to output some
-    # linebreaks
+  ~ > cat samples/e.rb
 
-   
-    tagz{
-      link = e(:a, :href => 'foo.com'){ 'link text' }
-
-      div_{ link }
+    #
+    # tagz.rb allows a safer method of mixin which requires any tagz methods to be
+    # insider a tagz block - tagz generating methods outside a tagz block with
+    # raise an error if tagz is included this way.  also notice that the error is
+    # reported from where it was raised - not from the bowels of the the tagz.rb
+    # lib.
+    #
+    
+    require 'tagz'
+    include Tagz
+    
+    puts tagz{
+     html_{ 'works only in here' }
     }
+    
+    begin
+      html_{ 'not out here' }
+    rescue Object => e
+      puts e.backtrace
+    end
+    
 
-    #=> <div><a href="foo.com">link text</a>
-
-
-  a couple of notes: *none* of the method_missing magic is available outside
-  the 'tagz' block and, even inside, it supers-up when the missing method does
-  not look like a tag method.  you can use Tagz{} as a module method but to
-  have access to @ivars you'll want to mixin the module to your own class and
-  use tagz{}.  no public methods are added to your object, only four private
-  ones.
-      
-
-HISTORY
-  1.0.0
-    totally reworked tagz, dropping 300 loc - only 170 loc now.  this release
-    is *NOT* backward compatible with other tagz versions, though the api is
-    very very close.  the rework makes tagz safer to mixin, faster, and
-    produces nicer looking html.  this version also marks ramaze template
-    support.
-
-INSTALL
-  gem install tagz
+  ~ > ruby samples/e.rb
 
-URI
-  http://rubyforge.org/projects/codeforpeople
+    <html>works only in here</html>
+    samples/e.rb:17
 
-AUTHOR
-  ara.t.howard@gmail.com

data/a.rb

@@ -0,0 +1,8 @@
+require 'tagz'
+
+include Tagz
+
+p a_{ 'foo' }
+p a_{ 'foo' }
+
+p tagz

data/gemspec.rb

@@ -1,27 +1,35 @@
-
 lib, version = File::basename(File::dirname(File::expand_path(__FILE__))).split %r/-/, 2
 
 require 'rubygems'
 
 Gem::Specification::new do |spec|
   $VERBOSE = nil
+
+  shiteless = lambda do |list|
+    list.delete_if do |file|
+      file =~ %r/\.svn/ or
+      file =~ %r/\.tmp/
+    end
+  end
+
   spec.name = lib 
   spec.version = version 
   spec.platform = Gem::Platform::RUBY
   spec.summary = lib 
 
-  spec.files = Dir::glob "**/**"
-  spec.executables = Dir::glob("bin/*").map{|exe| File::basename exe}
+  spec.files = shiteless[Dir::glob("**/**")]
+  spec.executables = shiteless[Dir::glob("bin/*")].map{|exe| File::basename exe}
   
   spec.require_path = "lib" 
   spec.autorequire = lib
 
   spec.has_rdoc = File::exist? "doc" 
   spec.test_suite_file = "test/#{ lib }.rb" if File::directory? "test"
+  #spec.add_dependency 'lib', '>= version'
 
   spec.extensions << "extconf.rb" if File::exists? "extconf.rb"
 
   spec.author = "Ara T. Howard"
-  spec.email = "ara.t.howard@noaa.gov"
+  spec.email = "ara.t.howard@gmail.com"
   spec.homepage = "http://codeforpeople.com/lib/ruby/#{ lib }/"
 end