Message/Util/ManakaiNode.dis

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

  @Author:
    @@FullName: Wakaba
    @@Mail: w@suika.fam.cx
  @License:
     license:Perl+MPL
  @Date:
    @@@:
      $Date: 2005/02/16 04:25:00 $
    @@ContentType:
      dis:Date.RCS
  
  @Require:
    @@Module:
      @@@Name: DISPerl
      @@@WithFor:
        ManakaiDOM:all
#    @@Module:
#      @@@Name: ManakaiNode
#      @@@WithFor:
#        ManakaiDOM:Perl

Namespace:
  @dis:
    http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#dis--
  @dis2pm:
    http://suika.fam.cx/~wakaba/archive/2004/11/8/dis2pm#
  @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#
  @owl:
    http://www.w3.org/2002/07/owl#
  @Perl:
    http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#Perl--
  @rdf:
    http://www.w3.org/1999/02/22-rdf-syntax-ns#
  @rdfs:
    http://www.w3.org/2000/01/rdf-schema#
  @TreeCore:\
  @Util:
    http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/

ResourceDef:
  @QName:
    Util:
  @rdf:type:
    dis:ModuleGroup
  @FullName:
    @@lang:en
    @@@:
      The manakai support modules
  @AppName:
    Message::Util::

## -- Internal node object

ClassDef:
  @QName: 
    ManakaiDOM:ManakaiDOMNodeObject
  @Description:
    @@lang:en
    @@@:
      Internal (actual) node objects that is accessed via 
      <Class::ManakaiDOM:ManakaiDOMNodeReference> objects referring it. 
  @ImplNote:
    @@lang:en
    @@@:
      No public interface should be defined for any class inheriting 
      this class - applications should access to nodes only via 
      <Class::ManakaiDOM:ManakaiDOMNodeReference> objects. 
  @ImplNote:
    @@lang:en
    @@@:
      A <Class::ManakaiDOM:ManakaiDOMNodeObject> is a blessed hash 
      reference.  Each hash key and value pair is called as a 
      <DFN::property>.  Currently, several core properties  
      are defined as listed below.  Applications for this class, 
      including <Class::DOMCore:ManakaiDOMNode>, defines additional 
      properties for their purpose and scope. 
      \
      {FIG:: Core node properties
         \
         - <CODE::TreeCore:nodeID>::: The global-unique identifier for 
                                      this node object. 
         \
         - <CODE::TreeCore:treeID>::: The global-unique identifier for the 
                                      tree containing this node object. 
         \
         - <CODE::TreeCore:rc>::: The number that denotes how many reference 
                                  to this node there are. 
         \
         - <CODE::TreeCore:origin>::: An array reference, containing 
                                  hash key names of <DFN::origin> 
                                  properties for this node. 
         \
         - <CODE::TreeCore:subnode>::: An array reference, containing 
                                hash key names of <DFN::subnode> 
                                properties for this node. 
         \
         - <CODE::TreeCore:subnode2>::: An array reference, containing 
                    hash key names of <DFN::subnode> (two steps) 
                    properties for this node. 
         \
         - <CODE::TreeCore:irefnode>::: An array reference, containing 
                    hash key names of <DFN::irefnode> 
                    properties for this node. 
         \
         - <CODE::TreeCore:anydata>::: An array reference, containing 
                    hash key names of <DFN::anydata> properties for this node. 
         \
         - <CODE::TreeCore:anydata2>::: An array reference, containing 
                    hash key names of <DFN::anydata> (two steps) properties 
                    for this node. 
         \
       }

  @IntMethod:
    @@Name: new
    @@Description:
      @@@lang:en
      @@@@: 
        Constructs a new instance of 
        <Class::ManakaiDOM:ManakaiDOMNodeObject> and returns it.
    @@Return:
      @@@Type: 
        ManakaiDOM:ManakaiDOMNodeObject
      @@@Description:
        @@@@lang:en
        @@@@@: 
          The newly created <Class::ManakaiDOM:ManakaiDOMNodeObject> instance.
      @@@PerlDef:
          $r = bless {
            <Q::TreeCore:origin> => [],
            <Q::TreeCore:subnode> => [],
            <Q::TreeCore:subnode2> => [],
            <Q::TreeCore:irefnode> => [],
            <Q::TreeCore:anydata> => [],
            <Q::TreeCore:anydata2> => [],
            <Q::TreeCore:rc> => 0,
            <Q::TreeCore:treeID> => <Code::ManakaiDOM:generateUniqueID>,
            <Q::TreeCore:nodeID> => <Code::ManakaiDOM:generateUniqueID>,
          }, ref $self || $self;
  @IntMethod:
    @@Name: newReference
    @@Description:
      @@@lang:en
      @@@@:
        Creates a new reference to this node and returns it.
    @@Param:
      @@@Name: class
      @@@Type:
        Perl:package-name
      @@@Description:
        @@@@lang:en
        @@@@@:
          A Perl class package name with which the newly created 
          reference is blessed.  The <P::class> class must be a 
          subclass of <Class::ManakaiDOM:ManakaiDOM:ManakaiDOMNodeReference>.
    @@Return:
      @@@Type: 
        ManakaiDOM:ManakaiDOMNodeReference
      @@@Description:
        @@@@lang:en
        @@@@@:
          The newly created node reference.
      @@@PerlDef:
          $r = bless {
            <Q::TreeCore:node> => $self,
          }, ref $class ? ref $class : $class ? $class :
             <ClassName::ManakaiDOM:ManakaiDOMNodeReference>;
          $self->{<Q::TreeCore:rc>}++;
  @IntMethod:
    @@Name: isExternallyReferred
    @@Description:
      @@@lang:en
      @@@@:
        Checks whether the tree containing this node has been referred 
        from the outside of the tree or not. 
    @@Return:
      @@@Type: 
        DISPerl:Boolean
      @@@InCase:
        @@@@Value: true
        @@@@Type:
          DISPerl:Boolean
        @@@@Description:
          @@@@@lang:en
          @@@@@@: 
            There is one or more nodes in the tree that has been 
            referred via <Class::ManakaiDOM:ManakaiDOMNodeReference> objects.
      @@@InCase:
        @@@@Value: false
        @@@@Type:
          DISPerl:Boolean
        @@@@Description:
          @@@@@lang:en
          @@@@@@: No external reference found.
      @@@PerlDef:
          if ($self->{<Q::TreeCore:rc>}) {
            $r = true;
          } else {
            my @node = ($self);
            my %checked;
            NODES: while (my $node = shift @node) {
              if ($node->{<Q::TreeCore:rc>}) {
                $r = true;
                last NODES;
              } elsif ($checked{$node->{<Q::TreeCore:nodeID>}}) {
                next NODES;
              }
              my @n;
              for (@{$node->{<Q::TreeCore:subnode2>}}) {
                if (ref $node->{$_} eq 'ARRAY') {
                  push @n, @{$node->{$_}};
                } elsif (ref $node->{$_} eq 'HASH') {
                  push @n, values %{$node->{$_}};
                }
              }
              for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
                if (ref $_ eq 'ARRAY') {
                  push @node, @$_;
                } elsif (ref $_ eq 'HASH') {
                  push @node, values %$_;
                }
              }
              for (@{$node->{<Q::TreeCore:origin>}}) {
                push @node, $node->{$_} if $node->{$_};
              }
              $checked{$node->{<Q::TreeCore:nodeID>}} = 1;
            }
          }

  @IntMethod:
    @@Name: destroy
    @@Description:
      @@@lang:en
      @@@@:
        Destructs the tree containing this node. 
    @@Return:
      @@@PerlDef:
        my @node = ($self);
        NODES: while (my $node = shift @node) {
              my @n;
              for (@{$node->{<Q::TreeCore:subnode2>}}) {
                if (ref $node->{$_} eq 'ARRAY') {
                  push @n, @{$node->{$_}};
                } elsif (ref $node->{$_} eq 'HASH') {
                  push @n, values %{$node->{$_}};
                }
              }
              for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
                if (ref $_ eq 'ARRAY') {
                  push @node, grep {defined $_->{<Q::TreeCore:nodeID>}} @$_;
                } elsif (ref $_ eq 'HASH') {
                  push @node, grep {defined $_->{<Q::TreeCore:nodeID>}}
                               values %$_;
                }
              }
              for (@{$node->{<Q::TreeCore:origin>}}) {
                push @node, $node->{$_}
                  if defined $node->{$_} and
                     defined $node->{$_}->{<Q::TreeCore:nodeID>};
              }
          %$node = ();
        }
    @@ImplNote:
      @@@lang:en
      @@@@:
        This method is different from Perl <Perl::DESTROY> special 
        purpose method.
        \
        An <QUOTE::uninitialized> warning in this method might mean 
        some method puts an <Perl::undef> into a list of nodes. 

  @IntMethod:
    @@Name: importTree
    @@Description:
      @@@lang:en
      @@@@:
        Changes the tree identifier of the nodes belong to another tree 
        to be same as this node's tree identifier. 
    @@Param:
      @@@Name: node
      @@@Type: 
        ManakaiDOM:ManakaiDOMNodeObject
      @@@Description:
        @@@@lang:en
        @@@@@:
          Any node from the tree to change its identifier. 
    @@Return:
      @@@PerlDef:
        unless ($node->{<Q::TreeCore:treeID>} eq
                $self->{<Q::TreeCore:treeID>}) {
          my @node = ($node);
          NODES: while (my $node = shift @node) {
              my @n;
              for (@{$node->{<Q::TreeCore:subnode2>}}) {
                if (ref $node->{$_} eq 'ARRAY') {
                  push @n, @{$node->{$_}};
                } elsif (ref $node->{$_} eq 'HASH') {
                  push @n, values %{$node->{$_}};
                }
              }
              for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
                if (ref $_ eq 'ARRAY') {
                  push @node, grep {$_->{<Q::TreeCore:treeID>} ne
                                    $self->{<Q::TreeCore:treeID>}} @$_;
                } elsif (ref $_ eq 'HASH') {
                  push @node, grep {$_->{<Q::TreeCore:treeID>} ne
                                    $self->{<Q::TreeCore:treeID>}}
                              values %$_;
                }
              }
            for (@{$node->{<Q::TreeCore:origin>}}) {
              push @node, $node->{$_}
                if defined $node->{$_} and
                   $node->{$_}->{<Q::TreeCore:treeID>} ne
                   $self->{<Q::TreeCore:treeID>};
            }
            $node->{<Q::TreeCore:treeID>} = $self->{<Q::TreeCore:treeID>};
          }
        }

  @IntMethod:
    @@Name: changeTreeID
    @@Description:
      @@@lang:en
      @@@@:
        Changes tree identifier of all nodes traversable from this node. 
    @@Param:
      @@@Name: treeID
      @@@Type: 
        DISPerl:String
      @@@Description:
        @@@@lang:en
        @@@@@:
          The new tree identifier. 
    @@Return:
      @@@PerlDef:
        unless ($self->{<Q::TreeCore:treeID>} eq $treeID) {
          my @node = ($self);
          NODES: while (my $node = shift @node) {
              my @n;
              for (@{$node->{<Q::TreeCore:subnode2>}}) {
                if (ref $node->{$_} eq 'ARRAY') {
                  push @n, @{$node->{$_}};
                } elsif (ref $node->{$_} eq 'HASH') {
                  push @n, values %{$node->{$_}};
                }
              }
              for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
                if (ref $_ eq 'ARRAY') {
                  push @node, grep {$_->{<Q::TreeCore:treeID>} ne $treeID} @$_;
                } elsif (ref $_ eq 'HASH') {
                  push @node, grep {$_->{<Q::TreeCore:treeID>} ne $treeID}
                              values %$_;
                }
              }
            for (@{$node->{<Q::TreeCore:origin>}}) {
              push @node, $node->{$_}
                if defined $node->{$_} and
                   $node->{$_}->{<Q::TreeCore:treeID>} ne $treeID;
            }
            $node->{<Q::TreeCore:treeID>} = $treeID;
          }
        }

  @IntMethod:
    @@Name: getRootNodes
    @@Description:
      @@@lang:en
      @@@@:
        Gets root nodes in the tree to which this node belongs,
        at <QUOTE::higher> level than this node. 
        \
        {NOTE:: The manakai internal tree structure may have more than 
                one tree root node - it is a set of tree sharing their 
                nodes rather than a single tree.  In this method 
                <DFN::root nodes> is defined as the nodes that 
                have no their <QUOTE::origin> node.  There is at least 
                one such node by definition of the manakai tree structure. 
                <QUOTE::Higher> in this context means that the node is reachable
                by only traversing <QUOTE::origin> relationships from this node. 
        \
        }
    @@Return:
      @@@Type:
        Perl:ARRAY
      @@@PerlDef:
        my %result;
        my @node = ($self);
        NODES: while (my $node = shift @node) {
          my $i = 0;
          ORIGINS: for (@{$node->{<Q::TreeCore:origin>}}) {
            next ORIGINS unless $node->{$_};
            $i++;
            push @node, $node->{$_};
          }
          if ($i == 0) {
            $result{$node->{<Q::TreeCore:nodeID>}} = $node;
          }
        }
   \    @$r = (grep {defined $_->{<Q::TreeCore:nodeID>}} values %result);

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

## -- Public node object

ClassDef:
  @QName: 
    ManakaiDOM:ManakaiDOMNodeReference
  @Description:
    @@lang:en
    @@@:
      References to the node object corresponding to it.  From 
      applications' view, any node object is hidden and 
      <Class::ManakaiDOM:ManakaiDOMNodeReference> seems as if 
      the node itself. 
  @ImplNote:
    @@lang:en
    @@@:
      A <Class::ManakaiDOM:ManakaiDOMNodeReference> is a blessed hash 
      reference; currently there is a hash key defined:
        \
        - <CODE::TreeCore:node>::: A node object 
             (<Class::ManakaiDOM:ManakaiDOMNodeObject>) to which 
             this is referring. 

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

## -- Frequently used code fragments

ResourceDef:
  @QName:
    ManakaiDOM:generateUniqueID
  @rdf:type:
    dis2pm:InlineCode
  @Description:
    @@lang:en
    @@@:
      Generates a global-unique opaque string. 
      \
      {NOTE:: A URI reference is generated by this code. 
      \
      }
  @AliasFor:
    @@@:
      ::ManakaiDOM:all
    @@For:
      !=ManakaiDOM:all
  @PerlDef:
      (
        sprintf 'mid:%d.%d.%s.dom.manakai@suika.fam.cx#',
                time, $$,
                ['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
                ['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
                ['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
                ['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
                ['A'..'Z', 'a'..'z', '0'..'9']->[rand 62]
      )
##ManakaiDOM:generateUniqueID

## -- lang:dis vocabulary

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

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

## -- Syntax sugar

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

ElementTypeBinding:
  @Name: ClassDef
  @ElementType:
    dis:ResourceDef
  @ShadowContent:
    @@rdf:type:
      ManakaiDOM:Class
    @@AliasFor:
      @@@@:
        ::ManakaiDOM:all
      @@@For:
        !=ManakaiDOM:all

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

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

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

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

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

## ManakaiNode.dis ends here
1	wakaba	1.1	Module:
2			@QName:
3			Util:ManakaiNode
4			@FullName:
5			@@lang: en
6			@@@:
7			Manakai Generic Node Implementation
8			@Namespace:
9			http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/ManakaiNode#
10
11			@Description:
12			@@lang:en
13			@@@:
14			The <Module::Util:ManakaiNode> module provides a basic
15			implementation for glaph (perhaps tree) structures.
16
17			@Author:
18			@@FullName: Wakaba
19			@@Mail: w@suika.fam.cx
20			@License:
21			license:Perl+MPL
22			@Date:
23			@@@:
24			$Date: 2005/02/16 04:25:00 $
25			@@ContentType:
26			dis:Date.RCS
27
28			@Require:
29			@@Module:
30			@@@Name: DISPerl
31			@@@WithFor:
32			ManakaiDOM:all
33			# @@Module:
34			# @@@Name: ManakaiNode
35			# @@@WithFor:
36			# ManakaiDOM:Perl
37
38			Namespace:
39			@dis:
40			http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#dis--
41			@dis2pm:
42			http://suika.fam.cx/~wakaba/archive/2004/11/8/dis2pm#
43			@lang:
44			http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#
45			@license:
46			http://suika.fam.cx/~wakaba/archive/2004/8/18/license#
47			@ManakaiDOM:
48			http://suika.fam.cx/~wakaba/archive/2004/8/18/manakai-dom#
49			@owl:
50			http://www.w3.org/2002/07/owl#
51			@Perl:
52			http://suika.fam.cx/~wakaba/archive/2004/8/18/lang#Perl--
53			@rdf:
54			http://www.w3.org/1999/02/22-rdf-syntax-ns#
55			@rdfs:
56			http://www.w3.org/2000/01/rdf-schema#
57			@TreeCore:\
58			@Util:
59			http://suika.fam.cx/~wakaba/archive/2005/manakai/Util/
60
61			ResourceDef:
62			@QName:
63			Util:
64			@rdf:type:
65			dis:ModuleGroup
66			@FullName:
67			@@lang:en
68			@@@:
69			The manakai support modules
70			@AppName:
71			Message::Util::
72
73			## -- Internal node object
74
75			ClassDef:
76			@QName:
77			ManakaiDOM:ManakaiDOMNodeObject
78			@Description:
79			@@lang:en
80			@@@:
81			Internal (actual) node objects that is accessed via
82			<Class::ManakaiDOM:ManakaiDOMNodeReference> objects referring it.
83			@ImplNote:
84			@@lang:en
85			@@@:
86			No public interface should be defined for any class inheriting
87			this class - applications should access to nodes only via
88			<Class::ManakaiDOM:ManakaiDOMNodeReference> objects.
89			@ImplNote:
90			@@lang:en
91			@@@:
92			A <Class::ManakaiDOM:ManakaiDOMNodeObject> is a blessed hash
93			reference. Each hash key and value pair is called as a
94			<DFN::property>. Currently, several core properties
95			are defined as listed below. Applications for this class,
96			including <Class::DOMCore:ManakaiDOMNode>, defines additional
97			properties for their purpose and scope.
98			\
99			{FIG:: Core node properties
100			\
101			- <CODE::TreeCore:nodeID>::: The global-unique identifier for
102			this node object.
103			\
104			- <CODE::TreeCore:treeID>::: The global-unique identifier for the
105			tree containing this node object.
106			\
107			- <CODE::TreeCore:rc>::: The number that denotes how many reference
108			to this node there are.
109			\
110			- <CODE::TreeCore:origin>::: An array reference, containing
111			hash key names of <DFN::origin>
112			properties for this node.
113			\
114			- <CODE::TreeCore:subnode>::: An array reference, containing
115			hash key names of <DFN::subnode>
116			properties for this node.
117			\
118			- <CODE::TreeCore:subnode2>::: An array reference, containing
119			hash key names of <DFN::subnode> (two steps)
120			properties for this node.
121			\
122			- <CODE::TreeCore:irefnode>::: An array reference, containing
123			hash key names of <DFN::irefnode>
124			properties for this node.
125			\
126			- <CODE::TreeCore:anydata>::: An array reference, containing
127			hash key names of <DFN::anydata> properties for this node.
128			\
129			- <CODE::TreeCore:anydata2>::: An array reference, containing
130			hash key names of <DFN::anydata> (two steps) properties
131			for this node.
132			\
133			}
134
135			@IntMethod:
136			@@Name: new
137			@@Description:
138			@@@lang:en
139			@@@@:
140			Constructs a new instance of
141			<Class::ManakaiDOM:ManakaiDOMNodeObject> and returns it.
142			@@Return:
143			@@@Type:
144			ManakaiDOM:ManakaiDOMNodeObject
145			@@@Description:
146			@@@@lang:en
147			@@@@@:
148			The newly created <Class::ManakaiDOM:ManakaiDOMNodeObject> instance.
149			@@@PerlDef:
150			$r = bless {
151			<Q::TreeCore:origin> => [],
152			<Q::TreeCore:subnode> => [],
153			<Q::TreeCore:subnode2> => [],
154			<Q::TreeCore:irefnode> => [],
155			<Q::TreeCore:anydata> => [],
156			<Q::TreeCore:anydata2> => [],
157			<Q::TreeCore:rc> => 0,
158			<Q::TreeCore:treeID> => <Code::ManakaiDOM:generateUniqueID>,
159			<Q::TreeCore:nodeID> => <Code::ManakaiDOM:generateUniqueID>,
160			}, ref $self \|\| $self;
161			@IntMethod:
162			@@Name: newReference
163			@@Description:
164			@@@lang:en
165			@@@@:
166			Creates a new reference to this node and returns it.
167			@@Param:
168			@@@Name: class
169			@@@Type:
170			Perl:package-name
171			@@@Description:
172			@@@@lang:en
173			@@@@@:
174			A Perl class package name with which the newly created
175			reference is blessed. The <P::class> class must be a
176			subclass of <Class::ManakaiDOM:ManakaiDOM:ManakaiDOMNodeReference>.
177			@@Return:
178			@@@Type:
179			ManakaiDOM:ManakaiDOMNodeReference
180			@@@Description:
181			@@@@lang:en
182			@@@@@:
183			The newly created node reference.
184			@@@PerlDef:
185			$r = bless {
186			<Q::TreeCore:node> => $self,
187			}, ref $class ? ref $class : $class ? $class :
188			<ClassName::ManakaiDOM:ManakaiDOMNodeReference>;
189			$self->{<Q::TreeCore:rc>}++;
190			@IntMethod:
191			@@Name: isExternallyReferred
192			@@Description:
193			@@@lang:en
194			@@@@:
195			Checks whether the tree containing this node has been referred
196			from the outside of the tree or not.
197			@@Return:
198			@@@Type:
199			DISPerl:Boolean
200			@@@InCase:
201			@@@@Value: true
202			@@@@Type:
203			DISPerl:Boolean
204			@@@@Description:
205			@@@@@lang:en
206			@@@@@@:
207			There is one or more nodes in the tree that has been
208			referred via <Class::ManakaiDOM:ManakaiDOMNodeReference> objects.
209			@@@InCase:
210			@@@@Value: false
211			@@@@Type:
212			DISPerl:Boolean
213			@@@@Description:
214			@@@@@lang:en
215			@@@@@@: No external reference found.
216			@@@PerlDef:
217			if ($self->{<Q::TreeCore:rc>}) {
218			$r = true;
219			} else {
220			my @node = ($self);
221			my %checked;
222			NODES: while (my $node = shift @node) {
223			if ($node->{<Q::TreeCore:rc>}) {
224			$r = true;
225			last NODES;
226			} elsif ($checked{$node->{<Q::TreeCore:nodeID>}}) {
227			next NODES;
228			}
229			my @n;
230			for (@{$node->{<Q::TreeCore:subnode2>}}) {
231			if (ref $node->{$_} eq 'ARRAY') {
232			push @n, @{$node->{$_}};
233			} elsif (ref $node->{$_} eq 'HASH') {
234			push @n, values %{$node->{$_}};
235			}
236			}
237			for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
238			if (ref $_ eq 'ARRAY') {
239			push @node, @$_;
240			} elsif (ref $_ eq 'HASH') {
241			push @node, values %$_;
242			}
243			}
244			for (@{$node->{<Q::TreeCore:origin>}}) {
245			push @node, $node->{$_} if $node->{$_};
246			}
247			$checked{$node->{<Q::TreeCore:nodeID>}} = 1;
248			}
249			}
250
251			@IntMethod:
252			@@Name: destroy
253			@@Description:
254			@@@lang:en
255			@@@@:
256			Destructs the tree containing this node.
257			@@Return:
258			@@@PerlDef:
259			my @node = ($self);
260			NODES: while (my $node = shift @node) {
261			my @n;
262			for (@{$node->{<Q::TreeCore:subnode2>}}) {
263			if (ref $node->{$_} eq 'ARRAY') {
264			push @n, @{$node->{$_}};
265			} elsif (ref $node->{$_} eq 'HASH') {
266			push @n, values %{$node->{$_}};
267			}
268			}
269			for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
270			if (ref $_ eq 'ARRAY') {
271			push @node, grep {defined $_->{<Q::TreeCore:nodeID>}} @$_;
272			} elsif (ref $_ eq 'HASH') {
273			push @node, grep {defined $_->{<Q::TreeCore:nodeID>}}
274			values %$_;
275			}
276			}
277			for (@{$node->{<Q::TreeCore:origin>}}) {
278			push @node, $node->{$_}
279			if defined $node->{$_} and
280			defined $node->{$_}->{<Q::TreeCore:nodeID>};
281			}
282			%$node = ();
283			}
284			@@ImplNote:
285			@@@lang:en
286			@@@@:
287			This method is different from Perl <Perl::DESTROY> special
288			purpose method.
289			\
290			An <QUOTE::uninitialized> warning in this method might mean
291			some method puts an <Perl::undef> into a list of nodes.
292
293			@IntMethod:
294			@@Name: importTree
295			@@Description:
296			@@@lang:en
297			@@@@:
298			Changes the tree identifier of the nodes belong to another tree
299			to be same as this node's tree identifier.
300			@@Param:
301			@@@Name: node
302			@@@Type:
303			ManakaiDOM:ManakaiDOMNodeObject
304			@@@Description:
305			@@@@lang:en
306			@@@@@:
307			Any node from the tree to change its identifier.
308			@@Return:
309			@@@PerlDef:
310			unless ($node->{<Q::TreeCore:treeID>} eq
311			$self->{<Q::TreeCore:treeID>}) {
312			my @node = ($node);
313			NODES: while (my $node = shift @node) {
314			my @n;
315			for (@{$node->{<Q::TreeCore:subnode2>}}) {
316			if (ref $node->{$_} eq 'ARRAY') {
317			push @n, @{$node->{$_}};
318			} elsif (ref $node->{$_} eq 'HASH') {
319			push @n, values %{$node->{$_}};
320			}
321			}
322			for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
323			if (ref $_ eq 'ARRAY') {
324			push @node, grep {$_->{<Q::TreeCore:treeID>} ne
325			$self->{<Q::TreeCore:treeID>}} @$_;
326			} elsif (ref $_ eq 'HASH') {
327			push @node, grep {$_->{<Q::TreeCore:treeID>} ne
328			$self->{<Q::TreeCore:treeID>}}
329			values %$_;
330			}
331			}
332			for (@{$node->{<Q::TreeCore:origin>}}) {
333			push @node, $node->{$_}
334			if defined $node->{$_} and
335			$node->{$_}->{<Q::TreeCore:treeID>} ne
336			$self->{<Q::TreeCore:treeID>};
337			}
338			$node->{<Q::TreeCore:treeID>} = $self->{<Q::TreeCore:treeID>};
339			}
340			}
341
342			@IntMethod:
343			@@Name: changeTreeID
344			@@Description:
345			@@@lang:en
346			@@@@:
347			Changes tree identifier of all nodes traversable from this node.
348			@@Param:
349			@@@Name: treeID
350			@@@Type:
351			DISPerl:String
352			@@@Description:
353			@@@@lang:en
354			@@@@@:
355			The new tree identifier.
356			@@Return:
357			@@@PerlDef:
358			unless ($self->{<Q::TreeCore:treeID>} eq $treeID) {
359			my @node = ($self);
360			NODES: while (my $node = shift @node) {
361			my @n;
362			for (@{$node->{<Q::TreeCore:subnode2>}}) {
363			if (ref $node->{$_} eq 'ARRAY') {
364			push @n, @{$node->{$_}};
365			} elsif (ref $node->{$_} eq 'HASH') {
366			push @n, values %{$node->{$_}};
367			}
368			}
369			for (@n, map {$node->{$_}} @{$node->{<Q::TreeCore:subnode>}}) {
370			if (ref $_ eq 'ARRAY') {
371			push @node, grep {$_->{<Q::TreeCore:treeID>} ne $treeID} @$_;
372			} elsif (ref $_ eq 'HASH') {
373			push @node, grep {$_->{<Q::TreeCore:treeID>} ne $treeID}
374			values %$_;
375			}
376			}
377			for (@{$node->{<Q::TreeCore:origin>}}) {
378			push @node, $node->{$_}
379			if defined $node->{$_} and
380			$node->{$_}->{<Q::TreeCore:treeID>} ne $treeID;
381			}
382			$node->{<Q::TreeCore:treeID>} = $treeID;
383			}
384			}
385
386			@IntMethod:
387			@@Name: getRootNodes
388			@@Description:
389			@@@lang:en
390			@@@@:
391			Gets root nodes in the tree to which this node belongs,
392			at <QUOTE::higher> level than this node.
393			\
394			{NOTE:: The manakai internal tree structure may have more than
395			one tree root node - it is a set of tree sharing their
396			nodes rather than a single tree. In this method
397			<DFN::root nodes> is defined as the nodes that
398			have no their <QUOTE::origin> node. There is at least
399			one such node by definition of the manakai tree structure.
400			<QUOTE::Higher> in this context means that the node is reachable
401			by only traversing <QUOTE::origin> relationships from this node.
402			\
403			}
404			@@Return:
405			@@@Type:
406			Perl:ARRAY
407			@@@PerlDef:
408			my %result;
409			my @node = ($self);
410			NODES: while (my $node = shift @node) {
411			my $i = 0;
412			ORIGINS: for (@{$node->{<Q::TreeCore:origin>}}) {
413			next ORIGINS unless $node->{$_};
414			$i++;
415			push @node, $node->{$_};
416			}
417			if ($i == 0) {
418			$result{$node->{<Q::TreeCore:nodeID>}} = $node;
419			}
420			}
421			\ @$r = (grep {defined $_->{<Q::TreeCore:nodeID>}} values %result);
422
423			@IntMethod:
424			@@Name: isSameNode
425			@@Description:
426			@@@lang:en
427			@@@@:
428			Returns whether a node is the same as this node or not.
429			\
430			{NOTE:: The sameness is different from the equality;
431			two nodes are same iff they are same hash reference.
432			\
433			}
434			@@Operator:
435			@@@ContentType:
436			lang:Perl
437			@@@@: eq
438			@@Param:
439			@@@Name: node
440			@@@Type:
441			ManakaiDOM:ManakaiDOMNodeObject
442			@@@Description:
443			@@@@lang:en
444			@@@@@:
445			A node to compare with.
446			@@Return:
447			@@@Type:
448			DISPerl:Boolean
449			@@@Description:
450			@@@@lang:en
451			@@@@@: Whether the two nodes are same or not.
452			@@@PerlDef:
453			if (ref $node and
454			UNIVERSAL::isa ($node,
455			<ClassName::ManakaiDOM:ManakaiDOMNodeObject>) and
456			$node->{<Q::TreeCore:nodeID>} eq $self->{<Q::TreeCore:nodeID>}) {
457			$r = true;
458			}
459			@IntMethod:
460			@@Name: orphanate
461			@@Description:
462			@@@lang:en
463			@@@@:
464			Notifies that this node (and its neibors if any) is no longer
465			part of the main tree. If the new tree containing this node
466			has been referred yet, then the tree is preserved except its
467			tree identifier has changed. Otherwise, i.e. the tree is
468			useless any more, then it is destructed.
469			\
470			{NOTE:: Interaction on deleting a relationship from multiply
471			organized <QUOTE::trees> (such as DOM tree and
472			styled displaying tree) is less studied. This
473			method might be modified or addition of another method(s)
474			might be required when style sheet, XBL, or other
475			technologies has been implemented.
476			\
477			}
478			@@Return:
479			@@@PerlDef:
480			if ($self-><M::ManakaiDOM:ManakaiDOMNodeObject.isExternallyReferred>) {
481			$self-><M::ManakaiDOM:ManakaiDOMNodeObject.changeTreeID>
482			(<Code::ManakaiDOM:generateUniqueID>);
483			} else {
484			$self-><M::ManakaiDOM:ManakaiDOMNodeObject.destroy>;
485			}
486			##Class:ManakaiDOMNodeObject
487
488			## -- Public node object
489
490			ClassDef:
491			@QName:
492			ManakaiDOM:ManakaiDOMNodeReference
493			@Description:
494			@@lang:en
495			@@@:
496			References to the node object corresponding to it. From
497			applications' view, any node object is hidden and
498			<Class::ManakaiDOM:ManakaiDOMNodeReference> seems as if
499			the node itself.
500			@ImplNote:
501			@@lang:en
502			@@@:
503			A <Class::ManakaiDOM:ManakaiDOMNodeReference> is a blessed hash
504			reference; currently there is a hash key defined:
505			\
506			- <CODE::TreeCore:node>::: A node object
507			(<Class::ManakaiDOM:ManakaiDOMNodeObject>) to which
508			this is referring.
509
510			@IntMethod:
511			@@Name: destroy
512			@@Description:
513			@@@lang:en
514			@@@@: Destroy this reference object.
515			@@Operator:
516			@@@ContentType:
517			lang:Perl
518			@@@@: DESTROY
519			@@Return:
520			@@@PerlDef:
521			@@@@@:
522			my $node = $self->{<Q::TreeCore:node>};
523			if ($node) {
524			CORE::delete $self->{<Q::TreeCore:node>};
525			$node->{<Q::TreeCore:rc>}--;
526			unless ($node-><M::ManakaiDOM:ManakaiDOMNodeObject
527			.isExternallyReferred>) {
528			$node-><M::ManakaiDOM:ManakaiDOMNodeObject.destroy>;
529			}
530			} else {
531			warn ref ($self) . q{->DESTROY: there is no associated }.
532			q{node object - you have a global variable or }.
533			qq{potential memory-leak detected\n};
534			}
535			@@@@ImplNote:
536			@@@@@lang:en
537			@@@@@@:
538			{P::Warning during the global destruction might mean:
539			\
540			- there be a loop in the manakai internal implementation -
541			it should be a bug.
542			\
543			- there be a loop created by application, e.g.
544			event handler containing a reference to any node
545			belonging to the same tree.
546			\
547			- there be a global variable that contains a node reference
548			and it is not altered or <Perl::undef>ed until the global
549			destruction.
550			\
551			- or other unknown bad situation.
552			\
553			}
554			@@ImplNote:
555			@@@lang:en
556			@@@@:
557			Don't override this method unintentionally - for example,
558			inheritting <PerlModule::Tie::Array> would hide this method
559			from that class, since that module defines its own
560			destructor.
561			##Class:ManakaiDOMNodeReference
562
563			## -- Frequently used code fragments
564
565			ResourceDef:
566			@QName:
567			ManakaiDOM:generateUniqueID
568			@rdf:type:
569			dis2pm:InlineCode
570			@Description:
571			@@lang:en
572			@@@:
573			Generates a global-unique opaque string.
574			\
575			{NOTE:: A URI reference is generated by this code.
576			\
577			}
578			@AliasFor:
579			@@@:
580			::ManakaiDOM:all
581			@@For:
582			!=ManakaiDOM:all
583			@PerlDef:
584			(
585			sprintf 'mid:%d.%d.%s.dom.manakai@suika.fam.cx#',
586			time, $$,
587			['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
588			['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
589			['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
590			['A'..'Z', 'a'..'z', '0'..'9']->[rand 62] .
591			['A'..'Z', 'a'..'z', '0'..'9']->[rand 62]
592			)
593			##ManakaiDOM:generateUniqueID
594
595			## -- lang:dis vocabulary
596
597			TreeElementType:
598			@QName:
599			dis:GetProp
600			@dataType:
601			dis:TypeQName
602			@rdfs:range:
603			rdf:Property
604			@Description:
605			@@lang:en
606			@@@:
607			Gets the non-nodal value of a <Class::ManakaiDOM:ManakaiDOMNodeReference>
608			property (actualy <Class::ManakaiDOM:ManakaiDOMNodeObject> property).
609
610			TreeElementType:
611			@QName:
612			dis:SetProp
613			@dataType:
614			dis:TypeQName
615			@rdfs:range:
616			rdf:Property
617			@Description:
618			@@lang:en
619			@@@:
620			Sets the non-nodal value of a <Class::ManakaiDOM:ManakaiDOMNodeReference>
621			property (actualy <Class::ManakaiDOM:ManakaiDOMNodeObject> property).
622
623			## -- Syntax sugar
624
625			ElementTypeBinding:
626			@Name: TreeElementType
627			@ElementType:
628			dis:ResourceDef
629			@ShadowContent:
630			@@rdf:type:
631			DISLang:TreeElementType
632			@@AliasFor:
633			@@@@:
634			::ManakaiDOM:all
635			@@@For:
636			!=ManakaiDOM:all
637
638			ElementTypeBinding:
639			@Name: ClassDef
640			@ElementType:
641			dis:ResourceDef
642			@ShadowContent:
643			@@rdf:type:
644			ManakaiDOM:Class
645			@@AliasFor:
646			@@@@:
647			::ManakaiDOM:all
648			@@@For:
649			!=ManakaiDOM:all
650
651			ElementTypeBinding:
652			@Name: IntMethod
653			@ElementType:
654			dis:ResourceDef
655			@ShadowContent:
656			@@rdf:type:
657			DISLang:Method
658			@@ManakaiDOM:isForInternal:1
659
660			ElementTypeBinding:
661			@Name: Return
662			@ElementType:
663			dis:ResourceDef
664			@ShadowContent:
665			@@rdf:type:
666			DISLang:MethodReturn
667
668			ElementTypeBinding:
669			@Name: Param
670			@ElementType:
671			dis:ResourceDef
672			@ShadowContent:
673			@@rdf:type:
674			DISLang:MethodParameter
675
676			ElementTypeBinding:
677			@Name: PerlDef
678			@ElementType:
679			dis:Def
680			@ShadowContent:
681			@@ContentType:
682			lang:Perl
683
684			ElementTypeBinding:
685			@Name: InCase
686			@ElementType:
687			dis:ResourceDef
688			@ShadowContent:
689			@@rdf:type:
690			ManakaiDOM:InCase
691
692			## ManakaiNode.dis ends here