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/18 06:13:52 $
    @@ContentType:
      dis:Date.RCS
  
  @Require:
    @@Module:
      @@@Name: DISPerl
      @@@WithFor:
        ManakaiDOM:all
    @@Module:
      @@@Name: ManakaiNode
      @@@WithFor:
        ManakaiDOM:Perl

  @DefaultFor:
    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:Perl
      @@@For:
        !=ManakaiDOM:Perl
    @@ForCheck:
      ManakaiDOM:Perl

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