Class: XmlNodeStream::Node

Inherits:
Object
  • Object
show all
Defined in:
lib/xml_node_stream/node.rb

Overview

Representation of an XML node.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, parent = nil, attributes = nil, value = nil) ⇒ Node

Create a new Node.

Parameters:

  • name (String) —

    the name of the node

  • parent (Node, nil) (defaults to: nil) —

    the parent node

  • attributes (Hash, nil) (defaults to: nil) —

    the node attributes

  • value (String, nil) (defaults to: nil) —

    the node value



15
16
17
18
19
20
21
22
 
# File 'lib/xml_node_stream/node.rb', line 15

def initialize(name, parent = nil, attributes = nil, value = nil)
  @name = name
  @attributes = attributes
  @parent = parent
  @parent&.add_child(self)
  @value = value
  @path = nil
end

Instance Attribute Details

#name ⇒ Object (readonly)

Returns the value of attribute name.



6
7
8
 
# File 'lib/xml_node_stream/node.rb', line 6

def name
  @name
end

#parent ⇒ Object (readonly)

Returns the value of attribute parent.



6
7
8
 
# File 'lib/xml_node_stream/node.rb', line 6

def parent
  @parent
end

#value ⇒ Object

Returns the value of attribute value.



7
8
9
 
# File 'lib/xml_node_stream/node.rb', line 7

def value
  @value
end

Instance Method Details

#[](name) ⇒ String?

Get the value of the node attribute with the given name.

Parameters:

  • name (String) —

    the attribute name

Returns:

  • (String, nil) —

    the attribute value



92
93
94
 
# File 'lib/xml_node_stream/node.rb', line 92

def [](name)
  @attributes[name] if @attributes
end

#[]=(name, val) ⇒ String

Set the value of the node attribute with the given name.

Parameters:

  • name (String) —

    the attribute name

  • val (String) —

    the attribute value

Returns:

  • (String) —

    the attribute value



101
102
103
 
# File 'lib/xml_node_stream/node.rb', line 101

def []=(name, val)
  attributes[name] = val
end

#add_child(node) ⇒ void

This method returns an undefined value.

Add a child node.

Parameters:

  • node (Node) —

    the child node to add



109
110
111
112
 
# File 'lib/xml_node_stream/node.rb', line 109

def add_child(node)
  children << node
  node.instance_variable_set(:@parent, self)
end

#ancestors ⇒ Array<Node>

Array of all ancestors of the node.

Returns:

  • (Array<Node>) —

    all ancestor nodes



55
56
57
58
59
60
61
 
# File 'lib/xml_node_stream/node.rb', line 55

def ancestors
  if @parent
    [@parent] + @parent.ancestors
  else
    []
  end
end

#append(text, strip_whitespace = true) ⇒ void

This method returns an undefined value.

Append text to the node value. If strip_whitespace is true, whitespace at the beginning and end of the node value will be removed.

Parameters:

  • text (String) —

    the text to append

  • strip_whitespace (Boolean) (defaults to: true) —

    whether to strip whitespace



164
165
166
167
168
169
170
171
 
# File 'lib/xml_node_stream/node.rb', line 164

def append(text, strip_whitespace = true)
  if text
    @value ||= +""
    @last_strip_whitespace = strip_whitespace
    text = text.lstrip if @value.length == 0 && strip_whitespace
    @value << text if text.length > 0
  end
end

#append_cdata(text) ⇒ void

This method returns an undefined value.

Append CDATA to the node value.

Parameters:

  • text (String) —

    the CDATA text to append



154
155
156
 
# File 'lib/xml_node_stream/node.rb', line 154

def append_cdata(text)
  append(text, false)
end

#attributes ⇒ Hash

Get the attributes of the node as a hash.

Returns:

  • (Hash) —

    the node attributes



66
67
68
 
# File 'lib/xml_node_stream/node.rb', line 66

def attributes
  @attributes ||= {}
end

#children ⇒ Array<Node>

Array of the child nodes of the node.

Returns:

  • (Array<Node>) —

    the child nodes



37
38
39
 
# File 'lib/xml_node_stream/node.rb', line 37

def children
  @children ||= []
end

#descendants ⇒ Array<Node>

Array of all descendants of the node.

Returns:

  • (Array<Node>) —

    all descendant nodes



44
45
46
47
48
49
50
 
# File 'lib/xml_node_stream/node.rb', line 44

def descendants
  if children.empty?
    children
  else
    (children + children.collect { |child| child.descendants }).flatten
  end
end

#find(selector) ⇒ Node?

Find the first node that matches the given XPath. See Selector for details.

Parameters:

  • selector (String, Selector) —

    the XPath selector

Returns:

  • (Node, nil) —

    the first matching node or nil



137
138
139
 
# File 'lib/xml_node_stream/node.rb', line 137

def find(selector)
  select(selector).first
end

#finish! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Called after end tag to ensure that whitespace at the end of the string is properly stripped.



177
178
179
 
# File 'lib/xml_node_stream/node.rb', line 177

def finish!
  @value.rstrip! if @value && @last_strip_whitespace
end

#first_child ⇒ Node?

Get the first child node.

Returns:

  • (Node, nil) —

    the first child node or nil



129
130
131
 
# File 'lib/xml_node_stream/node.rb', line 129

def first_child
  @children&.first
end

#path ⇒ String

Get the full XPath of the node.

Returns:

  • (String) —

    the XPath of the node



80
81
82
83
84
85
86
 
# File 'lib/xml_node_stream/node.rb', line 80

def path
  @path ||= if @parent
    "#{@parent.path}/#{@name}"
  else
    "/#{@name}"
  end
end

#release! ⇒ void

This method returns an undefined value.

Release a node by removing it from the tree structure so that the Ruby garbage collector can reclaim the memory. This method should be called after you are done with a node. After it is called, the node will be removed from its parent's children and will no longer be accessible.



29
30
31
32
 
# File 'lib/xml_node_stream/node.rb', line 29

def release!
  @parent&.remove_child(self)
  @path = nil
end

#remove_child(node) ⇒ Node?

Remove a child node.

Parameters:

  • node (Node) —

    the child node to remove

Returns:

  • (Node, nil) —

    the removed node or nil



118
119
120
121
122
123
124
 
# File 'lib/xml_node_stream/node.rb', line 118

def remove_child(node)
  if @children
    if @children.delete(node)
      node.instance_variable_set(:@parent, nil)
    end
  end
end

#root ⇒ Node

Get the root element of the node tree.

Returns:

  • (Node) —

    the root node



73
74
75
 
# File 'lib/xml_node_stream/node.rb', line 73

def root
  @parent ? @parent.root : self
end

#select(selector) ⇒ Array<Node>

Find all nodes that match the given XPath. See Selector for details.

Parameters:

  • selector (String, Selector) —

    the XPath selector

Returns:

  • (Array<Node>) —

    all matching nodes



145
146
147
148
 
# File 'lib/xml_node_stream/node.rb', line 145

def select(selector)
  selector = selector.is_a?(Selector) ? selector : Selector.new(selector)
  selector.find(self)
end