Class: Leptris::XML::Element

Inherits:
Node
  • Object
show all
Defined in:
lib/leptris/xml/element.rb

Instance Attribute Summary

Attributes inherited from Node

#c_ptr, #document

Instance Method Summary collapse

Methods inherited from Node

#<=>, #==, #cdata?, #child, #children, #comment?, #css_path, #element?, #element_children, #ensure_alive!, #ensure_writable!, #first_element_child, #initialize, #inner_text, #inspect, #last_element_child, #line, #next_element, #next_sibling, #parent, #path, #previous_element, #previous_sibling, #processing_instruction?, #readonly_document?, #text, #text?, #traverse, #type, #unlink, wrap

Methods included from Searchable

#at, #at_css, #at_xpath, #css, #search, wrap_xpath_first_result, wrap_xpath_result, #xpath

Constructor Details

This class inherits a constructor from Leptris::XML::Node

Instance Method Details

#[](key) ⇒ Object Also known as: attr, get_attribute 



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/leptris/xml/element.rb', line 37

def [](key)
  # BARE names serve from the versioned attributes hash (written
  # name == the only legal key for a no-namespace attribute);
  # materializes on demand, invalidates through the mutation gate
  # (ADR 0003's 1.9.14 extension); a hash read cannot
  # use-after-free. QUALIFIED names (with a colon) go to the
  # engine: they resolve through in-scope declarations, where the
  # written prefix never matters — the hash cannot answer them.
  name = key.to_s
  if @document && !name.include?(":")
    # The hottest read in the library: the memo guard is spelled
    # INLINE rather than through attributes/#memo_hit? — six
    # method dispatches per read was ~40% of the read cost, and
    # the external head-to-head (nokogiri's one C call) was
    # winning on it. Same three-line memo semantics (ADR 0003),
    # incl. the nil-miss — the hash answers misses too.
    values = @attr_values
    unless values && @attributes_version == @document.version
      attributes
      values = @attr_values
    end
    return values[name]
  end
  ensure_alive!
  Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
end

#[]=(key, value) ⇒ Object Also known as: set_attribute 



66
67
68
69
70
71
 
# File 'lib/leptris/xml/element.rb', line 66

def []=(key, value)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_set_attribute(@c_ptr, key.to_s, value.to_s))
  value
end

#add_child(node_or_markup) ⇒ Object Also known as: << 



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/leptris/xml/element.rb', line 261

def add_child(node_or_markup)
  ensure_writable!
  case node_or_markup
  when Leptris::XML::Node
    Leptris::XML::FFI.check_status(
      Leptris::XML::FFI.leptris_element_append_child(@c_ptr, node_or_markup.c_ptr))
    node_or_markup
  when String
    frag = Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
    added = []
    frag.children.each do |n|
      Leptris::XML::FFI.check_status(
        Leptris::XML::FFI.leptris_element_append_child(@c_ptr, n.c_ptr))
      added << n
    end
    Leptris::XML::NodeSet.new(@document, added)
  else
    raise ArgumentError, "add_child expects a Node or String, got #{node_or_markup.class}"
  end
end

#add_namespace_definition(prefix, href) ⇒ Object Also known as: add_namespace 



382
383
384
385
386
387
388
 
# File 'lib/leptris/xml/element.rb', line 382

def add_namespace_definition(prefix, href)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_add_namespace_definition(
      @c_ptr, prefix.to_s, href.to_s))
  Leptris::XML::Namespace.new(self, href.to_s, prefix: prefix.nil? ? nil : prefix.to_s)
end

#add_next_sibling(node) ⇒ Object 



183
184
185
186
187
188
 
# File 'lib/leptris/xml/element.rb', line 183

def add_next_sibling(node)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_insert_after(@c_ptr, node.c_ptr))
  node
end

#add_previous_sibling(node) ⇒ Object 



190
191
192
193
194
195
 
# File 'lib/leptris/xml/element.rb', line 190

def add_previous_sibling(node)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_insert_before(@c_ptr, node.c_ptr))
  node
end

#attribute_nodes ⇒ Object 



159
160
161
162
163
164
165
166
167
 
# File 'lib/leptris/xml/element.rb', line 159

def attribute_nodes
  return @attribute_nodes if memo_hit?(@attribute_nodes_version)
  result = each_attribute.to_a
  if @document
    @attribute_nodes = result
    @attribute_nodes_version = @document.version
  end
  result
end

#attribute_ns(uri, local) ⇒ Object

Expanded-name attribute access (libleptris 1.8.0): URI + local name with XML Namespaces 1.0 semantics — the written prefix never matters, only what it resolves to through this element's in-scope declarations. uri nil/"" matches no-namespace attributes only; xmlns declarations are invisible.



85
86
87
88
89
 
# File 'lib/leptris/xml/element.rb', line 85

def attribute_ns(uri, local)
  ensure_alive!
  Leptris::XML::FFI.leptris_element_attribute_ns(
    @c_ptr, uri&.to_s, local.to_s)
end

#attributes ⇒ Object 



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/leptris/xml/element.rb', line 143

def attributes
  return @attributes if memo_hit?(@attributes_version)
  result = {}
  values = {}
  each_attribute do |attr|
    result[attr.name] = attr
    values[attr.name] = attr.value
  end
  if @document
    @attributes = result
    @attr_values = values
    @attributes_version = @document.version
  end
  result
end

#canonicalize(version = Leptris::XML::FFI::C14N_1_0, inclusive_namespaces = nil, with_comments: false, exclusive: false, mode: nil) ⇒ Object Also known as: c14n 



367
368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/leptris/xml/element.rb', line 367

def canonicalize(version = Leptris::XML::FFI::C14N_1_0,
                 inclusive_namespaces = nil,
                 with_comments: false,
                 exclusive: false,
                 mode: nil)
  resolved_mode = mode || (exclusive ? Leptris::XML::FFI::C14N_MODE_EXCLUSIVE
                                     : Leptris::XML::FFI::C14N_MODE_CANONICAL)
  Leptris::XML::Serialization.canonicalize(
    Leptris::XML::FFI.method(:leptris_c14n_canonicalize_subtree_ex), @c_ptr,
    version: version, mode: resolved_mode,
    inclusive_namespaces: inclusive_namespaces,
    with_comments: with_comments)
end

#children=(node_or_nodes) ⇒ Object 



204
205
206
207
208
209
210
 
# File 'lib/leptris/xml/element.rb', line 204

def children=(node_or_nodes)
  ensure_writable!
  # Remove existing children, then attach the new ones in source order.
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_remove_children(@c_ptr))
  Array(node_or_nodes).each { |n| add_child(n) }
end

#content ⇒ Object 



19
20
21
22
23
24
25
26
27
28
 
# File 'lib/leptris/xml/element.rb', line 19

def content
  return @content if memo_hit?(@content_version)
  ensure_alive!
  result = Leptris::XML::FFI.leptris_element_text(@c_ptr)
  if @document
    @content = result
    @content_version = @document.version
  end
  result
end

#content=(new_content) ⇒ Object 



30
31
32
33
34
35
 
# File 'lib/leptris/xml/element.rb', line 30

def content=(new_content)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_set_text(@c_ptr, new_content.to_s))
  new_content
end

#default_namespace=(href) ⇒ Object 



391
392
393
394
395
396
 
# File 'lib/leptris/xml/element.rb', line 391

def default_namespace=(href)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_set_default_namespace(@c_ptr, href.to_s))
  href
end

#dup ⇒ Object Also known as: clone

Raises:



254
255
256
257
258
 
# File 'lib/leptris/xml/element.rb', line 254

def dup
  copy_ptr = Leptris::XML::FFI.leptris_element_copy(@c_ptr, @document.c_ptr)
  raise Leptris::XML::Error, "leptris_element_copy failed" if copy_ptr.null?
  Leptris::XML::Node.wrap(copy_ptr, @document)
end

#each_attribute ⇒ Object

Iterates the element's attributes via the v1.1.0 linked-list face (one FFI call per attribute; the name_at/value_at indexing API re-walks the list per index, making it O(n^2) per element). The C attribute handle rides along so Attr can serve the per-attribute namespace accessors (libleptris 1.8.0).



110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/leptris/xml/element.rb', line 110

def each_attribute
  return enum_for(:each_attribute) unless block_given?
  ensure_alive!
  attr = Leptris::XML::FFI.leptris_element_first_attribute(@c_ptr)
  until attr.nil? || attr.null?
    name = Leptris::XML::FFI.leptris_attribute_get_name(attr)
    value = Leptris::XML::FFI.leptris_attribute_get_value(@c_ptr, attr)
    yield Leptris::XML::Attr.new(name, value, self, c_handle: attr)
    attr = Leptris::XML::FFI.leptris_attribute_next(attr)
  end
  self
end

#has_attribute_ns?(uri, local) ⇒ Boolean

Returns:

  • (Boolean) 


91
92
93
94
95
 
# File 'lib/leptris/xml/element.rb', line 91

def has_attribute_ns?(uri, local)
  ensure_alive!
  Leptris::XML::FFI.leptris_element_has_attribute_ns(
    @c_ptr, uri&.to_s, local.to_s) != 0
end

#inner_html ⇒ Object

The serialized children (Nokogiri parity): elements serialize through the engine (correct escaping), text is XML-escaped, comments/CDATA/PIs render their literal forms. The complement of #inner_text, which returns the unescaped text content.



343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/leptris/xml/element.rb', line 343

def inner_html
  children.map do |child|
    case child
    when Leptris::XML::Element then child.to_xml
    when Leptris::XML::CDATA # before Text: CDATA subclasses it
      "<![CDATA[#{child.content}]]>"
    when Leptris::XML::Text
      Leptris::XML::Serialization.escape_text(child.content)
    when Leptris::XML::Comment then "<!--#{child.content}-->"
    when Leptris::XML::ProcessingInstruction
      data = child.content
      data.empty? ? "<?#{child.name}?>" : "<?#{child.name} #{data}?>"
    else
      Leptris::XML::Serialization.escape_text(child.content.to_s)
    end
  end.join
end

#key?(name) ⇒ Boolean Also known as: has_attribute?

Returns:

  • (Boolean) 


74
75
76
77
 
# File 'lib/leptris/xml/element.rb', line 74

def key?(name)
  ensure_alive!
  Leptris::XML::FFI.leptris_element_has_attribute(@c_ptr, name.to_s) != 0
end

#keys ⇒ Object 



123
124
125
126
127
128
129
130
131
 
# File 'lib/leptris/xml/element.rb', line 123

def keys
  return @keys if memo_hit?(@keys_version)
  result = each_attribute.to_a.map(&:name)
  if @document
    @keys = result
    @keys_version = @document.version
  end
  result
end

#name ⇒ Object Also known as: node_name 



4
5
6
7
8
 
# File 'lib/leptris/xml/element.rb', line 4

def name
  return @name if @name
  ensure_alive!
  @name = Leptris::XML::FFI.leptris_element_name(@c_ptr)
end

#name=(new_name) ⇒ Object Also known as: node_name= 



11
12
13
14
15
16
 
# File 'lib/leptris/xml/element.rb', line 11

def name=(new_name)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_set_name(@c_ptr, new_name))
  @name = new_name
end

#namespace ⇒ Object 



283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/leptris/xml/element.rb', line 283

def namespace
  return @namespace if memo_hit?(@namespace_version)
  ensure_alive!
  uri = Leptris::XML::FFI.leptris_element_namespace(@c_ptr)
  result =
    if uri.nil? || uri.empty?
      nil
    else
      # The resolved namespace is reached via this element's own
      # prefix, so carry it through: consumers that distinguish
      # {"p" => "urn:p"} from the default {"nil => "urn:p"} need it.
      prefix = Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
      prefix = nil if prefix.nil? || prefix.empty?
      Leptris::XML::Namespace.new(self, uri, prefix: prefix)
    end
  if @document
    @namespace = result
    @namespace_version = @document.version
  end
  result
end

#namespace_definitions ⇒ Object 



305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/leptris/xml/element.rb', line 305

def namespace_definitions
  return @namespace_definitions if memo_hit?(@namespace_definitions_version)
  ensure_alive!
  count = Leptris::XML::FFI.leptris_element_namespace_count(@c_ptr)
  result = count.times.map do |i|
    prefix = Leptris::XML::FFI.leptris_element_namespace_decl_prefix(@c_ptr, i)
    uri = Leptris::XML::FFI.leptris_element_namespace_decl_uri(@c_ptr, i)
    Leptris::XML::Namespace.new(self, uri, prefix: prefix)
  end
  if @document
    @namespace_definitions = result
    @namespace_definitions_version = @document.version
  end
  result
end

#namespaces ⇒ Object 



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/leptris/xml/element.rb', line 321

def namespaces
  return @namespaces if memo_hit?(@namespaces_version)
  scopes = {}
  node = self
  while node.is_a?(Leptris::XML::Element)
    node.namespace_definitions.each do |ns|
      key = ns.prefix ? "xmlns:#{ns.prefix}" : "xmlns"
      scopes[key] ||= ns.href
    end
    node = node.parent
  end
  if @document
    @namespaces = scopes
    @namespaces_version = @document.version
  end
  scopes
end

#prefix ⇒ Object

The element's own namespace prefix (e.g. "foo" for foo:child/), or nil when the element has none.



171
172
173
174
 
# File 'lib/leptris/xml/element.rb', line 171

def prefix
  ensure_alive!
  Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
end

#prepend_child(node) ⇒ Object 



176
177
178
179
180
181
 
# File 'lib/leptris/xml/element.rb', line 176

def prepend_child(node)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_prepend_child(@c_ptr, node.c_ptr))
  node
end

#remove_attribute(name) ⇒ Object Also known as: delete 



97
98
99
100
101
102
 
# File 'lib/leptris/xml/element.rb', line 97

def remove_attribute(name)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_remove_attribute(@c_ptr, name.to_s))
  self
end

#remove_child(node) ⇒ Object 



197
198
199
200
201
202
 
# File 'lib/leptris/xml/element.rb', line 197

def remove_child(node)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_remove_child(@c_ptr, node.c_ptr))
  node
end

#remove_namespace_definition(prefix) ⇒ Object 



398
399
400
401
402
403
 
# File 'lib/leptris/xml/element.rb', line 398

def remove_namespace_definition(prefix)
  ensure_writable!
  Leptris::XML::FFI.check_status(
    Leptris::XML::FFI.leptris_element_remove_namespace_definition(@c_ptr, prefix.to_s))
  self
end

#replace(new_node) ⇒ Object

Replace this element with new_node in the parent's child list. new_node must belong to the same document. Returns new_node.

Raises:



214
215
216
217
218
219
220
 
# File 'lib/leptris/xml/element.rb', line 214

def replace(new_node)
  parent = self.parent
  raise Leptris::XML::Error, "cannot replace a node with no parent" unless parent
  add_next_sibling(new_node)
  parent.remove_child(self)
  new_node
end

#swap(new_node) ⇒ Object

Like #replace but returns self for chaining.



223
224
225
226
 
# File 'lib/leptris/xml/element.rb', line 223

def swap(new_node)
  replace(new_node)
  self
end

#to_xml(indent: 0, no_decl: false, encoding: nil) ⇒ Object 



361
362
363
364
365
 
# File 'lib/leptris/xml/element.rb', line 361

def to_xml(indent: 0, no_decl: false, encoding: nil)
  Leptris::XML::Serialization.to_xml(
    Leptris::XML::FFI.method(:leptris_element_serialize_into), @c_ptr,
    indent: indent, no_decl: no_decl, encoding: encoding)
end

#values ⇒ Object 



133
134
135
136
137
138
139
140
141
 
# File 'lib/leptris/xml/element.rb', line 133

def values
  return @values if memo_hit?(@values_version)
  result = each_attribute.to_a.map(&:value)
  if @document
    @values = result
    @values_version = @document.version
  end
  result
end

#wrap(node_or_markup) ⇒ Object

Wrap this element in a new element parsed from markup or a dup of node. The wrapper takes this element's place in the tree, and this element becomes its only child. Returns self for chaining.

Raises:



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/leptris/xml/element.rb', line 231

def wrap(node_or_markup)
  wrapper =
    case node_or_markup
    when Leptris::XML::Element then node_or_markup.dup
    when String
      frag_doc = Leptris::XML::Document.parse(node_or_markup)
      frag_doc.root or raise Leptris::XML::Error, "wrap markup has no root element"
    else
      raise ArgumentError, "wrap expects a String or Element, got #{node_or_markup.class}"
    end

  parent = self.parent
  raise Leptris::XML::Error, "cannot wrap a node with no parent" unless parent

  # Insert wrapper at self's position, then move self into wrapper.
  # add_child moves self (unlinks from old parent first), so no explicit
  # remove_child needed — and trying to remove after the move corrupts
  # the C tree (libleptris silently handles non-child args badly).
  add_next_sibling(wrapper)
  wrapper.add_child(self)
  self
end