Debian Codegraph @

docs/manual/tools/generate_magml_tables.pl

raw
1 #!/usr/bin/env perl
2 # (C) Copyright 1996-2016 ECMWF.
3 #
4 # This software is licensed under the terms of the Apache Licence Version 2.0
5 # which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
6 # In applying this licence, ECMWF does not waive the privileges and immunities
7 # granted to it by virtue of its status as an intergovernmental organisation nor
8 # does it submit to any jurisdiction.
9
10
11 # use common::mpp_utils;
12
13 use XML::Parser;
14 use Data::Dumper;
15 my $Author="Iain Russell";
16 my $info = {};
17 my $element = {};
18 my $debug = 0;
19
20 my @params_done; # this will be a variable in which we maintain a list
21 # of all parameters dealt with so far...
22
23
24 # a set of routines for formatting magml tags/elememts/attributes
25
26 # ---------------------------------------------------------------
27
28
29 sub format_tag
30 {
31 my $tagname = $_[0];
32 return "<classname>$tagname</classname>";
33 }
34
35 sub format_tag_default_option
36 {
37 my $tagname = $_[0];
38 return "<classname>$tagname</classname>";
39 }
40
41
42 sub format_attr_name
43 {
44 my $name = $_[0];
45 return "<parameter>$name</parameter>";
46 }
47
48 sub format_attr_value
49 {
50 my $value = $_[0];
51
52 return translate_default($value);
53 }
54
55 sub format_comment
56 {
57 my $comment = $_[0];
58
59 return "<comment>$comment</comment>";
60 }
61
62
63
64 sub start_tag_open
65 {
66 my $tagname = $_[0];
67 my $isdefault = $_[1];
68 my $formatted_tag = ($isdefault) ? format_tag_default_option ($tagname) : format_tag ($tagname);
69
70 return "&lt;$formatted_tag";
71 }
72
73 sub start_tag_close
74 {
75 return "&gt;";
76 }
77
78
79 sub end_tag
80 {
81 my $tagname = $_[0];
82 my $isdefault = $_[1];
83 my $formatted_tag = ($isdefault) ? format_tag_default_option ($tagname) : format_tag ($tagname);
84
85 return "&lt;/$formatted_tag&gt;\n";
86 }
87
88
89 sub start_tag_close_sudden # eg <thing />
90 {
91 return " /&gt;";
92 }
93
94
95 sub attribute
96 {
97 my $name = $_[0];
98 my $value = $_[1];
99 my $indent = $_[2];
100 my $add_newline_to_start = $_[3];
101
102 my $newline = ($add_newline_to_start) ? "\n" : "";
103 my $formatted_name = format_attr_name ($name);
104 my $formatted_value = format_attr_value ($value);
105
106 return "$newline$indent$formatted_name = $formatted_value";
107 }
108
109
110 sub option_or
111 {
112 my $or = format_comment ("&lt;!--OR--&gt;");
113
114 return "$or";
115 }
116
117
118 sub option_default
119 {
120 my $or = format_comment ("&lt;!--Default:--&gt;");
121
122 return "$or";
123 }
124
125
126 sub html_comment
127 {
128 my $comment = $_[0];
129
130 return format_comment ("&lt;!--$comment--&gt;");
131 }
132
133
134 sub hlink
135 {
136 my $name = $_[0];
137 my $book = $_[1];
138 my $link = $_[2];
139
140 if ($book eq "")
141 {
142 return ("$name");
143 }
144 else
145 {
146 return ("<olink type=\"noref\" targetdoc=\"Magics_$book\" targetptr=\"$link\">$name</olink>");
147 }
148 }
149
150
151
152 # remove_prefix
153 # if $prefix is at the start of $string, then remove it and return the result.
154 # otherwise return $string
155
156 sub remove_prefix
157 {
158 my $string = $_[0];
159 my $prefix = $_[1];
160 my $prefix_length = length($prefix);
161
162 # yes, perhaps Perl has a fancy way of doing this, but let's make it
163 # readable...
164
165 # print (" Removing prefix -$prefix- from -$string-\n");
166
167 if ($prefix_length > 0 and (substr ($string, 0, $prefix_length) eq $prefix))
168 {
169 return substr ($string, $prefix_length + 1); # also remove the '_' after the prefix (+1)
170 }
171
172 else
173 {
174 return $string;
175 }
176 }
177
178
179 #sub remove_prefix
180 #{
181 # my $string = $_[0];
182 # my $prefixes = @_[1];
183 # my @prefix_list = split(/\//, $prefixes); # $prefix is a list of '/'-separated strings
184 # my $num_prefixes = @prefix_list;
185 #
186 # for ($i = $num_prefixes - 1; $i >= 0; $i--) # start with the longest prefix first
187 # {
188 # my $prefix = @prefix_list [$i];
189 # my $prefix_length = length ($prefix);
190 #
191 # # yes, perhaps Perl has a fancy way of doing this, but let's make it
192 # # readable...
193 #
194 # print (" Removing prefix -$prefix- ($i) from -$string- [@prefix_list[0], @prefix_list[1], @prefix_list[2]]\n");
195 #
196 # if ($prefix_length > 0 and (substr ($string, 0, $prefix_length) eq $prefix))
197 # {
198 # print ("YES\n");
199 # return substr ($string, $prefix_length + 1); # also remove the '_' after the prefix (+1)
200 # }
201 # }
202 #
203 # return $string;
204 #}
205
206
207 # translate_default
208 # performs a translation on certain default parameters - for example, sometimes a
209 # default may be 'floatarray()' - in this case, we want to display something more meaningful.
210
211 sub translate_default
212 {
213 my $string = $_[0];
214
215 my %map = ();
216 $map{"floatarray()"} = "'' " . html_comment("list of floats, e.g. '1/2/3.5'");
217 $map{"stringarray()"} = "'' " . html_comment("list of strings, e.g. 'a/b/c'");
218 $map{"intarray()"} = "'' " . html_comment("list of integers, e.g. '1/2/3'");
219
220 my $translated = $map{$string};
221
222 if ($translated eq "")
223 {
224 return "'$string'";
225 }
226 else
227 {
228 return $translated;
229 }
230 }
231
232
233
234
235 sub parse
236 {
237 my $def = shift;
238 my $node = shift;
239
240 while ( defined ( $element = shift @{ $node } ) )
241 {
242
243 my $child = shift @{ $node };
244 if ( ref $child )
245 {
246 my $attr = \%{ shift @{ $child } };
247 my $name = $attr->{name};
248
249 if ($name ne "")
250 {
251
252 $def->{$element}->{$name} = {};
253 my $list = $element . "_list";
254 push( @{$def->{$list}}, $name);
255 foreach my $a (keys %{$attr})
256 {
257 $def->{$element}->{$name}->{attributes}->{$a} = $attr->{$a};
258
259 }
260 parse($def->{$element}->{$name}, $child);
261
262 }
263 else
264 {
265 $def->{$element} = {};
266 foreach my $a (keys %{$attr})
267 {
268 $def->{$element}->{attributes}->{$a} = $attr->{$a};
269
270 }
271 parse($def->{$element}, $child);
272 }
273 }
274 else
275 {
276
277 $def->{data} = $child;
278 }
279 }
280 }
281
282
283
284
285 sub xml_action_routine {
286 my ($xmlaction) = $_[0];
287 my ($xmlprintname) = $_[1];
288 my ($max_depth) = $_[2]; # how deep do we recurse into the structure?
289 my ($filename_prefix) = $_[3]; # anything extra to add to the filename?
290 my ($outlinebak) = $outline;
291 my $flat = ($max_depth == 0);
292
293 $outline = 0;
294
295 $root_object = $xmlaction;
296 $action_xml = $root_object;
297 $xmlname = $xmlprintname;
298
299 $current = $info->{magics}->{class}->{$root_object};
300
301
302 if ($flat)
303 {
304 @params_done = ();
305 }
306
307 # object_parameters_recursive will be called from within generate_tables()
308
309 $text = generate_tables ($max_depth, $filename_prefix);
310
311 open HTML, ">paramtables/${root_object}_${xmlname}_magml_${filename_prefix}tables.xml";
312 print HTML $text;
313 close HTML;
314
315 $outline = $outlinebak;
316 }
317
318
319
320 sub outline_recursive {
321
322 my ($root) = $_[0];
323 my ($type) = $_[1];
324 my ($indent) = $_[2];
325 my ($max_depth) = $_[3]; # how deep do we recurse into the structure?
326 my ($filename_prefix) = $_[4]; # anything extra to add to the filename?
327 my ($indent_incr) = 4; # how much do we increase the indent by for each subobject?
328 my ($indent_string) = ' ' x $indent;
329 my ($result) = "";
330 my ($comment_col) = 28;
331 my ($extra_indent);
332
333 # have a quick look at the number of sub-elements and choices this element has
334
335 my $num_subs = @{$root->{element_list}} + @{$root->{choice_list}};
336
337
338 # for this element ...
339
340 my ($element_name) = $root->{attributes}->{name};
341 my ($object_name) = $root->{attributes}->{object};
342 my ($comment_indent) = $comment_col - length ($element_name) - $indent;
343 my ($comment_indent_string) = ' ' x $comment_indent;
344 my ($book) = $root->{attributes}->{chapter};
345 my ($forcelink) = $root->{attributes}->{linkid};
346 my ($link) = "";
347
348
349 if ($type eq "element")
350 {
351 # print its start tag, and, if there are no sub-elements or choices, then
352 # make it a short tag; otherwise we'll have to do it in 2 parts...
353 # eg. it's either <tag> </tag> or <tag />.
354
355 # also, the id that it links to will be calculated automatically unless linkid
356 # is set - this overrides.
357
358 $link = ($forcelink eq "")
359 ? "${object_name}_${element_name}_magml_tables"
360 : $forcelink;
361
362
363 # print ("linking to ${object_name}_${element_name}_magml_tables\n");
364
365 my $tag_end = ($num_subs != 0) ? start_tag_close () : start_tag_close_sudden ();
366 $extra_indent = ($num_subs != 0) ? " " : "";
367 my $object_tag = ($object_name eq "")
368 ? start_tag_open ($element_name, 0)
369 : start_tag_open (hlink($element_name, $book, $link), 0);
370
371 $result = $result . $indent_string . $object_tag . $tag_end;
372
373 xml_action_routine ($object_name, $element_name, $max_depth, $filename_prefix);
374 }
375 elsif ($type eq "choice")
376 {
377 $result = $result . $indent_string . html_comment ("choice");
378 }
379
380
381
382 # if it's '0+', then mention that it's optional
383
384 if ($root->{attributes}->{occurrence} eq '0+')
385 {
386 $result = $result . $comment_indent_string . $extra_indent . html_comment ("(0 or more allowed)");
387 }
388
389
390 # if it's '1+', then mention that it can be repeated
391
392 if ($root->{attributes}->{occurrence} eq '1+')
393 {
394 $result = $result . $comment_indent_string . $extra_indent . html_comment ("(1 or more allowed)");
395 }
396
397
398 # if it's '1', then mention that there can be only one
399
400 if ($root->{attributes}->{occurrence} eq '1')
401 {
402 $result = $result . $comment_indent_string . $extra_indent . html_comment ("(exactly 1 allowed)");
403 }
404
405
406 # if it's '01', then mention that we can have 0 or 1
407
408 if ($root->{attributes}->{occurrence} eq '01')
409 {
410 $result = $result . $comment_indent_string . $extra_indent . html_comment ("(0 or 1 allowed)");
411 }
412
413
414 # finish this element off with a newline
415
416 $result = $result . "\n";
417
418
419
420 # for each of its sub-elements
421
422 foreach my $element (@{$root->{element_list}})
423 {
424
425 # process them $info->{magics}->{magml}->{element}->{magics}
426
427 $result = $result . outline_recursive ($root->{element}->{$element},
428 "element",
429 $indent + $indent_incr,
430 $max_depth,
431 $filename_prefix);
432 }
433
434
435 # for each choice ...
436
437 foreach my $choice (@{$root->{choice_list}})
438 {
439 # if not the first choice, then print 'OR'
440
441 # process the choice
442
443 $result = $result . outline_recursive ($root->{choice}->{$choice},
444 "choice",
445 $indent + $indent_incr,
446 $max_depth,
447 $filename_prefix);
448 }
449
450
451
452 if ($num_subs != 0 && $type eq "element")
453 {
454 my $object_tag = ($object_name eq "")
455 ? end_tag ($element_name, 0)
456 : end_tag (hlink($element_name, $book, "${object_name}_${element_name}_magml_tables"), 0);
457
458 $result = $result . $indent_string . $object_tag;
459 }
460
461
462 return $result;
463 }
464
465
466
467
468 # --------------------------------------------
469 # object_parameters_recursive
470 # Recursively processes an obect's parameters
471 # --------------------------------------------
472
473 sub object_parameters_recursive {
474
475 my ($root) = $_[0];
476 my ($object_name) = $_[1];
477 my ($print_name) = $_[2];
478 my ($baseclass) = $_[3];
479 my ($indent) = $_[4];
480 my ($attr_indent) = $_[5];
481 my ($isdefault) = $_[6];
482 my ($dotags) = $_[7];
483 my ($done_first_attribute) = $_[8];
484 my ($depth) = $_[9]; # 0 if first call, 1 if called recursively once, 2 if 2nd recursive call, ...
485 my ($max_depth) = $_[10]; # how many levels down we will recurse to in our object description
486 my ($indent_incr) = 4; # how much do we increase the indent by for each subobject?
487 my ($result) = "";
488 my $tagname = ($print_name eq "") ? $object_name : $print_name;
489 my $xmltag = $root->{attributes}->{xmltag}; # we only check this for consistency, we don't use it.
490 my ($indent_string) = ' ' x $indent;
491 my ($attributes_indent_string) = ' ' x ($indent + length($tagname) + 2);
492 my ($indent_to_use);
493 my ($has_options) = 0;
494 my $num_parameters = @{$root->{parameter_list}};
495 my $num_subobjects = 0;
496 my $attributes_only = ($depth >= $max_depth) ? 1 : 0; # if deep enough, then only produce attributes, not new tags
497 my $dosubtags;
498 my $subindent_incr;
499 my $attr_indent_to_pass = $attr_indent; # attribute indent to pass to the next level of recursion
500 my $prefix = $root->{attributes}->{prefix}; # "map/map_grid"
501 my @prefix_list = split(/\//, $prefix); # $prefix is a list of '/'-separated strings
502 my $prefix_to_remove = ($max_depth == 0) ? "" : @prefix_list[$depth]; # print ("DEPTH: $depth");
503 my $flat = ($max_depth == 0);
504
505
506 # print ("Object: $object_name, Root: $root->{attributes}->{name}, depth: $depth, prefix: $prefix, prefix_to_remove: $prefix_to_remove\n");
507
508 if ($debug) { print ($indent_string . "object_name: $object_name, root: " . $root->{attributes}->{name} .", baseclass: $baseclass, attributes_only: $attributes_only, depth: $depth\n"); }
509
510 if ($xmltag ne "" && $xmltag ne $object_name)
511 {
512 # print ("Inconsistency: option name: $object_name, xmltag: $root->{attributes}->{xmltag} (object $root->{attributes}->{name})\n");
513 }
514
515 if (!$flat)
516 {
517 @params_done = ();
518 }
519
520
521 # does this object actually exist?
522
523 if (length($object_name) == 0)
524 {
525 # NOTE: this print could actually be quite useful, so don't forget about it!
526 # print ("No object for $root->{attributes}->{name}\n");
527 return "";
528 }
529
530 # print ("$indent_string Object $root->{attributes}->{name}\n");
531
532 if ($dotags)
533 {
534 $result = $result . $indent_string . start_tag_open ($tagname, $isdefault);
535 }
536
537
538
539 # construct a list of all classes from which we inherit attributes
540 # - starting with the base class
541
542 my @base_classes;
543
544 if ($root->{attributes}->{doc_inherits} ne "no" && $baseclass ne $root->{attributes}->{name})
545 {
546 @base_classes = ($baseclass);
547 }
548
549
550 # add the other base classes if they are mentioned
551
552 if ($root->{attributes}->{doc_inherits} ne "no" &&
553 ($root->{attributes}->{inherits} ne "" || $root->{attributes}->{doc_inherits} ne "" || $root->{attributes}->{xml_doc_inherits} ne ""))
554 {
555 my @base_list = split(/\//, $root->{attributes}->{inherits});
556 @base_list = (@base_list, split(/\//, $root->{attributes}->{doc_inherits}));
557 @base_list = (@base_list, split(/\//, $root->{attributes}->{xml_doc_inherits}));
558
559 foreach my $base (@base_list)
560 {
561 #print ("+$base,");
562 @base_classes = (@base_classes, $base);
563 }
564 }
565
566 if ($root->{attributes}->{base} ne "")
567 {
568 my @base_list = split(/\//, $root->{attributes}->{base});
569
570 foreach my $base (@base_list)
571 {
572 #print ("-$base,");
573 @base_classes = (@base_classes, $base);
574 }
575 }
576
577 # remove duplicate elements
578 undef %saw;
579 @base_classes = grep(!$saw{$_}++, @base_classes);
580
581
582
583 #print ("\n");
584 # for each of the base classes from which we inherit attributes, process them in
585 # order to print their attributes
586
587 foreach my $base (@base_classes)
588 {
589 # print ("1: ");
590 #print ("1\n");
591 my $base_result = object_parameters_recursive ($info->{magics}->{class}->{$base}, # root
592 $object_name, # object_name
593 $tagname, # print_name
594 $info->{magics}->{class}->{$base}->{attributes}->{name}, # base_class
595 $indent, # indent
596 $attr_indent_to_pass, # attr_indent
597 $isdef, # isdefault
598 0, # dotags
599 $done_first_attribute, # done_first_attribute
600 $depth, # depth
601 $max_depth); # max_depth
602 $result = $result . $base_result;
603
604
605 # ensure that if the base class gave us any attributes, then we remember that
606 # we've now actually done the first one for this class
607
608 if ($base_result ne "")
609 {
610 $done_first_attribute = 1;
611 }
612 }
613
614
615
616
617 # if we're just generating attributes, not embedded tags, then use the attribute
618 # indentation that has been passed through from the previous level
619
620 if ($attr_indent ne "")
621 {
622 $attributes_indent_string = $attr_indent;
623 }
624
625 if ($attributes_only)
626 {
627 $attr_indent_to_pass = $attributes_indent_string;
628 }
629
630
631
632 # For each parameter, check to see whether it has 'option' tags.
633 # If it does not, then it's just an attribute and we add it.
634
635 foreach my $key (@{$root->{parameter_list}})
636 {
637 my $num_options = @{$root->{parameter}->{$key}->{option_list}};
638
639 if ($num_options == 0 || $root->{parameter}->{$key}->{attributes}->{ignore_indirection} eq "yes") # no options, so it's an attribute
640 {
641 my $attr_name = $root->{parameter}->{$key}->{attributes}->{xml};
642
643 if ($flat || $attr_name eq "") # if flat view or no 'xml' tag, then use 'name'
644 {
645 $attr_name = $root->{parameter}->{$key}->{attributes}->{name};
646 }
647
648 if ($attr_name eq "") # some attributes have no xml member - we cannot document these (they cannot be used)
649 {
650 print ("Parameter '$root->{parameter}->{$key}->{attributes}->{name}' of object '$object_name' does not have an xml member.\n");
651 next;
652 }
653
654 # some parameters are not to be documented...
655 if ($root->{parameter}->{$key}->{documentation}->{attributes}->{for_docs} eq "no")
656 {
657 print ("Parameter '$root->{parameter}->{$key}->{attributes}->{name}' of object '$object_name' is hidden from docs.\n");
658 next;
659 }
660
661 my $implemented = $root->{parameter}->{$key}->{attributes}->{implemented};
662
663 if ($implemented ne "no")
664 {
665 # only document a parameter if it has not yet been documented
666
667 my @param_match = grep (/$root->{parameter}->{$key}->{attributes}->{name}\b/i, @params_done);
668 my $num_matches = @param_match;
669
670 if ($num_matches eq 0)
671 {
672 $indent_to_use = ($done_first_attribute) # have we done the first attribute?
673 ? $attributes_indent_string # yes - use the full indent
674 : ' '; # no - just a single space
675
676 my $attr_default = $root->{parameter}->{$key}->{attributes}->{default};
677
678 $result = $result . attribute (remove_prefix ($attr_name, $prefix_to_remove), $attr_default, $indent_to_use, $done_first_attribute);
679 # print ("$indent_to_use, $attr_name, $attr_default, $done_first_attribute\n");
680
681 $done_first_attribute = 1;
682 #print ("----attr: $key\n");
683
684 @params_done = (@params_done, $root->{parameter}->{$key}->{attributes}->{name});
685 }
686 }
687 }
688
689 else
690 {
691 $num_subobjects = $num_subobjects + 1;
692 }
693 }
694
695
696 # we have an attribute called 'doc_include' which means that we just include the
697 # flat parameters from the included object
698
699 # if ($root->{attributes}->{doc_includes} ne "")
700 # {
701 # my @include_list = split(/\//, $root->{attributes}->{doc_includes});
702 #
703 # foreach my $include (@include_list)
704 # {
705 # $result = $result . object_parameters_recursive ($info->{magics}->{class}->{$include}, # root
706 # "Dummy", # object_name
707 # "", # print_name
708 # $base, # base_class
709 # $indent, # indent
710 # $attributes_indent_string, # attr_indent
711 # $isdef, # isdefault
712 # $dosubtags, # dotags
713 # 1, # done_first_attribute
714 # $depth, # depth
715 # $max_depth); # max_depth
716 # }
717 # }
718 #
719
720
721
722
723
724
725
726 if ($dotags && ($num_subobjects != 0) && !$attributes_only)
727 {
728 $result = $result . start_tag_close () . "\n";
729 }
730
731
732
733
734 if (($num_subobjects == 0) && $dotags)
735 {
736 $result = $result . start_tag_close_sudden () . "\n";
737 return $result;
738 }
739
740
741
742
743 # For each parameter, check to see whether it has 'option' tags.
744 # If it has, then recursively call this function with each option's object.
745
746 if ($attributes_only)
747 {
748 $dosubtags = 0;
749 $subindent_incr = 0;
750 }
751 else
752 {
753 $dosubtags = 1;
754 $subindent_incr = $indent_incr;
755 }
756
757
758 foreach my $key (@{$root->{parameter_list}})
759 {
760 my $num_options = @{$root->{parameter}->{$key}->{option_list}};
761
762 if ($num_options != 0 && $root->{parameter}->{$key}->{attributes}->{ignore_indirection} ne "yes") # do we have any options to process?
763 {
764 if ($attributes_only)
765 {
766 my $attr_name = $root->{parameter}->{$key}->{attributes}->{xml};
767
768 if ($flat || $attr_name eq "") # if flat view or no 'xml' tag, then use 'name'
769 {
770 $attr_name = $root->{parameter}->{$key}->{attributes}->{name};
771 }
772
773 if ($attr_name eq "") # some attributes have no xml member - we cannot document these (they cannot be used)
774 {
775 print ("Parameter '$root->{parameter}->{$key}->{attributes}->{name}' of object '$object_name' does not have an xml member.\n");
776 next;
777 }
778
779
780 my $implemented = $root->{parameter}->{$key}->{attributes}->{implemented};
781
782 if ($implemented ne "no")
783 {
784 $indent_to_use = ($done_first_attribute) # have we done the first attribute?
785 ? $attributes_indent_string # yes - use the full indent
786 : ' '; # no - just a single space
787
788 my $attr_default = $root->{parameter}->{$key}->{attributes}->{default};
789
790 $result = $result . attribute (remove_prefix ($attr_name, $prefix_to_remove), $attr_default, $indent_to_use, $done_first_attribute);
791
792 $done_first_attribute = 1;
793 }
794
795
796 my $base = $root->{parameter}->{$key}->{attributes}->{to};
797 my $done_first_option = 0;
798 my $next_indent = ' ' x ($indent + $indent_incr + 2);
799 $has_options = 1;
800
801 foreach my $option (@{$root->{parameter}->{$key}->{option_list}})
802 {
803 my $option_xml = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{xml};
804 my $option_fortran = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{fortran};
805 my $isdef = ($option_fortran eq $defaultval)
806 ? 1 # yes, this is the default option
807 : 0; # no, this is not the default option
808 my $base_to_inherit = ($root->{parameter}->{$key}->{option}->{$option}->{attributes}->{doc_inherits} eq "no")
809 ? "" # we do not want to inherit the base class
810 : $base; # we do want to inherit the base class by default
811
812 #print ("2\n");
813 $result = $result . object_parameters_recursive ($info->{magics}->{class}->{$option}, # root
814 $option_xml, # object_name
815 "", # print_name
816 $base_to_inherit, # base_class
817 $indent + $subindent_incr, # indent
818 $attr_indent_to_pass, # attr_indent
819 $isdef, # isdefault
820 $dosubtags, # dotags
821 $attributes_only, # done_first_attribute
822 $depth, # depth
823 $max_depth); # max_depth
824 $done_first_option = 1;
825 }
826 }
827
828 else # ie, if (not($attributes_only))
829 {
830 my $defaultval = $root->{parameter}->{$key}->{attributes}->{default};
831 my $base = $root->{parameter}->{$key}->{attributes}->{to};
832 my $done_first_option = 0;
833 my $next_indent = ' ' x ($indent + $indent_incr + 2);
834 $has_options = 1;
835
836 if (!$attributes_only) {$result = $result . "\n";}
837
838 foreach my $option (@{$root->{parameter}->{$key}->{option_list}})
839 {
840 my $option_xml = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{xml};
841 my $option_fortran = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{fortran};
842 my $isdef = ($option_fortran eq $defaultval)
843 ? 1 # yes, this is the default option
844 : 0; # no, this is not the default option
845 my $base_to_inherit = ($root->{parameter}->{$key}->{option}->{$option}->{attributes}->{doc_inherits} eq "no")
846 ? "" # we do not want to inherit the base class
847 : $base; # we do want to inherit the base class by default
848
849
850 if ($done_first_option)
851 {
852 $result = $result . $next_indent . option_or() . "\n";
853 }
854
855
856 if ($isdef)
857 {
858 $result = $result . $next_indent . option_default() . "\n";
859 }
860
861 #print ("3\n");
862 $result = $result . object_parameters_recursive ($info->{magics}->{class}->{$option}, # root
863 $option_xml, # object_name
864 "", # print_name
865 $base_to_inherit, # base_class
866 $indent + $subindent_incr, # indent
867 $attr_indent_to_pass, # attr_indent
868 $isdef, # isdefault
869 $dosubtags, # dotags
870 $attributes_only, # done_first_attribute
871 $depth + 1, # depth
872 $max_depth); # max_depth
873 $done_first_option = 1;
874 }
875 }
876 }
877 }
878
879
880
881
882 if ($dotags)
883 {
884 if ($attributes_only)
885 {
886 $result = $result . start_tag_close_sudden () . "\n";
887 }
888
889 else
890 {
891 my $newline_before_endtag = ($has_options)
892 ? "\n"
893 : "";
894 $result = $result . $newline_before_endtag . $indent_string . end_tag ($tagname, $isdefault);
895 }
896 }
897
898 return $result;
899 }
900
901
902
903
904 sub generate_tables {
905 my ($default);
906 my ($max_depth) = $_[0]; # how deep do we recurse into the structure?
907 my ($filename_prefix) = $_[1]; # anything extra to add to the filename?
908 my ($object_name) = $current->{attributes}->{name};
909 my ($title) = ($max_depth == 0)
910 ? "MagML Flat Outline Template for $xmlname"
911 : "MagML Outline Template for $xmlname";
912
913
914 my $file_header =
915 "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
916 <section id=\"${object_name}_${xmlname}_magml_${filename_prefix}tables\">
917 <title>$title</title>
918 ";
919
920 my $file_footer = "
921 </programlisting>
922 </section>";
923
924
925 # are we producing the MagML outline document?
926
927 if ($outline)
928 {
929 $default = $file_header . "<programlisting>" . outline_recursive ($current, 1, -4, $max_depth, $filename_prefix);
930 }
931
932
933 # or one document per top-level tag?
934
935 else
936 {
937 my ($into_title);
938 my ($intro);
939 # First: a paragraph describing these parameters
940
941 if ($max_depth == 0)
942 {
943 $intro = "";
944 }
945 else
946 {
947 ($into_title) = "Description"; # "Element '$xmlname'";
948 ($intro) = (($current->{documentation}->{attributes}->{for_docs} eq "no") ||
949 ($current->{documentation}->{data} eq ""))
950 ? "" # do not add a section describing this class
951 : "<note><title>$into_title</title>" . $current->{documentation}->{data} . "</note>";
952
953 }
954
955
956 $default = $file_header . $intro . "<programlisting>\n" .
957 object_parameters_recursive ($current, # root
958 $action_xml, # object_name
959 $xmlname, # print_name
960 "", # base_class
961 0, # indent
962 "", # attr_indent
963 1, # isdefault
964 1, # dotags
965 0, # done_first_attribute
966 0, # depth
967 $max_depth); # max_depth
968 }
969
970
971 # finish off the table
972
973 $default = $default . $file_footer;
974
975
976 return $default;
977 }
978
979
980
981 # -----------------------------------------------------------------------------------------
982 # -----------------------------------------------------------------------------------------
983 #
984 # Main Code
985 #
986 # -----------------------------------------------------------------------------------------
987 # -----------------------------------------------------------------------------------------
988
989
990
991 my $xml= new XML::Parser(Style=>"Tree");
992
993 system ('perl -s ../../tools/mergexml.pl -XMLDir=\'../../src/xml\'');
994
995 parse ($info, $xml->parsefile('../../src/xml/magics.xml'));
996
997 $outline = 1;
998
999
1000 # construct the main page that gives the general outline of a 'MagML program'
1001
1002 # $current = $info->{magics}->{magml}->{element}->{magics};
1003 # $current = $info->{magics}->{justcontour};
1004
1005 print ("Generating deep MagML tables...\n");
1006 $current = $info->{magics}->{magml2};
1007 $text = generate_tables (10, "");
1008
1009 print ("Generating flat MagML tables...\n");
1010 $current = $info->{magics}->{magml2};
1011 $text = generate_tables ( 0, "flat_");
1012
1013 open HTML, ">paramtables/magml_outline.xml";
1014 print HTML $text;
1015 close HTML;
1016
1017
1018