[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Generic tree interface

Bigloo class: node

Abstract bigloo class, the base class for tree node objects. Each node may have a number of named attributes. The attribute names are symbols, the values are usually strings. All the functionality provided as a set of generic procedures, the base node class objects do not hold any data.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 Node attributes

generic procedure: node-atts self::node => pair-nil

List of node attributes. The generic function returns '().

generic procedure: node-add-attribute! self::node attname::symbol attvalue::bstring

Add the attribute named attname and value attvalue to node self. The generic procedure modifies the node attribute list using the node-atts-set! method.

abstract procedure: node-atts-set! self::node atts::pair-nil
Set the node attribute list. This method should be redefined in concrete subclasses.

generic procedure: node-attribute-string self::node attname::symbol => string or #f

Return the value of the first attribute of node self with name attname.

generic procedure: node-attribute-list self::node attname::symbol => pair-nil

Return the list of attributes of node self with name attname.

generic procedure: node-remove-attribute! self::node attname::symbol . attvalues

Remove the attributes of node self with name attname. If optional arguments attvalues are specified, only the attributes which values are within the attvalues list are removed.

generic procedure: node-replace-attribute! self::node attname::symbol . attvalues

Remove the attributes of node self with name attname. If optional arguments attvalues are specified, add new attributes with name attname and values attvalues. Otherwise the procedure effect is equivalent to that of node-remove-attribute!.

generic procedure: node-set-attribute! self::node attname::symbol attvalue::bstring

Set the value of specified attribute. Add the new attribute if necessary.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Node tree navigation

generic procedure: node-parents self::node => pair-nil

Get list of node parents or empty list for top nodes. The generic procedure returns an empty list.

generic procedure: node-parent self::node => node

Return first node as returned by node-parents, or self if node has no parents.

 
(let((self(make-node)))
  ;; generic node nether has parents
  (eq? self(node-parent self)))
=> #t

abstract procedure: node-parents-set! self::node parents::pair-nil

Set the node parents list. This method should be redefined in concrete subclasses.

generic procedure: node-root self::node => node

Return the topmost node of the node tree, recursively calling the node-parent.

generic procedure: node-ancestors self::node => pair-nil

Collect all the node-parents and their parents up to root node or nodes. Node self is also included into the list.

 
(let*((root(make-node))
      (child(make-dl-node (list root))))
  (node-ancestors child))
=> (#0=#|NODE| #|DL-NODE [PARENTS: (#0#)]|)

abstract procedure: node-children-set! self::node children::pair-nil

Set the node children list. This method should be redefined in concrete subclasses.

generic procedure: node-add-child! self::node child::node #!optional after::node

Insert child node child into list of node self children. If the concrete implementation supports ordering of the children, the optional after argument may be specified, to define the node insertion position. The generic procedure uses node-children-set! to do the insertion.

generic procedure: node-bind! self::node parent::node

Insert node self into the tree. The parent node is registered in self's parent list. The self node prepended to all parent's children lists using node-add-child!.

No checking for duplicates is performed.

 
(let*((parent(make-dl-node '()))
      (child(make-dl-node '())))
  (node-bind! child parent)
  parent)

generic procedure: node-bind-descendants! self::node

Do node-bind! for all descendants of node self.

generic procedure: node-children self::node => pair-nil

Return children list of self.

generic procedure: node-subtree self::node => pair

Return list including node self and all the self's descendants.

generic procedure: node-descendants self::node => pair-nil

Defined as:

 
(define-generic(node-descendants::pair-nil self::node)
  (cdr(node-subtree self)))

generic procedure: node-remove! self::node

Remove the node self from the tree. The meaning of this method is subclass implementation-dependent. The generic procedure does nothing.

generic procedure: node-siblings self::node => pair-nil

Return all the children of node returned by node-parent, excluding the node self.

generic procedure: node-rsiblings self::node => pair-nil

Right siblings of node. Return all the children of node returned by node-parent after the node self in children list.

generic procedure: node-lsiblings self::node => pair-nil

Left siblings of node. Return all the children of node returned by node-parent before the node self in children list.

generic procedure: node-ifollows self::node => node

Node that follows the node self or the self node if no node follows.

generic procedure: node-ipreced self::node => node

Node that precedes the node self or the self node if no node precedes.

generic procedure: node-next-hierarchy self::node => node

Return either the node immediately following self in sibling list, or the node following parent node of self, if self is the last node in the list of siblings.

generic procedure: node-prev-hierarchy self::node => node

Return either the node that immediately precedes self in sibling list, or the parent node of self, if self is the first node in the list of siblings.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Node naming and grove lookup

The concrete tree implementation may supply the mechanism for naming tree nodes to let the node be found given the path string is known. The described here naming scheme is based upon LDAP entries naming and used basically by LDAP library See section 9. Bigloo LDAP interface.

Every node has its own Relative Distinct Name (RDN), which must be unique between node siblings. The node RDN along with RDNs of node ancestors form the full node path, which is called Distinct Name (DN). The DN is result of string concatenation of node RDN and RDNs of node ancestors, delimited by comma character.

This module provides the generic procedures for getting and setting node DNs and RDNs along with useful procedures for parsing DN strings.

abstract procedure: node-rdn self::node => bstring

Return the RDN (Relative Distinct Name) of node. The RDN must be unique between node siblings. This method should be redefined in concrete subclasses.

abstract procedure: node-modrdn! self::node newrdn::bstring #!optional deleteatt?

Change the RDN of the node self. Using of optional deleteatt? is specific for LDAP node implementation only.

generic procedure: node-dn self::node => bstring

Get the DN (Distinct Name) if the node self. The generic function constructs DN by concatenating the RDN's of all the ancestors of the node, beginning with the node self itself, delimited by comma character. This procedure is relevant mostly for LDAP nodes.

procedure: dn-parent s::bstring => #unspecified

Parse the DN string, return DN for parent node.

 
(dn-parent "uid=wowa,dc=jet,dc=msk,dc=ru")
=>  "dc=jet,dc=msk,dc=ru"

procedure: dn-rdn s::bstring => bstring
Parse the DN of the node self, return DN of parent node.

 
(dn-rdn "uid=wowa,dc=jet,dc=msk,dc=ru")
=>  "uid=wowa"

procedure: dn-relative dn::bstring base::bstring => #unspecified

`Subtract' two DNs, return the difference as a list of RDNs. Return #f if the dn string does not begins with the base string.

 
(dn-relative
  "s=r,cn=wowa,o=jet,c=ru"
  "o=jet,c=ru")
=> (#"cn=wowa" #"s=r")

generic procedure: node-lookup self::node dn::bstring => node or #f

Lookup node with the dn given in same grove as self. Return #f if not found.

procedure: node-lookup-global dn::bstring =>

Find node in a global node registry.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.4 Other node procedures

generic procedure: node-data self::node => bstring

Some of classes derived from node class are assumed to redefine this method. The generic implementation concatenates the strings obtained by applying node-data to all the children of self.

See the examples in sgml-node description.

procedure: current-node #!optional value

current-node is parameter procedure See section 3. Bigloo Common Library. Plays the role of global variable to store current position in any tree of nodes in end user applications. This procedure is defined for convenience only, none of the library functionality relies on it.

generic procedure: node-title self::node => bstring

Node printed name. It is assumed that subclasses provide its own implementation. By default try the value of cn attribute or uses bigloo class name of the node.

generic procedure: node-display self::node port::output-port

This procedure is called by object-display method for nodes. The generic procedure displays the string as returned by node-title.

generic procedure: node-valid? self::node => bool

The meaning of this method is subclass implementation-dependent. The generic procedure returns #t.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Vladimir Tsichevski on December, 26 2003 using texi2html