erector 0.8.3 → 0.9.0.pre1

data/lib/erector/rails2/extensions/rails_widget.rb

@@ -45,7 +45,7 @@ module Erector
 
       output_buffer = view.with_output_buffer do
         # Set parent to the view and use Rails's output buffer.
-        new_output = Output.new { view.output_buffer }
+        new_output = Output.new :buffer => lambda { view.output_buffer }
         widget.to_html(options.merge(:parent => view,
                                   :output => new_output))
       end

data/lib/erector/rails3.rb

@@ -39,7 +39,7 @@ module Erector
           # Set parent and helpers to the view and use Rails's output buffer.
           widget.to_html(options.merge(:helpers => view,
                                        :parent  => view,
-                                       :output  => Output.new { view.output_buffer }))
+                                       :output  => Output.new(:buffer => lambda { view.output_buffer })))
         end
       end
 

data/lib/erector/sass.rb

@@ -1,22 +1,17 @@
-
-if Object.const_defined?(:Sass)
-  module Erector
-    # Adds sass support to Erector widgets. 
-    # Note that sass is provided inside the gem named "haml", 
-    # not the gem named "sass".
-    # To get sass support into your Erector project, install the 
-    # haml gem -- see http://sass-lang.com/download.html -- and
-    # then do something like this:
-    #     require 'rubygems'
-    #     require 'sass'
-    #
-    # Current support is barebones. Please offer suggestions (or better
-    # yet, patches) for whether and how to support, e.g., caching, 
-    # loading from files, precompilation, etc.
-    module Sass
-      def sass(sass_text)
-        style ::Sass::Engine.new(sass_text, :cache => false).render
-      end
+module Erector
+  # Adds sass support to Erector widgets.
+  #
+  # Sass is an *optional dependency* of the Erector gem, so
+  # a call to +sass+ inside a widget will fail unless you have already
+  # installed the sass gem (e.g. "gem 'sass'" in your code or Gemfile).
+  #
+  # Current support is barebones. Please offer suggestions (or better
+  # yet, patches) for whether and how to support, e.g., caching,
+  # loading from files, precompilation, etc.
+  module Sass
+    def sass(sass_text)
+      require "sass"
+      style ::Sass::Engine.new(sass_text, :cache => false).render
     end
   end
 end

data/lib/erector/tag.rb

@@ -0,0 +1,65 @@
+module Erector
+
+  # Defines a type of tag (not an actual element with attributes and contents)
+  class Tag
+
+    # Pass the self_closing and inline params as symbols, e.g.
+    #
+    # Tag.new("i", :inline)
+    # Tag.new("input", :inline, :self_closing)
+    #
+    # @param name the name of the tag, e.g. "div"
+    # @param self_closing whether it can (false) or cannot (true) contain text or other elements. Default: false
+    # @param inline whether it should appear in line with other elements (true) or on a line by itself (false) in pretty mode. Default: false
+    # @param snake whether to covert the method name into "snake case" (aka underscorized). Default: false
+    #
+    def initialize(name, *params)
+      @name = name.to_s
+      @method_name = if params.first.is_a? String
+        params.shift
+      else
+        @name
+      end
+      @self_closing = params.include?(:self_closing)
+      @inline = params.include?(:inline)
+      @method_name = snake_case(@method_name) if params.include?(:snake_case)
+    end
+
+    attr_reader :name, :method_name
+
+    def self_closing?
+      @self_closing
+    end
+
+    def newliney?
+      !@inline
+    end
+
+    def inline?
+      @inline
+    end
+
+    ##
+    # Convert to snake case.
+    #
+    #   "FooBar".snake_case           #=> "foo_bar"
+    #   "HeadlineCNNNews".snake_case  #=> "headline_cnn_news"
+    #   "CNN".snake_case              #=> "cnn"
+    #
+    # @return [String] Receiver converted to snake case.
+    #
+    # @api public
+    # borrowed from https://github.com/datamapper/extlib/blob/master/lib/extlib/string.rb
+    def snake_case(s)
+      if s.match(/\A[A-Z]+\z/)
+        s.downcase
+      else
+        s.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+         gsub(/([a-z])([A-Z])/, '\1_\2').
+         downcase
+      end
+    end
+
+  end
+
+end

data/lib/erector/text.rb

@@ -0,0 +1,123 @@
+require "erector/raw_string"
+
+module Erector
+  module Text
+    # Emits text to the output buffer, e.g.
+    #
+    #   text "my dog smells awful"
+    #   => "my dog smells awful"
+    #
+    # If a string is passed in, it will be HTML-escaped. If the
+    # result of calling methods such as raw is passed in, the HTML will not be
+    # HTML-escaped again. If another kind of object is passed in, the result
+    # of calling its to_s method will be treated as a string would be.
+    #
+    # You shouldn't pass a widget in to this method, as that will cause
+    # performance problems (as well as being semantically goofy). Use the
+    # #widget method instead.
+    #
+    # You may pass a series of values (i.e. varargs). In that case, each value
+    # will be emitted to the output stream in turn. You can specify a delimiter
+    # by using an options hash with as the final argument, using +:join+ as the key,
+    # e.g.
+    # 
+    #   text "my", "dog", "smells", :join => " "
+    #   => "my dog smells"
+    #
+    # You may also pass a Promise as a parameter; every tag
+    # method now returns a Promise after emitting. This allows
+    # you to easily embed simple HTML formatting into a sentence, e.g.
+    #
+    #   text "my", "dog", "smells", b("great!"), :join => " "
+    #   => "my dog smells <b>great!</b>"
+    #
+    # (Yes, the initial call to +b+ emits "\&lt;b>great\&lt;/b>" to the output buffer;
+    # the Promise feature takes care of rewinding and rewriting the output
+    # buffer during the later call to +text+.)
+    #
+    def text(*values)
+      options = if values.last.is_a? Hash
+        values.pop
+      else
+        {}
+      end
+      delimiter = options[:join]
+
+      values.select{|value| value.is_a? Promise}.each do |promise|
+        # erase whatever the promises wrote already
+        promise._rewind
+      end
+
+      first = true
+      values.each do |value|
+        if !first and delimiter
+          output << h(delimiter)
+        end
+        first = false
+
+        case value
+        when AbstractWidget
+          # todo: better deprecation
+          raise "Don't pass a widget to the text method. Use the widget method instead."
+        when Promise
+          value._mark # so the promise's rewind won't erase anything
+          value._render # render the promise to the output stream again
+          # note: we could let the promise cache its first effort, but
+          # here I think it's better to optimize for memory over speed
+        else
+          output << h(value)
+        end
+      end
+      nil
+    end
+
+    # Returns text which will *not* be HTML-escaped.
+    def raw(value)
+      RawString.new(value.to_s)
+    end
+
+    # Emits text which will *not* be HTML-escaped. Same effect as text(raw(s))
+    def text!(value)
+      text raw(value)
+    end
+
+    alias rawtext text!
+
+    # Returns a copy of value with spaces replaced by non-breaking space characters.
+    # With no arguments, return a single non-breaking space.
+    # The output uses the escaping format '&#160;' since that works
+    # in both HTML and XML (as opposed to '&nbsp;' which only works in HTML).
+    def nbsp(value = " ")
+      raw(h(value).gsub(/ /,'&#160;'))
+    end
+
+    # Returns an HTML-escaped version of its parameter. Leaves the output
+    # string untouched. This method is idempotent: h(h(text)) will not
+    # double-escape text. This means that it is safe to do something like
+    # text(h("2<4")) -- it will produce "2&lt;4", not "2&amp;lt;4".
+    def h(content)
+      if content.respond_to?(:html_safe?) && content.html_safe?
+        content
+      else
+        raw(CGI.escapeHTML(content.to_s))
+      end
+    end
+
+    # Return a character given its unicode code point or unicode name.
+    def character(code_point_or_name)
+      if code_point_or_name.is_a?(Symbol)
+        require "erector/unicode"
+        found = Erector::CHARACTERS[code_point_or_name]
+        if found.nil?
+          raise "Unrecognized character #{code_point_or_name}"
+        end
+        raw("&#x#{sprintf '%x', found};")
+      elsif code_point_or_name.is_a?(Integer)
+        raw("&#x#{sprintf '%x', code_point_or_name};")
+      else
+        raise "Unrecognized argument to character: #{code_point_or_name}"
+      end
+    end
+
+  end
+end

data/lib/erector/version.rb

@@ -6,7 +6,7 @@ module Erector
   if !Erector.const_defined?(:VERSION)
     dir = File.dirname(__FILE__)
     version = YAML.load_file(File.expand_path("#{dir}/../../VERSION.yml"))
-    VERSION = "#{version[:major]}.#{version[:minor]}.#{version[:patch]}"
+    VERSION = [version[:major], version[:minor], version[:patch], version[:build]].compact.join('.')
   end
 end
 

data/lib/erector/widget.rb

@@ -1,5 +1,13 @@
+require "erector/element"
+require "erector/attributes"
+require "erector/promise"
+require "erector/text"
+require "erector/tag"
+require "erector/html_widget"
+require "erector/needs"
+
 module Erector
-  
+
   # A Widget is the center of the Erector universe.
   #
   # To create a widget, extend Erector::Widget and implement the +content+
@@ -36,19 +44,51 @@ module Erector
   #
   # This class extends AbstractWidget and includes several modules,
   # so be sure to check all of those places for API documentation for the
-  # various methods of Widget. Also read the API Cheatsheet in the user guide
-  # at http://erector.rubyforge.org/userguide#apicheatsheet
+  # various methods of Widget:
+  #
+  # * AbstractWidget
+  # * Element
+  # * Attributes
+  # * Text
+  # * Needs
+  # * Caching
+  # * Externals
+  # * AfterInitialize
   #
-  # Now, seriously, after playing around a bit, go read the user guide. It's
-  # fun!  
-  class Widget < AbstractWidget
-    include Erector::HTML
-    include Erector::Needs
-    include Erector::Caching
-    include Erector::Externals
-    include Erector::Convenience
+  # * HTML
+  # * Convenience
+  # * JQuery
+  # * Sass
+  #
+  # Also read the API Cheatsheet in the user guide
+  # at http://erector.rubyforge.org/userguide#apicheatsheet
+  class Widget < HTMLWidget
+
+    # for some reason these need to be included in Widget and not AbstractWidget
+    include Needs
+    include Caching
+    include Externals
+
+    include HTML
+    include Convenience
     include Erector::JQuery
-    include Erector::AfterInitialize
     include Erector::Sass if Object.const_defined?(:Sass)
+
+    # alias for AbstractWidget#render
+    def to_html(options = {})
+      raise "Erector::Widget#to_html takes an options hash, not a symbol. Try calling \"to_html(:content_method_name=> :#{options})\"" if options.is_a? Symbol
+      _render(options).to_s
+    end
+
+    # alias for #to_html
+    # @deprecated Please use {#to_html} instead
+    def to_s(*args)
+      unless defined? @@already_warned_to_s
+        $stderr.puts "Erector::Widget#to_s is deprecated. Please use #to_html instead. Called from #{caller.first}"
+        @@already_warned_to_s = true
+      end
+      to_html(*args)
+    end
+
   end
 end

data/lib/erector/widgets/page.rb

@@ -7,14 +7,15 @@
 # declare it.
 #
 # The script and style declarations are accumulated at class load time, as
-# 'dependencies'. This technique allows all widgets to add their own requirements
-# to the page header without extra logic for declaring which pages include
-# which nested widgets. Fortunately, Page is now smart enough to figure out
-# which widgets were actually rendered during the body_content run, so it only
-# emits into its HEAD the dependencies that are relevant. If it misses some, or
-# if you want to add some extra dependencies -- for instance, styles that apply
-# to widgets that are rendered later via AJAX -- then return an array of those
-# widget classes in your subclass by overriding the #extra_widgets method.
+# 'dependencies'. This technique allows all widgets to add their own
+# requirements to the page header without extra logic for declaring which
+# pages include which nested widgets. Fortunately, Page is now smart enough to
+# figure out which widgets were actually rendered during the body_content run,
+# so it only emits into its HEAD the dependencies that are relevant. If it
+# misses some, or if you want to add some extra dependencies -- for instance,
+# styles that apply to widgets that are rendered later via AJAX -- then return
+# an array of those widget classes in your subclass by overriding the
+# #extra_widgets method.
 #
 # If you want something to show up in the headers for just one page type
 # (subclass), then override #head_content, call super, and then emit it
@@ -93,8 +94,9 @@
 #   end
 #
 # = Thoughts:
-#  * It may be desirable to unify #js and #script, and #css and #style, and have the routine be
-#    smart enough to analyze its parameter to decide whether to make it a file or a script.
+#  * It may be desirable to unify #js and #script, and #css and #style, and
+#    have the routine be smart enough to analyze its parameter to decide
+#    whether to make it a file or a script.
 #
 class Erector::Widgets::Page < Erector::InlineWidget
 

data/lib/erector/xml_widget.rb

@@ -0,0 +1,131 @@
+require 'erector/abstract_widget'
+require 'erector/tag'
+require 'erector/needs'
+
+module Erector
+
+  # Abstract base class for XML Widgets and HTMLWidget.
+  # Declares "tags" which define methods that emit tags.
+  class XMLWidget < AbstractWidget
+    include Needs
+
+    def self.tag_named tag_name, checked = []
+      @tags ||= {}
+      @tags[tag_name] || begin
+        tag = nil
+        checked << self
+        taggy_ancestors = (ancestors - checked).select{|k| k.respond_to? :tag_named}
+        taggy_ancestors.each do |k|
+          tag = k.tag_named(tag_name, checked)
+          if tag
+            @tags[tag_name] = tag
+            break
+          end
+        end
+        tag
+      end
+    end
+
+    def self.tag *args
+      tag = Tag.new(*args)
+      @tags ||= {}
+      @tags[tag.name] = tag
+
+      if instance_methods.include?(tag.method_name.to_sym)
+        warn "method '#{tag.method_name}' is already defined; skipping #{caller[1]}"
+        return
+      end
+
+      if tag.self_closing?
+        self.class_eval(<<-SRC, __FILE__, __LINE__ + 1)
+          def #{tag.method_name}(*args, &block)
+            _empty_element('#{tag.name}', *args, &block)
+          end
+        SRC
+      else
+        self.class_eval(<<-SRC, __FILE__, __LINE__ + 1)
+        def #{tag.method_name}(*args, &block)
+              _element('#{tag.name}', *args, &block)
+          end
+
+          def #{tag.method_name}!(*args, &block)
+            _element('#{tag.name}', *(args.map{|a|raw(a)}), &block)
+          end
+        SRC
+      end
+    end
+
+    # Tags which are always self-closing
+    def self.self_closing_tags
+      @tags.values.select{|tag| tag.self_closing?}.map{|tag| tag.name}
+    end
+
+    # Tags which can contain other stuff
+    def self.full_tags
+      @tags.values.select{|tag| !tag.self_closing?}.map{|tag| tag.name}
+    end
+
+    def newliney?(tag_name)
+      tag = self.class.tag_named tag_name
+      if tag
+        tag.newliney?
+      else
+        true
+      end
+    end
+
+    # Emits an XML instruction, which looks like this: <?xml version=\"1.0\" encoding=\"UTF-8\" ?>
+    def instruct(attributes={:version => "1.0", :encoding => "UTF-8"})
+      output << raw("<?xml#{format_sorted(sort_for_xml_declaration(attributes))} ?>")
+    end
+
+    # Emits an XML/HTML comment (&lt;!-- ... --&gt;) surrounding +text+ and/or
+    # the output of +block+. see
+    # http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.2.4
+    #
+    # If +text+ is an Internet Explorer conditional comment condition such as
+    # "[if IE]", the output includes the opening condition and closing
+    # "[endif]". See http://www.quirksmode.org/css/condcom.html
+    #
+    # Since "Authors should avoid putting two or more adjacent hyphens inside
+    # comments," we emit a warning if you do that.
+    def comment(text = '')
+      puts "Warning: Authors should avoid putting two or more adjacent hyphens inside comments." if text =~ /--/
+
+      conditional = text =~ /\[if .*\]/
+
+      rawtext "<!--"
+      rawtext text
+      rawtext ">" if conditional
+
+      if block_given?
+        rawtext "\n"
+        yield
+        rawtext "\n"
+      end
+
+      rawtext "<![endif]" if conditional
+      rawtext "-->\n"
+    end
+
+    alias_method :to_xml, :render
+
+    protected
+
+    def sort_for_xml_declaration(attributes)
+      # correct order is "version, encoding, standalone" (XML 1.0 section 2.8).
+      # But we only try to put version before encoding for now.
+      stringized = []
+      attributes.each do |key, value|
+        stringized << [key.to_s, value]
+      end
+      stringized.sort{|a, b| b <=> a}
+    end
+
+  end
+
+  public
+
+  XmlWidget = XMLWidget
+
+end