dinsley-markaby 0.0.5

data/README

@@ -0,0 +1,256 @@
+= Markaby (Markup as Ruby)
+
+Markaby is a very short bit of code for writing HTML pages in pure Ruby.
+It is an alternative to ERb which weaves the two languages together.
+Also a replacement for templating languages which use primitive languages
+that blend with HTML.
+
+== Using Markaby as a Rails plugin
+
+Write Rails templates in pure Ruby.  Example layout:
+
+  html do
+    head do
+      title 'Products: ' + action_name
+      stylesheet_link_tag 'scaffold'
+    end
+  
+    body do
+      p flash[:notice], :style => "color: green"
+  
+      self << content_for_layout
+    end
+  end
+
+== Using Markaby as a Ruby class
+
+Markaby is flaming easy to call from your Ruby classes.
+
+  require 'markaby'
+
+  mab = Markaby::Builder.new
+  mab.html do
+    head { title "Boats.com" }
+    body do
+      h1 "Boats.com has great deals"
+      ul do
+        li "$49 for a canoe"
+        li "$39 for a raft"
+        li "$29 for a huge boot that floats and can fit 5 people"
+      end
+    end
+  end
+  puts mab.to_s
+
+Markaby::Builder.new does take two arguments for passing in variables and
+a helper object.  You can also affix the block right on to the class.
+
+See Markaby::Builder for all of that.
+
+= A Note About <tt>instance_eval</tt>
+
+The Markaby::Builder class is different from the normal Builder class,
+since it uses <tt>instance_eval</tt> when running blocks.  This cleans
+up the appearance of the Markaby code you write.  If <tt>instance_eval</tt>
+was not used, the code would look like this:
+
+  mab = Markaby::Builder.new
+  mab.html do
+    mab.head { mab.title "Boats.com" }
+    mab.body do
+      mab.h1 "Boats.com has great deals"
+    end
+  end
+  puts mab.to_s
+
+So, the advantage is the cleanliness of your code.  The disadvantage is that
+the block will run inside the Markaby::Builder object's scope.  This means
+that inside these blocks, <tt>self</tt> will be your Markaby::Builder object.
+When you use instance variables in these blocks, they will be instance variables
+of the Markaby::Builder object.
+
+This doesn't affect Rails users, but when used in regular Ruby code, it can
+be a bit disorienting.  You are recommended to put your Markaby code in a
+module where it won't mix with anything.
+
+= The Six Steps of Markaby
+
+If you dive right into Markaby, it'll probably make good sense, but you're
+likely to run into a few kinks.  Why not review these six steps and commit
+them memory so you can really *know* what you're doing?
+
+== 1. Element Classes
+
+Element classes may be added by hooking methods onto container elements:
+
+  div.entry do
+    h2.entryTitle 'Son of WebPage'
+    div.entrySection %{by Anthony}
+    div.entryContent 'Okay, once again, the idea here is ...'
+  end
+
+Which results in:
+
+  <div class="entry">
+    <h2 class="entryTitle">Son of WebPage</h2>
+    <div class="entrySection">by Anthony</div>
+    <div class="entryContent">Okay, once again, the idea here is ...</div>
+  </div>
+
+== 2. Element IDs
+
+IDs may be added by the use of bang methods:
+
+  div.page! {
+    div.content! {
+      h1 "A Short Short Saintly Dog"
+    }
+  }
+
+Which results in:
+
+  <div id="page">
+    <div id="content">
+      <h1>A Short Short Saintly Dog</h1>
+    </div>
+  </div>
+
+== 3. Validate Your XHTML 1.0 Output 
+
+If you'd like Markaby to help you assemble valid XHTML documents,
+you can use the <tt>xhtml_transitional</tt> or <tt>xhtml_strict</tt>
+methods in place of the normal <tt>html</tt> tag.
+
+  xhtml_strict do
+    head { ... }
+    body { ... }
+  end
+
+This will add the XML instruction and the doctype tag to your document.
+Also, a character set meta tag will be placed inside your <tt>head</tt>
+tag.
+
+Now, since Markaby knows which doctype you're using, it checks a big
+list of valid tags and attributes before printing anything.
+
+  >> div :styl => "padding: 10px" do
+  >>   img :src => "samorost.jpg"
+  >> end
+  InvalidHtmlError: no such attribute `styl'
+
+Markaby will also make sure you don't use the same element ID twice!
+
+== 4. Escape or No Escape?
+
+Markaby uses a simple convention for escaping stuff: if a string
+is an argument, it gets escaped.  If the string is in a block, it
+doesn't.
+
+This is handy if you're using something like RedCloth or
+RDoc inside an element.  Pass the string back through the block
+and it'll skip out of escaping.
+
+  div.comment { RedCloth.new(str).to_html }
+
+But, if we have some raw text that needs escaping, pass it in
+as an argument:
+
+  div.comment raw_str
+
+One caveat: if you have other tags inside a block, the string
+passed back will be ignored.
+
+  div.comment {
+    div.author "_why"
+    div.says "Torpedoooooes!"
+    "<div>Silence.</div>"
+  }
+
+The final div above won't appear in the output.  You can't mix
+tag modes like that, friend.
+
+== 5. Auto-stringification
+
+If you end up using any of your Markaby "tags" as a string, the
+tag won't be output.  It'll be up to you to add the new string
+back into the HTML output.
+
+This means if you call <tt>to_s</tt>, you'll get a string back.
+
+  div.title { "Rock Bottom" + span(" by Robert Wyatt").to_s }
+
+But, when you're adding strings in Ruby, <tt>to_s</tt> happens automatically.
+
+  div.title { "Rock Bottom" + span(" by Robert Wyatt") }
+
+Interpolation works fine.
+
+  div.title { "Rock Bottom #{span(" by Robert Wyatt")}" }
+
+And any other operation you might perform on a string.
+
+  div.menu! \
+    ['5.gets', 'bits', 'cult', 'inspect', '-h'].map do |category|
+      link_to category
+    end.
+    join( " | " )
+
+== 6. The <tt>tag!</tt> Method
+
+If you need to force a tag at any time, call <tt>tag!</tt> with the
+tag name followed by the possible arguments and block.  The CssProxy
+won't work with this technique.
+
+  tag! :select, :id => "country_list" do
+    countries.each do |country|
+      tag! :option, country
+    end
+  end
+
+= A Note About Rails Helpers
+
+When used in Rails templates, the Rails helper object is passed into 
+Markaby::Builder.  When you call helper methods inside Markaby, the output
+from those methods will be output to the stream.  This is incredibly
+handy, since most Rails helpers output HTML tags.
+
+  head do
+    javascript_include_tag 'prototype'
+    autodiscovery_link_tag
+  end
+
+However, some methods are designed to give back a String which you can use
+elsewhere.  That's okay!  Every method returns a Fragment object, which can
+be used as a string.
+
+  p { "Total is: #{number_to_human_size @file_bytes}" }
+
+Also see the Quick Tour above, specifically the stuff about auto-stringification.
+
+If for any reason you have trouble with fragments, you can just
+call the <tt>@helpers</tt> object with the method and you'll get
+the String back and nothing will be output.
+
+  p { "Total is: #{@helpers.number_to_human_size @file_bytes}" }
+
+Conversely, you may call instance variables from your controller by using
+a method and its value will be returned, nothing will be output.
+
+  # Inside imaginary ProductController
+  def list
+    @products = Product.find :all
+  end
+
+  # Inside app/views/product/list.mab
+  products.each do |product|
+    p product.title
+  end
+
+= Credits
+
+Markaby is a work of immense hope by Tim Fletcher and why the lucky stiff.
+Thankyou for giving it a whirl.
+
+Markaby is inspired by the HTML library within cgi.rb.  Hopefully it will
+turn around and take some cues.
+

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rcov/rcovtask'
+
+begin
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |s|
+    s.name = "markaby"
+    s.summary = "Markaby is a very short bit of code for writing HTML pages in pure Ruby."
+    s.email = "dinsley@gmail.com  "
+    s.homepage = "http://github.com/dinsley/markaby"
+    s.description = "Markaby is a very short bit of code for writing HTML pages in pure Ruby."
+    s.authors = ["Tim Fletcher", "why_", "Daniel Insley"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+task :test do
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = ['test/markaby_test.rb']
+    t.verbose = false
+  end
+
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = ['test/markaby_controller_test.rb']
+    t.verbose = false
+  end
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'Jeweler'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Rcov::RcovTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['markaby_test.rb', 'test/markaby_controller_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 0
+:patch: 5
+:major: 0

data/lib/markaby/builder.rb

@@ -0,0 +1,289 @@
+require 'markaby/tags'
+
+module Markaby
+  # The Markaby::Builder class is the central gear in the system. When using
+  # from Ruby code, this is the only class you need to instantiate directly.
+  #
+  # mab = Markaby::Builder.new
+  # mab.html do
+  # head { title "Boats.com" }
+  # body do
+  # h1 "Boats.com has great deals"
+  # ul do
+  # li "$49 for a canoe"
+  # li "$39 for a raft"
+  # li "$29 for a huge boot that floats and can fit 5 people"
+  # end
+  # end
+  # end
+  # puts mab.to_s
+  #
+  class Builder
+
+    @@default = {
+      :indent => 0,
+      :output_helpers => true,
+      :output_xml_instruction => true,
+      :output_meta_tag => true,
+      :auto_validation => true,
+      :tagset => Markaby::XHTMLTransitional,
+      :root_attributes => {
+        :xmlns => 'http://www.w3.org/1999/xhtml', :'xml:lang' => 'en', :lang => 'en'
+      }
+    }
+
+    def self.set(option, value)
+      @@default[option] = value
+    end
+
+    def self.ignored_helpers
+      @@ignored_helpers ||= []
+    end
+
+    def self.ignore_helpers(*helpers)
+      ignored_helpers.concat helpers
+    end
+
+    attr_accessor :output_helpers, :tagset
+
+    # Create a Markaby builder object. Pass in a hash of variable assignments to
+    # +assigns+ which will be available as instance variables inside tag construction
+    # blocks. If an object is passed in to +helpers+, its methods will be available
+    # from those same blocks.
+    #
+    # Pass in a +block+ to new and the block will be evaluated.
+    #
+    # mab = Markaby::Builder.new {
+    # html do
+    # body do
+    # h1 "Matching Mole"
+    # end
+    # end
+    # }
+    #
+    def initialize(assigns = {}, helpers = nil, &block)
+      @streams = [[]]
+      @assigns = assigns.dup
+      @helpers = helpers
+      @elements = {}
+
+      @@default.each do |k, v|
+        instance_variable_set("@#{k}", @assigns.delete(k) || v)
+      end
+
+      @assigns.each do |k, v|
+        instance_variable_set("@#{k}", v)
+      end
+
+      @builder = XmlMarkup.new(:indent => @indent, :target => @streams.last)
+
+      text(capture(&block)) if block
+    end
+
+    # Returns a string containing the HTML stream. Internally, the stream is stored as an Array.
+    def to_s
+      @streams.last.to_s
+    end
+
+    # Write a +string+ to the HTML stream without escaping it.
+    def text(string)
+      @builder << string.to_s
+      nil
+    end
+    alias_method :<<, :text
+    alias_method :concat, :text
+
+    # Captures the HTML code built inside the +block+. This is done by creating a new
+    # stream for the builder object, running the block and passing back its stream as a string.
+    #
+    # >> Markaby::Builder.new.capture { h1 "TEST"; h2 "CAPTURE ME" }
+    # => "<h1>TITLE</h1>\n<h2>CAPTURE ME</h2>\n"
+    #
+    def capture(&block)
+      @streams.push(@builder.target = [])
+      @builder.level += 1
+      str = instance_eval(&block)
+      str = @streams.last.join if @streams.last.any?
+      @streams.pop
+      @builder.level -= 1
+      @builder.target = @streams.last
+      str
+    end
+
+    # Create a tag named +tag+. Other than the first argument which is the tag name,
+    # the arguments are the same as the tags implemented via method_missing.
+    def tag!(tag, *args, &block)
+      ele_id = nil
+      if @auto_validation and @tagset
+          if !@tagset.tagset.has_key?(tag)
+              raise InvalidXhtmlError, "no element `#{tag}' for #{tagset.doctype}"
+          elsif args.last.respond_to?(:to_hash)
+              attrs = args.last.to_hash
+
+              if @tagset.forms.include?(tag) and attrs[:id]
+                attrs[:name] ||= attrs[:id]
+              end
+
+              attrs.each do |k, v|
+                  atname = k.to_s.downcase.intern
+                  unless k =~ /:/ or @tagset.tagset[tag].include? atname
+                      raise InvalidXhtmlError, "no attribute `#{k}' on #{tag} elements"
+                  end
+                  if atname == :id
+                      ele_id = v.to_s
+                      if @elements.has_key? ele_id
+                          raise InvalidXhtmlError, "id `#{ele_id}' already used (id's must be unique)."
+                      end
+                  end
+              end
+          end
+      end
+      if block
+        str = capture(&block)
+        block = proc { text(str) }
+      end
+
+      f = fragment { @builder.method_missing(tag, *args, &block) }
+      @elements[ele_id] = f if ele_id
+      f
+    end
+
+    # This method is used to intercept calls to helper methods and instance
+    # variables. Here is the order of interception:
+    #
+    # * If +sym+ is a helper method, the helper method is called
+    # and output to the stream.
+    # * If +sym+ is a Builder::XmlMarkup method, it is passed on to the builder object.
+    # * If +sym+ is also the name of an instance variable, the
+    # value of the instance variable is returned.
+    # * If +sym+ has come this far and no +tagset+ is found, +sym+ and its arguments are passed to tag!
+    # * If a tagset is found, though, +NoMethodError+ is raised.
+    #
+    # method_missing used to be the lynchpin in Markaby, but it's no longer used to handle
+    # HTML tags. See html_tag for that.
+    def method_missing(sym, *args, &block)
+      if @helpers.respond_to?(sym, true) && !self.class.ignored_helpers.include?(sym)
+        r = @helpers.send(sym, *args, &block)
+        if @output_helpers and r.respond_to? :to_str
+          fragment { @builder << r }
+        else
+          r
+        end
+      elsif @assigns.has_key?(sym)
+        @assigns[sym]
+      elsif @assigns.has_key?(stringy_key = sym.to_s)
+        # Rails' ActionView assigns hash has string keys for
+        # instance variables that are defined in the controller.
+        @assigns[stringy_key]
+      elsif instance_variables.include?(ivar = "@#{sym}")
+        instance_variable_get(ivar)
+      elsif !@helpers.nil? && @helpers.instance_variables.include?(ivar)
+        @helpers.instance_variable_get(ivar)
+      elsif ::Builder::XmlMarkup.instance_methods.include?(sym.to_s)
+        @builder.__send__(sym, *args, &block)
+      elsif @tagset.nil?
+        tag!(sym, *args, &block)
+      else
+        raise NoMethodError, "no such method `#{sym}'"
+      end
+    end
+
+    # Every HTML tag method goes through an html_tag call. So, calling <tt>div</tt> is equivalent
+    # to calling <tt>html_tag(:div)</tt>. All HTML tags in Markaby's list are given generated wrappers
+    # for this method.
+    #
+    # If the @auto_validation setting is on, this method will check for many common mistakes which
+    # could lead to invalid XHTML.
+    def html_tag(sym, *args, &block)
+      if @auto_validation and @tagset.self_closing.include?(sym) and block
+        raise InvalidXhtmlError, "the `#{sym}' element is self-closing, please remove the block"
+      elsif args.empty? and block.nil?
+        CssProxy.new(self, @streams.last, sym)
+      else
+        tag!(sym, *args, &block)
+      end
+    end
+
+    XHTMLTransitional.tags.each do |k|
+      class_eval %{
+def #{k}(*args, &block)
+html_tag(#{k.inspect}, *args, &block)
+end
+}
+    end
+
+    remove_method :head
+
+    # Builds a head tag. Adds a <tt>meta</tt> tag inside with Content-Type
+    # set to <tt>text/html; charset=utf-8</tt>.
+    def head(*args, &block)
+      tag!(:head, *args) do
+        tag!(:meta, "http-equiv" => "Content-Type", "content" => "text/html; charset=utf-8") if @output_meta_tag
+        instance_eval(&block)
+      end
+    end
+
+    # Builds an html tag. An XML 1.0 instruction and an XHTML 1.0 Transitional doctype
+    # are prepended. Also assumes <tt>:xmlns => "http://www.w3.org/1999/xhtml",
+    # :lang => "en"</tt>.
+    def xhtml_transitional(attrs = {}, &block)
+      self.tagset = Markaby::XHTMLTransitional
+      xhtml_html(attrs, &block)
+    end
+
+    # Builds an html tag with XHTML 1.0 Strict doctype instead.
+    def xhtml_strict(attrs = {}, &block)
+      self.tagset = Markaby::XHTMLStrict
+      xhtml_html(attrs, &block)
+    end
+
+    # Builds an html tag with XHTML 1.0 Frameset doctype instead.
+    def xhtml_frameset(attrs = {}, &block)
+      self.tagset = Markaby::XHTMLFrameset
+      xhtml_html(attrs, &block)
+    end
+
+    private
+
+    def xhtml_html(attrs = {}, &block)
+      instruct! if @output_xml_instruction
+      declare!(:DOCTYPE, :html, :PUBLIC, *tagset.doctype)
+      tag!(:html, @root_attributes.merge(attrs), &block)
+    end
+
+    def fragment
+      stream = @streams.last
+      start = stream.length
+      yield
+      length = stream.length - start
+      Fragment.new(stream, start, length)
+    end
+
+  end
+
+  # Every tag method in Markaby returns a Fragment. If any method gets called on the Fragment,
+  # the tag is removed from the Markaby stream and given back as a string. Usually the fragment
+  # is never used, though, and the stream stays intact.
+  #
+  # For a more practical explanation, check out the README.
+  class Fragment < ::Builder::BlankSlate
+    def initialize(*args)
+      @stream, @start, @length = args
+    end
+    def method_missing(*args, &block)
+      # We can't do @stream.slice!(@start, @length),
+      # as it would invalidate the @starts and @lengths of other Fragment instances.
+      @str = @stream[@start, @length].to_s
+      @stream[@start, @length] = [nil] * @length
+      def self.method_missing(*args, &block)
+        @str.send(*args, &block)
+      end
+      @str.send(*args, &block)
+    end
+  end
+
+  class XmlMarkup < ::Builder::XmlMarkup
+    attr_accessor :target, :level
+  end
+
+end