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/04/04 10:53:15 $

  @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::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)
      )

  @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>};
        if (--($bag->{${$self->{<H::mg|nodeIDReference>}}}
                   ->{<H::mg|references>}) < 1) {
          if (++($bag->{<H::mg|mutations>})
                  > (defined $Message::Util::Grove::GCLatency
                       ? $Message::Util::Grove::GCLatency : 25000)) {
            __CODE{mg|collectGarbage:: $bag => $bag}__;
          }
        }

  @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

## -- Other Property Names for Options

IntPropDef:
  @QName: mg|nodeRefClass
  @mg:nodeStemKey: nrcls
  @enDesc:
    The Perl package name of the class of the node reference.

IntPropDef:
  @QName: mg|nodeRefInterfaces
  @mg:nodeStemKey: nrifs
  @enDesc:
    A reference to the array that contains the Perl
    package names of the interfaces that the node reference
    should implement.
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.13	$Date: 2006/04/04 10:53:15 $
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::UniqueIDR \|\|=
218			[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
219			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
220			0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
221			[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
222			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
223			0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
224			[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
225			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
226			0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
227			[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
228			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
229			0 1 2 3 4 5 6 7 8 9/]->[rand 62] .
230			[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
231			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
232			0 1 2 3 4 5 6 7 8 9/]->[rand 62]) .
233			(++$Message::Util::ManakaiNode::UniqueIDN)
234			)
235
236			@CODE:
237			@@QName: mg\|setOwnerProp
238			@@enDesc:
239			Setting <Q::mg\|owner0> and <Q::mg\|ownee1h> property values.
240			@@PerlDef:
241			$ownee->{$owner0prop} = $ownerref->{<H::mg\|nodeIDReference>};
242			$bag->{${$ownerref->{<H::mg\|nodeIDReference>}}}
243			->{$ownee1hprop}->{${$ownee->{<H::mg\|nodeID>}}}
244			= $ownee->{<H::mg\|nodeID>};
245	wakaba	1.6
246			@CODE:
247			@@QName: mg\|setOwnerPropRR
248			@@enDesc:
249			Setting <Q::mg\|owner0> and <Q::mg\|ownee1h> property values
250			(node reference to node reference).
251			@@PerlDef:
252			$bag->{${$owneeref->{<H::mg\|nodeIDReference>}}}->{$owner0prop}
253			= $ownerref->{<H::mg\|nodeIDReference>};
254			$bag->{${$ownerref->{<H::mg\|nodeIDReference>}}}
255			->{$ownee1hprop}->{${$owneeref->{<H::mg\|nodeIDReference>}}}
256			= $owneeref->{<H::mg\|nodeIDReference>};
257
258			@CODE:
259			@@QName: mg\|deleteOwnerProp
260			@@enDesc:
261			Deletes <Q::mg\|owner0> and <Q::mg\|ownee1h> property values.
262			@@PerlDef:
263			CORE::delete $bag->{${$bag->{${$owneeref->{<H::mg\|nodeIDReference>}}}
264			->{$owner0prop} or \''}}
265			->{$ownee1hprop};
266	wakaba	1.12	$bag->{<H::mg\|mutations>}++;
267	wakaba	1.6	CORE::delete $bag->{${$owneeref->{<H::mg\|nodeIDReference>}}}
268			->{$owner0prop};
269	wakaba	1.1	##NodeStem
270
271
272			## -- Stem Internal Property Types
273
274			RPropDef:
275			@QName: mg\|propertyTypeKey
276			@subsetOf: DISPerl\|propHashKey
277
278			PTPropDef:
279			@QName: mg\|subnode0
280			@enDesc:
281			A subnode property.
282			@mg:propertyTypeKey: s0
283
284			PTPropDef:
285			@QName: mg\|subnode1a
286			@enDesc:
287			A subnode property containing an array reference.
288			@mg:propertyTypeKey: s1a
289
290			PTPropDef:
291			@QName: mg\|subnode1h
292			@enDesc:
293			A subnode property containing a hash reference.
294			@mg:propertyTypeKey: s1h
295
296			PTPropDef:
297			@QName: mg\|subnode2hh
298			@enDesc:
299			A subnode property containing a hash reference
300			containing hash references.
301			@mg:propertyTypeKey: s2hh
302
303			PTPropDef:
304			@QName: mg\|origin0
305			@enDesc:
306			An origin property.
307			@mg:propertyTypeKey: o0
308
309			PTPropDef:
310			@QName: mg\|owner0
311			@enDesc:
312			An owner property. It is <EM::not> traversed when garbage collection is
313			done.
314			@mg:propertyTypeKey: w0
315
316			PTPropDef:
317			@QName: mg\|ownee1h
318			@enDesc:
319			An ownee property. It <EM::is> traversed when garvage collection is done.
320			@mg:propertyTypeKey: v1h
321
322			ElementTypeBinding:
323			@Name: PTPropDef
324			@ElementType:
325			dis:ResourceDef
326			@ShadowContent:
327			@@DISCore:resourceType: DISSource\|ResourceProperty
328			@@multipleProperties: DISCore\|UnorderedList
329			@@dataType: DISCore\|QName
330
331			## -- Stem Internal Properties
332
333			RPropDef:
334			@QName: mg\|nodeStemKey
335			@subsetOf: DISPerl\|propHashKey
336			@multipleProperties: DISCore\|Single
337			@dataType: DISCore\|String
338
339			IntPropDef:
340			@QName: mg\|references
341			@enDesc:
342			The number of the external references to the node.
343			@Type: DISPerl\|Number
344			@mg:nodeStemKey: rc
345
346			IntPropDef:
347			@QName: mg\|nodeClass
348			@enDesc:
349			The Perl fully-qualified package name of the class
350			whose <CODE::___create_node_ref> method is invoked when
351			a reference to the node is instantiated.
352			@Type: DISPerl\|String
353			@mg:nodeStemKey: cls
354
355			IntPropDef:
356			@QName: mg\|nodeID
357			@enDesc:
358			The hash key string by which the node stem object can
359			be retrieved from the node bag.
360			@Type: DISPerl\|SCALAR
361			@mg:nodeStemKey: id
362
363	wakaba	1.8	IntPropDef:
364			@QName: mg\|onunload
365			@enDesc:
366			The code that is executed just before the node stem
367			is deleted from the node bag. Applications <kwd:MUST-NOT>
368			rely on the code being executed. Exactly when it
369			is executed is undefined. However, at the time of the
370			execution, the node stem is still accessible from
371			the node bag.
372
373			The code would receive two parameters: the node bag
374			and a reference to the node identifier. The code
375			<kwd:MUST-NOT> modify the node identifier. The code
376			<kwd:MUST-NOT> modify the node bag directly (neither
377			by hand nor by code fragments defined in this module); if
378			it does, the result is undefined. The code <kwd:MAY>
379			modify the node bag indirectly, via other node references,
380			since the referenced nodes should never part of the grove
381			being removed if there is such node reference.
382
383			The code <kwd:MUST-NOT> throw exceptions; if it does, result is undefined.
384			@Type: DISPerl\|CODE
385			@mg:nodeStemKey: beforefree
386	wakaba	1.1
387			## --------------------------------
388			## --- Node Reference
389
390			ClsDef:
391			@ClsQName: NodeRef
392
393			@ResourceDef:
394			@@QName: mg\|NodeRefRole
395			@@DISCore:resourceType: DISLang\|Role
396			@@enDesc:
397			Any class that is used as a node reference <kwd:MUST> set
398			its <Q::DISLang\|role> property as <Q::mg\|NodeRefRole>.
399
400			@ResourceDef:
401			@@QName: mg\|CreateNodeStemMethod
402			@@DISCore:resourceType: DISPerl\|CommonMethod
403			@@enDesc:
404			The method to create a node stem.
405
406			The method will invoked with four parameters: class name, node bag,
407			node stem prototype, and a reference to hash containing
408			optional parameters. The method <kwd:MUST> return a node
409			stem object. It <kwd:MAY> create and return the node
410			stem optionally by <Perl::bless>ing the node stem prototype
411			parameter with any appropriate class, or <kwd:MAY> create and
412			return the node stem object by its own way. It
413			<kwd:MAY> use options contained by the third parameter
414			to create the node stem object.
415
416			@CODE:
417			@@QName: mg\|createNodeRef
418			@@enDesc:
419			Creates a new node reference for the node stem.
420			@@PerlDef:
421	wakaba	1.2	$ref = ${$stem->{<H::mg\|nodeClass>}}->___create_node_ref ({
422	wakaba	1.1	<H::mg\|nodeIDReference> => $stem->{<H::mg\|nodeID>},
423			<H::mg\|nodeBag> => $bag,
424			}, $opt);
425			$stem->{<H::mg\|references>}++;
426
427	wakaba	1.2	@CODE:
428			@@QName: mg\|createNodeRefFromID
429			@@enDesc:
430			Creates a new node reference for the node stem.
431			@@PerlDef:
432	wakaba	1.3	$ref = ${$bag->{${$stemid}}->{<H::mg\|nodeClass>}}->___create_node_ref ({
433	wakaba	1.2	<H::mg\|nodeIDReference> => $stemid,
434			<H::mg\|nodeBag> => $bag,
435			}, $opt);
436	wakaba	1.3	$bag->{${$stemid}}->{<H::mg\|references>}++;
437	wakaba	1.2
438	wakaba	1.6	@Code:
439			@@QName: mg\|createNodeRefHashFromID
440			@@enDesc:
441			Creates a node reference hash, which is a hash reference
442			that can be handled as if it were a node reference,
443			from a node bag by its node identifier.
444			@@PerlDef:
445			{
446			<H::mg\|nodeIDReference> => $stemid,
447			<H::mg\|nodeBag> => $bag,
448			}
449
450	wakaba	1.1	@ResourceDef:
451			@@QName: mg\|CreateNodeRefMethod
452			@@DISCore:resourceType: DISPerl\|CommonMethod
453			@@enDesc:
454			The method to create a node reference to the node.
455
456			The method will invoked with three parameters: class name,
457			node reference prototype, and a reference to hash containing
458			optional parameters. The method <kwd:MUST> return a node
459			reference object. It <kwd:MAY> create and return the node
460			reference by <Perl::bless>ing the node reference prototype
461			parameter with any appropriate class, or <kwd:MAY> create and
462			return the node reference object by its own way. It
463			<kwd:MAY> use options contained by the third parameter
464			to create the node reference object.
465
466			@Code:
467			@@QName: mg\|getNodeBag
468			@@enDesc:
469	wakaba	1.3	Returns the node bag to which the node stem referenced by
470			a node reference belongs.
471	wakaba	1.1	@@PerlDef:
472			$ref->{<H::mg\|nodeBag>}
473
474	wakaba	1.3	@Code:
475			@@QName: mg\|getNodeID
476			@@enDesc:
477			Returns the identifier of the node referenced by a node reference.
478			@@PerlDef:
479			$ref->{<H::mg\|nodeIDReference>}
480
481			@Code:
482			@@QName: mg\|getNodeStem
483			@@enDesc:
484			Returns the node stem referenced by a node reference.
485			@@PerlDef:
486			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
487
488	wakaba	1.1	@Method:
489			@@Name: destroy
490			@@Return:
491			@@@PerlDef:
492			my $bag = $self->{<H::mg\|nodeBag>};
493	wakaba	1.12	if (--($bag->{${$self->{<H::mg\|nodeIDReference>}}}
494			->{<H::mg\|references>}) < 1) {
495			if (++($bag->{<H::mg\|mutations>})
496	wakaba	1.9	> (defined $Message::Util::Grove::GCLatency
497	wakaba	1.12	? $Message::Util::Grove::GCLatency : 25000)) {
498	wakaba	1.10	__CODE{mg\|collectGarbage:: $bag => $bag}__;
499	wakaba	1.1	}
500			}
501
502			@CODE:
503			@@QName: mg\|collectGarbage
504			@@enDesc:
505			Garbage collection.
506			@@Param:
507	wakaba	1.10	@@@Name: bag
508	wakaba	1.1	@@@Type: HASH
509			@@@enDesc:
510	wakaba	1.10	The node bag.
511	wakaba	1.1	@@PerlDef:
512	wakaba	1.12	my @has_xref_group = ([]);
513			my @other_group = ([]);
514			my %done = (<H::mg\|mutations> => true);
515			TARGET: while (defined (my $target = each %{$bag})) {
516			next TARGET if $done{$target};
517			my $has_xref;
518			my %grove;
519			my %xgref;
520			my @gtarget = ($target);
521			GTARGET: while (defined (my $gtarget = shift @gtarget)) {
522			$done{$gtarget} = true;
523
524			next GTARGET if $grove{$gtarget};
525			$grove{$gtarget} = true;
526
527			my $gtstem = $bag->{$gtarget};
528			my $clsprop = $Message::Util::Grove::ClassProp{
529			${$gtstem->{<H::mg\|nodeClass>}}
530			};
531
532			$has_xref = true if $gtstem->{<H::mg\|references>};
533
534			for my $key (@{$clsprop->{<H::mg\|origin0>} or []}) {
535	wakaba	1.13	push @gtarget, ${$gtstem->{$key}} if defined $gtstem->{$key};
536	wakaba	1.12	}
537	wakaba	1.1
538	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|subnode1h>} or []}) {
539			for (values %{$gtstem->{$key} or {}}) {
540	wakaba	1.13	push @gtarget, $$_;
541	wakaba	1.12	}
542	wakaba	1.1	}
543
544	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|subnode1a>} or []}) {
545			for (@{$gtstem->{$key}}) {
546	wakaba	1.13	push @gtarget, $$_;
547	wakaba	1.1	}
548	wakaba	1.12	}
549	wakaba	1.1
550	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|subnode2hh>} or []}) {
551			for my $v (values %{$gtstem->{$key} or {}}) {
552			for (values %{$v or {}}) {
553	wakaba	1.13	push @gtarget, $$_;
554	wakaba	1.1	}
555			}
556	wakaba	1.12	}
557	wakaba	1.1
558	wakaba	1.12	for my $key (@{$clsprop->{<H::mg\|owner0>} or []}) {
559			$xgref{${$gtstem->{$key}}} = true if defined $gtstem->{$key};
560			}
561			} # GTARGET
562	wakaba	1.1
563	wakaba	1.12	for my $xgref (keys %xgref) {
564			CORE::delete $xgref{$xgref} if $grove{$xgref};
565			}
566	wakaba	1.1
567	wakaba	1.12	if ($has_xref) {
568			push @{$has_xref_group[0]}, [\%grove, \%xgref];
569			} else {
570			push @{$other_group[0]}, [\%grove, \%xgref];
571			}
572			} # target
573	wakaba	1.1
574	wakaba	1.12	my $i = 0;
575			GI: {
576	wakaba	1.13	$has_xref_group[$i+1] = [];
577			$other_group[$i+1] = [];
578
579	wakaba	1.12	OG: while (@{$other_group[$i]}) {
580			my $other_group = shift @{$other_group[$i]};
581			for my $has_group (@{$has_xref_group[$i]}) {
582			for (keys %{$has_group->[1]}) {
583			if ($other_group->[0]->{$_}) {
584	wakaba	1.13	push @{$has_xref_group[$i+1]}, $other_group;
585	wakaba	1.12	CORE::delete $has_group->[1]->{$_};
586			next OG;
587	wakaba	1.1	}
588			}
589	wakaba	1.12	}
590	wakaba	1.13	push @{$other_group[$i+1]}, $other_group;
591	wakaba	1.12	} # OG
592
593	wakaba	1.13	$i++;
594			if (@{$has_xref_group[$i]}) { # changed
595	wakaba	1.12	redo GI;
596			}
597			} # GI
598	wakaba	1.1
599	wakaba	1.13	for my $nid (map {keys %{$_->[0]}} @{$other_group[$i]}) {
600	wakaba	1.12	if ($bag->{$nid}->{<H::mg\|onunload>}) {
601			$bag->{$nid}->{<H::mg\|onunload>}->($bag, \$nid);
602			}
603			CORE::delete $bag->{$nid};
604			}
605	wakaba	1.1
606	wakaba	1.12	$bag->{<H::mg\|mutations>} = 0;
607	wakaba	1.2
608			@CODE:
609			@@QName: mg\|getNodeStemPropValue
610			@@enDesc:
611			Obtains a property value set to the node stem associated
612			to the node reference.
613			@@PerlDef:
614			$r = $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
615			->{$prop};
616
617			@CODE:
618	wakaba	1.3	@@QName: mg\|getNodeStemPropValueRef
619			@@enDesc:
620			Obtains the reference to a property value set to the node stem associated
621			to the node reference.
622			@@PerlDef:
623			$r = \$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
624			->{$prop};
625
626			@CODE:
627	wakaba	1.4	@@QName: mg\|get++NodeStemPropValue
628			@@enDesc:
629			Obtains a property value set to the node stem associated
630			to the node reference and then increments the value.
631			@@PerlDef:
632			$r = $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
633			->{$prop}++;
634
635			@CODE:
636	wakaba	1.2	@@QName: mg\|setNodeStemPropValue
637			@@enDesc:
638			Sets a property value to the node stem associated
639			to the node reference.
640			@@PerlDef:
641			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
642			->{$prop} = $given;
643	wakaba	1.4
644			@CODE:
645			@@QName: mg\|orSetNodeStemPropValue
646			@@enDesc:
647			Sets a property value to the node stem associated
648			to the node reference by <Perl::\|\|=> operator.
649			@@PerlDef:
650			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
651			->{$prop} \|\|= $given;
652	wakaba	1.2
653			@CODE:
654			@@QName: mg\|getNodeStemProp0Node
655			@@enDesc:
656			Obtains a property value node reference set to the node stem associated
657			to the node reference.
658			@@PerlDef:
659			my $__v = $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
660			->{$prop};
661			if (defined $__v) {
662			__CODE{mg\|createNodeRefFromID\|\|ManakaiDOM\|all::
663			$bag => {$ref->{<H::mg\|nodeBag>}},
664			$stemid => $__v,
665			$ref => $r,
666	wakaba	1.7	$opt => $opt,
667	wakaba	1.2	}__;
668			}
669	wakaba	1.3
670			@CODE:
671			@@QName: mg\|setNodeStemProp0Node
672			@@enDesc:
673			Sets a property value node to the node stem associated
674			to the node reference.
675			@@PerlDef:
676			$ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
677			->{$prop} = $given->{<H::mg\|nodeIDReference>};
678
679			@CODE:
680			@@QName: mg\|deleteNodeStemPropValue
681			@@enDesc:
682			Deletes a property value node from the node stem associated
683			to the node reference.
684			@@PerlDef:
685			CORE::delete $ref->{<H::mg\|nodeBag>}->{${$ref->{<H::mg\|nodeIDReference>}}}
686			->{$prop};
687
688			@Code:
689			@@QName: mg\|nodeIDMatch
690			@@enDesc:
691			Whether a node reference references the same node
692			as a reference to a node identifier.
693			@@PerlDef:
694			(${$noderef->{<H::mg\|nodeIDReference>}} eq ${$nodeid})
695	wakaba	1.5
696			@CODE:
697			@@QName: mg\|getNodeRefPropValue
698			@@enDesc:
699			Obtains a property value set to the node reference.
700			@@PerlDef:
701			$r = $ref->{$prop};
702
703			@CODE:
704			@@QName: mg\|setNodeRefPropValue
705			@@enDesc:
706			Sets a property value set to the node reference.
707			@@PerlDef:
708			$ref->{$prop} = $given;
709	wakaba	1.1	##NodeRef
710
711			## -- Reference Internal Properties
712
713			RPropDef:
714			@QName: mg\|nodeRefKey
715			@subsetOf: DISPerl\|propHashKey
716			@multipleProperties: DISCore\|Single
717			@dataType: DISCore\|String
718
719			IntPropDef:
720			@QName: mg\|nodeIDReference
721			@enDesc:
722			The <Q::mg\|nodeID> of the node referenced by the node reference object.
723			@Type: DISPerl\|SCALAR
724			@mg:nodeRefKey: id
725
726			IntPropDef:
727			@QName: mg\|nodeBag
728			@enDesc:
729			The node bag object referenced by the node reference object.
730			@Type: DISPerl\|Ref
731			@mg:nodeRefKey: b
732	wakaba	1.6
733			## -- Other Property Names for Options
734
735			IntPropDef:
736			@QName: mg\|nodeRefClass
737			@mg:nodeStemKey: nrcls
738			@enDesc:
739			The Perl package name of the class of the node reference.
740	wakaba	1.7
741			IntPropDef:
742			@QName: mg\|nodeRefInterfaces
743			@mg:nodeStemKey: nrifs
744			@enDesc:
745			A reference to the array that contains the Perl
746			package names of the interfaces that the node reference
747			should implement.