Message/Util/Grove.dis

Module:
  @QName: Util|Grove
  @enFN:
    Manakai Grove Module

  @Namespace:
    http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/Grove/

  @DISCore:author: DISCore|Wakaba
  @License: license|Perl+MPL
  @Date:
    $Date: 2006/11/05 09:16:34 $

  @Require:
    @@Module:
      @@@QName: DISlib|DISPerl
  @DefaultFor: ManakaiDOM|all

Namespace:
  @dis:
    http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#dis--
  @DISlib:
    http://suika.fam.cx/~wakaba/archive/2004/dis/
  @f:
    http://suika.fam.cx/~wakaba/archive/2004/dom/feature#
  @fe:
    http://suika.fam.cx/www/2006/feature/
  @idl:
    http://suika.fam.cx/~wakaba/archive/2004/dis/IDL#
  @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#
  @mg:
    http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/Grove/
  @test:
    http://suika.fam.cx/~wakaba/archive/2004/dis/Test#
  @Util:
    http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/

ElementTypeBinding:
  @Name: ClsDef
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISLang|Class

ElementTypeBinding:
  @Name: CODE
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISPerl|BlockCode

ElementTypeBinding:
  @Name: Method
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISLang|Method

ElementTypeBinding:
  @Name: Param
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISLang|MethodParameter

ElementTypeBinding:
  @Name: Return
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISLang|MethodReturn

ElementTypeBinding:
  @Name: nullCase
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType:
      ManakaiDOM:InCase
    @@Value:
      @@@is-null:1

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

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

ElementTypeBinding:
  @Name: enImplNote
  @ElementType:
    dis:ImplNote
  @ShadowContent:
    @@lang:en

ElementTypeBinding:
  @Name: enFN
  @ElementType:
    dis:FullName
  @ShadowContent:
    @@lang:en

ElementTypeBinding:
  @Name: ClsQName
  @ElementType:
    dis:QName

ElementTypeBinding:
  @Name: Code
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISPerl|InlineCode

ElementTypeBinding:
  @Name: IntPropDef
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISCore|Property

ElementTypeBinding:
  @Name: RPropDef
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISSource|ResourceProperty

ElementTypeBinding:
  @Name: Test
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: test|StandaloneTest

ResourceDef:
  @QName: HASH
  @AliasFor: DISPerl|HASH||ManakaiDOM|all

## --------------------------------
## --- Node Bag

ClsDef:
  @ClsQName: NodeBag

  @CODE:
    @@QName: mg|createNodeBag
    @@enDesc:
      Creates a new node bag.
    @@PerlDef:
      $bag = {
        <H::mg|mutations> => 0,
      };
##NodeBag

## -- Bag Internal Properties

RPropDef:
  @QName: mg|nodeBagKey
  @subsetOf: DISPerl|propHashKey
  @multipleProperties: DISCore|Single
  @dataType: DISCore|String

IntPropDef:
  @QName: mg|mutations
  @mg:nodeBagKey: m
  @enDesc:
    The <Q::mg|mutations> property of a node bag contains
    a reference to the array that contains references to
    the node identifiers.  They should be identifiers 
    of nodes that might be no longer referenced from anywhere
    other than bag and when garbage collection procedure is 
    invoked they are really no longer referenced or not.

## --------------------------------
## --- Node Stem

ClsDef:
  @ClsQName: NodeStem

  @CODE:
    @@QName: mg|createNodeStem
    @@enDesc:
      Creates a new node stem.
    @@PerlDef:
      $stem = $class->___create_node_stem ($bag, {
        <H::mg|references> => 0,
        <H::mg|nodeID> => \<Code::mg|generateUniqueID>,
      }, $opt);
      __CODE{DISPerl|HashStringRef||ManakaiDOM|all::
        $result => {$stem->{<H::mg|nodeClass>}},
        $given => {$class},
      }__;
      $bag->{${$stem->{<H::mg|nodeID>}}} = $stem;

  @Code:
    @@QName: mg|generateUniqueID
    @@PerlDef:
      (
        'tag:suika.fam.cx,2005-09:' . time . ':' . $$ . ':' .
        (++$Message::Util::ManakaiNode::UniqueIDN)
      )
  @CODE:
    @@QName: mg|setOwnerProp
    @@enDesc:
      Setting <Q::mg|owner0> and <Q::mg|ownee1h> property values.
    @@PerlDef:
      $ownee->{$owner0prop} = $ownerref->{<H::mg|nodeIDReference>};
      $bag->{${$ownerref->{<H::mg|nodeIDReference>}}}
          ->{$ownee1hprop}->{${$ownee->{<H::mg|nodeID>}}}
        = $ownee->{<H::mg|nodeID>};

  @CODE:
    @@QName: mg|setOwnerPropRR
    @@enDesc:
      Setting <Q::mg|owner0> and <Q::mg|ownee1h> property values
      (node reference to node reference).
    @@PerlDef:
      $bag->{${$owneeref->{<H::mg|nodeIDReference>}}}->{$owner0prop}
        = $ownerref->{<H::mg|nodeIDReference>};
      $bag->{${$ownerref->{<H::mg|nodeIDReference>}}}
          ->{$ownee1hprop}->{${$owneeref->{<H::mg|nodeIDReference>}}}
        = $owneeref->{<H::mg|nodeIDReference>};

  @CODE:
    @@QName: mg|deleteOwnerProp
    @@enDesc:
      Deletes <Q::mg|owner0> and <Q::mg|ownee1h> property values.
    @@PerlDef:
      CORE::delete $bag->{${$bag->{${$owneeref->{<H::mg|nodeIDReference>}}}
                                ->{$owner0prop} or \''}}
                       ->{$ownee1hprop};
      $bag->{<H::mg|mutations>}++;
      CORE::delete $bag->{${$owneeref->{<H::mg|nodeIDReference>}}}
                       ->{$owner0prop};
##NodeStem


## -- Stem Internal Property Types

RPropDef:
  @QName: mg|propertyTypeKey
  @subsetOf: DISPerl|propHashKey

PTPropDef:
  @QName: mg|subnode0
  @enDesc:
    A subnode property.
  @mg:propertyTypeKey: s0

PTPropDef:
  @QName: mg|subnode1a
  @enDesc:
    A subnode property containing an array reference.
  @mg:propertyTypeKey: s1a

PTPropDef:
  @QName: mg|subnode1h
  @enDesc:
    A subnode property containing a hash reference.
  @mg:propertyTypeKey: s1h

PTPropDef:
  @QName: mg|subnode2hh
  @enDesc:
    A subnode property containing a hash reference 
    containing hash references.
  @mg:propertyTypeKey: s2hh

PTPropDef:
  @QName: mg|origin0
  @enDesc:
    An origin property.
  @mg:propertyTypeKey: o0

PTPropDef:
  @QName: mg|owner0
  @enDesc:
    An owner property.  It is <EM::not> traversed when garbage collection is
    done.
  @mg:propertyTypeKey: w0

PTPropDef:
  @QName: mg|ownee1h
  @enDesc:
    An ownee property.  It <EM::is> traversed when garvage collection is done.
  @mg:propertyTypeKey: v1h

ElementTypeBinding:
  @Name: PTPropDef
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@DISCore:resourceType: DISSource|ResourceProperty
    @@multipleProperties: DISCore|UnorderedList
    @@dataType: DISCore|QName

## -- Stem Internal Properties

RPropDef:
  @QName: mg|nodeStemKey
  @subsetOf: DISPerl|propHashKey
  @multipleProperties: DISCore|Single
  @dataType: DISCore|String

IntPropDef:
  @QName: mg|references
  @enDesc:
    The number of the external references to the node.
  @Type: DISPerl|Number
  @mg:nodeStemKey: rc

IntPropDef:
  @QName: mg|nodeClass
  @enDesc:
    The Perl fully-qualified package name of the class
    whose <CODE::___create_node_ref> method is invoked when
    a reference to the node is instantiated.
  @Type: DISPerl|String
  @mg:nodeStemKey: cls

IntPropDef:
  @QName: mg|nodeID
  @enDesc:
    The hash key string by which the node stem object can
    be retrieved from the node bag.
  @Type: DISPerl|SCALAR
  @mg:nodeStemKey: id

IntPropDef:
  @QName: mg|onunload
  @enDesc:
    The code that is executed just before the node stem
    is deleted from the node bag.  Applications <kwd:MUST-NOT>
    rely on the code being executed.  Exactly when it
    is executed is undefined.  However, at the time of the
    execution, the node stem is still accessible from
    the node bag.

    The code would receive two parameters: the node bag
    and a reference to the node identifier.  The code 
    <kwd:MUST-NOT> modify the node identifier.  The code
    <kwd:MUST-NOT> modify the node bag directly (neither
    by hand nor by code fragments defined in this module); if
    it does, the result is undefined.  The code <kwd:MAY> 
    modify the node bag indirectly, via other node references,
    since the referenced nodes should never part of the grove
    being removed if there is such node reference.

    The code <kwd:MUST-NOT> throw exceptions; if it does, result is undefined.
  @Type: DISPerl|CODE
  @mg:nodeStemKey: beforefree

## --------------------------------
## --- Node Reference

ClsDef:
  @ClsQName: NodeRef

  @ResourceDef:
    @@QName: mg|NodeRefRole
    @@DISCore:resourceType: DISLang|Role
    @@enDesc:
      Any class that is used as a node reference <kwd:MUST> set
      its <Q::DISLang|role> property as <Q::mg|NodeRefRole>.

  @ResourceDef:
    @@QName: mg|CreateNodeStemMethod
    @@DISCore:resourceType: DISPerl|CommonMethod
    @@enDesc:
      The method to create a node stem.

      The method will invoked with four parameters: class name, node bag,
      node stem prototype, and a reference to hash containing
      optional parameters.  The method <kwd:MUST> return a node
      stem object.  It <kwd:MAY> create and return the node
      stem optionally by <Perl::bless>ing the node stem prototype
      parameter with any appropriate class, or <kwd:MAY> create and
      return the node stem object by its own way.   It
      <kwd:MAY> use options contained by the third parameter 
      to create the node stem object.

  @CODE:
    @@QName: mg|createNodeRef
    @@enDesc:
      Creates a new node reference for the node stem.
    @@PerlDef:
      $ref = ${$stem->{<H::mg|nodeClass>}}->___create_node_ref ({
        <H::mg|nodeIDReference> => $stem->{<H::mg|nodeID>},
        <H::mg|nodeBag> => $bag,
      }, $opt);
      $stem->{<H::mg|references>}++;

  @CODE:
    @@QName: mg|createNodeRefFromID
    @@enDesc:
      Creates a new node reference for the node stem.
    @@PerlDef:
      $ref = ${$bag->{${$stemid}}->{<H::mg|nodeClass>}}->___create_node_ref ({
        <H::mg|nodeIDReference> => $stemid,
        <H::mg|nodeBag> => $bag,
      }, $opt);
      $bag->{${$stemid}}->{<H::mg|references>}++;

  @Code:
    @@QName: mg|createNodeRefHashFromID
    @@enDesc:
      Creates a node reference hash, which is a hash reference
      that can be handled as if it were a node reference,
      from a node bag by its node identifier.
    @@PerlDef:
      {
        <H::mg|nodeIDReference> => $stemid,
        <H::mg|nodeBag> => $bag,
      }

  @ResourceDef:
    @@QName: mg|CreateNodeRefMethod
    @@DISCore:resourceType: DISPerl|CommonMethod
    @@enDesc:
      The method to create a node reference to the node.

      The method will invoked with three parameters: class name,
      node reference prototype, and a reference to hash containing
      optional parameters.  The method <kwd:MUST> return a node
      reference object.  It <kwd:MAY> create and return the node
      reference by <Perl::bless>ing the node reference prototype
      parameter with any appropriate class, or <kwd:MAY> create and
      return the node reference object by its own way.   It
      <kwd:MAY> use options contained by the third parameter 
      to create the node reference object.

  @Code:
    @@QName: mg|getNodeBag
    @@enDesc:
      Returns the node bag to which the node stem referenced by
      a node reference belongs.
    @@PerlDef:
      $ref->{<H::mg|nodeBag>}

  @Code:
    @@QName: mg|getNodeID
    @@enDesc:
      Returns the identifier of the node referenced by a node reference.
    @@PerlDef:
      $ref->{<H::mg|nodeIDReference>}

  @Code:
    @@QName: mg|getNodeStem
    @@enDesc:
      Returns the node stem referenced by a node reference.
    @@PerlDef:
      $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}

  @Method:
    @@Name: destroy
    @@Return:
      @@@PerlDef:
        my $bag = $self->{<H::mg|nodeBag>};
        my $nid = $self->{<H::mg|nodeIDReference>};
        my $gtstem = $bag->{$$nid};
        if (--($gtstem->{<H::mg|references>}) < 1) {
          if (++($bag->{<H::mg|mutations>})
                  > (defined $Message::Util::Grove::GCLatency
                       ? $Message::Util::Grove::GCLatency : 50000)) {
            __CODE{mg|collectGarbage:: $bag => $bag}__;
          } else {
            HASREF: {
              my $clsprop = $Message::Util::Grove::ClassProp{
                              ${$gtstem->{<H::mg|nodeClass>}}
                            };
          
              for my $key (@{$clsprop->{<H::mg|origin0>} or []}) {
                last HASREF if defined $gtstem->{$key};
              }

              for my $key ((@{$clsprop->{<H::mg|subnode1h>} or []}),
                           (@{$clsprop->{<H::mg|ownee1h>} or []})) {
                last HASREF if keys %{$gtstem->{$key}};
              }

              for my $key (@{$clsprop->{<H::mg|subnode1a>} or []}) {
                last HASREF if @{$gtstem->{$key}};
              }

              for my $key (@{$clsprop->{<H::mg|subnode2hh>} or []}) {
                for my $v (values %{$gtstem->{$key}}) {
                  last HASREF if keys %$v;
                }
              }

              # No reference - i.e. not referenced
              if ($gtstem->{<H::mg|onunload>}) {
                $gtstem->{<H::mg|onunload>}->($bag, $nid);
              }
              CORE::delete $bag->{$$nid};
            } # HASREF
          }
        }

  @CODE:
    @@QName: mg|collectGarbage
    @@enDesc:
      Garbage collection.
    @@Param:
      @@@Name: bag
      @@@Type: HASH
      @@@enDesc:
        The node bag.
    @@PerlDef:
      my @has_xref_group = ([]);
      my @other_group = ([]);
      my %done = (<H::mg|mutations> => true);
      TARGET: while (defined (my $target = each %{$bag})) {
        next TARGET if $done{$target};
        my $has_xref;
        my %grove;
        my %xgref;
        my @gtarget = ($target);
        GTARGET: while (defined (my $gtarget = shift @gtarget)) {
          $done{$gtarget} = true;

          next GTARGET if $grove{$gtarget};
          $grove{$gtarget} = true;

          my $gtstem = $bag->{$gtarget};
          my $clsprop = $Message::Util::Grove::ClassProp{
                          ${$gtstem->{<H::mg|nodeClass>}}
                        };
          
          $has_xref = true if $gtstem->{<H::mg|references>};

          for my $key (@{$clsprop->{<H::mg|origin0>} or []}) {
            push @gtarget, ${$gtstem->{$key}} if defined $gtstem->{$key};
          }

          for my $key (@{$clsprop->{<H::mg|subnode1h>} or []}) {
            for (values %{$gtstem->{$key} or {}}) {
              push @gtarget, $$_;
            }
          }

          for my $key (@{$clsprop->{<H::mg|subnode1a>} or []}) {
            for (@{$gtstem->{$key}}) {
              push @gtarget, $$_;
            }
          }

          for my $key (@{$clsprop->{<H::mg|subnode2hh>} or []}) {
            for my $v (values %{$gtstem->{$key} or {}}) {
              for (values %{$v or {}}) {
                push @gtarget, $$_;
              }
            }
          }

          for my $key (@{$clsprop->{<H::mg|owner0>} or []}) {
            $xgref{${$gtstem->{$key}}} = true if defined $gtstem->{$key};
          }
        } # GTARGET

        for my $xgref (keys %xgref) {
          CORE::delete $xgref{$xgref} if $grove{$xgref};
        }

        if ($has_xref) {
          push @{$has_xref_group[0]}, [\%grove, \%xgref];
        } else {
          push @{$other_group[0]}, [\%grove, \%xgref];
        }
      } # target

      my $i = 0; 
      GI: {
        $has_xref_group[$i+1] = [];
        $other_group[$i+1] = [];

        OG: while (@{$other_group[$i]}) {
          my $other_group = shift @{$other_group[$i]};
          for my $has_group (@{$has_xref_group[$i]}) {
            for (keys %{$has_group->[1]}) {
              if ($other_group->[0]->{$_}) {
                push @{$has_xref_group[$i+1]}, $other_group;
                CORE::delete $has_group->[1]->{$_};
                next OG;
              }
            }
          }
          push @{$other_group[$i+1]}, $other_group;
        } # OG
        
        $i++;
        if (@{$has_xref_group[$i]}) { # changed
          redo GI;
        }
      } # GI

      for my $nid (map {keys %{$_->[0]}} @{$other_group[$i]}) {
        if ($bag->{$nid}->{<H::mg|onunload>}) {
          $bag->{$nid}->{<H::mg|onunload>}->($bag, \$nid);
        }
        CORE::delete $bag->{$nid};
      }

      $bag->{<H::mg|mutations>} = 0;

  @CODE:
    @@QName: mg|getNodeStemPropValue
    @@enDesc:
      Obtains a property value set to the node stem associated
      to the node reference.
    @@PerlDef:
      $r = $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
               ->{$prop};

  @CODE:
    @@QName: mg|getNodeStemPropValueRef
    @@enDesc:
      Obtains the reference to a property value set to the node stem associated
      to the node reference.
    @@PerlDef:
      $r = \$ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
                ->{$prop};

  @CODE:
    @@QName: mg|get++NodeStemPropValue
    @@enDesc:
      Obtains a property value set to the node stem associated
      to the node reference and then increments the value.
    @@PerlDef:
      $r = $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
               ->{$prop}++;

  @CODE:
    @@QName: mg|setNodeStemPropValue
    @@enDesc:
      Sets a property value to the node stem associated
      to the node reference.
    @@PerlDef:
      $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
          ->{$prop} = $given;

  @CODE:
    @@QName: mg|orSetNodeStemPropValue
    @@enDesc:
      Sets a property value to the node stem associated
      to the node reference by <Perl::||=> operator.
    @@PerlDef:
      $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
          ->{$prop} ||= $given;

  @CODE:
    @@QName: mg|getNodeStemProp0Node
    @@enDesc:
      Obtains a property value node reference set to the node stem associated
      to the node reference.
    @@PerlDef:
      my $__v = $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
                    ->{$prop};
      if (defined $__v) {
        __CODE{mg|createNodeRefFromID||ManakaiDOM|all::
          $bag => {$ref->{<H::mg|nodeBag>}},
          $stemid => $__v,
          $ref => $r,
          $opt => $opt,
        }__;
      }

  @CODE:
    @@QName: mg|setNodeStemProp0Node
    @@enDesc:
      Sets a property value node to the node stem associated
      to the node reference.
    @@PerlDef:
      $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
          ->{$prop} = $given->{<H::mg|nodeIDReference>};

  @CODE:
    @@QName: mg|deleteNodeStemPropValue
    @@enDesc:
      Deletes a property value node from the node stem associated
      to the node reference.
    @@PerlDef:
      CORE::delete $ref->{<H::mg|nodeBag>}->{${$ref->{<H::mg|nodeIDReference>}}}
                       ->{$prop};

  @Code:
    @@QName: mg|nodeIDMatch
    @@enDesc:
      Whether a node reference references the same node
      as a reference to a node identifier.
    @@PerlDef:
      (${$noderef->{<H::mg|nodeIDReference>}} eq ${$nodeid})

  @CODE:
    @@QName: mg|getNodeRefPropValue
    @@enDesc:
      Obtains a property value set to the node reference.
    @@PerlDef:
      $r = $ref->{$prop};

  @CODE:
    @@QName: mg|setNodeRefPropValue
    @@enDesc:
      Sets a property value set to the node reference.
    @@PerlDef:
      $ref->{$prop} = $given; 
##NodeRef

## -- Reference Internal Properties

RPropDef:
  @QName: mg|nodeRefKey
  @subsetOf: DISPerl|propHashKey
  @multipleProperties: DISCore|Single
  @dataType: DISCore|String

IntPropDef:
  @QName: mg|nodeIDReference
  @enDesc:
    The <Q::mg|nodeID> of the node referenced by the node reference object.
  @Type: DISPerl|SCALAR
  @mg:nodeRefKey: id

IntPropDef:
  @QName: mg|nodeBag
  @enDesc:
    The node bag object referenced by the node reference object.
  @Type: DISPerl|Ref
  @mg:nodeRefKey: b
1	wakaba	1.1	Module:
2			@QName: Util\|Grove
3			@enFN:
4			Manakai Grove Module
5
6			@Namespace:
7			http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/Grove/
8
9			@DISCore:author: DISCore\|Wakaba
10			@License: license\|Perl+MPL
11			@Date:
12	wakaba	1.17	$Date: 2006/11/05 09:16:34 $
13	wakaba	1.1
14			@Require:
15			@@Module:
16			@@@QName: DISlib\|DISPerl
17			@DefaultFor: ManakaiDOM\|all
18
19			Namespace:
20			@dis:
21			http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#dis--
22			@DISlib:
23			http://suika.fam.cx/~wakaba/archive/2004/dis/
24			@f:
25			http://suika.fam.cx/~wakaba/archive/2004/dom/feature#
26			@fe:
27			http://suika.fam.cx/www/2006/feature/
28			@idl:
29			http://suika.fam.cx/~wakaba/archive/2004/dis/IDL#
30			@kwd:
31			http://suika.fam.cx/~wakaba/archive/2005/rfc2119/
32			@lang:
33			http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#
34			@license:
35			http://suika.fam.cx/~wakaba/archive/2004/8/18/license#
36			@ManakaiDOM:
37			http://suika.fam.cx/~wakaba/archive/2004/8/18/manakai-dom#
38			@mg:
39			http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/Grove/
40			@test:
41			http://suika.fam.cx/~wakaba/archive/2004/dis/Test#
42			@Util:
43			http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/
44
45			ElementTypeBinding:
46			@Name: ClsDef
47			@ElementType:
48			dis:ResourceDef
49			@ShadowContent:
50			@@DISCore:resourceType: DISLang\|Class
51
52			ElementTypeBinding:
53			@Name: CODE
54			@ElementType:
55			dis:ResourceDef
56			@ShadowContent:
57			@@DISCore:resourceType: DISPerl\|BlockCode
58
59			ElementTypeBinding:
60			@Name: Method
61			@ElementType:
62			dis:ResourceDef
63			@ShadowContent:
64			@@DISCore:resourceType: DISLang\|Method
65
66			ElementTypeBinding:
67			@Name: Param
68			@ElementType:
69			dis:ResourceDef
70			@ShadowContent:
71			@@DISCore:resourceType: DISLang\|MethodParameter
72
73			ElementTypeBinding:
74			@Name: Return
75			@ElementType:
76			dis:ResourceDef
77			@ShadowContent:
78			@@DISCore:resourceType: DISLang\|MethodReturn
79
80			ElementTypeBinding:
81			@Name: nullCase
82			@ElementType:
83			dis:ResourceDef
84			@ShadowContent:
85			@@DISCore:resourceType:
86			ManakaiDOM:InCase
87			@@Value:
88			@@@is-null:1
89
90			ElementTypeBinding:
91			@Name: PerlDef
92			@ElementType:
93			dis:Def
94			@ShadowContent:
95			@@ContentType:
96			lang:Perl
97
98			ElementTypeBinding:
99			@Name: enDesc
100			@ElementType:
101			dis:Description
102			@ShadowContent:
103			@@lang:en
104
105			ElementTypeBinding:
106			@Name: enImplNote
107			@ElementType:
108			dis:ImplNote
109			@ShadowContent:
110			@@lang:en
111
112			ElementTypeBinding:
113			@Name: enFN
114			@ElementType:
115			dis:FullName
116			@ShadowContent:
117			@@lang:en
118
119			ElementTypeBinding:
120			@Name: ClsQName
121			@ElementType:
122			dis:QName
123
124			ElementTypeBinding:
125			@Name: Code
126			@ElementType:
127			dis:ResourceDef
128			@ShadowContent:
129			@@DISCore:resourceType: DISPerl\|InlineCode
130
131			ElementTypeBinding:
132			@Name: IntPropDef
133			@ElementType:
134			dis:ResourceDef
135			@ShadowContent:
136			@@DISCore:resourceType: DISCore\|Property
137
138			ElementTypeBinding:
139			@Name: RPropDef
140			@ElementType:
141			dis:ResourceDef
142			@ShadowContent:
143			@@DISCore:resourceType: DISSource\|ResourceProperty
144
145			ElementTypeBinding:
146			@Name: Test
147			@ElementType:
148			dis:ResourceDef
149			@ShadowContent:
150			@@DISCore:resourceType: test\|StandaloneTest
151
152			ResourceDef:
153			@QName: HASH
154			@AliasFor: DISPerl\|HASH\|\|ManakaiDOM\|all
155
156			## --------------------------------
157			## --- Node Bag
158
159			ClsDef:
160			@ClsQName: NodeBag
161
162			@CODE:
163			@@QName: mg\|createNodeBag
164			@@enDesc:
165			Creates a new node bag.
166			@@PerlDef:
167			$bag = {
168	wakaba	1.12	<H::mg\|mutations> => 0,
169	wakaba	1.1	};
170			##NodeBag
171
172			## -- Bag Internal Properties
173
174			RPropDef:
175			@QName: mg\|nodeBagKey
176			@subsetOf: DISPerl\|propHashKey
177			@multipleProperties: DISCore\|Single
178			@dataType: DISCore\|String
179
180			IntPropDef:
181			@QName: mg\|mutations
182			@mg:nodeBagKey: m
183			@enDesc:
184			The <Q::mg\|mutations> property of a node bag contains
185			a reference to the array that contains references to
186			the node identifiers. They should be identifiers
187			of nodes that might be no longer referenced from anywhere
188			other than bag and when garbage collection procedure is
189			invoked they are really no longer referenced or not.
190
191			## --------------------------------
192			## --- Node Stem
193
194			ClsDef:
195			@ClsQName: NodeStem
196
197			@CODE:
198			@@QName: mg\|createNodeStem
199			@@enDesc:
200			Creates a new node stem.
201			@@PerlDef:
202			$stem = $class->___create_node_stem ($bag, {
203			<H::mg\|references> => 0,
204			<H::mg\|nodeID> => \<Code::mg\|generateUniqueID>,
205			}, $opt);
206	wakaba	1.2	__CODE{DISPerl\|HashStringRef\|\|ManakaiDOM\|all::
207			$result => {$stem->{<H::mg\|nodeClass>}},
208			$given => {$class},
209			}__;
210	wakaba	1.1	$bag->{${$stem->{<H::mg\|nodeID>}}} = $stem;
211
212			@Code:
213			@@QName: mg\|generateUniqueID
214			@@PerlDef:
215			(
216			'tag:suika.fam.cx,2005-09:' . time . ':' . $$ . ':' .
217			(++$Message::Util::ManakaiNode::UniqueIDN)
218			)
219			@CODE:
220			@@QName: mg\|setOwnerProp
221			@@enDesc:
222			Setting <Q::mg\|owner0> and <Q::mg\|ownee1h> property values.
223			@@PerlDef:
224			$ownee->{$owner0prop} = $ownerref->{<H::mg\|nodeIDReference>};
225			$bag->{${$ownerref->{<H::mg\|nodeIDReference>}}}
226			->{$ownee1hprop}->{${$ownee->{<H::mg\|nodeID>}}}
227			= $ownee->{<H::mg\|nodeID>};
228	wakaba	1.6
229			@CODE:
230			@@QName: mg\|setOwnerPropRR
231			@@enDesc:
232			Setting <Q::mg\|owner0> and <Q::mg\|ownee1h> property values
233			(node reference to node reference).
234			@@PerlDef:
235			$bag->{${$owneeref->{<H::mg\|nodeIDReference>}}}->{$owner0prop}
236			= $ownerref->{<H::mg\|nodeIDReference>};
237			$bag->{${$ownerref->{<H::mg\|nodeIDReference>}}}
238			->{$ownee1hprop}->{${$owneeref->{<H::mg\|nodeIDReference>}}}
239			= $owneeref->{<H::mg\|nodeIDReference>};
240
241			@CODE:
242			@@QName: mg\|deleteOwnerProp
243			@@enDesc:
244			Deletes <Q::mg\|owner0> and <Q::mg\|ownee1h> property values.
245			@@PerlDef:
246			CORE::delete $bag->{${$bag->{${$owneeref->{<H::mg\|nodeIDReference>}}}
247			->{$owner0prop} or \''}}
248			->{$ownee1hprop};
249	wakaba	1.12	$bag->{<H::mg\|mutations>}++;
250	wakaba	1.6	CORE::delete $bag->{${$owneeref->{<H::mg\|nodeIDReference>}}}
251			->{$owner0prop};
252	wakaba	1.1	##NodeStem
253
254
255			## -- Stem Internal Property Types
256
257			RPropDef:
258			@QName: mg\|propertyTypeKey
259			@subsetOf: DISPerl\|propHashKey
260
261			PTPropDef:
262			@QName: mg\|subnode0
263			@enDesc:
264			A subnode property.
265			@mg:propertyTypeKey: s0
266
267			PTPropDef:
268			@QName: mg\|subnode1a
269			@enDesc:
270			A subnode property containing an array reference.
271			@mg:propertyTypeKey: s1a
272
273			PTPropDef:
274			@QName: mg\|subnode1h
275			@enDesc:
276			A subnode property containing a hash reference.
277			@mg:propertyTypeKey: s1h
278
279			PTPropDef:
280			@QName: mg\|subnode2hh
281			@enDesc:
282			A subnode property containing a hash reference
283			containing hash references.
284			@mg:propertyTypeKey: s2hh
285
286			PTPropDef:
287			@QName: mg\|origin0
288			@enDesc:
289			An origin property.
290			@mg:propertyTypeKey: o0
291
292			PTPropDef:
293			@QName: mg\|owner0
294			@enDesc:
295			An owner property. It is <EM::not> traversed when garbage collection is
296			done.
297			@mg:propertyTypeKey: w0
298
299			PTPropDef:
300			@QName: mg\|ownee1h
301			@enDesc:
302			An ownee property. It <EM::is> traversed when garvage collection is done.
303			@mg:propertyTypeKey: v1h
304
305			ElementTypeBinding:
306			@Name: PTPropDef
307			@ElementType:
308			dis:ResourceDef
309			@ShadowContent:
310			@@DISCore:resourceType: DISSource\|ResourceProperty
311			@@multipleProperties: DISCore\|UnorderedList
312			@@dataType: DISCore\|QName
313
314			## -- Stem Internal Properties
315
316			RPropDef:
317			@QName: mg\|nodeStemKey
318			@subsetOf: DISPerl\|propHashKey
319			@multipleProperties: DISCore\|Single
320			@dataType: DISCore\|String
321
322			IntPropDef:
323			@QName: mg\|references
324			@enDesc:
325			The number of the external references to the node.
326			@Type: DISPerl\|Number
327			@mg:nodeStemKey: rc
328
329			IntPropDef:
330			@QName: mg\|nodeClass
331			@enDesc:
332			The Perl fully-qualified package name of the class
333			whose <CODE::___create_node_ref> method is invoked when
334			a reference to the node is instantiated.
335			@Type: DISPerl\|String
336			@mg:nodeStemKey: cls
337
338			IntPropDef:
339			@QName: mg\|nodeID
340			@enDesc:
341			The hash key string by which the node stem object can
342			be retrieved from the node bag.
343			@Type: DISPerl\|SCALAR
344			@mg:nodeStemKey: id
345
346	wakaba	1.8	IntPropDef:
347			@QName: mg\|onunload
348			@enDesc:
349			The code that is executed just before the node stem
350			is deleted from the node bag. Applications <kwd:MUST-NOT>
351			rely on the code being executed. Exactly when it
352			is executed is undefined. However, at the time of the
353			execution, the node stem is still accessible from
354			the node bag.
355
356			The code would receive two parameters: the node bag
357			and a reference to the node identifier. The code
358			<kwd:MUST-NOT> modify the node identifier. The code
359			<kwd:MUST-NOT> modify the node bag directly (neither
360			by hand nor by code fragments defined in this module); if
361			it does, the result is undefined. The code <kwd:MAY>
362			modify the node bag indirectly, via other node references,
363			since the referenced nodes should never part of the grove
364			being removed if there is such node reference.
365
366			The code <kwd:MUST-NOT> throw exceptions; if it does, result is undefined.
367			@Type: DISPerl\|CODE
368			@mg:nodeStemKey: beforefree
369	wakaba	1.1
370			## --------------------------------
371			## --- Node Reference
372
373			ClsDef:
374			@ClsQName: NodeRef
375
376			@ResourceDef:
377			@@QName: mg\|NodeRefRole
378			@@DISCore:resourceType: DISLang\|Role
379			@@enDesc:
380			Any class that is used as a node reference <kwd:MUST> set
381			its <Q::DISLang\|role> property as <Q::mg\|NodeRefRole>.
382
383			@ResourceDef:
384			@@QName: mg\|CreateNodeStemMethod
385			@@DISCore:resourceType: DISPerl\|CommonMethod
386			@@enDesc:
387			The method to create a node stem.
388
389			The method will invoked with four parameters: class name, node bag,
390			node stem prototype, and a reference to hash containing
391			optional parameters. The method <kwd:MUST> return a node
392			stem object. It <kwd:MAY> create and return the node
393			stem optionally by <Perl::bless>ing the node stem prototype
394			parameter with any appropriate class, or <kwd:MAY> create and
395			return the node stem object by its own way. It
396			<kwd:MAY> use options contained by the third parameter
397			to create the node stem object.
398
399			@CODE:
400			@@QName: mg\|createNodeRef
401			@@enDesc:
402			Creates a new node reference for the node stem.
403			@@PerlDef:
404	wakaba	1.2	$ref = ${$stem->{<H::mg\|nodeClass>}}->___create_node_ref ({
405	wakaba	1.1	<H::mg\|nodeIDReference> => $stem->{<H::mg\|nodeID>},
406			<H::mg\|nodeBag> => $bag,
407			}, $opt);
408			$stem->{<H::mg\|references>}++;
409
410	wakaba	1.2	@CODE:
411			@@QName: mg\|createNodeRefFromID
412			@@enDesc:
413			Creates a new node reference for the node stem.
414			@@PerlDef:
415	wakaba	1.3	$ref = ${$bag->{${$stemid}}->{<H::mg\|nodeClass>}}->___create_node_ref ({
416	wakaba	1.2	<H::mg\|nodeIDReference> => $stemid,
417			<H::mg\|nodeBag> => $bag,
418			}, $opt);
419	wakaba	1.3	$bag->{${$stemid}}->{<H::mg\|references>}++;
420	wakaba	1.2
421	wakaba	1.6	@Code:
422			@@QName: mg\|createNodeRefHashFromID
423			@@enDesc:
424			Creates a node reference hash, which is a hash reference
425			that can be handled as if it were a node reference,
426			from a node bag by its node identifier.
427			@@PerlDef:
428			{
429			<H::mg\|nodeIDReference> => $stemid,
430			<H::mg\|nodeBag> => $bag,
431			}
432
433	wakaba	1.1	@ResourceDef:
434			@@QName: mg\|CreateNodeRefMethod
435			@@DISCore:resourceType: DISPerl\|CommonMethod
436			@@enDesc:
437			The method to create a node reference to the node.
438
439			The method will invoked with three parameters: class name,
440			node reference prototype, and a reference to hash containing
441			optional parameters. The method <kwd:MUST> return a node
442			reference object. It <kwd:MAY> create and return the node
443			reference by <Perl::bless>ing the node reference prototype
444			parameter with any appropriate class, or <kwd:MAY> create and
445			return the node reference object by its own way. It
446			<kwd:MAY> use options contained by the third parameter
447			to create the node reference object.
448
449			@Code:
450			@@QName: mg\|getNodeBag
451			@@enDesc:
452	wakaba	1.3	Returns the node bag to which the node stem referenced by
453			a node reference belongs.
454	wakaba	1.1	@@PerlDef:
455			$ref->{<H::mg\|nodeBag>}
456
457	wakaba	1.3	@Code:
458			@@QName: mg\|getNodeID
459			@@enDesc:
460			Returns the identifier of the node referenced by a node reference.
461			@@PerlDef:
462			$ref->{<H::mg\|nodeIDReference>}
463
464			@Code:
465			@@QName: mg\|getNodeStem
466			@@enDesc:
467			Returns the node stem referenced by a node reference.
468			@@PerlDef:
469			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
470
471	wakaba	1.1	@Method:
472			@@Name: destroy
473			@@Return:
474			@@@PerlDef:
475			my $bag = $self->{<H::mg\|nodeBag>};
476	wakaba	1.15	my $nid = $self->{<H::mg\|nodeIDReference>};
477			my $gtstem = $bag->{$$nid};
478			if (--($gtstem->{<H::mg\|references>}) < 1) {
479	wakaba	1.12	if (++($bag->{<H::mg\|mutations>})
480	wakaba	1.9	> (defined $Message::Util::Grove::GCLatency
481	wakaba	1.14	? $Message::Util::Grove::GCLatency : 50000)) {
482	wakaba	1.10	__CODE{mg\|collectGarbage:: $bag => $bag}__;
483	wakaba	1.15	} else {
484			HASREF: {
485			my $clsprop = $Message::Util::Grove::ClassProp{
486			${$gtstem->{<H::mg\|nodeClass>}}
487			};
488
489			for my $key (@{$clsprop->{<H::mg\|origin0>} or []}) {
490			last HASREF if defined $gtstem->{$key};
491			}
492
493			for my $key ((@{$clsprop->{<H::mg\|subnode1h>} or []}),
494			(@{$clsprop->{<H::mg\|ownee1h>} or []})) {
495			last HASREF if keys %{$gtstem->{$key}};
496			}
497
498			for my $key (@{$clsprop->{<H::mg\|subnode1a>} or []}) {
499			last HASREF if @{$gtstem->{$key}};
500			}
501
502			for my $key (@{$clsprop->{<H::mg\|subnode2hh>} or []}) {
503			for my $v (values %{$gtstem->{$key}}) {
504			last HASREF if keys %$v;
505			}
506			}
507
508			# No reference - i.e. not referenced
509			if ($gtstem->{<H::mg\|onunload>}) {
510			$gtstem->{<H::mg\|onunload>}->($bag, $nid);
511			}
512			CORE::delete $bag->{$$nid};
513			} # HASREF
514	wakaba	1.1	}
515			}
516
517			@CODE:
518			@@QName: mg\|collectGarbage
519			@@enDesc:
520			Garbage collection.
521			@@Param:
522	wakaba	1.10	@@@Name: bag
523	wakaba	1.1	@@@Type: HASH
524			@@@enDesc:
525	wakaba	1.10	The node bag.
526	wakaba	1.1	@@PerlDef:
527	wakaba	1.12	my @has_xref_group = ([]);
528			my @other_group = ([]);
529			my %done = (<H::mg\|mutations> => true);
530			TARGET: while (defined (my $target = each %{$bag})) {
531			next TARGET if $done{$target};
532			my $has_xref;
533			my %grove;
534			my %xgref;
535			my @gtarget = ($target);
536			GTARGET: while (defined (my $gtarget = shift @gtarget)) {
537			$done{$gtarget} = true;
538
539			next GTARGET if $grove{$gtarget};
540			$grove{$gtarget} = true;
541
542			my $gtstem = $bag->{$gtarget};
543			my $clsprop = $Message::Util::Grove::ClassProp{
544			${$gtstem->{<H::mg\|nodeClass>}}
545			};
546
547			$has_xref = true if $gtstem->{<H::mg\|references>};
548
549			for my $key (@{$clsprop->{<H::mg\|origin0>} or []}) {
550	wakaba	1.13	push @gtarget, ${$gtstem->{$key}} if defined $gtstem->{$key};
551	wakaba	1.12	}
552	wakaba	1.1
553	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|subnode1h>} or []}) {
554			for (values %{$gtstem->{$key} or {}}) {
555	wakaba	1.13	push @gtarget, $$_;
556	wakaba	1.12	}
557	wakaba	1.1	}
558
559	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|subnode1a>} or []}) {
560			for (@{$gtstem->{$key}}) {
561	wakaba	1.13	push @gtarget, $$_;
562	wakaba	1.1	}
563	wakaba	1.12	}
564	wakaba	1.1
565	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|subnode2hh>} or []}) {
566			for my $v (values %{$gtstem->{$key} or {}}) {
567			for (values %{$v or {}}) {
568	wakaba	1.13	push @gtarget, $$_;
569	wakaba	1.1	}
570			}
571	wakaba	1.12	}
572	wakaba	1.1
573	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|owner0>} or []}) {
574			$xgref{${$gtstem->{$key}}} = true if defined $gtstem->{$key};
575			}
576			} # GTARGET
577	wakaba	1.1
578	wakaba	1.12	for my $xgref (keys %xgref) {
579			CORE::delete $xgref{$xgref} if $grove{$xgref};
580			}
581	wakaba	1.1
582	wakaba	1.12	if ($has_xref) {
583			push @{$has_xref_group[0]}, [\%grove, \%xgref];
584			} else {
585			push @{$other_group[0]}, [\%grove, \%xgref];
586			}
587			} # target
588	wakaba	1.1
589	wakaba	1.12	my $i = 0;
590			GI: {
591	wakaba	1.13	$has_xref_group[$i+1] = [];
592			$other_group[$i+1] = [];
593
594	wakaba	1.12	OG: while (@{$other_group[$i]}) {
595			my $other_group = shift @{$other_group[$i]};
596			for my $has_group (@{$has_xref_group[$i]}) {
597			for (keys %{$has_group->[1]}) {
598			if ($other_group->[0]->{$_}) {
599	wakaba	1.13	push @{$has_xref_group[$i+1]}, $other_group;
600	wakaba	1.12	CORE::delete $has_group->[1]->{$_};
601			next OG;
602	wakaba	1.1	}
603			}
604	wakaba	1.12	}
605	wakaba	1.13	push @{$other_group[$i+1]}, $other_group;
606	wakaba	1.12	} # OG
607
608	wakaba	1.13	$i++;
609			if (@{$has_xref_group[$i]}) { # changed
610	wakaba	1.12	redo GI;
611			}
612			} # GI
613	wakaba	1.1
614	wakaba	1.13	for my $nid (map {keys %{$_->[0]}} @{$other_group[$i]}) {
615	wakaba	1.12	if ($bag->{$nid}->{<H::mg\|onunload>}) {
616			$bag->{$nid}->{<H::mg\|onunload>}->($bag, \$nid);
617			}
618			CORE::delete $bag->{$nid};
619			}
620	wakaba	1.1
621	wakaba	1.12	$bag->{<H::mg\|mutations>} = 0;
622	wakaba	1.2
623			@CODE:
624			@@QName: mg\|getNodeStemPropValue
625			@@enDesc:
626			Obtains a property value set to the node stem associated
627			to the node reference.
628			@@PerlDef:
629			$r = $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
630			->{$prop};
631
632			@CODE:
633	wakaba	1.3	@@QName: mg\|getNodeStemPropValueRef
634			@@enDesc:
635			Obtains the reference to a property value set to the node stem associated
636			to the node reference.
637			@@PerlDef:
638			$r = \$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
639			->{$prop};
640
641			@CODE:
642	wakaba	1.4	@@QName: mg\|get++NodeStemPropValue
643			@@enDesc:
644			Obtains a property value set to the node stem associated
645			to the node reference and then increments the value.
646			@@PerlDef:
647			$r = $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
648			->{$prop}++;
649
650			@CODE:
651	wakaba	1.2	@@QName: mg\|setNodeStemPropValue
652			@@enDesc:
653			Sets a property value to the node stem associated
654			to the node reference.
655			@@PerlDef:
656			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
657			->{$prop} = $given;
658	wakaba	1.4
659			@CODE:
660			@@QName: mg\|orSetNodeStemPropValue
661			@@enDesc:
662			Sets a property value to the node stem associated
663			to the node reference by <Perl::\|\|=> operator.
664			@@PerlDef:
665			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
666			->{$prop} \|\|= $given;
667	wakaba	1.2
668			@CODE:
669			@@QName: mg\|getNodeStemProp0Node
670			@@enDesc:
671			Obtains a property value node reference set to the node stem associated
672			to the node reference.
673			@@PerlDef:
674			my $__v = $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
675			->{$prop};
676			if (defined $__v) {
677			__CODE{mg\|createNodeRefFromID\|\|ManakaiDOM\|all::
678			$bag => {$ref->{<H::mg\|nodeBag>}},
679			$stemid => $__v,
680			$ref => $r,
681	wakaba	1.7	$opt => $opt,
682	wakaba	1.2	}__;
683			}
684	wakaba	1.3
685			@CODE:
686			@@QName: mg\|setNodeStemProp0Node
687			@@enDesc:
688			Sets a property value node to the node stem associated
689			to the node reference.
690			@@PerlDef:
691			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
692			->{$prop} = $given->{<H::mg\|nodeIDReference>};
693
694			@CODE:
695			@@QName: mg\|deleteNodeStemPropValue
696			@@enDesc:
697			Deletes a property value node from the node stem associated
698			to the node reference.
699			@@PerlDef:
700			CORE::delete $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
701			->{$prop};
702
703			@Code:
704			@@QName: mg\|nodeIDMatch
705			@@enDesc:
706			Whether a node reference references the same node
707			as a reference to a node identifier.
708			@@PerlDef:
709			(${$noderef->{<H::mg\|nodeIDReference>}} eq ${$nodeid})
710	wakaba	1.5
711			@CODE:
712			@@QName: mg\|getNodeRefPropValue
713			@@enDesc:
714			Obtains a property value set to the node reference.
715			@@PerlDef:
716			$r = $ref->{$prop};
717
718			@CODE:
719			@@QName: mg\|setNodeRefPropValue
720			@@enDesc:
721			Sets a property value set to the node reference.
722			@@PerlDef:
723			$ref->{$prop} = $given;
724	wakaba	1.1	##NodeRef
725
726			## -- Reference Internal Properties
727
728			RPropDef:
729			@QName: mg\|nodeRefKey
730			@subsetOf: DISPerl\|propHashKey
731			@multipleProperties: DISCore\|Single
732			@dataType: DISCore\|String
733
734			IntPropDef:
735			@QName: mg\|nodeIDReference
736			@enDesc:
737			The <Q::mg\|nodeID> of the node referenced by the node reference object.
738			@Type: DISPerl\|SCALAR
739			@mg:nodeRefKey: id
740
741			IntPropDef:
742			@QName: mg\|nodeBag
743			@enDesc:
744			The node bag object referenced by the node reference object.
745			@Type: DISPerl\|Ref
746			@mg:nodeRefKey: b