The tgraph::open operation returns Tcl objects representing e4Graph storages. This page describes the operations supported by these Tcl objects. An object oriented style of programming is supported where the object returned from tgraph::open is used as the command name and the specific operation being invoked is the first argument.
The following operations on tgraph storage objects are supported:
$storage kind | Returns "storage". Can be used to determine the type of tgraph object stored in the Tcl variable storage. |
$storage autocommit | Returns 1 if auto-commit is turned on, or 0 if it is turned off. If auto-commit is turned on, when the storage is closed (e.g. at program termination) all outstanding changes will be committed. |
$storage autocommit on-or-off | on-or-off is a value acceptable to Tcl as a boolean. If the value is interpreted as true, auto-commit is turned on, otherwise it is turned off. |
$storage close | The e4Graph storage represented by storage is closed and potentially all outstanding changes are committed, if auto-commit is on. |
$storage commit | All outstanding changes to the e4Graph storage represented by storage are committed immediately. |
$storage copyto otherstorage ?commit? | Copies the e4Graph data from this storage to otherstorage. If the optional argument commit is present and true, then otherstorage is committed after the copy. After this operation, this storage and otherstorage contain exactly the same e4Graph data. |
$storage delete | The e4Graph storage represented by storage is deleted. All tgraph objects that belong to the storage become invalid and cannot be used for subsequent commands. |
$storage markerexists markername | Returns a boolean indicating whether a marker by the given name exists in this storage. The marker is not created. |
$storage markercount | Returns an integer representing the number of markers defined in the e4Graph storage denoted by storage. |
$storage marker markername | Returns a tgraph marker object that
represents the marker named markername in the e4Graph storage denoted
by storage. This operation creates a new marker by that name in
the e4Graph storage if it wasn't present before, and may increase the number
of markers defined in the storage. This operation also creates a new node,
the node marked by the new marker. The tgraph node object created can be
obtained by the markednode operation, below.
The supported operations on tgraph marker objects are described here. The operations suported on tgraph node objects are described here. |
$storage markednode markername | Returns a tgraph node object that represents the node marked by the marker named markername in the e4Graph storage denoted by storage. This operation creates a new marker by that name in the e4Graph storage if it wasn't present before, and may increate the number of markers defined in the storage. |
$storage isempty | Returns 1 if the e4Graph storage represented by storage is empty (contains no markers, nodes and vertices) and 0 otherwise. |
$storage makeempty | Deletes all markers, nodes and vertices from the e4Graph storage represented by storage. Subsequently all tgraph objects that represent markers, nodes and vertices obtained from that storage become invalid and cannot be used anymore. |
$storage isvalid | Returns 1 if storage represents an open tgraph storage object and the e4Graph storage denoted by it is valid (has not been destroyed). Returns 0 if either of these conditions is not met. |
$storage isdirty | Returns 1 if there are outstanding uncommitted changes for the e4Graph storage object represented by storage, and 0 if a commit operation is not needed to save any changes. |
$storage markdirty | Marks the e4Graph storage represented by storage as having uncommitted outstanding changes. This is done automatically as needed by the implementation of the tgraph package, so you should rarely if ever need to call this operation. |
$storage name | Returns the name of the storage used in the tgraph::open operation that opened this storage. |
$storage driver | Returns the name of the driver used in the tgraph::open operation that opened this storage. |
$storage mode | Returns the open mode used in the tgraph::open operation that opened this storage. Currently always returns "w". |
$storage statistic space kind | Returns a selected statistic measure about a specified allocation space within storage. The value of space can be marker, node, vertex, name, string, int, float, or binary, to select the corresponding allocation space. The value of kind can be used, available, freed, or allocated, to select the statistic measure gathered about allocation within that space. |
$storage foreach marker m ?-keep bool? cmd | Evaluates cmd, a list of Tcl commands, once for each marker in storage. While cmd is being evaluated, the Tcl variable m is bound to each marker in turn. If the optional argument -keep bool is present and bool is true, the Tcl command for each marker is left defined; otherwise, if it wasn't already defined, it is disposed before the next iteration starts. |
$storage foreach node n ?-keep bool? cmd | Evaluates cmd, a list of Tcl commands, once for each node in storage. While cmd is being evaluated, the Tcl variable n is bound to each node in turn. If the optional argument -keep bool is present and bool is true, the Tcl command for each node is left defined; otherwise, if it wasn't already defined, it is disposed before the next iteration starts. |
$storage foreach vertex v ?-keep bool? ?-type t? ?-name n? cmd | Evaluates cmd, a list of Tcl commands, once for each vertex in storage. While cmd is being evaluated, the Tcl variable v is bound to each vertex in turn. If the optional argument -keep bool is present and bool is true, the Tcl command for each vertex is left defined; otherwise, if it wasn't already defined, it is disposed before the next iteration starts. If the optional argument -type t is present, only vertices in this storage with values of type t are visited. If the optional argument -name n is present, only vertices in this storage with the name n are visited. |
$storage callback add elementtype eventtype cmd | Registers cmd, a command prefix, to be called when the specified
eventtype
occurs on the given elementtype. The elementtype is one of marker,
node,
or vertex. The eventtype is one of add or remove.
When the event occurs on an element of the given type in this storage,
the Tcl command name for that element is appended to cmd and the
resulting string is invoked as a Tcl command.
For an explanation of callbacks, see the documentation of e4_Storage. This command returns a token, denoted callbacktoken below, that can be used later to manipulate the registered callback. |
$storage callback delete callbacktoken | Removes a previously registered callback identified by the given callbacktoken. This is the callback token returned by a preceding callback add operation. |
$storage callback get callbacktoken | Retrieves the command prefix cmd registered for the callback identified by the given callbacktoken, a value returned by a preceding callback add operation. |
$storage callback set callbacktoken newcmd | Replaces the previously registered command prefix for callbacktoken with newcmd. The callbacktoken is a value returned by a preceding callback add operation. |
$storage callback kind callbacktoken | Returns a two element list containing the elementtype and eventtype for the callback that callbacktoken denotes, where callbacktoken is a value returned by a preceding callback add operation. |
$storage callback count elementtype eventtype | Returns the number of callbacks registered on this storage for the given elementtype and eventtype. |
$storage callback exists elementtype eventtype | Returns 1 if this storage has any callbacks registered for the given elementtype and eventtype and 0 otherwise. |
$storage get elementtype id | Returns the name of the Tcl command for the element identified by id and elementtype in this storage. The elementtype is one of marker, node, or vertex. The given id must be the id of an element of the specified type in that storage, i.e. the same integer value as returned by the id operation on that element. |
Here is an example showing how to use a tgraph storage object to invoke operations on the underlying e4Graph storage object:
set mystorage [tgraph::open foo.db] puts "The name of $mystorage is [$mystorage name]" puts "mystorage isempty == [$mystorage isempty]" set mymarker [$mystorage marker m1] ... $mystorage close $mystorage foreach node n {puts "$n: [$n vertexcount]"} .. proc callback {pref node} {puts "Hello, $pref of $node"} $mystorage callback add node add "callback addition" set newmarker [$mystorage marker newmarker] ==> Hello, addition of ::tgraph::storage0::nodes::node0