Module: Dom

Defined in:
lib/dom/dom.rb,
lib/dom/node.rb,
lib/dom/no_doc.rb,
lib/dom/exceptions.rb

Overview

Storing Objects

The datastructure is based on a treelike concept. Every new inserted object is represented by a node of the tree. There are three types of nodes:

1. {Dom::NoDoc Not documented nodes} that contain other nodes
2. {Dom::Node Documented nodes}, that contain other nodes
3. Leafs of the tree, without children. (Those leafs have to be {Dom::Node documented nodes})

Take the following code-sample:

/**
 *  @function Foo.bar
 */

The tree could look like:

ROOT
 |
Foo (not documented)
 |
bar

Extending this example with two other comments

/**
 *  @object Foo
 */

/**
 *  @object Foo.baz
 */

leads to this tree:

  ROOT
   |
  Foo
  / \
bar baz

Now all nodes are documented (i.e. a CodeObject exists for every node) and ‘Foo` contains two other CodeObjects. `bar` and `baz` are leafs of the tree.

Adding a new node to the tree is as simple as:

Dom.add_node "Foo.bar", my_code_object

Traversing the Tree

There are several method, which you can use to navigate throught the dom. The most important is the children selector.

The tree above could be traversed using the following operations:

Dom[:Foo]
#=> #<CodeObject::Base:72903230 @parent=__ROOT__ @children=[:bar, :baz]> 

Dom[:Foo][:bar]
#=> #<CodeObject::Base:72919910 @parent=Foo @children=[]>

The Root Node

The Dom inherits functionality from it’s root-node. So all method’s invoked on the root node, can be expressed equivalent as member of the Dom.

Dom.root[:some_child] <=> Dom[:some_child]
Dom.root.children <=> Dom.children
Dom.root.print_tree <=> Dom.print_tree

Please note, that some methods of the root-node are hidden behind direct implementations.

Dom.add_node != Dom.root.add_node

Using the Dom for Documents

The Dom can be used in two ways. Because Document-structure can be very similiar to the one of our documentation-elements there are two kind of ‘root-nodes`:

  1. Dom.root

  2. Dom.docs

Examples:

Adding some Nodes

o1 = CodeObject::Object.new "foo"
o2 = CodeObject::Object.new "poo"
o3 = CodeObject::Object.new "bar"
o4 = CodeObject::Object.new "baz"
Dom.add_node "foo", o1
Dom.add_node "foo.poo", o2
Dom.add_node "foo.poo.bar", o3
Dom.add_node "foo.poo.baz", o4

Dom.print_tree
# -foo
#   -poo
#     -bar
#     -baz

See Also:

Defined Under Namespace

Modules: Node Classes: NoDoc, NoNameInPath, NoPathGiven, NodeAlreadyExists, RelativePathInNoContext, WrongPath

Constant Summary collapse

@@cache_path = 
File.expand_path("../../../cache/dom.cache", __FILE__)
@@root = 
NoDoc.new('__ROOT__')
@@docs = 
NoDoc.new('__DOCUMENTS__')

Dom Access-Methods collapse

Dom Management Methods collapse

Caching Methods collapse

Document Objects collapse

Class Method Details

.clear ⇒ Object

Reset the Dom to it’s initial state by creating an empty root-node



127
128
129
130
 
# File 'lib/dom/dom.rb', line 127

def self.clear
  @@root = NoDoc.new('__ROOT__')
  @@docs = NoDoc.new('__DOCUMENTS__')
end

.docs ⇒ Dom::NoDoc

Returns the root of the Documenttree, consisting of Document::Document.

Returns:



166
167
168
 
# File 'lib/dom/dom.rb', line 166

def self.docs
  @@docs
end

.dump(file = @@cache_path) ⇒ Object

Note:

To recreate the Dom from the dump-file, use load.

Serializes and dumps the complete Domtree to the specified ‘path`. If no `path` is given, the default `@@cache_path` will be used instead.

This Method can be useful, to save a specific state of the Domtree to disk and reuse it later, without the need to reconstruct it from zero.

Parameters:

  • file (String) (defaults to: @@cache_path) —

    the filepath, where to write the serialized data



143
144
145
146
147
148
149
150
 
# File 'lib/dom/dom.rb', line 143

def self.dump(file = @@cache_path)
  File.open(file, 'w') do |f|
    f.write Marshal.dump({ 
      :root => @@root,
      :docs => @@docs
    })
  end
end

.load(file = @@cache_path) ⇒ Object

Loads the serialized Dom and replaces the current root node with the one created from the file.

Parameters:

  • file (String) (defaults to: @@cache_path) —

    the filepath from which to load the Dom

See Also:



157
158
159
160
161
 
# File 'lib/dom/dom.rb', line 157

def self.load(file = @@cache_path)
  dom = Marshal.load(File.read(file))
  @@root = dom[:root]
  @@docs = dom[:docs]
end

.root ⇒ Dom::NoDoc

Returns The Dom’s root-node.

Returns:



120
121
122
 
# File 'lib/dom/dom.rb', line 120

def self.root
  @@root
end