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/03 12:53:25 $

  @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> => {},
      };
##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>}
          ->{${$bag->{${$owneeref->{<H::mg|nodeIDReference>}}}->{$owner0prop}}}
          = true;
      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 $id = $self->{<H::mg|nodeIDReference>};
        my $bag = $self->{<H::mg|nodeBag>};
        if (--$bag->{$$id}->{<H::mg|references>} < 1) {
          $bag->{<H::mg|mutations>}->{$$id} = true;
          if (0+(keys %{$bag->{<H::mg|mutations>}})
                  > (defined $Message::Util::Grove::GCLatency
                       ? $Message::Util::Grove::GCLatency : 40000)) {
            __CODE{mg|collectGarbage:: $bag => $bag}__;
          }
        }

  @CODE:
    @@QName: mg|collectGarbage
    @@enDesc:
      Garbage collection.
    @@Param:
      @@@Name: bag
      @@@Type: HASH
      @@@enDesc:
        The node bag.
    @@PerlDef:
        my %done;
        my %has_xref;
        TARGET: while (%{$bag->{<H::mg|mutations>}}) {
          my $target = each %{$bag->{<H::mg|mutations>}};
          next TARGET unless defined $target;
          CORE::delete $bag->{<H::mg|mutations>}->{$target};
        
          next TARGET if $has_xref{$target} or $done{$target};

          unless (defined $bag->{$target}) {
            $done{$target} = true;
            next TARGET;
          }

          my %grove;
          my %gtarget = ($target => true);
          my @gwreferred;
          GTARGET: while (%gtarget) {
            my $gtarget = each %gtarget;
            next GTARGET unless defined $gtarget;
            CORE::delete $gtarget{$gtarget};
            next GTARGET if $grove{$gtarget};

            my $gtstem = $bag->{$gtarget};
            unless (defined $gtstem) {
              $done{$gtarget} = true;
              next GTARGET;
            }

            if ($has_xref{$gtarget} or $gtstem->{<H::mg|references>}) {
              $has_xref{$gtarget} = true;
              $has_xref{$_} = true for keys %grove;
              for (keys %gtarget) {
                $has_xref{$_} = defined $bag->{$_};
                $done{$_} = true;
              }
              next TARGET;
            } elsif ($done{$gtarget}) {
              next GTARGET;
            }

            my $clsprop = $Message::Util::Grove::ClassProp{
                            ${$gtstem->{<H::mg|nodeClass>}}
                          };

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

            A: for my $key ((@{$clsprop->{<H::mg|ownee1h>} or []}),
                            (@{$clsprop->{<H::mg|subnode1h>} or []})) {
              next A unless ref $gtstem->{$key};
              $gtarget{$$_} = true for grep {ref $_} values %{$gtstem->{$key}};
            }

            A: for my $key (@{$clsprop->{<H::mg|subnode1a>} or []}) {
              next A unless ref $gtstem->{$key};
              $gtarget{$$_} = true for grep {ref $_} @{$gtstem->{$key}};
            }

            A: for my $key (@{$clsprop->{<H::mg|subnode2hh>} or []}) {
              next A unless ref $gtstem->{$key};
              B: for my $key2 (keys %{$gtstem->{$key}}) {
                next B unless ref $gtstem->{$key}->{$key2};
                $gtarget{$$_} = true for grep {ref $_}
                                         values %{$gtstem->{$key}->{$key2}};
              }
            }

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

            $grove{$gtarget} = true;
          } # GTARGET

          for (keys %grove) {
            $done{$_} = true;
            if (defined $bag->{$_}->{<H::mg|onunload>}) {
              $bag->{$_}->{<H::mg|onunload>}->($bag, \$_);
            }
            delete $bag->{$_};
          }
          $bag->{<H::mg|mutations>}->{$_} = true for @gwreferred;
        } # TARGET

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