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/03/31 16:44: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};
      push @{$bag->{<H::mg|mutations>}},
           $bag->{${$owneeref->{<H::mg|nodeIDReference>}}}->{$owner0prop};
      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) {
          push @{$bag->{<H::mg|mutations>}}, $id;
          if (@{$bag->{<H::mg|mutations>}}
                  > (defined $Message::Util::Grove::GCLatency
                       ? $Message::Util::Grove::GCLatency : 4096)) {
            __CODE{mg|collectGarbage:: $ref => $self}__;
          }
        }

  @CODE:
    @@QName: mg|collectGarbage
    @@enDesc:
      Garbage collection.
    @@Param:
      @@@Name: ref
      @@@Type: HASH
      @@@enDesc:
        The node reference object.
    @@PerlDef:
        my $bag = $ref->{<H::mg|nodeBag>};
        my @target = @{$bag->{<H::mg|mutations>}};
        my %done;
        my %has_xref;
        TARGET: while (@target) {
          my $target = shift @target;

          next TARGET if $has_xref{$$target} or $done{$$target};

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

          my %grove;
          my @gtarget = ($target);
          my @gwreferred;
          GTARGET: while (@gtarget) {
            my $gtarget = shift @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 (@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>}}) {
              push @gtarget, $gtstem->{$key} if ref $gtstem->{$key};
            }

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

            A: for my $key (@{$clsprop->{<H::mg|subnode1a>}}) {
              next A unless ref $gtstem->{$key};
              push @gtarget, grep {ref $_} @{$gtstem->{$key}};
            }

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

            for my $key (@{$clsprop->{<H::mg|owner0>}}) {
              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->{$_};
          }
          push @target, @gwreferred;
        } # TARGET
        $bag->{<H::mg|mutations>} = [];

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