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})

The architecure of the Dom looks pretty much like this:


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

For the example above the full UML-Graph, including the root-node, could look like:


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:

• Node
• NoDoc
• CodeObject::Base
• Document::Document

Defined Under Namespace

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

Constant Summary

@@cache_path =

File.expand_path("../../../cache/dom.cache", __FILE__)

@@root =

NoDoc.new('__ROOT__')

@@docs =

NoDoc.new('__DOCUMENTS__')

Dom Access-Methods

• .root ⇒ Dom::NoDoc

  The Dom’s root-node.

Dom Management Methods

• .clear ⇒ Object

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

Caching Methods

• .dump(file = @@cache_path) ⇒ Object

  Serializes and dumps the complete Domtree (but without last_position) to the specified ‘path`.

• .load(file = @@cache_path) ⇒ Object

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

Document Objects

• .docs ⇒ Dom::NoDoc

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

Class Method Details

.clear ⇒ Object

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

# File 'lib/dom/dom.rb', line 138

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

.docs ⇒ Dom::NoDoc

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

Returns:

• (Dom::NoDoc) —

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

# File 'lib/dom/dom.rb', line 172

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 (but without last_position) 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

# File 'lib/dom/dom.rb', line 154

def self.dump(file = @@cache_path)
  File.open(file, 'w') do |f|
    f.write Marshal.dump @@root
  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:

• dump

# File 'lib/dom/dom.rb', line 165

def self.load(file = @@cache_path)
  @@root = Marshal.load(File.read(file))
end

.root ⇒ Dom::NoDoc

Returns The Dom’s root-node.

Returns:

• (Dom::NoDoc) —

  The Dom’s root-node

# File 'lib/dom/dom.rb', line 131

def self.root
  @@root
end