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