rxhp 0.1.1 → 0.1.2

data/lib/rxhp/attribute_validator.rb

@@ -1,7 +1,25 @@
 require 'rxhp/error'
 
 module Rxhp
+  # Provide support for limiting or requiring attributes.
+  #
+  # Attributes can be:
+  # * whitelisted (see {ClassMethods#accept_attributes})
+  # * required (see {ClassMethods#require_attributes})
+  #
+  # Requiring an attribute automaticaly whitelists it.
+  #
+  # To use:
+  # * +include+ this module
+  # * whitelist/require attributes as appropriate
+  # * call {#validate_attributes!} from wherever seems appropriate - such
+  #   {Rxhp::Element#validate!}
+  #
+  # Subclasses will automatically have validated attributes, and will
+  # copy the rules from their parent class. Additional attributes can be
+  # accepted or required in subclasses without affecting the parent class.
   module AttributeValidator
+    # Indicates that a provided attribute was not whitelisted.
     class UnacceptableAttributeError < ValidationError
       attr_reader :element, :attribute, :value
       def initialize element, attribute, value
@@ -10,6 +28,7 @@ module Rxhp
       end
     end
 
+    # Indicates that a required attribute was not provided.
     class MissingRequiredAttributeError < ValidationError
       attr_reader :element, :attribute
       def initialize element, attribute
@@ -18,6 +37,13 @@ module Rxhp
       end
     end
 
+    # Whether or not the attributes are acceptable.
+    #
+    # If you need more details than just "it's invalid", call
+    # {#validate_attributes!} instead and examine the exceptions it raises.
+    #
+    # @return whether or not the attributes are all whitelisted, and all
+    #   required attributes are provided.
     def valid_attributes?
       begin
         self.validate_attributes!
@@ -27,6 +53,14 @@ module Rxhp
       end
     end
 
+    # Check if attributes are valid, and raise an exception if they're not.
+    #
+    # @raise {MissingRequiredAttributeError} if an attribute that is
+    #   required was not provided.
+    # @raise {UnacceptableAttributeError} if a non-whitelisted attribute
+    #   was provided.
+    # @return [true] if the attribute are all valid, and all required
+    #   attributes are provided.
     def validate_attributes!
       # Check for required attributes
       self.class.required_attributes.each do |matcher|
@@ -72,6 +106,56 @@ module Rxhp
       end
     end
 
+    module ClassMethods
+      attr_accessor :acceptable_attributes, :required_attributes
+      # Accept all attributes matching the specified pattern.
+      #
+      # @param pattern can be a:
+      #   +Symbol+:: must equal the attribute name after converting to a
+      #              +String+, and replacing underscores with hyphens.
+      #   +Object+:: must match the attribute name with +===+.
+      #   +Array+:: the members must be a any of the above that matches the
+      #             attribute name.
+      #   +Hash+:: the key can be any of the above that matches the
+      #            attribute name; the value is matched against the
+      #            attribute value in the same way.
+      # @example
+      #   accept_attribute 'id'
+      #   accept_attribute /^data-/
+      #   accept_attributes ['href', 'src']
+      #   accept_attributes ({ 'type' => ['checkbox', 'text', 'submit'] })
+      def accept_attributes pattern
+        acceptable_attributes.push pattern
+      end
+      alias :accept_attribute :accept_attributes
+
+      # Require an attribute matching the specified pattern.
+      #
+      # @param pattern accepts the same values as {#accept_attributes}
+      def require_attributes pattern
+        accept_attributes pattern
+        required_attributes.push pattern
+      end
+      alias :require_attribute :require_attributes
+
+      # Accept any attributes whatsoever.
+      def accept_all_attributes
+        accept_attributes Object
+      end
+
+      private
+
+      def inherited(subklass) # @Private @api
+        Rxhp::AttributeValidator.inherited(subklass)
+      end
+    end
+
+    private
+
+    def self.name_from_symbol symbol
+      symbol.to_s.gsub('_', '-')
+    end
+
     def self.match_value? matcher, value
       if matcher == String
         return (value.is_a? String) || (value.is_a? Symbol)
@@ -91,34 +175,18 @@ module Rxhp
       end
     end
 
-    def self.name_from_symbol symbol
-      symbol.to_s.gsub('_', '-')
-    end
-
+    # Include class methods, and initialize class variables.
     def self.included(klass)
       klass.extend(ClassMethods)
-      class << klass
-        attr_accessor :acceptable_attributes, :required_attributes
-        def accept_attributes matcher
-          acceptable_attributes.push matcher
-        end
-        alias :accept_attribute :accept_attributes
-
-        def require_attributes matcher
-          accept_attributes matcher
-          required_attributes.push matcher
-        end
-        alias :require_attribute :require_attributes
-
-        def accept_all_attributes
-          accept_attributes Object
-        end
-      end
 
       klass.acceptable_attributes = []
       klass.required_attributes = []
     end
 
+    # Make subclasses validated too.
+    #
+    # Their accept/require lists will be copied from their superclass, but
+    # can be modified separately.
     def self.inherited(subklass)
       subklass.class_eval do
         include Rxhp::AttributeValidator
@@ -126,12 +194,5 @@ module Rxhp
       subklass.acceptable_attributes = subklass.superclass.acceptable_attributes.dup
       subklass.required_attributes = subklass.superclass.required_attributes.dup
     end
-
-    module ClassMethods
-      def inherited(subklass)
-        Rxhp::AttributeValidator.inherited(subklass)
-      end
-
-    end
   end
 end

data/lib/rxhp/composable_element.rb

@@ -12,6 +12,8 @@ module Rxhp
   class ComposableElement < Rxhp::Element
     include Rxhp::AttributeValidator
 
+    # Check that there are no detectable problems, such as invalid
+    # attributes.
     def validate!
       super
       validate_attributes!
@@ -33,6 +35,8 @@ module Rxhp
     end
 
     # Implement this method - return an Rxhp::Element subclass.
+    #
+    # @yieldreturn child elements
     def compose
       raise NotImplementedError.new
     end

data/lib/rxhp/constants.rb

@@ -1,10 +1,17 @@
 module Rxhp
-  # Basic output formats
+  # Render 'nice' HTML
+  # @example
+  #   <div><p>foo<br>bar</p></div>
   HTML_FORMAT = :html
+  # Render ugly, but valid HTML
+  # @example
+  #  <div><p>foo<br>bar</div>
   TINY_HTML_FORMAT = :tiny_html
+  # Render XHTML
+  # @example
+  #  <div><p>foo<br />bar</p></div>
   XHTML_FORMAT = :xhtml
 
-  # Doctypes
   HTML_5 = "<!DOCTYPE html>\n"
   HTML_4_01_TRANSITIONAL = <<EOF
 <!DOCTYPE HTML PUBLIC

data/lib/rxhp/data/html/attributes.rb

@@ -2,10 +2,10 @@ require 'uri'
 
 module Rxhp
   module Html
-    # Given ['foo', 'bar', 'baz'], match:
-    # - 'foo'
-    # - 'bar baz'
-    # - 'foo bar baz'
+    # Given +['foo', 'bar', 'baz']+, match:
+    # * +'foo'+
+    # * +'bar baz'+
+    # * +'foo bar baz'+
     # etc.
     def self.token_list tokens
       token = tokens.join('|')

data/lib/rxhp/element.rb

@@ -9,18 +9,31 @@ module Rxhp
   # error at render-time :p
   class Element
     include ::Rxhp::Scope
-    attr_accessor :attributes, :children
+    # A name => value map of attributes.
+    attr_accessor :attributes
+    # A list of child elements of this one.
+    attr_accessor :children
 
+    # Construct a new element with no children.
     def initialize attributes = {}
       @attributes = attributes
       @children = Array.new
       validate!
     end
 
+    # Whether or not this element has any child element.
     def children?
       !children.empty?
     end
 
+    # Whether there are any detectable problems with this element.
+    #
+    # See {AttributeValidator} for an example.
+    #
+    # You probably don't want to override this function in your subclasses;
+    # instead, you probably want to change {#validate!} to recognize your
+    # validations - all this does is check that it {#validate!} executes
+    # without raising a {ValidationError}.
     def valid?
       begin
         validate!
@@ -30,6 +43,9 @@ module Rxhp
       end
     end
 
+    # Check that this element is valid.
+    #
+    # @raise Rxhp::ValidationError if a problem is found.
     def validate!
       # no-op
     end
@@ -37,15 +53,23 @@ module Rxhp
     # Return a flat HTML string for this element and all its' decendants.
     #
     # You probably don't want to implement this yourself - interesting
-    # implementations are in Rxhp::Fragment, Rxhp::HtmlElement, and
-    # Rxhp::ComposableElement
+    # implementations are in {Fragment}, {HtmlElement}, and
+    # {ComposableElement}.
+    #
+    # Valid options include:
+    # +:pretty+:: add whitespace to make the output more readable. Defaults
+    #             to true.
+    # +:indent+:: how many spaces to use to indent when +:pretty+ is true.
+    # +:format+:: See {Rxhp} for values. Default is {Rxhp::HTML_FORMAT}
+    # +:skip_doctype+:: Self explanatory. Defaults to false.
+    # +:doctype+:: See {Rxhp} for values. Default is {Rxhp::HTML_5}
     def render options = {}
       raise NotImplementedError.new
     end
 
     # Called when something that isn't an element is found in the tree.
     #
-    # Implemented in Rxhp::HtmlElement.
+    # Implemented in {HtmlElement}.
     def render_string string, options
       raise NotImplementedError.new
     end
@@ -58,7 +82,11 @@ module Rxhp
       flattened_children.map{ |child| render_child(child, options) }.join
     end
 
-    # Fill default options
+    # Fill default render options.
+    #
+    # These are as defined for {#render}, with the addition of a
+    # +:depth+ value of 0. Other values aren't guaranteed to stay fixed,
+    # check source for current values.
     def fill_options options
       {
         :pretty => true,
@@ -85,6 +113,12 @@ module Rxhp
       end
     end
 
+    # Normalize the children.
+    #
+    # For example, turn +['foo', 'bar']+ into +['foobar']+.
+    #
+    # This is needed to stop things like pretty printing adding extra
+    # whitespace between the two strings.
     def flattened_children
       no_frags = []
       children.each do |node|

data/lib/rxhp/error.rb

@@ -1,10 +1,16 @@
 module Rxhp
+  # Base class for runtime errors from Rxhp.
+  #
+  # Most exceptions in Rxhp are actually subclasses of {Rxhp::ScriptError},
+  # which is not a subclass of this.
   class Error < ::StandardError
   end
 
+  # Base class for script errors from Rxhp.
   class ScriptError < ::ScriptError
   end
 
+  # Base class for element correctness errors from Rxhp.
   class ValidationError < Rxhp::ScriptError
   end
 end

data/lib/rxhp/fragment.rb

@@ -6,6 +6,7 @@ module Rxhp
   # Can be used like an array, or if you just need something that acts like
   # an element - this is used internally as the root of all render trees.
   class Fragment < Element
+    # Call {#render_children}
     def render options = {}
       self.render_children(options)
     end

data/lib/rxhp/html.rb

@@ -2,7 +2,19 @@ require 'rxhp/data/html/attributes'
 require 'rxhp/data/html/tags'
 
 module Rxhp
+  # Namespace for all HTML-related classes and methods.
+  #
+  # Most of RXhp is for generic trees; everything that is HTML or XML
+  # specific is defined here, or in {HtmlElement} and its subclasses.
   module Html
+    # Add a child node.
+    #
+    # @example
+    #   include Rxhp::Html
+    #   p do
+    #     text 'foo'
+    #     text 'bar'
+    #   end
     def fragment x
       Rxhp::Scope.current.children.push x
     end

data/lib/rxhp/html_element.rb

@@ -10,30 +10,38 @@ module Rxhp
   #
   # To use:
   # 1. subclass
-  # 2. define tag_name
-  # 3. call Rxhp::Scope.define_element('foo', Foo) to register the class
-  # ... or just add a define_tag line to html.rb.
+  # 2. define {#tag_name}
+  # 3. call +Rxhp::Scope.define_element('foo', Foo, MyModule)+ to register
+  #    the class
+  # ... or just add a +define_tag+ line to html.rb.
   #
   # There's another two base classes for special types of html elements:
-  # - HtmlSelfClosingElement - elements where in HTML, the closing tag is
-  #   optional - for example, <p>, <li>, and <body>
-  # - HtmlSingletonElement - not only is the closing tag optional, but
-  #   child elements are forbidden - for example, <br> and <img>
+  # {HtmlSelfClosingElement}::: elements where in HTML, the closing tag is
+  #                             optional - for example, <p> and <li>
+  # {HtmlSingletonElement}::: not only is the closing tag optional, but
+  #                           child elements are forbidden - for example,
+  #                           <br> and <img>
   #
-  # These can also be defined via Rxhp::Html#define_tag
+  # These can also be defined via {Rxhp::Html#define_tag}
   #
   # If you're making a custom element that's purely server-side (i.e. is
-  # just composed of HTML elements), you want to subclass ComposableElement
-  # instead.
+  # just composed of HTML elements), you want to subclass
+  # {ComposableElement} instead.
   class HtmlElement < Element
     include Rxhp::AttributeValidator
     accept_attributes Rxhp::Html::GLOBAL_ATTRIBUTES
     accept_attributes Rxhp::Html::GLOBAL_EVENT_HANDLERS
 
+    # Literal string to include in render output.
+    #
+    # For example, +'html'+ will lead to +'<html>...</html>'+.
     def tag_name
       raise NotImplementedError.new
     end
 
+    # Check that the element usage does nto have detectable errors.
+    #
+    # At the moment, this just checks for attribute correctness.
     def validate!
       super
       validate_attributes!
@@ -42,7 +50,7 @@ module Rxhp
     # Render the element.
     #
     # Pays attention to the formatter type, doctype, pretty print options,
-    # etc.
+    # etc. See {Element#render} for options.
     def render options = {}
       validate!
       options = fill_options(options)
@@ -66,7 +74,9 @@ module Rxhp
       end
     end
 
-    # Override to increase the depth count for the sake of pretty printing
+    # Render child elements.
+    #
+    # Increases the depth count for the sake of pretty printing.
     def render_children options = {}
       child_options = options.dup
       child_options[:depth] += 1

data/lib/rxhp/html_self_closing_element.rb

@@ -4,11 +4,14 @@ module Rxhp
   # Base class for HTML elements where the closing tag is optional, but
   # there can still be children.
   #
-  # For example, </p> is optional in HTML, but required in XHTML.
+  # For example, +</p>+ is optional in HTML, but required in XHTML.
   # This will change whether they're included or not based on the selected
   # render format.
   class HtmlSelfClosingElement < HtmlElement
     protected
+    # Render a close tag if appropriate.
+    #
+    # The close tag is appropriate if we're outputting nice HTML, or XHTML.
     def render_close_tag options
       super if options[:format] != Rxhp::TINY_HTML_FORMAT
     end

data/lib/rxhp/html_singleton_element.rb

@@ -4,22 +4,31 @@ require 'rxhp/error'
 module Rxhp
   # Superclass for all HTML elements that should never have children.
   #
-  # This is enforced. Examples include '<br>', '<img>' etc
+  # This is enforced. Examples include +<br>+, +<img>+ etc
   #
   # There is never a close tag:
-  # - in HTML it would be optional (and meaningless) anyway
-  # - people don't expect to see them
-  # - in XHTML, the opening tag will have been self closing.
+  # * in HTML it would be optional (and meaningless) anyway
+  # * people don't expect to see them
+  # * in XHTML, the opening tag will have been self closing.
   class HtmlSingletonElement < HtmlElement
+    # Exception indicating that you gave a singleton element children.
+    #
+    # For example, +<br>foo</br>+ is invalid.
     class HasChildrenError < Rxhp::ValidationError
     end
 
+    # Check that there are no child elements.
+    #
+    # @raises {HasChildrenError}
     def validate!
       super
       raise HasChildrenError.new unless children.empty?
     end
 
     protected
+    # Skip the closing tag.
+    #
+    # In XHTML mode, {#render_open_tag} should have made it self-closing.
     def render_close_tag options
       nil
     end

data/lib/rxhp/scope.rb

@@ -1,52 +1,82 @@
+require 'continuation' unless RUBY_VERSION =~ /^1\.8\./
 module Rxhp
   autoload :Fragment, 'rxhp/fragment'
   # A place for factory methods to be defined.
   #
-  # These are methods like Rxhp::Scope#h1 which creates an Rxhp::Html::H1
-  # instance.
+  # These are methods like +Rxhp::Scope#h1+ which creates an instance of
+  # +Rxhp::Html::H1+.
   #
   # The actual HTML classes are defined in rxhp/html.rb
   #
   module Scope
     # Helper function to append a child to the current context.
-    # Allows you to do this:
+    #
+    # @example Here's one I made earlier
     #   inner = body { 'hi' }
     #   html do
     #     fragment inner
     #   end
+    #
+    # @example Multiple +String+ children
+    #   p do
+    #     text 'foo'
+    #     text 'bar'
+    #   end
     def fragment x
       Rxhp::Scope.current.children.push x
     end
     alias :frag :fragment
     alias :text :fragment
 
+    # The element nesting scope.
+    #
+    # @example
+    #   Rxhp::Scope.current.should be_a Rxhp::Fragment
+    #   html.do
+    #     Rxhp::Scope.current.should be_a Rxhp::Html::Html
+    #     body do
+    #       Rxhp::Scope.current.should be_a Rxhp::Html::Body
+    #     end
+    #   end
     def self.current
-      self.stack.last || Rxhp::Fragment.new
+      callcc do |cc|
+        begin
+          throw(:rxhp_parent, cc)
+        rescue NameError, ArgumentError
+          Rxhp::Fragment.new
+        end
+      end
     end
 
-    def self.with_parent parent
-      result = nil
-      begin
-        self.stack.push parent
-        result = yield
-      ensure
-        self.stack.pop
+    # Set the value of {#current} for a block, and call it.
+    #
+    # Used by {#define_element}
+    def self.with_parent parent, &block
+      # push element onto the render stack...
+      cc = catch(:rxhp_parent) do
+        # ... and call the block with that new stack
+        block.call
+        nil
       end
-      result
+      cc.call(parent) if cc
     end
 
-    # Define the factory method.
+    # Define a factory method that takes a block, with a scope.
+    #
+    # @param [String] name is the name of the method to define
+    # @param [Class] klass is the {Element} subclass to construct
+    # @param [Module] namespace is where to define the method
     #
-    # can be called like:
+    # @example
+    #   define_element tag, Tag
+    #   tag
     #   tag 'content'
-    #   tag { content }
-    #   tag 'content', :attribute => 'value'
-    #   tag(:attribute=>'value') do
-    #     content
+    #   tag(:attribute => value)
+    #   tag('content', :attribute => 'value')
+    #   tag(:attribute => 'value') do
+    #     text 'content'
     #   end
-    #   tag
-    #   tag (:attribute => value)
-    def self.define_element name, klass, namespace
+    def self.define_element name, klass, namespace = Kernel
       impl = Proc.new do |*args, &block|
         # Yay for faking named parameters as a hash :p
         children = nil
@@ -101,11 +131,5 @@ module Rxhp
       #  end
       (class <<namespace; self; end).send(:define_method, name, impl)
     end
-
-    private
-
-    def self.stack
-      Thread.current[:rxhp_scope_stack] ||= []
-    end
   end
 end

data/lib/rxhp/tags/html_tag.rb

@@ -3,6 +3,9 @@ require 'rxhp/scope'
 
 module Rxhp
   module Html
+    # Special-case for the <html> tag.
+    #
+    # This handles doctype rendering.
     class Html < HtmlSelfClosingElement
       def tag_name; 'html'; end
 

metadata

@@ -1,33 +1,23 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: rxhp
-version: !ruby/object:Gem::Version 
-  hash: 25
+version: !ruby/object:Gem::Version
+  version: 0.1.2
   prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
 platform: ruby
-authors: 
+authors:
 - Fred Emmott
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-01-23 00:00:00 Z
+date: 2012-01-26 00:00:00.000000000Z
 dependencies: []
-
 description: An object-oriented validating HTML template system
-email: 
+email:
 - rxhp-gem@fredemmott.co.uk
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/rxhp/attribute_validator.rb
 - lib/rxhp/composable_element.rb
 - lib/rxhp/constants.rb
@@ -45,36 +35,27 @@ files:
 - lib/rxhp.rb
 homepage: https://github.com/fredemmott/rxhp
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
 rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: An object-oriented validating HTML template system
 test_files: []
-
+has_rdoc: