/[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.2 - (hide annotations) (download)
Fri Feb 18 12:14:19 2005 UTC (20 years, 4 months ago) by wakaba
Branch: MAIN
Changes since 1.1: +12 -7 lines
ManakaiNode: Now compilable

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

admin@suikawiki.org
ViewVC Help
Powered by ViewVC 1.1.24