Module: Moxml::ElementBehavior

Included in:
Element
Defined in:
lib/moxml/element.rb

Overview

Instance behavior for Moxml::Element, extracted so the leptris adapter can extend natives with it in place (issue #230); the class remains the consumer-facing contract.

Instance Method Summary collapse

Instance Method Details

#[](name) ⇒ Object

Unified XML-correct name resolution (see AttributeResolver): bare names match only no-namespace attributes; prefixed names resolve through in-scope declarations to expanded names.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/moxml/element.rb', line 61

def [](name)
  key = name.to_s
  # Bare names on qualified-name engines: one adapter call with
  # the adapter's own marker restoration (bare_attr_value). The
  # resolver's expanded-name semantics only pay for prefixed
  # names, where resolution is real work.
  adapter = self.adapter
  # Capability memo: the adapter predicate is a per-read
  # dispatch for a lifetime constant.
  if !key.include?(":") &&
      ((@bare_qname_safe ||= adapter.bare_get_qname_safe?) == true)
    # The entity-restore decision rides the wrapper's generation
    # memo (as Element#text) — the adapter-level probe walks to
    # the document and the attachment store on every read, which
    # dominated the fast path.
    value = adapter.bare_attr_value(@native, key)
    return adapter.restore_entities(value) if value.is_a?(String) && entity_bearing?

    return value
  end

  cache = attribute_read_cache
  unless cache.key?(key)
    cache[key] = if key.include?(":")
                   Moxml::AttributeResolver.resolve_value(self, key)
                 else
                   Moxml::AttributeResolver.resolve(self, key)&.value
                 end
  end
  cache[key]
end

#[]=(name, value) ⇒ Object

Write path shares the resolver's expanded-name semantics (see AttributeResolver.assign): bare names target no-namespace attributes only; prefixed names replace by namespace URI and require a declared prefix. Cache coherence is the resolver's.



51
52
53
54
55
56
 
# File 'lib/moxml/element.rb', line 51

def []=(name, value)
  # Every assign path (native set or value=) ends in
  # invalidate_attribute_cache!, which bumps the generation —
  # a leading bump here was one per write.
  Moxml::AttributeResolver.assign(self, name, normalize_xml_value(value))
end

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



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/moxml/element.rb', line 165

def add_namespace(prefix, uri)
  adapter.create_namespace(@native, prefix, uri,
                           namespace_validation_mode: context.config.namespace_validation_mode)
  invalidate_namespace_cache!
  self
rescue ValidationError => e
  # Re-raise as NamespaceError, provide attributes for error context
  # but the to_s will only add details if provided
  raise Moxml::NamespaceError.new(
    e.message,
    prefix: prefix,
    uri: uri,
    element: self,
  )
end

#append_xml(fragment) ⇒ Moxml::Element

Append a raw XML fragment's top-level nodes as children.

Bulk construction rides the engine's parser instead of per-node create/attach calls — measured 2.0x faster than per-node building through the same adapter, and faster than per-node building on Nokogiri (the parse is C; the per-node path pays an FFI crossing per node).

The fragment must be namespace-self-contained (declarations inside it ride along with the moved subtrees; prefixes relying on THIS element's scope must be spelled out in the fragment) and well-formed as the content of a single wrapper element — declarations and doctypes raise ParseError.

Returns:

  • self



151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/moxml/element.rb', line 151

def append_xml(fragment)
  if context.config.adapter_name == :ox
    raise Moxml::AdapterError.new(
      "append_xml is not supported by the Ox adapter (its customized node wrappers do not survive cross-document attachment)",
      adapter: "Ox", operation: "append_xml",
    )
  end

  wrapper = context.parse("<m>#{fragment}</m>")
  children = wrapper.root.children.to_a
  children.each { |child| add_child(child) }
  self
end

#attribute(name) ⇒ Object 



93
94
95
 
# File 'lib/moxml/element.rb', line 93

def attribute(name)
  Moxml::AttributeResolver.resolve(self, name)
end

#attribute_read_cache ⇒ Object

Resolution reads the element.s in-scope namespaces, so the cache rides the context.s namespace-scope generation clock — every attribute or namespace mutation anywhere bumps it.



100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/moxml/element.rb', line 100

def attribute_read_cache
  generation = context.namespace_scope_generation
  # @attribute_cache.nil? covers the local invalidation clears —
  # a value or list change without a scope bump (see
  # invalidate_local_attribute_cache!) — so writes never allocate
  # a replacement hash; the next read materializes one lazily.
  if @attribute_cache.nil? || @attribute_cache_generation != generation
    @attribute_cache = {}
    @attribute_cache_generation = generation
  end
  @attribute_cache
end

#attributes ⇒ Object 



118
119
120
121
122
123
124
125
126
127
 
# File 'lib/moxml/element.rb', line 118

def attributes
  # Primed like Node.wrap: the adapter and type are known at
  # mint, so the first name/value/attribute? access skips the
  # context hop and the adapter's type probe.
  @attributes ||= adapter.attributes(@native).map do |attr|
    a = Wrappers::Attribute.new(attr, context, adapter, :attribute)
    a.parent_node = self
    a
  end
end

#declared_namespaces ⇒ Object

The element's OWN namespace declarations as [prefix, uri] pairs (nil prefix = default namespace) — not the inherited scope. The shape materialize records carry (issue #138).



226
227
228
229
230
231
 
# File 'lib/moxml/element.rb', line 226

def declared_namespaces
  adapter.namespace_definitions(@native).map do |ns|
    wrapper = Wrappers::Namespace.new(ns, context)
    [wrapper.prefix, wrapper.uri]
  end
end

#expanded_name ⇒ Object

Returns the expanded name including namespace prefix



27
28
29
30
31
32
33
 
# File 'lib/moxml/element.rb', line 27

def expanded_name
  if namespace_prefix && !namespace_prefix.empty?
    "#{namespace_prefix}:#{name}"
  else
    name
  end
end

#find_all(xpath) ⇒ Object 



321
322
323
 
# File 'lib/moxml/element.rb', line 321

def find_all(xpath)
  xpath(xpath).to_a
end

#find_element(xpath) ⇒ Object

Convenience find methods



317
318
319
 
# File 'lib/moxml/element.rb', line 317

def find_element(xpath)
  at_xpath(xpath)
end

#get(attr_name) ⇒ Object

Returns attribute value by name (used by XPath engine)



114
115
116
 
# File 'lib/moxml/element.rb', line 114

def get(attr_name)
  self[attr_name]
end

#identifier ⇒ String

Returns the primary identifier for this element (its tag name)

Returns:

  • the element name



22
23
24
 
# File 'lib/moxml/element.rb', line 22

def identifier
  name
end

#in_scope_namespaces ⇒ Object

Returns all namespaces in scope for this element, including those inherited from ancestor elements.



235
236
237
238
239
240
241
242
243
244
 
# File 'lib/moxml/element.rb', line 235

def in_scope_namespaces
  generation = context.namespace_scope_generation
  if @in_scope_namespaces.nil? || @in_scope_generation != generation
    @in_scope_namespaces = adapter.in_scope_namespaces(@native).map do |ns|
      Wrappers::Namespace.new(ns, context)
    end
    @in_scope_generation = generation
  end
  @in_scope_namespaces
end

#inner_text ⇒ Object 



266
267
268
269
 
# File 'lib/moxml/element.rb', line 266

def inner_text
  text = raw_inner_text
  entity_bearing? ? adapter.restore_entities(text) : text
end

#inner_xml ⇒ Object 



277
278
279
 
# File 'lib/moxml/element.rb', line 277

def inner_xml
  adapter.inner_xml(@native)
end

#inner_xml=(xml) ⇒ Object 



281
282
283
284
285
286
 
# File 'lib/moxml/element.rb', line 281

def inner_xml=(xml)
  wrapper = "_moxml_inner_#{Process.pid}_#{object_id}"
  doc = context.parse("<#{wrapper}>#{xml}</#{wrapper}>")
  adapter.replace_children(@native, doc.root.children.map(&:native))
  invalidate_children_cache!
end

#invalidate_attribute_cache! ⇒ Object

Called by the namespace-scoped attribute paths (xmlns writes and removals) and Attribute#name=. Clears the attribute list and the resolved-read cache, and bumps the context generation so cross-wrapper reads recompute.



349
350
351
352
353
 
# File 'lib/moxml/element.rb', line 349

def invalidate_attribute_cache!
  @attributes = nil
  @attribute_cache = nil
  context.bump_namespace_scope_generation
end

#invalidate_attribute_value_cache! ⇒ Object

Attribute mutations that cannot change namespace scope (bare and non-xmlns prefixed names) invalidate locally: the resolved-read cache alone for value writes, the wrapper list too when the attribute set changes. No context generation bump — that would evict every wrapper's caches document-wide on each write of a bulk build.



336
337
338
 
# File 'lib/moxml/element.rb', line 336

def invalidate_attribute_value_cache!
  @attribute_cache = nil
end

#invalidate_local_attribute_cache! ⇒ Object 



340
341
342
343
 
# File 'lib/moxml/element.rb', line 340

def invalidate_local_attribute_cache!
  @attributes = nil
  @attribute_cache = nil
end

#invalidate_namespace_cache! ⇒ Object

Clear the namespace caches and bump the context's scope generation so every wrapper — including ones not reachable from any children cache — recomputes on next read.



358
359
360
361
362
363
 
# File 'lib/moxml/element.rb', line 358

def invalidate_namespace_cache!
  @namespaces = nil
  @namespace_definitions = nil
  @in_scope_namespaces = nil
  context.bump_namespace_scope_generation
end

#name ⇒ Object 



8
9
10
11
12
13
 
# File 'lib/moxml/element.rb', line 8

def name
  # The adapter read is an FFI call plus (on several adapters) a
  # defensive string copy; names only change through name= and
  # native adoption, both of which clear this.
  @name ||= adapter.node_name(@native)
end

#name=(value) ⇒ Object 



15
16
17
18
 
# File 'lib/moxml/element.rb', line 15

def name=(value)
  @name = nil
  adapter.set_node_name(@native, value)
end

#namespace ⇒ Object

it's NOT the same as namespaces.first



183
184
185
186
 
# File 'lib/moxml/element.rb', line 183

def namespace
  ns = adapter.namespace(@native)
  ns && Wrappers::Namespace.new(ns, context)
end

#namespace=(ns_or_hash) ⇒ Object

add the prefix to the element name and add the namespace to the list of namespace definitions



190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/moxml/element.rb', line 190

def namespace=(ns_or_hash)
  if ns_or_hash.is_a?(Hash)
    adapter.set_namespace(
      @native,
      adapter.create_namespace(@native, *ns_or_hash.to_a.first,
                               namespace_validation_mode: context.config.namespace_validation_mode),
    )
  else
    adapter.set_namespace(@native, ns_or_hash&.native)
  end
  invalidate_namespace_cache!
end

#namespace_definitions ⇒ Object

The element's OWN namespace declarations only (not inherited). C14n's visibly-utilized calculation and the materializer's declaration pairs want exactly this shape.



215
216
217
218
219
220
221
 
# File 'lib/moxml/element.rb', line 215

def namespace_definitions
  return @namespace_definitions unless @namespace_definitions.nil?

  @namespace_definitions = adapter.namespace_definitions(@native).map do |ns|
    Wrappers::Namespace.new(ns, context)
  end
end

#namespace_name ⇒ Object

Returns the namespace URI of this element (alias for namespace_uri)



247
248
249
 
# File 'lib/moxml/element.rb', line 247

def namespace_name
  namespace_uri
end

#namespace_prefix ⇒ Object

Returns the namespace prefix of this element



36
37
38
39
 
# File 'lib/moxml/element.rb', line 36

def namespace_prefix
  ns = namespace
  ns&.prefix
end

#namespace_uri ⇒ Object

Returns the namespace URI of this element



42
43
44
45
 
# File 'lib/moxml/element.rb', line 42

def namespace_uri
  ns = namespace
  ns&.uri
end

#namespaces ⇒ Object

All namespaces IN SCOPE for this element — its own declarations plus everything inherited from ancestors — matching the Nokogiri #namespaces contract consumers port against (issue #198: this returned only own declarations, losing ancestor scope under every backend).



208
209
210
 
# File 'lib/moxml/element.rb', line 208

def namespaces
  in_scope_namespaces
end

#nodes ⇒ Object

Alias for children (used by XPath engine)



326
327
328
 
# File 'lib/moxml/element.rb', line 326

def nodes
  children
end

#raw_inner_text ⇒ Object

Returns inner text without entity marker restoration. Used internally when raw content with markers is needed (e.g., for DOM construction).



273
274
275
 
# File 'lib/moxml/element.rb', line 273

def raw_inner_text
  adapter.inner_text(@native)
end

#remove_attribute(name) ⇒ Object 



129
130
131
132
133
134
 
# File 'lib/moxml/element.rb', line 129

def remove_attribute(name)
  # Both remove paths end in invalidate_attribute_cache!, which
  # bumps the generation.
  Moxml::AttributeResolver.remove(self, name)
  self
end

#set_attributes(attributes_hash) ⇒ Object

Bulk attribute setting



305
306
307
308
 
# File 'lib/moxml/element.rb', line 305

def set_attributes(attributes_hash)
  attributes_hash.each { |name, value| self[name] = value }
  self
end

#text ⇒ Object Also known as: content 



251
252
253
254
255
256
257
 
# File 'lib/moxml/element.rb', line 251

def text
  val = adapter.text_content(@native)
  # Entity-free documents (the common case) skip the marker
  # restore scans entirely — the per-wrapper entity_bearing?
  # memo rides the adapter's serialize generation.
  entity_bearing? ? adapter.restore_entities(val) : val
end

#text=(content) ⇒ Object 



261
262
263
264
 
# File 'lib/moxml/element.rb', line 261

def text=(content)
  adapter.set_text_content(@native, normalize_xml_value(content))
  invalidate_children_cache!
end

#with_attribute(name, value) ⇒ Object

Fluent interface methods



289
290
291
292
 
# File 'lib/moxml/element.rb', line 289

def with_attribute(name, value)
  self[name] = value
  self
end

#with_child(child) ⇒ Object

Chainable child addition



311
312
313
314
 
# File 'lib/moxml/element.rb', line 311

def with_child(child)
  add_child(child)
  self
end

#with_namespace(prefix, uri) ⇒ Object 



294
295
296
297
 
# File 'lib/moxml/element.rb', line 294

def with_namespace(prefix, uri)
  add_namespace(prefix, uri)
  self
end

#with_text(content) ⇒ Object 



299
300
301
302
 
# File 'lib/moxml/element.rb', line 299

def with_text(content)
  self.text = content
  self
end