The tgraph node Object

The tgraph node Object

The root operation on tgraph storage objects returns a tgraph node object. This page describes the operations supported by these Tcl objects. An object oriented style of programming is supported where the object returned from $storage root is used as the command name and the specific operation being invoked is the first argument.

In many operations, a vertex selector is used to specify a vertex. Vertex selectors come in two forms:

A string optionally followed by a positive integer enclosed in matching parentheses. Examples: foo, bar(33). The first example denotes the first occurrence of a vertex named foo, while the second form denotes the 33rd occurrence of a vertex named bar.
A positive integer. Examples: 17, 4203. These denote the vertex whose rank is the specified number. The first vertex's rank in a node is 1, the second 2, and so on.

Many operations use an insert order specifier. Some insert order specifiers are followed by a rank specifier, a positive integer, to determine an absolute position. The allowable insert order specifiers are:

first. The newly inserted vertex becomes the first (ranked 1) in this node. This insert order specifier is not followed by a rank specifier.
last. The newly inserted vertex becomes the last in this node. This insert order specifier is not followed by a rank specifier.
at. Must be followed by a rank specifier. The newly inserted vertex becomes the vertex with the specified rank.
before. Must be followed by a rank specifier. The newly inserted vertex appears immediately before the vertex with the specified rank.
after. Must be followed by a rank specifier. The newly inserted vertex appears immediately following the vertex with the specified rank.

Several operations take parent specifiers as arguments. These are non-negative integers and denote the parent with the specified index for this node.

The tgraph node object supports programmatic extension through definition of new methods. See the method operation described below for the complete details. Such programmatically added methods are invoked through the call operation, also described below.

The following operations on tgraph node objects are supported:

$node kind Returns "node". This operation can be used to determine the kind of tgraph object stored in the Tcl variable node.

$node vertexcount Returns an integer representing the number of vertices in the e4Graph node denoted by node.

$node set vertexselector value ?astype? Sets the selected vertex to the specified value value. If the vertex selector is in a simple format (e.g. foo) and a vertex by that name does not exist, it is created as the last vertex in this node, and the vertex count of this node is incremented by one. If the optional type selector astype is given, it specifies the type to which to convert value before assigning it to the vertex. See the description of the tgraph vertex object for a discussion of allowed value types.

$node add vertexname insertorder ?rank? value ?astype? Adds a new vertex with the given vertexname at the absolute rank selected by insertorder and rank, if present, with the value value. Note that the second argument (the vertexname) is used without interpretation, so you can create vertices with names like 42 or foo(12). However, this is not advised as using vertices with such names is inconvenient. If the optional type selector astype is given, it specifies the type of the value to assign to the new vertex.
Note that if five arguments are given, the fourth is interpreted as a rank and the fifth as the value to assign. This means that you must specify six arguments to give a value for the type selector astype. See the description of the tgraph vertex object for a discussion of allowed value types.

$node get vertexselector ?createval? ?astype? Returns the value of the selected vertex. If the vertex selector is simple (e.g. foo) and a vertex by that name does not exist, and createval is given, the vertex is created as the last vertex in this node and initialized to createval. If the optional type specifier astype is given and the vertex is created by this operation, then createval is converted to the selected type before assigning it to the new vertex.

$node setnode vertexselector Sets the selected vertex to a new node. Creates the underlying e4Graph node object and exports it to Tcl, and returns the new tgraph node object. If the vertex selector is simple (e.g. foo) and a vertex by that name does not exist, it is created as the last vertex in this node and its vertex count is incremented by one.

$node addnode vertexname insertorder ?rank? Creates a new vertex as with the add operation, and sets it to a new node. Creates the underlying e4Graph node object and exports it to Tcl, and returns the new tgraph node object.

$node getvertex vertexselector ?createval? ?astype? Returns a tgraph vertex object for the selected vertex. If the vertex selector is simple (e.g. foo) and a vertex by that name does not exist, and createval is given, the vertex is created as the last vertex in this node and initialized to createval, and the node's vertex count is incremented by one. If the optional type selector astype is given, then createval is converted to the requested type before assigning it to the new vertex.

$node movevertex vertexobj insertorder ?rank? Makes the specified tgraph vertex object, which must denote a valid tgraph vertex object, a vertex in this node, at the absolute rank selected by insertorder and rank, if present. If rank is given, the node must contain at least that many vertices before this operation.

$node detachvertex vertexselector Detaches the selected vertex, which must exist. The vertex count for this node is decremented by one if the operation succeeds.

$node vertextype vertexselector Returns the type of the value stored in the selected vertex, which must exist.

$node vertexname vertexselector Returns the string name of the selected vertex, which must exist.

$node vertexrank vertexselector Returns the integer rank of the selected vertex, which must exist.

$node renamevertex vertexselector newname Renames the selected vertex, which must exist, to newname.

$node exists vertexselector Returns 1 if the vertex specified by vertexselector exists in this node, 0 otherwise.

$node parentcount Returns an integer, the number of distinct parent nodes that contain at least one vertex whose value is this node.

$node isroot Returns 1 if this node is the current root of its storage.

$node parent ?parentindex? Returns the tgraph node object representing the parent of this node selected by parentindex. Parents are indexed from 1, so parentindex must range from 1 to the number of parents for this node.

$node occurrencecount ?parentobj? Returns an integer, the number of vertices in the tgraph node object parentobj whose value is this node.

$node parentrank parentobj Returns an integer, the rank of the node object parentobj in the list of parents of node.

$node nameinparent ?parentindex? Returns the name of the first vertex in the parent node selected by parentindex whose value is this node. If parentindex is not given, the first parent is used.

$node rankinparent ?parentindex? Returns the rank of the first vertex in the parent node selected by parentindex whose value is this node. If parentindex is not given, the first parent is used.

$node root Returns the tgraph node object for the root node of the storage containing this node.

$node storage Returns the tgraph storage object for the e4Graph storage that contains the e4Graph node denoted by this node.

$node detach Detaches the node by detaching all vertices for which it is the value.

$node isdetached If $node is a detached node (it is not the value of any vertices that are attached) then returns 1, else 0.

$node dispose DEPRECATED. This API will be removed before the final version of e4Graph 1.0 is released. This API is a no-op.

$node precache Pre-caches vertex IDs for all vertices in this node, so that vertex lookup will be faster. Vertex IDs are cached only if the storage state permits it. The cache is emptied by actions that change the node in ways that invalidate the cache, e.g. by renaming a vertex or adding a vertex to the node.

$node isvalid Returns 1 if the node is valid (its tgraph storage object has not been closed) or 0 if the node is not valid.

$node method vertexselector args body Sets a vertex selected by vertexselector to a two element Tcl list formed from args and body. This is a convenience operation to define new methods that extend the operations of this node in a programmatic manner. The body has access to the Tcl variable this, which is set to this tgraph node object when the method is invoked by a call operation. If vertexselector is simple (e.g. foo) and a vertex by that name does not exist, it is created as the last vertex in this node, and its vertex count is incremented by one.

$node call vertexselector ?arg ...? The value of the vertex selected by vertexselector is retrieved and invoked as a Tcl procedure. The value of the vertex must be a two element Tcl list. The first element is used as a list of formal parameters, and the second element is used as the body of the procedure to invoke. The formal parameter list is prepended by a Tcl variable named this, and the body is invoked with the specified list of arguments, prepended with the tgraph node object for this node. This has the effect of making the Tcl variable this accessible in the body code when the method is invoked.

$node foreach vertex v ?-type t? ?-name n? cmd Evaluates cmd, a list of Tcl commands, once for each vertex in this node. While cmd is being evaluated, the Tcl variable v is bound to each vertex in turn. If the optional argument -type t is present, only vertices in this node with values of type t are visited. If the optional argument -name n is present, only vertices in this node with name n are visited.

$node foreach parent p cmd Evaluates cmd, a list of Tcl commands, once for each parent node of this node. While cmd is being evaluated, the Tcl variable p is bound to each parent node in turn.

$node id Returns an identifier for node that is unique within the storage containing this node. Subsequently you can give this identifier as an argument to $storage get node $id to retrieve this node.

$node userdata ?newvalue? Sets or retrieves the user data (an integer) that is persistently associated with this node. The Tcl binding will in the future use this field to store additional type information for tgraph objects; the existence of this method is documented here for completeness only.

Here is an example showing how a tgraph node object can be used to manipulate the underlying e4Graph node:

set mystorage [tgraph::open foo.db]
set mynode [$storage root]
puts "$mynode has [$mynode vertexcount] vertices"
set sum 0
for {set i 1; set lim [$mynode vertexcount]}
    {$i < $lim}
    {incr i} { 
      if {[$mynode vertextype $i] == "int"} {
        incr sum [$mynode get $i]
      }
}
puts "The sum of all integer fields is $sum"
==> 317         # This is just an example
$mynode method frobozify {} {
    set sum 0
    for {set i 0; set lim [$this vertexcount]}
        {$i < $lim}
        {incr i} {
          if {[$this vertextype $i] == "int"} {
            incr sum [$this get $i]
          }
    }
    return $sum
}
$mynode call frobozify
==> 317         # This is just an example
set sum 0
$mynode foreach vertex v -type int {incr sum [$v get]}
puts "the sum is $sum"
==> 317         # This is just an example

Please note that the method frobozify is very inefficient and is shown here for demonstration purposes only. A production program would use tgraph vertices instead of repeatedly indexing $mynode, which is exceedingly inefficient. Alternatively, the use of foreach as shown above, is very efficient.


$node kind	Returns "node". This operation can be used to determine the kind of tgraph object stored in the Tcl variable node.
$node vertexcount	Returns an integer representing the number of vertices in the e4Graph node denoted by node.
$node set vertexselector value ?astype?	Sets the selected vertex to the specified value value. If the vertex selector is in a simple format (e.g. foo) and a vertex by that name does not exist, it is created as the last vertex in this node, and the vertex count of this node is incremented by one. If the optional type selector astype is given, it specifies the type to which to convert value before assigning it to the vertex. See the description of the tgraph vertex object for a discussion of allowed value types.
$node add vertexname insertorder ?rank? value ?astype?	Adds a new vertex with the given vertexname at the absolute rank selected by insertorder and rank, if present, with the value value. Note that the second argument (the vertexname) is used without interpretation, so you can create vertices with names like 42 or foo(12). However, this is not advised as using vertices with such names is inconvenient. If the optional type selector astype is given, it specifies the type of the value to assign to the new vertex. Note that if five arguments are given, the fourth is interpreted as a rank and the fifth as the value to assign. This means that you must specify six arguments to give a value for the type selector astype. See the description of the tgraph vertex object for a discussion of allowed value types.
$node get vertexselector ?createval? ?astype?	Returns the value of the selected vertex. If the vertex selector is simple (e.g. foo) and a vertex by that name does not exist, and createval is given, the vertex is created as the last vertex in this node and initialized to createval. If the optional type specifier astype is given and the vertex is created by this operation, then createval is converted to the selected type before assigning it to the new vertex.
$node setnode vertexselector	Sets the selected vertex to a new node. Creates the underlying e4Graph node object and exports it to Tcl, and returns the new tgraph node object. If the vertex selector is simple (e.g. foo) and a vertex by that name does not exist, it is created as the last vertex in this node and its vertex count is incremented by one.
$node addnode vertexname insertorder ?rank?	Creates a new vertex as with the add operation, and sets it to a new node. Creates the underlying e4Graph node object and exports it to Tcl, and returns the new tgraph node object.
$node getvertex vertexselector ?createval? ?astype?	Returns a tgraph vertex object for the selected vertex. If the vertex selector is simple (e.g. foo) and a vertex by that name does not exist, and createval is given, the vertex is created as the last vertex in this node and initialized to createval, and the node's vertex count is incremented by one. If the optional type selector astype is given, then createval is converted to the requested type before assigning it to the new vertex.
$node movevertex vertexobj insertorder ?rank?	Makes the specified tgraph vertex object, which must denote a valid tgraph vertex object, a vertex in this node, at the absolute rank selected by insertorder and rank, if present. If rank is given, the node must contain at least that many vertices before this operation.
$node detachvertex vertexselector	Detaches the selected vertex, which must exist. The vertex count for this node is decremented by one if the operation succeeds.
$node vertextype vertexselector	Returns the type of the value stored in the selected vertex, which must exist.
$node vertexname vertexselector	Returns the string name of the selected vertex, which must exist.
$node vertexrank vertexselector	Returns the integer rank of the selected vertex, which must exist.
$node renamevertex vertexselector newname	Renames the selected vertex, which must exist, to newname.
$node exists vertexselector	Returns 1 if the vertex specified by vertexselector exists in this node, 0 otherwise.
$node parentcount	Returns an integer, the number of distinct parent nodes that contain at least one vertex whose value is this node.
$node isroot	Returns 1 if this node is the current root of its storage.
$node parent ?parentindex?	Returns the tgraph node object representing the parent of this node selected by parentindex. Parents are indexed from 1, so parentindex must range from 1 to the number of parents for this node.
$node occurrencecount ?parentobj?	Returns an integer, the number of vertices in the tgraph node object parentobj whose value is this node.
$node parentrank parentobj	Returns an integer, the rank of the node object parentobj in the list of parents of node.
$node nameinparent ?parentindex?	Returns the name of the first vertex in the parent node selected by parentindex whose value is this node. If parentindex is not given, the first parent is used.
$node rankinparent ?parentindex?	Returns the rank of the first vertex in the parent node selected by parentindex whose value is this node. If parentindex is not given, the first parent is used.
$node root	Returns the tgraph node object for the root node of the storage containing this node.
$node storage	Returns the tgraph storage object for the e4Graph storage that contains the e4Graph node denoted by this node.
$node detach	Detaches the node by detaching all vertices for which it is the value.
$node isdetached	If $node is a detached node (it is not the value of any vertices that are attached) then returns 1, else 0.
$node dispose	DEPRECATED. This API will be removed before the final version of e4Graph 1.0 is released. This API is a no-op.
$node precache	Pre-caches vertex IDs for all vertices in this node, so that vertex lookup will be faster. Vertex IDs are cached only if the storage state permits it. The cache is emptied by actions that change the node in ways that invalidate the cache, e.g. by renaming a vertex or adding a vertex to the node.
$node isvalid	Returns 1 if the node is valid (its tgraph storage object has not been closed) or 0 if the node is not valid.
$node method vertexselector args body	Sets a vertex selected by vertexselector to a two element Tcl list formed from args and body. This is a convenience operation to define new methods that extend the operations of this node in a programmatic manner. The body has access to the Tcl variable this, which is set to this tgraph node object when the method is invoked by a call operation. If vertexselector is simple (e.g. foo) and a vertex by that name does not exist, it is created as the last vertex in this node, and its vertex count is incremented by one.
$node call vertexselector ?arg ...?	The value of the vertex selected by vertexselector is retrieved and invoked as a Tcl procedure. The value of the vertex must be a two element Tcl list. The first element is used as a list of formal parameters, and the second element is used as the body of the procedure to invoke. The formal parameter list is prepended by a Tcl variable named this, and the body is invoked with the specified list of arguments, prepended with the tgraph node object for this node. This has the effect of making the Tcl variable this accessible in the body code when the method is invoked.
$node foreach vertex v ?-type t? ?-name n? cmd	Evaluates cmd, a list of Tcl commands, once for each vertex in this node. While cmd is being evaluated, the Tcl variable v is bound to each vertex in turn. If the optional argument -type t is present, only vertices in this node with values of type t are visited. If the optional argument -name n is present, only vertices in this node with name n are visited.
$node foreach parent p cmd	Evaluates cmd, a list of Tcl commands, once for each parent node of this node. While cmd is being evaluated, the Tcl variable p is bound to each parent node in turn.
$node id	Returns an identifier for node that is unique within the storage containing this node. Subsequently you can give this identifier as an argument to $storage get node $id to retrieve this node.
$node userdata ?newvalue?	Sets or retrieves the user data (an integer) that is persistently associated with this node. The Tcl binding will in the future use this field to store additional type information for tgraph objects; the existence of this method is documented here for completeness only.