Message/Util/ManakaiNode.dis

Module:
  @QName:
    Util:ManakaiNode
  @FullName:
    @@lang: en
    @@@:
      Manakai Generic Node Implementation
  @Namespace:
    http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/ManakaiNode#
  
  @Description:
    @@lang:en
    @@@:
      The <Module::Util:ManakaiNode> module provides a basic 
      implementation for glaph (perhaps tree) structures. 

  @DISCore:author: DISCore|Wakaba
  @License:
     license:Perl+MPL
  @Date:
    $Date: 2005/10/12 00:31:05 $
  
  @Require:
    @@Module:
      @@@QName: DISlib|DISPerl
      @@@WithFor: ManakaiDOM|all

  @DefaultFor:
    ManakaiDOM:Perl

Namespace:
  @dis:
    http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#dis--
  @DISlib:
    http://suika.fam.cx/~wakaba/archive/2004/dis/
  @kwd:
    http://suika.fam.cx/~wakaba/archive/2005/rfc2119/
  @lang:
    http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#
  @license:
    http://suika.fam.cx/~wakaba/archive/2004/8/18/license#
  @ManakaiDOM:
    http://suika.fam.cx/~wakaba/archive/2004/8/18/manakai-dom#
  @mn:
    http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/ManakaiNode#
  @rdf:
    http://www.w3.org/1999/02/22-rdf-syntax-ns#
  @rdfs:
    http://www.w3.org/2000/01/rdf-schema#
  @Util:
    http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/

ResourceDef:
  @QName:
    Util:
  @rdf:type:
    dis:ModuleGroup
  @FullName:
    @@lang:en
    @@@:
      The manakai support modules
  @DISPerl:packageName:
    Message::Util::
  @DISPerl:interfacePackageName:
    Message::Util::IF::
  @ImplNote:
    @@lang:en
    @@@:
      This resource is also defined in <Module::Util:DIS> and
      <Module::Util:PerlCode> modules.

## -- Internal node object

ClassDef:
  @resourceFor: ManakaiDOM|ForIF
  @resourceFor: ManakaiDOM|ForClass
  
  @QName:
    @@@: NodeStem
    @@ForCheck: ManakaiDOM|ForIF

  @QName:
    @@@: ManakaiNodeStem
    @@ForCheck: ManakaiDOM|ForClass

  @Implement:
    @@@: NodeStem
    @@ForCheck: ManakaiDOM|ForClass

  @Implement:
    @@@: NodeStem
    @@ForCheck: ManakaiDOM|ForClass

  @Description:
    @@lang:en
    @@@:
      Internal (actual) node objects that is accessed via 
      <Class::ManakaiDOM:ManakaiDOMNodeReference> objects referring it. 
  @ImplNote:
    @@lang:en
    @@@:
      No public interface should be defined for any class inheriting 
      this class - applications should access to nodes only via 
      <Class::ManakaiDOM:ManakaiDOMNodeReference> objects. 
  @ImplNote:
    @@ForCheck: ManakaiDOM|ForClass
    @@lang:en
    @@@:
      A <Class::> object is a blessed hash 
      reference.  Each hash key and value pair is called as a 
      <DFN::property>.  Currently, several core properties  
      are defined.  Applications of this class
      define additional properties for their own purpose and scope. 

  @IntMethod:
    @@Name: new
    @@Description:
      @@@lang:en
      @@@@: 
        Constructs a new instance of 
        <Class::ManakaiDOM:ManakaiDOMNodeObject> and returns it.
    @@Param:
      @@@Name: className
      @@@Type: DISLang|String||ManakaiDOM|all
      @@@enDesc:
        The name of a class which is typically used as reference
        to the node.  The class <kwd:SHOULD> implement the 
        <IF::NodeRef> interface.  The <QUOTE::dis> definition
        for the class <kwd:SHOULD> play the role of <Q::mn|NodeRefRole
        ||ManakaiDOM|all>.
    @@Return:
      @@@Type: NodeStem
      @@@Description:
        @@@@lang:en
        @@@@@: 
          The newly created <Class::ManakaiDOM:ManakaiDOMNodeObject> instance.
      @@@PerlDef: 
          my $grc = 0;
          $r = bless {
            <H::mn:type>   => $className,
            <H::mn:groveReferenceCounter> => \$grc,
            <H::mn:rc>     => 0,
            <H::mn:treeID> => \ (<Code::ManakaiDOM:generateUniqueID>),
            <H::mn:nodeID> => <Code::ManakaiDOM:generateUniqueID>,
          }, ref $self || $self;

  @IntMethod:
    @@Name: newNode
    @@enDesc:
      Returns a new node that belongs to the same grove with
      the node.
    @@Param:
      @@@Name: className
      @@@Type: DISLang|String||ManakaiDOM|all
      @@@enDesc:
        The name of a class which is typically used as reference
        to the node.  The class <kwd:SHOULD> implement the 
        <IF::NodeRef> interface.  The <QUOTE::dis> definition
        for the class <kwd:SHOULD> play the role of <Q::mn|NodeRefRole
        ||ManakaiDOM|all>.
    @@Return:
      @@@Type: NodeStem
      @@@enDesc: The newly created node.
      @@@PerlDef:
        $r = bless {
          <H::mn:type>   => $className,
          <H::mn:groveReferenceCounter>
                         => $self->{<H::mn:groveReferenceCounter>},
          <H::mn:rc>     => 0,
          <H::mn:treeID> => $self->{<H::mn:treeID>},
          <H::mn:nodeID> => <Code::ManakaiDOM:generateUniqueID>,
        }, ref $self;

  @ResourceDef:
    @@QName: getNewReference
    @@rdf:type: DISPerl|BlockCode
    @@ForCheck: ManakaiDOM|ForClass
    @@Description:
      @@@lang:en
      @@@@:
        Creates a new node reference object. 
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $object
      @@@Type: NodeStem
      @@@In:1
      @@@enDesc:
        A node object for which a reference is created.
      @@@DISPerl:paramStyle: var
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $ref
      @@@Type: NodeRef
      @@@Out:1
      @@@enDesc:
        A node reference for <P::$object>.  It may or may not 
        be same as <P::$object>.
      @@@DISPerl:paramStyle: var
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $class
      @@@Type: DISLang|String||ManakaiDOM|all
      @@@enDesc:
        A package name with which <P::$ref> is blessed. 
      @@@In:1
      @@@DISPerl:paramStyle: any
    @@PerlDef:
      $object->{<H::mn:rc>}++;
      ${$object->{<H::mn:groveReferenceCounter>}}++;
      $ref = bless {
        <H::mn:node> => $object,
      }, $class;

  @ResourceDef:
    @@QName: getWeakReference
    @@rdf:type: DISPerl|BlockCode
    @@ForCheck: ManakaiDOM|ForClass
    @@Description:
      @@@lang:en
      @@@@:
        Creates a new weak node reference object. 
        \
        The weak node reference is actually a node reference
        except that this code fragment does not increment
        the reference count of the object.  When all non-weak 
        references to the object are destructed, then
        the object is destructed and any operation via 
        weak references will lead unexpected result.
        \
        {NOTE:: It is intended that internal code creates a weak reference
                so that it gets access to public interface. 
        \
        }
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $object
      @@@Type: NodeStem
      @@@In:1
      @@@enDesc:
        A node object for which a reference is created.
      @@@DISPerl:paramStyle: var
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $ref
      @@@Type: NodeRef
      @@@Out:1
      @@@enDesc:
        A node reference for <P::$object>.  It may or may not 
        be same as <P::$object>.
      @@@DISPerl:paramStyle: var
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $class
      @@@Type: DISLang|String||ManakaiDOM|all
      @@@enDesc:
        A package name with which <P::$ref> is blessed. 
      @@@In:1
      @@@DISPerl:paramStyle: any
    @@PerlDef:
      $ref = bless {
        <H::mn:node> => $object,
        <H::mn:isWeak> => true,
      }, $class;

  @ResourceDef:
    @@QName: getWeakRef
    @@rdf:type: DISPerl|InlineCode
    @@ForCheck: ManakaiDOM|ForClass
    @@Description:
      @@@lang:en
      @@@@:
        Creates a new weak node reference object.
        \
        The weak node reference is actually a node reference
        except that this code fragment does not increment
        the reference count of the object.  When all non-weak
        references to the object are destructed, then
        the object is destructed and any operation via
        weak references will lead unexpected result.
        \
        {NOTE:: It is intended that internal code creates a weak reference
                so that it gets access to public interface.
        \
        }
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $object
      @@@Type: NodeStem
      @@@In:1
      @@@enDesc:
        A node object for which a reference is created.
      @@@DISPerl:paramStyle: var
    @@ResourceDef:
      @@@rdf:type:
        DISPerl:CodeParameter
      @@@Name: $class
      @@@Type: DISLang|String||ManakaiDOM|all
      @@@enDesc:
        A package name with which <P::$ref> is blessed.
      @@@In:1
      @@@DISPerl:paramStyle: any
    @@PerlDef:
      (bless {
        <H::mn:node> => $object,
        <H::mn:isWeak> => true,
      }, $class)

  @IntMethod:
    @@Name: isExternallyReferred
    @@Description:
      @@@lang:en
      @@@@:
        Checks whether the tree containing this node has been referred 
        from the outside of the tree or not. 
    @@Return:
      @@@Type: 
        DISPerl:Boolean::ManakaiDOM:all
      @@@InCase:
        @@@@Value:
          @@@@@@:1
          @@@@@ContentType: DISCore|Boolean
        @@@@Description:
          @@@@@lang:en
          @@@@@@: 
            There is one or more nodes in the tree that has been 
            referred via <Class::ManakaiDOM:ManakaiDOMNodeReference> objects.
      @@@InCase:
        @@@@Value:
          @@@@@@:0
          @@@@@ContentType: DISCore|Boolean
        @@@@Description:
          @@@@@lang:en
          @@@@@@: No external reference found.
      @@@PerlDef:
          if ($self->{<H::mn:rc>}) {
            $r = true;
          } else {
            my @node = ($self);
            my %checked;
            NODES: while (@node) {
              my $node = shift @node;
              next NODES unless ref $node;
              if ($node->{<H::mn:rc>}) {
                $r = true;
                last NODES;
              } elsif ($checked{$node->{<H::mn:nodeID>}}) {
                next NODES;
              }
              my @n;
              my $nt = $Message::Util::ManakaiNode::ManakaiNodeRef::Prop{
                $node->{<H::mn:type>}
              }; 
              for my $p (@{$nt->{<H::mn:subnode2>}}) {
                if (ref $node->{$p} eq 'ARRAY') {
                  push @n, @{$node->{$p}};
                } elsif (ref $node->{$p} eq 'HASH') {
                  push @n, values %{$node->{$p}};
                }
              }
              for my $p (@n,
                         map {$node->{$_}} @{$nt->{<H::mn:subnode1>}}) {
                if (ref $p eq 'ARRAY') {
                  push @node, @$p;
                } elsif (ref $p eq 'HASH') {
                  push @node, values %$p;
                }
              }
              for my $p (@{$nt->{<H::mn:origin0>}}) {
                unshift @node, $node->{$p} if $node->{$p};
                ## NOTE: Puts the top of the list,
                ##       since upper-level nodes are expected to be referred
                ##       more than lower-levels.
              }
              for my $p (@{$nt->{<H::mn:subnode0>}}) {
                push @node, $node->{$p} if $node->{$p};
              }
              $checked{$node->{<H::mn:nodeID>}} = true;
            }
          }

  @ResourceDef:
    @@QName: mn|isGroveReferenced
    @@rdf:type: DISPerl|InlineCode
    @@ForCheck: ManakaiDOM|ForClass
    @@PerlDef:
      (${$node->{<H::mn:groveReferenceCounter>}} > 0)

  @IntMethod:
    @@Name: destroy
    @@Description:
      @@@lang:en
      @@@@:
        Destructs the tree containing this node. 
    @@Return:
      @@@PerlDef:
        my @node = ($self);
        my $tid = $self->{<H::mn:treeID>};
        my %xrnode;
        NODES: while (@node) {
          my $node = shift @node;
          next NODES unless ref $node and defined $node->{<H::mn:nodeID>};
          my @n;
              my $nt = $Message::Util::ManakaiNode::ManakaiNodeRef::Prop{
                $node->{<H::mn:type>}
              }; 
              for my $p (@{$nt->{<H::mn:subnode2>}||[]}) {
                my $ref = ref $node->{$p};
                if ($ref eq 'HASH') {
                  push @n, values %{$node->{$p}};
                } elsif ($ref eq 'ARRAY') {
                  push @n, @{$node->{$p}};
                }
              }
              for my $p (@n, map {$node->{$_}} @{$nt->{<H::mn:subnode1>}||[]}) {
                my $ref = ref $p;
                if ($ref eq 'ARRAY') {
                  push @node, @$p;
                } elsif ($ref eq 'HASH') {
                  push @node, values %$p;
                }
              }
              for my $p (@{$nt->{<H::mn:origin0>}||[]},
           \             @{$nt->{<H::mn:subnode0>}||[]}) {
                push @node, $node->{$p};
              }

          for my $p (@{$nt->{<H::mn:xrefnode0>}||[]}) {
            if (defined $node->{$p} and 
                ${$node->{$p}->{<H::mn:treeID>}||$tid} ne $$tid) {
              $node->{$p}->{<H::mn:rc>}--;
              ${$node->{$p}->{<H::mn:groveReferenceCounter>}}--;
              $xrnode{${$node->{$p}->{<H::mn:treeID>}}} = $node->{$p};
            }
          }

          %$node = ();
        } # @node

        CORE::delete $xrnode{$$tid};
        for my $node (values %xrnode) {
          unless (<Code::isGroveReferenced:: $node = $node>) {
            $node-><M::NodeStem.destroy>;
          }
        }
    @@ImplNote:
      @@@lang:en
      @@@@:
        This method is different from Perl <Perl::DESTROY> special 
        purpose method.
        \
        An <QUOTE::uninitialized> warning in this method might mean 
        some method puts an <Perl::undef> into a list of nodes. 

  @IntMethod:
    @@Name: importTree
    @@Description:
      @@@lang:en
      @@@@:
        Changes the tree identifier of the nodes belong to another tree 
        to be same as this node's tree identifier. 
    @@Param:
      @@@Name: node
      @@@Type: NodeStem
      @@@Description:
        @@@@lang:en
        @@@@@:
          Any node from the tree to change its identifier. 
    @@Return:
      @@@PerlDef:
          my @node = ($node);
          my $newgrc = $self->{<H::mn:groveReferenceCounter>};
          my $newtid = $self->{<H::mn:treeID>};
          my $oldtid = $node->{<H::mn:treeID>};
          my @xrnode;
          NODES: while (@node) {
            my $node = shift @node;
            next NODES unless ref $node;
            next NODES if ${$node->{<H::mn:treeID>}} eq $$newtid;
            my @n;
              my $nt = $Message::Util::ManakaiNode::ManakaiNodeRef::Prop{
                $node->{<H::mn:type>}
              }; 
              for my $p (@{$nt->{<H::mn:subnode2>}||[]}) {
                my $ref = ref $node->{$p};
                if ($ref eq 'HASH') {
                  push @n, values %{$node->{$p}};
                } elsif ($ref eq 'ARRAY') {
                  push @n, @{$node->{$p}};
                }
              }
              for my $p (@n, map {$node->{$_}} @{$nt->{<H::mn:subnode1>}||[]}) {
                my $ref = ref $p;
                if ($ref eq 'ARRAY') {
                  push @node, @$p;
                } elsif ($ref eq 'HASH') {
                  push @node, values %$p;
                }
              }
            for my $p (@{$nt->{<H::mn:origin0>}||[]},
           \           @{$nt->{<H::mn:subnode0>}||[]}) {
              push @node, $node->{$p} if defined $node->{$p};
            }

            for (@{$nt->{<H::mn:xrefnode0>}||[]}) {
              push @xrnode, $node->{$_} if defined $node->{$_};
            }

            ${$node->{<H::mn:groveReferenceCounter>}} -= $node->{<H::mn:rc>};
            $node->{<H::mn:treeID>} = $newtid;
            $node->{<H::mn:groveReferenceCounter>} = $newgrc;
            $$newgrc += $node->{<H::mn:rc>};
          }

          for my $n (@xrnode) {
            if (${$n->{<H::mn:treeID>}} eq $$oldtid) {
              $n->{<H::mn:rc>}++;
              ${$n->{<H::mn:groveReferenceCounter>}}++;
            } elsif (${$n->{<H::mn:treeID>}} eq $$newtid) {
              $n->{<H::mn:rc>}--;
              ${$n->{<H::mn:groveReferenceCounter>}}--;
              ## Is it necessary to test whether rc is 0 or not
              ## and if so call "destroy" method?  Maybe it need not
              ## (or should not, rather).
            }
          }

  @IntMethod:
    @@Name: changeTreeID
    @@Description:
      @@@lang:en
      @@@@:
        Changes tree identifier of all nodes traversable from this node. 

        If a node has <Q::mn:xrefnode0> property value and it
        is a node in the tree to which the node formally belongs,
        then reference counters are updated to new status.
    @@Param:
      @@@Name: treeID
      @@@Type: 
        DISPerl:String::ManakaiDOM:all
      @@@Description:
        @@@@lang:en
        @@@@@:
          The new tree identifier. 
       @@@InCase:
        @@@@Type: DISPerl|SCALAR||ManakaiDOM|all
        @@@@enDesc:
          A reference to the new tree identifier.
          The tree will reference the identifier as it.
    @@Param:
      @@@Name: groveRC
      @@@Type: DISPerl|SCALAR||ManakaiDOM|all
      @@@enDesc:
        The new reference counter.
    @@Return:
      @@@PerlDef:
          my $tid = ref $treeID ? $treeID : \$treeID;
          my $oldtid = $self->{<H::mn:treeID>};
          my @xrnode;
          my @node = ($self);
          NODES: while (@node) {
            my $node = shift @node;
            next NODES unless ref $node;
            next NODES if ${$node->{<H::mn:treeID>}} eq $$tid;
              my @n;
              my $nt = $Message::Util::ManakaiNode::ManakaiNodeRef::Prop{
                $node->{<H::mn:type>}
              }; 
              for my $p (@{$nt->{<H::mn:subnode2>}||[]}) {
                if (ref $node->{$p} eq 'ARRAY') {
                  push @n, @{$node->{$p}};
                } elsif (ref $node->{$p} eq 'HASH') {
                  push @n, values %{$node->{$p}};
                }
              }
              for my $p (@n,
                         map {$node->{$_}} @{$nt->{<H::mn:subnode1>}||[]}) {
                if (ref $p eq 'ARRAY') {
                  push @node, @$p;
                } elsif (ref $p eq 'HASH') {
                  push @node, values %$p;
                }
              }
            for my $p (@{$nt->{<H::mn:origin0>}||[]},
       \               @{$nt->{<H::mn:subnode0>}||[]}) {
              push @node, $node->{$p};
            }

            for (@{$nt->{<H::mn:xrefnode0>}||[]}) {
              push @xrnode, $node->{$_} if defined $node->{$_};
            }

            ${$node->{<H::mn:groveReferenceCounter>}} -= $node->{<H::mn:rc>};
            $node->{<H::mn:treeID>} = $tid;
            $node->{<H::mn:groveReferenceCounter>} = $groveRC;
            ${$node->{<H::mn:groveReferenceCounter>}} += $node->{<H::mn:rc>};
          }

          for my $n (@xrnode) {
            if (${$n->{<H::mn:treeID>}} eq $$oldtid) {
              $n->{<H::mn:rc>}++;
              ${$n->{<H::mn:groveReferenceCounter>}}++;
            } elsif (${$n->{<H::mn:treeID>}} eq $$tid) {
              $n->{<H::mn:rc>}--;
              ${$n->{<H::mn:groveReferenceCounter>}}--;
              ## Is it necessary to test whether rc is 0 or not
              ## and if so call "destroy" method?  Maybe it need not
              ## (or should not, rather).
            }
          }

  @IntMethod:
    @@Name: isSameNode
    @@Description:
      @@@lang:en
      @@@@:
        Returns whether a node is the same as this node or not. 
        \
        {NOTE:: The sameness is different from the equality; 
                two nodes are same iff they are same hash reference. 
        \
        }
    @@Operator:
      @@@ContentType:
        lang:Perl
      @@@@: eq
    @@Param:
      @@@Name: node
      @@@Type: NodeStem
      @@@Description:
        @@@@lang:en
        @@@@@:
          A node to compare with. 
    @@Return:
      @@@Type: 
        DISPerl:Boolean::ManakaiDOM:all
      @@@Description:
        @@@@lang:en
        @@@@@: Whether the two nodes are same or not.
      @@@PerlDef:
          if (ref $node and
              UNIVERSAL::isa ($node, <ClassName::ManakaiNodeStem>) and
              $node->{<H::mn:nodeID>} eq $self->{<H::mn:nodeID>}) {
            $r = true;
          }
  @IntMethod:
    @@Name: orphanate
    @@Description:
      @@@lang:en
      @@@@:
        Notifies that this node (and its neibors if any) is no longer 
        part of the main tree.  If the new tree containing this node 
        has been referred yet, then the tree is preserved except its 
        tree identifier has changed.  Otherwise, i.e. the tree is 
        useless any more, then it is destructed. 
        \
        {NOTE:: Interaction on deleting a relationship from multiply 
                organized <QUOTE::trees> (such as DOM tree and 
                styled displaying tree) is less studied.  This 
                method might be modified or addition of another method(s) 
                might be required when style sheet, XBL, or other 
                technologies has been implemented.
        \
        }
    @@Return:
      @@@PerlDef:
          if ($self-><M::NodeStem.isExternallyReferred>) {
            my $grc = 0;
            $self-><M::NodeStem.changeTreeID>
                         (\(<Code::ManakaiDOM:generateUniqueID>), \$grc);
          } else {
            $self-><M::NodeStem.destroy>;
          }

  @ResourceDef:
    @@ForCheck: ManakaiDOM|ForClass
    @@QName: mn|setXRefNode
    @@enDesc:
      Sets a <Q::mn:xrefnode0> property.
    @@rdf:type: DISPerl|BlockCode
    @@PerlDef:
      $referrer->{$propName} = $referent;
      if (${$referrer->{<H::mn:treeID>}} ne ${$referent->{<H::mn:treeID>}}) {
        $referent->{<H::mn:rc>}++;
        ${$referent->{<H::mn:groveReferenceCounter>}}++;
      }

  @ResourceDef:
    @@ForCheck: ManakaiDOM|ForClass
    @@QName: mn|unsetXRefNode
    @@enDesc:
      Unsets a <Q::mn:xrefnode0> property.
    @@rdf:type: DISPerl|BlockCode
    @@PerlDef:
      if (defined $referrer->{$propName}) {
        my $__referent = $referrer->{$propName};
        if (${$referrer->{<H::mn:treeID>}} ne ${$__referent->{<H::mn:treeID>}}) {
          $__referent->{<H::mn:rc>}--;
          ${$__referent->{<H::mn:groveReferenceCounter>}}--;
          unless (<Code::isGroveReferenced:: $node = $__referent>) {
            $__referent-><M::NodeStem.destroy>;
          }
        }
        CORE::delete $referrer->{$propName};
      }
##NodeStem

## -- Public node object

ClassDef:
  @resourceFor: ManakaiDOM|ForClass
  @resourceFor: ManakaiDOM|ForIF

  @QName:
    @@@: NodeRef
    @@ForCheck: ManakaiDOM|ForIF

  @QName:
    @@@: ManakaiNodeRef
    @@ForCheck: ManakaiDOM|ForClass

  @Implement:
    @@@: NodeRef
    @@ForCheck: ManakaiDOM|ForClass

  @DISLang:role:
    @@@: mn|NodeRefRole
    @@ForCheck: ManakaiDOM|ForClass

  @Description:
    @@lang:en
    @@@:
      References to the node object corresponding to it.  From 
      applications' view, any node object is hidden and 
      <Class::ManakaiDOM:ManakaiDOMNodeReference> seems as if 
      the node itself. 
  @ImplNote:
    @@lang:en
    @@@:
      {P:: A <Class::ManakaiDOM:ManakaiDOMNodeReference> is a blessed hash 
      reference; currently there is a hash key defined:
        \
        - <Q::mn:node>::: A node object 
             (<Class::ManakaiDOM:ManakaiDOMNodeObject>) to which 
             this is referring. 
        
        - <Q::mn:isWeak>::: Whether the reference is <QUOTE::weak>
             or not.
      }

  @ResourceDef: 
    @@Name: free
    @@rdf:type: DISLang|Method
    @@enDesc:
      Frees the grove referenced by this object.  Once
      this operation is done, results of operations to objects belonging
      to the grove are unknown.
    @@Return:
      @@@PerlDef:
        $self->{<H::mn:node>}-><M::NodeStem.destroy>;

  @IntMethod:
    @@Name: destroy
    @@Description:
      @@@lang:en
      @@@@: Destroy this reference object.
    @@Operator:
      @@@ContentType:
        lang:Perl
      @@@@: DESTROY
    @@Return:
      @@@PerlDef:
        @@@@@:
          if (my $node = $self->{<H::mn:node>}) {
            CORE::delete $self->{<H::mn:node>};
            unless ($self->{<H::mn:isWeak>}) {
              $node->{<H::mn:rc>}--;
              ${$node->{<H::mn:groveReferenceCounter>}}--;
              unless (<Code::isGroveReferenced:: $node = $node>) {
                $node-><M::NodeStem.destroy>;
              }
            }
          } else {
            warn ref ($self) . q{->DESTROY: there is no associated }.
                 q{node object - you have a global variable or }.
                 qq{potential memory-leak detected\n};
          }
       @@@@ImplNote:
         @@@@@lang:en
         @@@@@@:
           {P::Warning during the global destruction might mean:
              \
              - there be a loop in the manakai internal implementation - 
                it should be a bug.
              \
              - there be a loop created by application, e.g. 
                event handler containing a reference to any node 
                belonging to the same tree.
              \
              - there be a global variable that contains a node reference 
                and it is not altered or <Perl::undef>ed until the global 
                destruction. 
              \
              - or other unknown bad situation.
              \
            }
    @@ImplNote:
      @@@lang:en
      @@@@:
        Don't override this method unintentionally - for example, 
        inheritting <PerlModule::Tie::Array> would hide this method 
        from that class, since that module defines its own 
        destructor. 
##NodeRef

ResourceDef:
  @QName: mn|NodeRefRole
  @rdf:type: DISLang|Role
  @For: =ManakaiDOM|all
  @enDesc: 
    The <QUOTE::dis> definition for a class which plays the role
    of <Q::mn|NodeRefRole> provides a set of <QUOTE::dis> properties such
    as <Q::mn|subnode0> which identify the set of object internal
    property names (or hash key names) used to construct groves.

PropDef:
  @QName: mn|type
  @mn:stemName: t

PropDef:
  @QName: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList

PropDef:
  @QName: mn|subnode0
  @enDesc:
    A property of type <Q::mn|subnode0> takes a value of 
    reference to another node (<Q::mn|NodeStem||ManakaiDOM|Perl>)
    in the same grove.  The referenced node is considered
    to make a part of the node and just one <Q::mn|origin0>
    property of the referenced node <kwd:MUST> have a reference
    to the node.  That is, these properties shows
    a origin-subnode-relationship.
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: s0

PropDef:
  @QName: mn|subnode1
  @enDesc:
    A property of type <Q::mn|subnode1> is similar to <Q::mn|subnode0>
    properties, but its value is an array or hash reference whose
    values are references to subnodes.
  @rdfs:subPropertyOf: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: s

PropDef:
  @QName: mn|subnode2
  @enDesc:
    A property of type <Q::mn|subnode2> is similar to <Q::mn|subnode1>
    properties, but its value is an array or hash reference whose
    values are array or hash references whose values are
    references to subnodes.
  @rdfs:subPropertyOf: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: s2

PropDef:
  @QName: mn|origin0
  @rdfs:subPropertyOf: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: o

PropDef:
  @QName: mn|xrefnode0
  @rdfs:subPropertyOf: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: x
  @rdf:type: DISSource|ResourceProperty
  @enDesc:
    An <Q::mn:xrefnode0> property references a node <html5:var::m> in the tree
    <html5:var::s> that might be different from the tree <html5:var::t> to which
    the subject node <html5::var::n> of the property belongs.

    When the property value is set and <html5:var::s> is
    different from <html5:var::t>, then reference counters for
    <html5:var::m> and <html5:var::s> are increased, so that
    the tree <html5:var::s> would not be deleted while this
    link has been maintained.  When the property value is unset
    or an <M::NodeStem||ManakaiDOM|Perl.importTree> operation
    makes two trees to one, then two reference counters
    are decreased.

PropDef:
  @QName: mn|irefnode0
  @rdfs:subPropertyOf: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: i

PropDef:
  @QName: mn|anydata1
  @rdfs:subPropertyOf: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: a1

PropDef:
  @QName: mn|anydata2
  @rdfs:subPropertyOf: mn|noderef
  @dataType: DISCore|QName
  @multipleProperties: DISCore|UnorderedList
  @mn:stemName: a2

PropDef:
  @QName: mn|nodeID
  @enDesc:
    The globally unique identifier of the node.
  @mn:stemName: nid

PropDef:
  @QName: mn|treeID
  @enDesc:
    The globally unique identifier of the grove to which the
    node belongs.
  @mn:stemName: tid

PropDef:
  @QName: mn|rc
  @enDesc:
    The number of the reference that points the node.
  @mn:stemName: rc

PropDef:
  @QName: mn|groveReferenceCounter
  @enDesc:
    A reference to the number of references that reference
    a node in the grove.
  @mn:stemName: grc

PropDef:
  @QName: mn|node
  @mn:refName: node
  @rdfs:domain: mn|NodeRef||ManakaiDOM|Perl
  @rdfs:range: mn|NodeStem||ManakaiDOM|Perl

PropDef:
  @QName: mn|isWeak
  @enDesc:
    Whether a reference is weak or not. 
  @rdfs:domain: mn|NodeRef||ManakaiDOM|Perl
  @Type: DISPerl|Boolean
  @mn:refName: w

PropDef:
  @QName: mn|stemName
  @enDesc:
    The key name of the property when it is used in <Class::ManakaiNodeStem
    ::ManakaiDOM:Perl>.
  @dataType: DISCore|String
  @multipleProperties: DISCore|Single
  @rdfs:domain: rdfs|Property
  @rdfs:subPropertyOf: DISPerl|propHashKey

PropDef:
  @QName: mn|refName
  @enDesc:
    The key name of the property when it is used in <Class::ManakaiNodeRef
    ::ManakaiDOM:Perl>.
  @dataType: DISCore|String
  @multipleProperties: DISCore|Single
  @rdfs:domain: rdfs|Property
  @rdfs:subPropertyOf: DISPerl|propHashKey

ElementTypeBinding:
  @Name:PropDef
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      rdf:Property
    @@For: =ManakaiDOM|all

ElementTypeBinding:
  @Name:enDesc
  @ElementType:
    dis:Description
  @ShadowContent:
    @@lang:en

## -- Frequently used code fragments

ResourceDef:
  @QName:
    ManakaiDOM:generateUniqueID
  @rdf:type: DISPerl|InlineCode
  @Description:
    @@lang:en
    @@@:
      Generates a global-unique opaque string. 
      \
      {NOTE:: A URI reference is generated by this code. 
      \
      }

  @For: =ManakaiDOM|Perl

  @PerlDef:
      (
        'tag:suika.fam.cx,2005-09:' . time . ':' . $$ . ':' .
        ($Message::Util::ManakaiNode::UniqueIDR ||=
          [qw/A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
              a b c d e f g h i j k l m n o p q r s t u v w x y z
              0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
          [qw/A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
              a b c d e f g h i j k l m n o p q r s t u v w x y z
              0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
          [qw/A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
              a b c d e f g h i j k l m n o p q r s t u v w x y z
              0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
          [qw/A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
              a b c d e f g h i j k l m n o p q r s t u v w x y z
              0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
          [qw/A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
              a b c d e f g h i j k l m n o p q r s t u v w x y z
              0 1 2 3 4 5 6 7 8 9/]->[rand 62]) .
        (++$Message::Util::ManakaiNode::UniqueIDN)
      )
##ManakaiDOM:generateUniqueID

## -- lang:dis vocabulary

TreeElementType:
  @QName:
    dis:GetProp
  @dataType:
    dis:TypeQName
  @rdfs:range:
    rdf:Property
  @Description:
    @@lang:en
    @@@:
      Gets the non-nodal value of a <Class::ManakaiDOM:ManakaiDOMNodeReference> 
      property (actualy <Class::ManakaiDOM:ManakaiDOMNodeObject> property). 

TreeElementType:
  @QName:
    dis:SetProp
  @dataType: DISCore|QName
  @rdfs:range:
    rdf:Property
  @Description:
    @@lang:en
    @@@:
      Sets the non-nodal value of a <Class::ManakaiDOM:ManakaiDOMNodeReference> 
      property (actualy <Class::ManakaiDOM:ManakaiDOMNodeObject> property). 

## -- Syntax sugar

ElementTypeBinding:
  @Name: TreeElementType
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      DISLang:TreeElementType
    @@For: =ManakaiDOM|all

ElementTypeBinding:
  @Name: ClassDef
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      @@@@:
        dis:MultipleResource
      @@@ForCheck: !ManakaiDOM|ForClass !ManakaiDOM|ForIF
    @@rdf:type:
      @@@@: DISLang|Interface
      @@@ForCheck: ManakaiDOM|ForIF
    @@rdf:type:
      @@@@: DISLang|Class
      @@@ForCheck: ManakaiDOM|ForClass
    @@ForCheck: ManakaiDOM|Perl

ElementTypeBinding:
  @Name: IntMethod
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      DISLang:Method
    @@ManakaiDOM:isForInternal:1

ElementTypeBinding:
  @Name: Return
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      DISLang:MethodReturn

ElementTypeBinding:
  @Name: Param
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      DISLang:MethodParameter

ElementTypeBinding:
  @Name: PerlDef
  @ElementType:
    dis:Def
  @ShadowContent:
    @@ContentType:
      lang:Perl

ElementTypeBinding:
  @Name: InCase
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      ManakaiDOM:InCase