/[suikacvs]/messaging/manakai/lib/Message/Util/ManakaiNode.dis
Suika

Contents of /messaging/manakai/lib/Message/Util/ManakaiNode.dis

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download)
Fri Feb 18 06:13:52 2005 UTC (20 years, 4 months ago) by wakaba
Branch: MAIN
SuikaWikiConfig21: New module; DISIDL, ManakaiNode, DOMException: split from DOMMain

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

admin@suikawiki.org
ViewVC Help
Powered by ViewVC 1.1.24