# File lib/sdl4r/tag.rb, line 95
    def initialize(namespace, name = nil, &block)
      namespace, name = to_nns namespace, name

      raise ArgumentError, "tag namespace must be a String" unless namespace.is_a? String
      raise ArgumentError, "tag name must be a String" unless name.is_a? String

      SDL4R.validate_identifier(namespace) unless namespace.empty?
      @namespace = namespace
      
      name = name.to_s.strip
      raise ArgumentError, "Tag name cannot be nil or empty" if name.empty?
      SDL4R.validate_identifier(name)
      @name = name
      
      @children = []
      @values = []
      
      # a Hash of Hash : {namespace => {name => value}}
      # The default namespace is represented by an empty string.
      @attributesByNamespace = {}

      instance_eval(&block) if block_given?
    end

# File lib/sdl4r/tag.rb, line 169
    def <<(o)
      if o.is_a?(Tag)
        add_child(o)
      elsif o.is_a?(Hash)
        o.each_pair { |key, value|
          namespace, key = key.split(/:/) if key.match(/:/)
          namespace ||= ""
          set_attribute(namespace, key, value)
        }
      elsif o.is_a? Array
        o.each { |item|
          if item.is_a? Array
            anonymous = new_child("content")
            anonymous << item
          else
            self << item
          end
        }
      else
        add_value(o)
      end
      return self
    end

# File lib/sdl4r/tag.rb, line 142
    def add_child(child)
      @children.push(child)
      return child
    end

# File lib/sdl4r/tag.rb, line 409
    def add_value(v)
      @values.push(SDL4R::coerce_or_fail(v))
      return nil
    end

# File lib/sdl4r/tag.rb, line 518
    def attribute(namespace, key = nil)
      namespace, key = to_nns namespace, key
      attributes = @attributesByNamespace[namespace]
      return attributes.nil? ? nil : attributes[key]
    end

# File lib/sdl4r/tag.rb, line 556
    def attributes(namespace = nil, &block) # :yields: namespace, key, value
      if block_given?
        each_attribute(namespace, &block)
        
      else
        if namespace.nil?
          hash = {}

          each_attribute do | namespace, key, value |
            qualified_name = namespace.empty? ? key : namespace + ':' + key
            hash[qualified_name] = value
          end

          return hash

        else
          return @attributesByNamespace[namespace]
        end
      end
    end

# File lib/sdl4r/tag.rb, line 660
    def attributes=(attribute_hash)
      set_attributes(attribute_hash)
    end

# File lib/sdl4r/tag.rb, line 313
    def child(recursive = false, name = nil)
      if name.nil?
        name = recursive
        recursive = false
      end
      
      unless name
        return @children.first
      else
        each_child(recursive, name) { |child| return child }
      end
    end

# File lib/sdl4r/tag.rb, line 234
    def child_count
      @children.size
    end

# File lib/sdl4r/tag.rb, line 258
    def children(recursive = false, namespace = nil, name = :DEFAULT, &block) # :yields: child
      if name == :DEFAULT
        name = namespace
        namespace = nil
      end

      if block_given?
        each_child(recursive, namespace, name, &block)
        return nil
        
      else
        unless recursive or name or namespace
          return @children
          
        else
          result = []
          each_child(recursive, namespace, name) { |child|
            result << child
          }
          return result
        end
      end
    end

# File lib/sdl4r/tag.rb, line 833
    def children_to_string(line_prefix = "", s = "")
      @children.each do |child|
        s << child.to_string(line_prefix) << $/
      end
      
      return s
    end

# File lib/sdl4r/tag.rb, line 287
    def children_values(name = nil)
      children_values = []
      each_child(false, name) { |child|
        case child.values.size
        when 0
          children_values << nil
        when 1
          children_values << child.value
        else
          children_values << child.values
        end
      }
      return children_values
    end

# File lib/sdl4r/tag.rb, line 596
    def clear_attributes(namespace = nil)
      if namespace.nil?
        @attributesByNamespace.clear
      else
        @attributesByNamespace.delete(namespace)
      end
    end

# File lib/sdl4r/tag.rb, line 205
    def clear_children
      @children = []
      nil
    end

# File lib/sdl4r/tag.rb, line 437
    def clear_values
      @values = []
      nil
    end

# File lib/sdl4r/tag.rb, line 846
    def eql?(o)
      # this is safe because to_string() dumps the full state
      return o.is_a?(Tag) && o.to_string == to_string;
    end

# File lib/sdl4r/tag.rb, line 531
    def has_attribute?(namespace = nil, key = nil)
      namespace, key = to_nns namespace, key

      if namespace or key
        attributes = @attributesByNamespace[namespace]
        return attributes.nil? ? false : attributes.has_key?(key)

      else
        attributes { return true }
        return false
      end
    end

# File lib/sdl4r/tag.rb, line 330
    def has_child?(name)
      !child(name).nil?
    end

# File lib/sdl4r/tag.rb, line 336
    def has_children?
      !@children.empty?
    end

# File lib/sdl4r/tag.rb, line 416
    def has_value?(v)
      @values.include?(v)
    end

# File lib/sdl4r/tag.rb, line 854
    def hash
      return to_string.hash
    end

# File lib/sdl4r/tag.rb, line 669
    def name=(a_name)
      a_name = a_name.to_s
      SDL4R.validate_identifier(a_name)
      @name = a_name
    end

# File lib/sdl4r/tag.rb, line 680
    def namespace=(a_namespace)
      a_namespace = a_namespace.to_s
      SDL4R.validate_identifier(a_namespace) unless a_namespace.empty?
      @namespace = a_namespace
    end

# File lib/sdl4r/tag.rb, line 132
    def new_child(*args, &block)
      return add_child Tag.new(*args, &block)
    end

# File lib/sdl4r/tag.rb, line 690
    def read(input)
      if input.is_a? String
        read_from_io(true) { StringIO.new(input) }

      elsif input.is_a? Pathname
        read_from_io(true) { input.open("r:UTF-8") }

      elsif input.is_a? URI
        read_from_io(true) { input.open }

      else
        read_from_io(false) { input }
      end
      
      return self
    end

# File lib/sdl4r/tag.rb, line 709
    def read_from_io(close_io)
      io = yield

      begin
        Parser.new(io).parse.each do |tag|
          add_child(tag)
        end

      ensure
        if close_io
          io.close rescue IOError
        end
      end
    end

# File lib/sdl4r/tag.rb, line 587
    def remove_attribute(namespace, key = nil)
      namespace, key = to_nns namespace, key
      attributes = @attributesByNamespace[namespace]
      return attributes.nil? ? nil : attributes.delete(key)
    end

# File lib/sdl4r/tag.rb, line 199
    def remove_child(child)
      return !@children.delete(child).nil?
    end

# File lib/sdl4r/tag.rb, line 426
    def remove_value(v)
      index = @values.index(v)
      if index
        return !@values.delete_at(index).nil?
      else
        return false
      end
    end

# File lib/sdl4r/tag.rb, line 488
    def set_attribute(namespace, key, value = :default)
      if value == :default
        value = key
        key = namespace
        namespace = ""
      end

      raise ArgumentError, "attribute namespace must be a String" unless namespace.is_a? String
      raise ArgumentError, "attribute key must be a String" unless key.is_a? String
      raise ArgumentError, "attribute key cannot be empty" if key.empty?

      SDL4R.validate_identifier(namespace) unless namespace.empty?
      SDL4R.validate_identifier(key)

      attributes = @attributesByNamespace[namespace]
      
      if attributes.nil?
        attributes = {}
        @attributesByNamespace[namespace] = attributes
      end
      
      attributes[key] = SDL4R.coerce_or_fail(value)
    end

# File lib/sdl4r/tag.rb, line 637
    def set_attributes(namespace, attribute_hash = nil)
      if attribute_hash.nil?
        attribute_hash = namespace
        namespace = ""
      end
      
      raise ArgumentError, "namespace can't be nil" if namespace.nil?
      raise ArgumentError, "attribute_hash should be a Hash" unless attribute_hash.is_a? Hash

      namespace_attributes = @attributesByNamespace[namespace]
      namespace_attributes.clear if namespace_attributes
      
      attribute_hash.each_pair do |key, value|
          # Calling set_attribute() is required to ensure validations
          set_attribute(namespace, key, value)
      end
    end

# File lib/sdl4r/tag.rb, line 375
    def to_child_hash
      hash = {}
      children { |child| hash[child.name] = child.value }
      return hash
    end

# File lib/sdl4r/tag.rb, line 393
    def to_child_string_hash
      hash = {}
      children do |child|
        # FIXME: it is quite hard to be sure whether we should mimic the Java version
        # as there might be a lot of values that don't translate nicely to Strings.
        hash[child.name] = child.value.to_s
      end
      return hash
    end

# File lib/sdl4r/tag.rb, line 766
    def to_s
      to_string
    end

# File lib/sdl4r/tag.rb, line 776
    def to_string(line_prefix = "", indent = "\t")
      line_prefix = "" if line_prefix.nil?
      s = ""
      s << line_prefix
      
      if name == "content" && namespace.empty?
        skip_value_space = true
      else
        skip_value_space = false
        s << "#{namespace}:" unless namespace.empty?
        s << name
      end

      # output values
      values do |value|
        if skip_value_space
          skip_value_space = false
        else
          s << " "
        end
        s << SDL4R.format(value, true, line_prefix, indent)
      end

      # output attributes
      unless @attributesByNamespace.empty?
        all_attributes_hash = attributes
        all_attributes_array = all_attributes_hash.sort { |a, b|
          namespace1, name1 = a[0].split(':')
          namespace1, name1 = "", namespace1 if name1.nil?
          namespace2, name2 = b[0].split(':')
          namespace2, name2 = "", namespace2 if name2.nil?

          diff = namespace1 <=> namespace2
          diff == 0 ? name1 <=> name2 : diff
        }
        all_attributes_array.each do |attribute_name, attribute_value|
          s << " " << attribute_name << '=' << SDL4R.format(attribute_value, true)
        end
      end

      # output children
      unless @children.empty?
        s << " {#{$/}"
        children_to_string(line_prefix + indent, s)
        s << line_prefix << ?}
      end

      return s
    end

# File lib/sdl4r/tag.rb, line 864
    def to_xml_string(line_prefix = "", uri_by_namespace = nil)
      line_prefix ||= ""
  
      s = ""
      s << line_prefix << ?<
      s << "#{namespace}:" unless namespace.empty?
      s << name

      # output namespace declarations
      if uri_by_namespace
        uri_by_namespace.each_pair do |namespace, uri|
          if namespace
            s << " xmlns:#{namespace}=\"#{uri}\""
          else
            s << " xmlns=\"#{uri}\""
          end
        end
      end
      
      # output values
      unless @values.empty?
        i = 0
        @values.each do |value|
          s << " _val" << i.to_s << "=\"" << SDL4R.format(value, false) << "\""
          i += 1
        end
      end
      
      # output attributes
      if has_attribute?
        attributes do |attribute_namespace, attribute_name, attribute_value|
          s << " "
          s << "#{attribute_namespace}:" unless attribute_namespace.empty?
          s << attribute_name << "=\"" << SDL4R.format(attribute_value, false) << ?"
        end
      end
  
      if @children.empty?
        s << "/>"
      else
        s << ">\n"
        @children.each do |child|
          s << child.to_xml_string(line_prefix + "    ") << ?\n
        end
        
        s << line_prefix << "</"
        s << "#{namespace}:" unless namespace.empty?
        s << name << ?>
      end
  
      return s
    end

# File lib/sdl4r/tag.rb, line 228
    def value
      @values[0]
    end

# File lib/sdl4r/tag.rb, line 220
    def value=(value)
      @values[0] = SDL4R.coerce_or_fail(value)
      nil
    end

# File lib/sdl4r/tag.rb, line 447
    def values # :yields: value
      if block_given?
        @values.each { |v| yield v }
        nil
      else
        return @values
      end
    end

# File lib/sdl4r/tag.rb, line 463
    def values=(someValues)
      @values.clear()
      someValues.to_a.each { |v|
        # this is required to ensure validation of types
        add_value(v)
      }
      nil
    end

# File lib/sdl4r/tag.rb, line 732
    def write(output, include_root = false)
      if output.is_a? String
        io = StringIO.new(output)
        close_io = true # indicates we close the IO ourselves
      elsif output.is_a? IO or output.is_a? StringIO
        io = output
        close_io = false # let the caller close the IO
      else
        raise ArgumentError, "'output' should be a String or an IO but was #{output.class}"
      end
      
      if include_root
        io << to_s
      else
        first = true
        children do |child|
          io << $/ unless first
          first = false
          io << child.to_s
        end
      end
      
      io.close() if close_io

      output
    end