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