blather 0.4.7 → 0.4.8

data/lib/blather/stream/parser.rb

@@ -42,7 +42,6 @@ class Stream # :nodoc:
         @current = node
       end
 
-
       ns_keys = namespaces.map { |pre, href| pre }
       namespaces.delete_if { |pre, href| NS_TO_IGNORE.include? href }
       @namespace_definitions.push []
@@ -56,14 +55,12 @@ class Stream # :nodoc:
 
       deliver(node) if elem == 'stream'
 
-=begin
-      $stderr.puts "\n\n"
-      $stderr.puts [elem, attrs, prefix, uri, namespaces].inspect
-      $stderr.puts @namespaces.inspect
-      $stderr.puts [@namespaces[[prefix, uri]].prefix, @namespaces[[prefix, uri]].href].inspect if @namespaces[[prefix, uri]]
-      $stderr.puts node.inspect
-      $stderr.puts node.document.to_s.gsub(/\n\s*/,'')
-=end
+      # $stderr.puts "\n\n"
+      # $stderr.puts [elem, attrs, prefix, uri, namespaces].inspect
+      # $stderr.puts @namespaces.inspect
+      # $stderr.puts [@namespaces[[prefix, uri]].prefix, @namespaces[[prefix, uri]].href].inspect if @namespaces[[prefix, uri]]
+      # $stderr.puts node.inspect
+      # $stderr.puts node.document.to_s.gsub(/\n\s*/,'')
     end
 
     def end_element_namespace(elem, prefix, uri)

data/lib/blather/xmpp_node.rb

@@ -1,42 +1,50 @@
 module Blather
 
-  ##
   # Base XML Node
-  # All XML classes subclass XMPPNode
-  # it allows the addition of helpers
+  # All XML classes subclass XMPPNode it allows the addition of helpers
   class XMPPNode < Nokogiri::XML::Node
+    # @private
     BASE_NAMES = %w[presence message iq].freeze
 
+    # @private
     @@registrations = {}
 
     class_inheritable_accessor  :registered_ns,
                                 :registered_name
 
-    ##
-    # Lets a subclass register itself
+    # Register a new stanza class to a name and/or namespace
     #
     # This registers a namespace that is used when looking
     # up the class name of the object to instantiate when a new
     # stanza is received
+    #
+    # @param [#to_s] name the name of the node
+    # @param [String, nil] ns the namespace the node belongs to
     def self.register(name, ns = nil)
       self.registered_name = name.to_s
       self.registered_ns = ns
       @@registrations[[self.registered_name, self.registered_ns]] = self
     end
 
-    ##
     # Find the class to use given the name and namespace of a stanza
-    def self.class_from_registration(name, xmlns)
+    #
+    # @param [#to_s] name the name to lookup
+    # @param [String, nil] xmlns the namespace the node belongs to
+    # @return [Class, nil] the class appropriate for the name/ns combination
+    def self.class_from_registration(name, ns = nil)
       name = name.to_s
-      @@registrations[[name, xmlns]] || @@registrations[[name, nil]]
+      @@registrations[[name, ns]] || @@registrations[[name, nil]]
     end
 
-    ##
-    # Looks up the class to use then instantiates an object
-    # of that class and imports all the <tt>node</tt>'s attributes
-    # and children into it.
+    # Import an XML::Node to the appropriate class
+    #
+    # Looks up the class the node should be then creates it based on the
+    # elements of the XML::Node
+    # @param [XML::Node] node the node to import
+    # @return the appropriate object based on the node name and namespace
     def self.import(node)
-      klass = class_from_registration(node.element_name, (node.namespace.href if node.namespace))
+      ns = (node.namespace.href if node.namespace)
+      klass = class_from_registration(node.element_name, ns)
       if klass && klass != self
         klass.import(node)
       else
@@ -44,151 +52,71 @@ module Blather
       end
     end
 
-    ##
-    # Provides an attribute reader helper. Default behavior is to
-    # conver the values of the attribute into a symbol. This can
-    # be turned off by passing <tt>:to_sym => false</tt>
+    # Create a new Node object
     #
-    #   class Node
-    #     attribute_reader :type
-    #     attribute_reader :name, :to_sym => false
-    #   end
-    #
-    #   n = Node.new
-    #   n[:type] = 'foo'
-    #   n.type == :foo
-    #   n[:name] = 'bar'
-    #   n.name == 'bar'
-    def self.attribute_reader(*syms)
-      opts = syms.last.is_a?(Hash) ? syms.pop : {}
-      convert_str = "val.#{opts[:call]} if val" if opts[:call]
-      syms.flatten.each do |sym|
-        class_eval(<<-END, __FILE__, __LINE__)
-          def #{sym}
-            val = self[:#{sym}]
-            #{convert_str}
-          end
-        END
-      end
-    end
+    # @param [String, nil] name the element name
+    # @param [XML::Document, nil] doc the document to attach the node to. If
+    # not provided one will be created
+    # @return a new object with the registered name and namespace
+    def self.new(name = nil, doc = nil)
+      name ||= self.registered_name
 
-    ##
-    # Provides an attribute writer helper.
-    #
-    #   class Node
-    #     attribute_writer :type
-    #   end
-    #
-    #   n = Node.new
-    #   n.type = 'foo'
-    #   n[:type] == 'foo'
-    def self.attribute_writer(*syms)
-      syms.flatten.each do |sym|
-        next if sym.is_a?(Hash)
-        class_eval(<<-END, __FILE__, __LINE__)
-          def #{sym}=(value)
-            self[:#{sym}] = value
-          end
-        END
-      end
+      node = super name.to_s, (doc || Nokogiri::XML::Document.new)
+      node.document.root = node unless doc
+      node.namespace = self.registered_ns unless BASE_NAMES.include?(name.to_s)
+      node
     end
 
-    ##
-    # Provides an attribute accessor helper combining
-    # <tt>attribute_reader</tt> and <tt>attribute_writer</tt>
-    #
-    #   class Node
-    #     attribute_accessor :type
-    #     attribute_accessor :name, :to_sym => false
-    #   end
+    # Helper method to read an attribute
     #
-    #   n = Node.new
-    #   n.type = 'foo'
-    #   n.type == :foo
-    #   n.name = 'bar'
-    #   n.name == 'bar'
-    def self.attribute_accessor(*syms)
-      attribute_reader *syms
-      attribute_writer *syms
+    # @param [#to_sym] attr_name the name of the attribute
+    # @param [String, Symbol, nil] to_call the name of the method to call on
+    # the returned value
+    # @return nil or the value
+    def read_attr(attr_name, to_call = nil)
+      val = self[attr_name.to_sym]
+      val && to_call ? val.__send__(to_call) : val
     end
 
-    ##
-    # Provides a content reader helper that returns the content of a node
-    # +method+ is the method to create
-    # +conversion+ is a method to call on the content before sending it back
-    # +node+ is the name of the content node (this defaults to the method name)
+    # Helper method to write a value to an attribute
     #
-    #   class Node
-    #     content_attr_reader :body
-    #     content_attr_reader :type, :to_sym
-    #     content_attr_reader :id, :to_i, :identity
-    #   end
-    #
-    #   n = Node.new 'foo'
-    #   n.to_s == "<foo><body>foobarbaz</body><type>error</type><identity>1000</identity></foo>"
-    #   n.body == 'foobarbaz'
-    #   n.type == :error
-    #   n.id == 1000
-    def self.content_attr_reader(method, conversion = nil, node = nil)
-      node ||= method
-      conversion = "val.#{conversion} if val.respond_to?(:#{conversion})" if conversion
-      class_eval(<<-END, __FILE__, __LINE__)
-        def #{method}
-          val = content_from :#{node}
-          #{conversion}
-        end
-      END
+    # @param [#to_sym] attr_name the name of the attribute
+    # @param [#to_s] value the value to set the attribute to
+    def write_attr(attr_name, value)
+      self[attr_name.to_sym] = value
     end
 
-    ##
-    # Provides a content writer helper that creates or updates the content of a node
-    # +method+ is the method to create
-    # +node+ is the name of the node to create (defaults to the method name)
-    #
-    #   class Node
-    #     content_attr_writer :body
-    #     content_attr_writer :id, :identity
-    #   end
+    # Helper method to read the content of a node
     #
-    #   n = Node.new 'foo'
-    #   n.body = 'thebodytext'
-    #   n.id = 'id-text'
-    #   n.to_s == '<foo><body>thebodytext</body><identity>id-text</identity></foo>'
-    def self.content_attr_writer(method, node = nil)
-      node ||= method
-      class_eval(<<-END, __FILE__, __LINE__)
-        def #{method}=(val)
-          set_content_for :#{node}, val
-        end
-      END
-    end
-
-    ##
-    # Provides a quick way of building +content_attr_reader+ and +content_attr_writer+
-    # for the same method and node
-    def self.content_attr_accessor(method, conversion = nil, node = nil)
-      content_attr_reader method, conversion, node
-      content_attr_writer method, node
+    # @param [#to_sym] node the name of the node
+    # @param [String, Symbol, nil] to_call the name of the method to call on
+    # the returned value
+    # @return nil or the value
+    def read_content(node, to_call = nil)
+      val = content_from node.to_sym
+      val && to_call ? val.__send__(to_call) : val
     end
 
-    ##
-    # Automatically sets the namespace registered by the subclass
-    def self.new(name = nil, doc = nil)
-      name ||= self.registered_name
-
-      node = super name.to_s, (doc || Nokogiri::XML::Document.new)
-      node.document.root = node unless doc
-      node.namespace = self.registered_ns unless BASE_NAMES.include?(name.to_s)
-      node
-    end
-
-    ##
-    # Quickway of turning itself into a proper object
+    # Turn the object into a proper stanza
+    #
+    # @return a stanza object
     def to_stanza
       self.class.import self
     end
 
+    # @private
     alias_method :nokogiri_namespace=, :namespace=
+    # Attach a namespace to the node
+    #
+    # @overload namespace=(ns)
+    #   Attach an already created XML::Namespace
+    #   @param [XML::Namespace] ns the namespace object
+    # @overload namespace=(ns)
+    #   Create a new namespace and attach it
+    #   @param [String] ns the namespace uri
+    # @overload namespace=(namespaces)
+    #   Createa and add new namespaces from a hash
+    #   @param [Hash] namespaces a hash of prefix => uri pairs
     def namespace=(namespaces)
       case namespaces
       when Nokogiri::XML::Namespace
@@ -206,34 +134,46 @@ module Blather
       end
     end
 
+    # Helper method to get the node's namespace
+    #
+    # @return [XML::Namespace, nil] The node's namespace object if it exists
     def namespace_href
       namespace.href if namespace
     end
 
-    ##
     # Remove a child with the name and (optionally) namespace given
+    #
+    # @param [String] name the name or xpath of the node to remove
+    # @param [String, nil] ns the namespace the node is in
     def remove_child(name, ns = nil)
       child = xpath(name, ns).first
       child.remove if child
     end
 
-    ##
-    # Remove all children with a given name
+    # Remove all children with a given name regardless of namespace
+    #
+    # @param [String] name the name of the nodes to remove
     def remove_children(name)
       xpath("./*[local-name()='#{name}']").remove
     end
 
-    ##
-    # Pull the content from a child
+    # The content of the named node
+    #
+    # @param [String] name the name or xpath of the node
+    # @param [String, nil] ns the namespace the node is in
+    # @return [String, nil] the content of the node
     def content_from(name, ns = nil)
       child = xpath(name, ns).first
       child.content if child
     end
 
-    ##
     # Sets the content for the specified node.
     # If the node exists it is updated. If not a new node is created
-    # If the node exists and the content is nil, the node will be removed entirely
+    # If the node exists and the content is nil, the node will be removed
+    # entirely
+    #
+    # @param [String] node the name of the node to update/create
+    # @param [String, nil] content the content to set within the node
     def set_content_for(node, content = nil)
       if content
         child = xpath(node).first
@@ -246,8 +186,10 @@ module Blather
 
     alias_method :copy, :dup
 
-    ##
-    # Inherit all of <tt>stanza</tt>'s attributes and children
+    # Inherit the attributes and children of an XML::Node
+    #
+    # @param [XML::Node] stanza the node to inherit
+    # @return [self]
     def inherit(stanza)
       set_namespace stanza.namespace if stanza.namespace
       inherit_attrs stanza.attributes
@@ -259,12 +201,18 @@ module Blather
       self
     end
 
-    ##
-    # Inherit only <tt>stanza</tt>'s attributes
+    # Inherit a set of attributes
+    #
+    # @param [Hash] attrs a hash of attributes to set on the node
+    # @return [self]
     def inherit_attrs(attrs)
       attrs.each  { |name, value| self[name] = value }
       self
     end
-  end #XMPPNode
 
-end
+    def inspect
+      self.to_xml
+    end
+  end  # XMPPNode
+
+end  # Blather

data/spec/blather/client/client_spec.rb

@@ -164,7 +164,7 @@ describe Blather::Client do
     @client.receive_data stanza
   end
 
-  it 'allows for passing to the next handler in the heirarchy' do
+  it 'allows for passing to the next handler in the hierarchy' do
     stanza = Blather::Stanza::Iq::Query.new
     response = mock(:query => nil, :iq => nil)
     @client.register_handler(:query) do |_|

data/spec/blather/errors_spec.rb

@@ -2,15 +2,15 @@ require File.join(File.dirname(__FILE__), *%w[.. spec_helper])
 
 describe Blather::BlatherError do
   it 'is handled by :error' do
-    Blather::BlatherError.new.handler_heirarchy.must_equal [:error]
+    Blather::BlatherError.new.handler_hierarchy.must_equal [:error]
   end
 end
 
 describe 'Blather::ParseError' do
   before { @error = Blather::ParseError.new('</generate-parse-error>"') }
 
-  it 'is registers with the handler heirarchy' do
-    @error.handler_heirarchy.must_equal [:parse_error, :error]
+  it 'is registers with the handler hierarchy' do
+    @error.handler_hierarchy.must_equal [:parse_error, :error]
   end
 
   it 'contains the error message' do
@@ -22,8 +22,8 @@ end
 describe 'Blather::UnknownResponse' do
   before { @error = Blather::UnknownResponse.new(Blather::XMPPNode.new('foo-bar')) }
 
-  it 'is registers with the handler heirarchy' do
-    @error.handler_heirarchy.must_equal [:unknown_response_error, :error]
+  it 'is registers with the handler hierarchy' do
+    @error.handler_hierarchy.must_equal [:unknown_response_error, :error]
   end
 
   it 'holds on to a copy of the failure node' do

data/spec/blather/stanza/message_spec.rb

@@ -73,4 +73,60 @@ describe Blather::Stanza::Message do
       Blather::Stanza::Message.new.must_respond_to :"#{valid_type}?"
     end
   end
+
+  it 'ensures an html node exists when asked for xhtml_node' do
+    search_args = [
+      '/message/html_ns:html',
+      {:html_ns => Blather::Stanza::Message::HTML_NS}
+    ]
+    msg = Blather::Stanza::Message.new
+    msg.find_first(*search_args).must_be_nil
+
+    msg.xhtml_node
+    msg.find_first(*search_args).wont_be_nil
+  end
+
+  it 'ensures a body node exists when asked for xhtml_node' do
+    search_args = [
+      '/message/html_ns:html/body_ns:body',
+      {:html_ns => Blather::Stanza::Message::HTML_NS,
+      :body_ns => Blather::Stanza::Message::HTML_BODY_NS}
+    ]
+    msg = Blather::Stanza::Message.new
+    msg.find_first(*search_args).must_be_nil
+
+    msg.xhtml_node
+    msg.find_first(*search_args).wont_be_nil
+  end
+
+  it 'returns an existing node when asked for xhtml_node' do
+    msg = Blather::Stanza::Message.new
+    msg << (h = Blather::XMPPNode.new('html', msg.document))
+    h.namespace = Blather::Stanza::Message::HTML_NS
+    h << (b = Blather::XMPPNode.new('body', msg.document))
+    b.namespace = Blather::Stanza::Message::HTML_BODY_NS
+
+    msg.xhtml_node.must_equal(b)
+  end
+
+  it 'has an xhtml setter' do
+    msg = Blather::Stanza::Message.new
+    xhtml = "<some>xhtml</some>"
+    msg.xhtml = xhtml
+    msg.xhtml_node.content.strip.must_equal(xhtml)
+  end
+
+  it 'sets valid xhtml even if the input is not valid' do
+    msg = Blather::Stanza::Message.new
+    xhtml = "<some>xhtml"
+    msg.xhtml = xhtml
+    msg.xhtml_node.content.strip.must_equal("<some>xhtml</some>")
+  end
+
+  it 'has an xhtml getter' do
+    msg = Blather::Stanza::Message.new
+    xhtml = "<some>xhtml</some>"
+    msg.xhtml = xhtml
+    msg.xhtml.must_equal(xhtml)
+  end
 end