oga 1.2.3-java → 1.3.0-java

data/lib/oga/ruby/node.rb

@@ -0,0 +1,189 @@
+module Oga
+  module Ruby
+    # Class representing a single node in a Ruby AST.
+    #
+    # The setup of this class is roughly based on the "ast" Gem. The "ast" Gem
+    # is not used for this class as it provides too many methods that might
+    # conflict with this class' {#method_missing}.
+    #
+    # ASTs can be built by creating a node and then chaining various method
+    # calls together. For example, the following could be used to build an "if"
+    # statement:
+    #
+    #     number1 = Node.new(:lit, %w{10})
+    #     number2 = Node.new(:lit, %w{20})
+    #
+    #     (number2 > number1).if_true do
+    #       Node.new(:lit, %w{30})
+    #     end
+    #
+    # When serialized to Ruby this would roughly lead to the following code:
+    #
+    #     if 20 > 10
+    #       30
+    #     end
+    #
+    # @private
+    class Node < BasicObject
+      undef_method :!, :!=
+
+      # @return [Symbol]
+      attr_reader :type
+
+      # @param [Symbol] type
+      # @param [Array] children
+      def initialize(type, children = [])
+        @type     = type.to_sym
+        @children = children
+      end
+
+      # @return [Array]
+      def to_a
+        @children
+      end
+
+      alias_method :to_ary, :to_a
+
+      # Returns a "to_a" call node.
+      #
+      # @return [Oga::Ruby::Node]
+      def to_array
+        Node.new(:send, [self, :to_a])
+      end
+
+      # Returns an assignment node.
+      #
+      # This method wraps assigned values in a begin/end block to ensure that
+      # multiple lines of code result in the proper value being assigned.
+      #
+      # @param [Oga::Ruby::Node] other
+      # @return [Oga::Ruby::Node]
+      def assign(other)
+        if other.type == :followed_by
+          other = other.wrap
+        end
+
+        Node.new(:assign, [self, other])
+      end
+
+      # Returns an equality expression node.
+      #
+      # @param [Oga::Ruby::Node] other
+      # @return [Oga::Ruby::Node]
+      def eq(other)
+        Node.new(:eq, [self, other])
+      end
+
+      # Returns a boolean "and" node.
+      #
+      # @param [Oga::Ruby::Node] other
+      # @return [Oga::Ruby::Node]
+      def and(other)
+        Node.new(:and, [self, other])
+      end
+
+      # Returns a boolean "or" node.
+      #
+      # @param [Oga::Ruby::Node] other
+      # @return [Oga::Ruby::Node]
+      def or(other)
+        Node.new(:or, [self, other])
+      end
+
+      # Returns a node that evaluates to its inverse.
+      #
+      # For example, a variable `foo` would be turned into `!foo`.
+      #
+      # @return [Oga::Ruby::Node]
+      def not
+        !self
+      end
+
+      # Returns a node for Ruby's "is_a?" method.
+      #
+      # @param [Class] klass
+      # @return [Oga::Ruby::Node]
+      def is_a?(klass)
+        Node.new(:send, [self, 'is_a?', Node.new(:lit, [klass.to_s])])
+      end
+
+      # Wraps the current node in a block.
+      #
+      # @param [Array] args Arguments (as Node instances) to pass to the block.
+      # @return [Oga::Ruby::Node]
+      def add_block(*args)
+        Node.new(:block, [self, args, yield])
+      end
+
+      # Wraps the current node in a `begin` node.
+      #
+      # @return [Oga::Ruby::Node]
+      def wrap
+        Node.new(:begin, [self])
+      end
+
+      # Wraps the current node in an if statement node.
+      #
+      # The body of this statement is set to the return value of the supplied
+      # block.
+      #
+      # @return [Oga::Ruby::Node]
+      def if_true
+        Node.new(:if, [self, yield])
+      end
+
+      # Wraps the current node in an `if !...` statement.
+      #
+      # @see [#if_true]
+      def if_false
+        self.not.if_true { yield }
+      end
+
+      # Wraps the current node in a `while` statement.
+      #
+      # The body of this statement is set to the return value of the supplied
+      # block.
+      #
+      # @return [Oga::Ruby::Node]
+      def while_true
+        Node.new(:while, [self, yield])
+      end
+
+      # Adds an "else" statement to the current node.
+      #
+      # This method assumes it's being called only on "if" nodes.
+      #
+      # @return [Oga::Ruby::Node]
+      def else
+        Node.new(:if, @children + [yield])
+      end
+
+      # Chains two nodes together.
+      #
+      # @param [Oga::Ruby::Node] other
+      # @return [Oga::Ruby::Node]
+      def followed_by(other = nil)
+        other = yield if ::Kernel.block_given?
+
+        Node.new(:followed_by, [self, other])
+      end
+
+      # Returns a node for a method call.
+      #
+      # @param [Symbol] name The name of the method to call.
+      #
+      # @param [Array] args Any arguments (as Node instances) to pass to the
+      #  method.
+      #
+      # @return [Oga::Ruby::Node]
+      def method_missing(name, *args)
+        Node.new(:send, [self, name.to_s, *args])
+      end
+
+      # @return [String]
+      def inspect
+        "(#{type} #{@children.map(&:inspect).join(' ')})"
+      end
+    end # Node
+  end # Ruby
+end # Oga

data/lib/oga/version.rb

@@ -1,3 +1,3 @@
 module Oga
-  VERSION = '1.2.3'
+  VERSION = '1.3.0'
 end # Oga

data/lib/oga/whitelist.rb

@@ -1,18 +1,12 @@
 module Oga
-  ##
   # @api private
-  #
   class Whitelist < Blacklist
-    ##
     # @return [TrueClass|FalseClass]
-    #
     def allow?(name)
       names.include?(name)
     end
 
-    ##
     # @return [Oga::Blacklist]
-    #
     def to_blacklist
       Blacklist.new(names)
     end

data/lib/oga/xml/attribute.rb

@@ -1,9 +1,9 @@
 module Oga
   module XML
-    ##
     # Class for storing information about a single XML attribute.
-    #
     class Attribute
+      include ExpandedName
+
       # The name of the attribute.
       # @return [String]
       attr_accessor :name
@@ -15,25 +15,23 @@ module Oga
       # @return [Oga::XML::Element]
       attr_accessor :element
 
-      ##
+      alias_method :parent, :element
+
       # The default namespace available to all attributes. This namespace can
       # not be modified.
       #
       # @return [Oga::XML::Namespace]
-      #
       DEFAULT_NAMESPACE = Namespace.new(
         :name => 'xml',
         :uri  => XML::DEFAULT_NAMESPACE.uri
       ).freeze
 
-      ##
       # @param [Hash] options
       #
       # @option options [String] :name
       # @option options [String] :namespace_name
       # @option options [String] :value
       # @option options [Oga::XML::Element] :element
-      #
       def initialize(options = {})
         @name    = options[:name]
         @value   = options[:value]
@@ -42,12 +40,10 @@ module Oga
         @namespace_name = options[:namespace_name]
       end
 
-      ##
       # Returns the {Oga::XML::Namespace} instance for the current namespace
       # name.
       #
       # @return [Oga::XML::Namespace]
-      #
       def namespace
         unless @namespace
           if namespace_name == DEFAULT_NAMESPACE.name
@@ -60,19 +56,15 @@ module Oga
         @namespace
       end
 
-      ##
       # @param [String] value
-      #
       def value=(value)
         @value   = value
         @decoded = false
       end
 
-      ##
       # Returns the value of the attribute or nil if no explicit value was set.
       #
       # @return [String|NilClass]
-      #
       def value
         if !@decoded and @value
           @value   = EntityDecoder.try_decode(@value, html?)
@@ -82,18 +74,14 @@ module Oga
         @value
       end
 
-      ##
       # @return [String]
-      #
       def text
         value.to_s
       end
 
       alias_method :to_s, :text
 
-      ##
       # @return [String]
-      #
       def to_xml
         if namespace_name
           full_name = "#{namespace_name}:#{name}"
@@ -106,9 +94,7 @@ module Oga
         %Q(#{full_name}="#{enc_value}")
       end
 
-      ##
       # @return [String]
-      #
       def inspect
         segments = []
 
@@ -123,11 +109,18 @@ module Oga
         "Attribute(#{segments.join(' ')})"
       end
 
+      # @see [Oga::XML::Node#each_ancestor]
+      def each_ancestor(&block)
+        return unless element
+
+        yield element
+
+        element.each_ancestor(&block)
+      end
+
       private
 
-      ##
       # @return [TrueClass|FalseClass]
-      #
       def html?
         !!@element && @element.html?
       end

data/lib/oga/xml/cdata.rb

@@ -1,14 +1,10 @@
 module Oga
   module XML
-    ##
     # Class used for storing information about CDATA tags.
-    #
     class Cdata < CharacterNode
-      ##
       # Converts the node back to XML.
       #
       # @return [String]
-      #
       def to_xml
         "<![CDATA[#{text}]]>"
       end

data/lib/oga/xml/character_node.rb

@@ -1,34 +1,26 @@
 module Oga
   module XML
-    ##
     # Base class for nodes that represent a text-like value such as Text and
     # Comment nodes.
-    #
     class CharacterNode < Node
       # @return [String]
       attr_accessor :text
 
-      ##
       # @param [Hash] options
       #
       # @option options [String] :text The text of the node.
-      #
       def initialize(options = {})
         super
 
         @text = options[:text]
       end
 
-      ##
       # @return [String]
-      #
       def to_xml
         text.to_s
       end
 
-      ##
       # @return [String]
-      #
       def inspect
         "#{self.class.to_s.split('::').last}(#{text.inspect})"
       end

data/lib/oga/xml/comment.rb

@@ -1,14 +1,10 @@
 module Oga
   module XML
-    ##
     # Class used for storing information about XML comments.
-    #
     class Comment < CharacterNode
-      ##
       # Converts the node back to XML.
       #
       # @return [String]
-      #
       def to_xml
         "<!--#{text}-->"
       end

data/lib/oga/xml/default_namespace.rb

@@ -1,10 +1,8 @@
 module Oga
   module XML
-    ##
     # The default XML namespace.
     #
     # @return [Oga::XML::Namespace]
-    #
     DEFAULT_NAMESPACE = Namespace.new(
       :name => 'xmlns',
       :uri  => 'http://www.w3.org/XML/1998/namespace'

data/lib/oga/xml/doctype.rb

@@ -1,8 +1,6 @@
 module Oga
   module XML
-    ##
     # Class used for storing information about Doctypes.
-    #
     class Doctype
       # The name of the doctype (e.g. "HTML").
       # @return [String]
@@ -24,7 +22,6 @@ module Oga
       # @return [String]
       attr_accessor :inline_rules
 
-      ##
       # @example
       #  dtd = Doctype.new(:name => 'html', :type => 'PUBLIC')
       #
@@ -34,7 +31,6 @@ module Oga
       # @option options [String] :type
       # @option options [String] :public_id
       # @option options [String] :system_id
-      #
       def initialize(options = {})
         @name         = options[:name]
         @type         = options[:type]
@@ -43,11 +39,9 @@ module Oga
         @inline_rules = options[:inline_rules]
       end
 
-      ##
       # Converts the doctype back to XML.
       #
       # @return [String]
-      #
       def to_xml
         segments = "<!DOCTYPE #{name}"
 
@@ -59,11 +53,9 @@ module Oga
         segments + '>'
       end
 
-      ##
       # Inspects the doctype.
       #
       # @return [String]
-      #
       def inspect
         segments = []