Class: Leptris::XML::Document

Inherits:
Object
  • Object
show all
Includes:
Searchable
Defined in:
lib/leptris/xml/document.rb

Defined Under Namespace

Classes: Freed

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Searchable

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

Constructor Details

#initialize(c_ptr = nil, freed = Freed.new(:alive)) ⇒ Document

Returns a new instance of Document.



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/leptris/xml/document.rb', line 17

def initialize(c_ptr = nil, freed = Freed.new(:alive))
  @c_ptr = c_ptr
  @freed = freed
  # Per-document STRONG cache for Node wrappers, keyed on c_ptr
  # address. Every wrapper is created through Node.wrap, which is the
  # single construction path, so the same C node always yields the
  # same Ruby object. Cleared when the Document is freed — no stale
  # entries.
  #
  # Deliberately NOT ObjectSpace::WeakMap: a weak cache makes wrapper
  # identity a GC race. `doc.root.equal?(doc.root)` failed on the
  # Windows CI matrix (188 examples, the 4 identity specs) because
  # between the two calls the first wrapper was referenced only by
  # the weak map — any GC sweep evicted it and the second call built
  # a fresh object. A strong cache costs at most one wrapper per node
  # actually visited, held until the document dies.
  @wrapper_cache = {}
end

Instance Attribute Details

#c_ptr ⇒ Object (readonly)

Returns the value of attribute c_ptr.



6
7
8
 
# File 'lib/leptris/xml/document.rb', line 6

def c_ptr
  @c_ptr
end

#wrapper_cache ⇒ Object (readonly)

Returns the value of attribute wrapper_cache.



6
7
8
 
# File 'lib/leptris/xml/document.rb', line 6

def wrapper_cache
  @wrapper_cache
end

Class Method Details

.parse(xml_or_io, options: nil) ⇒ Object 



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/leptris/xml/document.rb', line 36

def self.parse(xml_or_io, options: nil)
  xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
  if xml.empty?
    raise Leptris::XML::ParseError, "empty input"
  end
  flags = resolve_flags(options)
  status_ptr = ::FFI::MemoryPointer.new(:int)
  raw =
    if flags.zero?
      Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, status_ptr)
    else
      Leptris::XML::FFI.leptris_parse_string_flags(
        xml, xml.bytesize, flags, status_ptr)
    end
  if raw.null?
    status = status_ptr.read_int
    raise Leptris::XML::ParseError,
      "leptris_parse_string failed (status=#{status})"
  end
  wrap(raw)
end

.parse_file(path) ⇒ Object 



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/leptris/xml/document.rb', line 58

def self.parse_file(path)
  status_ptr = ::FFI::MemoryPointer.new(:int)
  raw = Leptris::XML::FFI.leptris_parse_file(path, status_ptr)
  if raw.null?
    status = status_ptr.read_int
    raise Leptris::XML::ParseError,
      "leptris_parse_file failed (status=#{status})"
  end
  wrap(raw)
end

.wrap(raw_address) ⇒ Object

Convert a raw LeptrisDocument pointer into a Ruby Document with safe GC lifetime management. The finalizer captures the raw address integer (not the Document or Pointer object — those would prevent GC) and shares a one-shot flag with the instance so explicit #free and the GC finalizer can never both call leptris_document_free on the same address.



75
76
77
78
79
80
81
82
 
# File 'lib/leptris/xml/document.rb', line 75

def self.wrap(raw_address)
  addr = raw_address.is_a?(::FFI::Pointer) ? raw_address.address : raw_address
  ptr = ::FFI::Pointer.new(addr)
  freed = Freed.new(:alive)
  doc = new(ptr, freed)
  ObjectSpace.define_finalizer(doc, finalizer(addr, freed))
  doc
end

Instance Method Details

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

Raises:



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/leptris/xml/document.rb', line 179

def canonicalize(version = Leptris::XML::FFI::C14N_1_0,
                 inclusive_namespaces = nil,
                 with_comments: false,
                 exclusive: false,
                 mode: nil)
  raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
  return "" if @c_ptr.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_ex), @c_ptr,
    version: version, mode: resolved_mode,
    inclusive_namespaces: inclusive_namespaces,
    with_comments: with_comments)
end

#create_cdata(content) ⇒ Object

Raises:



128
129
130
131
132
 
# File 'lib/leptris/xml/document.rb', line 128

def create_cdata(content)
  ptr = Leptris::XML::FFI.leptris_cdata_node_create(@c_ptr, content.to_s)
  raise Leptris::XML::Error, "leptris_cdata_node_create failed" if ptr.null?
  Leptris::XML::Node.wrap(ptr, self)
end

#create_comment(content) ⇒ Object

Raises:



122
123
124
125
126
 
# File 'lib/leptris/xml/document.rb', line 122

def create_comment(content)
  ptr = Leptris::XML::FFI.leptris_comment_node_create(@c_ptr, content.to_s)
  raise Leptris::XML::Error, "leptris_comment_node_create failed" if ptr.null?
  Leptris::XML::Node.wrap(ptr, self)
end

#create_element(name) ⇒ Object

Raises:



110
111
112
113
114
 
# File 'lib/leptris/xml/document.rb', line 110

def create_element(name)
  ptr = Leptris::XML::FFI.leptris_element_create(@c_ptr, name)
  raise Leptris::XML::Error, "leptris_element_create failed" if ptr.null?
  Leptris::XML::Node.wrap(ptr, self)
end

#create_processing_instruction(target, data = "") ⇒ Object

Raises:



134
135
136
137
138
 
# File 'lib/leptris/xml/document.rb', line 134

def create_processing_instruction(target, data = "")
  ptr = Leptris::XML::FFI.leptris_pi_node_create(@c_ptr, target.to_s, data.to_s)
  raise Leptris::XML::Error, "leptris_pi_node_create failed" if ptr.null?
  Leptris::XML::Node.wrap(ptr, self)
end

#create_text_node(content) ⇒ Object

Raises:



116
117
118
119
120
 
# File 'lib/leptris/xml/document.rb', line 116

def create_text_node(content)
  ptr = Leptris::XML::FFI.leptris_text_node_create(@c_ptr, content.to_s)
  raise Leptris::XML::Error, "leptris_text_node_create failed" if ptr.null?
  Leptris::XML::Node.wrap(ptr, self)
end

#doctype ⇒ Object Also known as: internal_subset 



151
152
153
154
155
 
# File 'lib/leptris/xml/document.rb', line 151

def doctype
  ptr = Leptris::XML::FFI.leptris_document_internal_subset(@c_ptr)
  return nil if ptr.null?
  Leptris::XML::DocType.new(ptr, self)
end

#document ⇒ Object 



205
 
# File 'lib/leptris/xml/document.rb', line 205

def document; self; end

#dup ⇒ Object Also known as: clone

Raises:



144
145
146
147
148
 
# File 'lib/leptris/xml/document.rb', line 144

def dup
  raw = Leptris::XML::FFI.leptris_document_copy(@c_ptr)
  raise Leptris::XML::Error, "leptris_document_copy failed" if raw.null?
  self.class.wrap(raw)
end

#encoding ⇒ Object 



206
207
208
209
 
# File 'lib/leptris/xml/document.rb', line 206

def encoding
  return nil if @c_ptr.nil?
  Leptris::XML::FFI.leptris_document_encoding(@c_ptr)
end

#fragment(markup) ⇒ Object 



140
141
142
 
# File 'lib/leptris/xml/document.rb', line 140

def fragment(markup)
  Leptris::XML::DocumentFragment.parse(markup, self)
end

#free ⇒ Object 



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

def free
  return if @freed.state == :freed
  @freed.state = :freed
  Leptris::XML::FFI.leptris_document_free(@c_ptr) unless @c_ptr.nil?
  @c_ptr = nil
  @wrapper_cache.clear
end

#name ⇒ Object 



204
 
# File 'lib/leptris/xml/document.rb', line 204

def name; "document"; end

#root ⇒ Object

Raises:



102
103
104
105
106
107
108
 
# File 'lib/leptris/xml/document.rb', line 102

def root
  raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
  return nil if @c_ptr.nil?
  ptr = Leptris::XML::FFI.leptris_document_root(@c_ptr)
  return nil if ptr.null?
  Leptris::XML::Node.wrap(ptr, self)
end

#save(path, **opts) ⇒ Object 



168
169
170
171
172
173
174
175
176
177
 
# File 'lib/leptris/xml/document.rb', line 168

def save(path, **opts)
  opts_struct, _encoding_anchor = Leptris::XML::Serialization.build_options(
    indent: opts.fetch(:indent, 0),
    no_decl: opts.fetch(:no_decl, false),
    encoding: opts[:encoding])
  status = Leptris::XML::FFI.leptris_document_save_file(
    @c_ptr, path, opts_struct.pointer)
  Leptris::XML::FFI.check_status(status)
  self
end

#to_xml(indent: 0, no_decl: false, encoding: nil) ⇒ Object Also known as: to_s, serialize

Raises:



158
159
160
161
162
163
164
 
# File 'lib/leptris/xml/document.rb', line 158

def to_xml(indent: 0, no_decl: false, encoding: nil)
  raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
  return "" if @c_ptr.nil?
  Leptris::XML::Serialization.to_xml(
    Leptris::XML::FFI.method(:leptris_document_serialize), @c_ptr,
    indent: indent, no_decl: no_decl, encoding: encoding)
end