Class: Oga::XML::Element

Inherits:
Node
  • Object
show all
Includes:
ExpandedName, Querying
Defined in:
lib/oga/xml/element.rb

Overview

Class that contains information about an XML element such as the name, attributes and child nodes.

Constant Summary collapse

XMLNS_PREFIX =

The attribute prefix/namespace used for registering element namespaces.

Returns:

  • (String) 
'xmlns'.freeze

Instance Attribute Summary collapse

Attributes inherited from Node

#next, #node_set, #previous

Instance Method Summary collapse

Methods included from ExpandedName

#expanded_name

Methods included from Querying

#at_css, #at_xpath, #css, #xpath

Methods inherited from Node

#after, #before, #children, #children=, #each_ancestor, #html?, #next_element, #parent, #previous_element, #remove, #replace, #root_node, #xml?

Methods included from ToXML

#to_xml

Methods included from Traversal

#each_node

Constructor Details

#initialize(options = {}) ⇒ Element

Returns a new instance of Element

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :name (String) —

    The name of the element.

  • :namespace_name (String) —

    The name of the namespace.

  • :attributes (Array<Oga::XML::Attribute>) —

    The attributes of the element as an Array.



34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/oga/xml/element.rb', line 34

def initialize(options = {})
  super

  @name                 = options[:name]
  @namespace_name       = options[:namespace_name]
  @attributes           = options[:attributes] || []
  @namespaces           = options[:namespaces] || {}
  @available_namespaces = nil

  link_attributes
  register_namespaces_from_attributes
end

Instance Attribute Details

#attributes ⇒ Array<Oga::XML::Attribute>

Returns:



16
17
18
 
# File 'lib/oga/xml/element.rb', line 16

def attributes
  @attributes
end

#name ⇒ String

Returns:

  • (String) 


13
14
15
 
# File 'lib/oga/xml/element.rb', line 13

def name
  @name
end

#namespace_name ⇒ String

Returns:

  • (String) 


10
11
12
 
# File 'lib/oga/xml/element.rb', line 10

def namespace_name
  @namespace_name
end

#namespaces ⇒ Hash

Returns the namespaces registered on this element, or an empty Hash in case of an HTML element.

Returns:

  • (Hash) 


161
162
163
 
# File 'lib/oga/xml/element.rb', line 161

def namespaces
  html? ? {} : @namespaces
end

Instance Method Details

#add_attribute(attribute) ⇒ Object

Adds a new attribute to the element.

Parameters:



100
101
102
103
104
 
# File 'lib/oga/xml/element.rb', line 100

def add_attribute(attribute)
  attribute.element = self

  attributes << attribute
end

#attribute(name) ⇒ Oga::XML::Attribute Also known as: attr

Returns an attribute matching the given name (with or without the namespace).

Examples:

# find an attribute that only has the name "foo"
attribute('foo')

# find an attribute with namespace "foo" and name bar"
attribute('foo:bar')

Parameters:

  • name (String|Symbol) —

    The name (with or without the namespace) of the attribute.

Returns:



67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/oga/xml/element.rb', line 67

def attribute(name)
  name_str, ns = if html?
    [name.to_s, nil]
  else
    split_name(name)
  end

  attributes.each do |attr|
    return attr if attribute_matches?(attr, ns, name_str)
  end

  return
end

#available_namespaces ⇒ Hash

Returns a Hash containing all the namespaces available to the current element.

Returns:

  • (Hash) 


253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/oga/xml/element.rb', line 253

def available_namespaces
  # HTML(5) completely ignores namespaces
  unless @available_namespaces
    if html?
      @available_namespaces = {}
    else
      merged = namespaces.dup
      node   = parent

      while node && node.respond_to?(:namespaces)
        node.namespaces.each do |prefix, ns|
          merged[prefix] = ns unless merged[prefix]
        end

        node = node.parent
      end

      @available_namespaces = merged
    end
  end

  @available_namespaces
end

#default_namespace? ⇒ TrueClass|FalseClass

Returns true if the current element resides in the default XML namespace.

Returns:

  • (TrueClass|FalseClass) 


169
170
171
 
# File 'lib/oga/xml/element.rb', line 169

def default_namespace?
  namespace == DEFAULT_NAMESPACE || namespace.nil?
end

#flush_namespaces_cache ⇒ Object

Flushes the namespaces cache of the current element and all its child elements.



294
295
296
297
298
299
300
301
 
# File 'lib/oga/xml/element.rb', line 294

def flush_namespaces_cache
  @available_namespaces = nil
  @namespace            = nil

  children.each do |child|
    child.flush_namespaces_cache if child.is_a?(Element)
  end
end

#get(name) ⇒ Object Also known as: []

Returns the value of the given attribute.

Examples:

element.get('class') # => "container"

See Also:

  • Oga::XML::Element.[[#attribute]


89
90
91
92
93
 
# File 'lib/oga/xml/element.rb', line 89

def get(name)
  found = attribute(name)

  found ? found.value : nil
end

#inner_text ⇒ String

Returns the text of the current element only.

Returns:

  • (String) 


183
184
185
186
187
188
189
190
191
 
# File 'lib/oga/xml/element.rb', line 183

def inner_text
  text = ''

  text_nodes.each do |node|
    text << node.text
  end

  text
end

#inner_text=(text) ⇒ Object

Sets the inner text of the current element to the given String.

Parameters:

  • text (String) 


210
211
212
213
 
# File 'lib/oga/xml/element.rb', line 210

def inner_text=(text)
  text_node = XML::Text.new(:text => text)
  @children = NodeSet.new([text_node], self)
end

#inspect ⇒ String

Returns:

  • (String) 


216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/oga/xml/element.rb', line 216

def inspect
  segments = []

  [:name, :namespace, :attributes, :children].each do |attr|
    value = send(attr)

    if !value or (value.respond_to?(:empty?) and value.empty?)
      next
    end

    segments << "#{attr}: #{value.inspect}"
  end

  "Element(#{segments.join(' ')})"
end

#literal_html_name? ⇒ TrueClass|FalseClass

Returns true if the current element name is the name of one of the literal HTML elements.

Returns:

  • (TrueClass|FalseClass) 


307
308
309
 
# File 'lib/oga/xml/element.rb', line 307

def literal_html_name?
  Lexer::LITERAL_HTML_ELEMENTS.allow?(name)
end

#namespace ⇒ Oga::XML::Namespace

Returns the namespace of the element.

Returns:



148
149
150
151
152
153
154
155
 
# File 'lib/oga/xml/element.rb', line 148

def namespace
  unless @namespace
    available  = available_namespaces
    @namespace = available[namespace_name] || available[XMLNS_PREFIX]
  end

  @namespace
end

#register_namespace(name, uri, flush = true) ⇒ Object

Registers a new namespace for the current element and its child elements.

Parameters:

  • name (String)
  • uri (String)
  • flush (TrueClass|FalseClass) (defaults to: true)

See Also:

  • Oga::XML::Element.[Oga[Oga::XML[Oga::XML::Namespace[Oga::XML::Namespace#initialize]


239
240
241
242
243
244
245
246
247
 
# File 'lib/oga/xml/element.rb', line 239

def register_namespace(name, uri, flush = true)
  if namespaces[name]
    raise ArgumentError, "The namespace #{name.inspect} already exists"
  end

  namespaces[name] = Namespace.new(:name => name, :uri => uri)

  flush_namespaces_cache if flush
end

#self_closing? ⇒ TrueClass|FalseClass

Returns true if the element is a self-closing element.

Returns:

  • (TrueClass|FalseClass) 


280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/oga/xml/element.rb', line 280

def self_closing?
  self_closing = children.empty?
  root         = root_node

  if root.is_a?(Document) and root.html? \
  and !HTML_VOID_ELEMENTS.allow?(name)
    self_closing = false
  end

  self_closing
end

#set(name, value) ⇒ Object Also known as: []=

Sets the value of an attribute to the given value. If the attribute does not exist it is created automatically.

Parameters:

  • name (String) —

    The name of the attribute, optionally including the namespace.

  • value (String) —

    The new value of the attribute.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/oga/xml/element.rb', line 113

def set(name, value)
  found = attribute(name)

  if found
    found.value = value
  else
    name_str, ns = split_name(name)

    attr = Attribute.new(
      :name           => name_str,
      :namespace_name => ns,
      :value          => value
    )

    add_attribute(attr)
  end
end

#text ⇒ String

Returns the text of all child nodes joined together.

Returns:

  • (String) 


176
177
178
 
# File 'lib/oga/xml/element.rb', line 176

def text
  children.text
end

#text_nodes ⇒ Oga::XML::NodeSet

Returns any Text nodes that are a direct child of this element.

Returns:



197
198
199
200
201
202
203
204
205
 
# File 'lib/oga/xml/element.rb', line 197

def text_nodes
  nodes = NodeSet.new

  children.each do |child|
    nodes << child if child.is_a?(Text)
  end

  nodes
end

#unset(name) ⇒ Oga::XML::Attribute

Removes an attribute from the element.

Parameters:

  • name (String) —

    The name (optionally including namespace prefix) of the attribute to remove.

Returns:



139
140
141
142
143
 
# File 'lib/oga/xml/element.rb', line 139

def unset(name)
  found = attribute(name)

  return attributes.delete(found) if found
end