Debian Codegraph @

docs/manual/tools/generate_param_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
16
17 my $Author="Sylvie Lamy-Thepaut, Iain Russell";
18 my $info = {};
19 my $element = {};
20
21 my @params_done; # this will be a variable in which we maintain a list
22 # of all parameters dealt with so far...
23
24
25 # translate_default
26 # performs a translation on certain default parameters - for example, sometimes a
27 # default may be 'floatarray()' - in this case, we want to display something more meaningful.
28
29 sub translate_default
30 {
31 my $string = $_[0];
32
33 my %map = ();
34 $map{"floatarray()"} = "list of floats, e.g. /1,2,3.5/";
35 $map{"stringarray()"} = "list of strings, e.g. /'a','b','c'/";
36 $map{"intarray()"} = "list of integers, e.g. /1,2,3/";
37
38 my $translated = $map{$string};
39
40 if ($translated eq "")
41 {
42 return $string;
43 }
44 else
45 {
46 return $translated;
47 }
48 }
49
50
51
52 sub parse
53 {
54 my $def = shift;
55 my $node = shift;
56
57 while ( defined ( $element = shift @{ $node } ) )
58 {
59
60 my $child = shift @{ $node };
61 if ( ref $child )
62 {
63 my $attr = \%{ shift @{ $child } };
64 my $name = $attr->{name};
65
66 if ($name ne "")
67 {
68
69 $def->{$element}->{$name} = {};
70 my $list = $element . "_list";
71 push( @{$def->{$list}}, $name);
72 foreach my $a (keys %{$attr})
73 {
74 $def->{$element}->{$name}->{attributes}->{$a} = $attr->{$a};
75
76 }
77 parse($def->{$element}->{$name}, $child);
78
79 }
80 else
81 {
82 $def->{$element} = {};
83 foreach my $a (keys %{$attr})
84 {
85 $def->{$element}->{attributes}->{$a} = $attr->{$a};
86
87 }
88 parse($def->{$element}, $child);
89 }
90 }
91 else
92 {
93
94 $def->{data} = $child;
95 }
96 }
97 }
98
99
100
101
102 #sub generate_tables_for_class {
103 #
104 # my ($default) = @_;
105 #
106 #
107 # # start the table off, creating its title and header section
108 #
109 # my $table_name = "table_" . $current->{attributes}->{name} . "_parameters";
110 # my $table_title = $current->{attributes}->{name} . " Parameters";
111 #
112 #
113 #
114 # $default =
115 #"<?xml version=\"1.0\" encoding=\"UTF-8\"?>
116 # <table border=\"1\" id=\"$table_name\">
117 # <title>$table_title</title>
118 # <tgroup cols=\"4\">
119 # <colspec colwidth=\"140\" />
120 # <colspec colwidth=\"70\" />
121 # <colspec colwidth=\"150\" />
122 # <colspec colwidth=\"80\" />
123 # <thead>
124 # <row>
125 # <entry align=\"center\"><literallayout>Parameter
126 #<emphasis>XML</emphasis></literallayout></entry>
127 # <entry align=\"center\">Type</entry>
128 # <entry align=\"center\">Function</entry>
129 # <entry align=\"center\">Default</entry>
130 # </row>
131 # </thead>
132 # <tbody>
133 #";
134 #
135 #
136 #
137 #
138 # # for each parameter...
139 #
140 # foreach my $key (@{$current->{parameter_list}})
141 # {
142 #
143 # # For the current parameter, create its description. This will
144 # # always start with the documentation string from the XML, but may
145 # # also include a reference to the object that is created when
146 # # the parameter is activated.
147 #
148 #
149 # # if this parameter has not been implemented, then do not document it
150 #
151 # next if $current->{parameter}->{$key}->{attributes}->{implemented} eq 'no';
152 #
153 #
154 # $default = $default .
155 #"
156 # <row>
157 # <entry><literallayout>$current->{parameter}->{$key}->{attributes}->{name}
158 #<emphasis>$current->{parameter}->{$key}->{attributes}->{xml}</emphasis></literallayout></entry>
159 # <entry>$current->{parameter}->{$key}->{attributes}->{from}</entry>
160 # <entry>$current->{parameter}->{$key}->{documentation}->{data}</entry>
161 # <entry>$current->{parameter}->{$key}->{attributes}->{default}</entry>
162 # </row>
163 #";
164 #
165 # }
166 #
167 #
168 # $default = $default .
169 #"
170 # </tbody>
171 # </tgroup>
172 # </table>";
173 #
174 # return $default;
175 #
176 #}
177 #
178
179
180
181 #sub generate_list_of_tables_for_action_routine
182 #{
183 #
184 # # start recursively from the root object
185 #
186 ## print (" root: $actionroutine->{attributes}->{root_object}\n");
187 #
188 # generate_list_of_tables_recursive ($actionroutine->{attributes}->{root_object});
189 #}
190
191
192 sub generate_tables_for_action_routine
193 {
194 my ($dorecursive) = $_[0];
195 my ($actionroutine) = $_[1];
196 my ($default) = @_;
197
198
199 # First: a paragraph describing these parameters
200
201 my ($action_desc) = ($actionroutine eq "") ? "" : "Action routine: '$actionroutine', ";
202 # my ($intro_desc) = "${action_desc}'$current->{attributes}->{name}'";
203 my ($into_title) = "Description"; # $intro_desc; # "Notes";
204 my ($intro) = (($current->{documentation}->{attributes}->{for_docs} eq "no") ||
205 ($current->{documentation}->{data} eq ""))
206 ? "" # do not add a section describing this class
207 : "<note><title>$into_title</title>" . $current->{documentation}->{data} . "</note>";
208
209
210 # start the table off, creating its title and header section
211
212 my $table_name = "table_" . $current->{attributes}->{name} . "_parameters";
213 my $table_title = $actionroutine . " Parameters";
214
215
216
217 $default = $intro .
218 " <table border=\"1\" id=\"$table_name\">
219 <title>$table_title</title>
220 <tgroup cols=\"4\">
221 <colspec colwidth=\"140px\" />
222 <colspec colwidth=\"70px\" />
223 <colspec colwidth=\"150px\" />
224 <colspec colwidth=\"80px\" />
225 <thead>
226 <row>
227 <entry align=\"center\">Parameter</entry>
228 <entry align=\"center\">Type</entry>
229 <entry align=\"center\">Function</entry>
230 <entry align=\"center\">Default</entry>
231 </row>
232 </thead>
233 <tbody>
234 ";
235
236
237 # $default =
238 #" <table border=\"1\" id=\"$table_name\">
239 # <title>$table_title</title>
240 # <tgroup cols=\"4\">
241 # <colspec colwidth=\"140\" />
242 # <colspec colwidth=\"70\" />
243 # <colspec colwidth=\"150\" />
244 # <colspec colwidth=\"80\" />
245 # <thead>
246 # <row>
247 # <entry align=\"center\"><literallayout>Parameter
248 #<emphasis>MagML</emphasis></literallayout></entry>
249 # <entry align=\"center\">Type</entry>
250 # <entry align=\"center\">Function</entry>
251 # <entry align=\"center\">Default</entry>
252 # </row>
253 # </thead>
254 # <tbody>
255 #";
256
257
258
259 # start recursively from the root object
260
261 $default = $default . object_parameters_recursive ($current, $current{attributes}->{name}, "", $dorecursive);
262
263
264 # # write the table footer
265
266 $default = $default .
267 "
268 </tbody>
269 </tgroup>
270 </table>";
271
272 }
273
274
275
276
277
278 # --------------------------------------------
279 # object_parameters_recursive
280 # Recursively processes an obect's parameters
281 # --------------------------------------------
282
283 sub object_parameters_recursive {
284 my ($root) = $_[0];
285 my ($object_name) = $_[1];
286 my ($baseclass) = $_[2];
287 my ($dorecursive) = $_[3];
288 my ($result) = "";
289
290
291 if ($dorecursive eq "do-recursive")
292 {
293
294 # construct a list of all classes from which we inherit attributes
295 # - starting with the base class
296
297 my @base_classes;
298
299 if ( ($baseclass ne $root->{attributes}->{name}) && ($baseclass ne ""))
300 {
301 @base_classes = ($baseclass);
302 }
303
304 if ($root->{attributes}->{inherits} ne "" || $root->{attributes}->{doc_inherits} ne "")
305 {
306 my @base_list = split(/\//, $root->{attributes}->{inherits});
307 @base_list = (@base_list, split(/\//, $root->{attributes}->{doc_inherits}));
308
309 foreach my $base (@base_list)
310 {
311 @base_classes = (@base_classes, $base);
312 }
313 }
314
315
316 # for each of the base classes from which we inherit attributes, process them in
317 # order to print their attributes
318
319 foreach my $base (@base_classes)
320 {
321 my $base_result = object_parameters_recursive ($info->{magics}->{class}->{$base},
322 $object_name,
323 $info->{magics}->{class}->{$base}->{attributes}->{name},
324 $dorecursive);
325 $result = $result . $base_result;
326 }
327 }
328
329
330
331
332 foreach my $key (@{$root->{parameter_list}})
333 {
334
335 # only document those parameters that have been implemented
336
337 my $implemented = $root->{parameter}->{$key}->{attributes}->{implemented};
338
339 if ($implemented ne "no")
340 {
341
342 # only document a parameter if it has not yet been documented
343
344 # my @param_match = grep (/contour_max_level\b/i, @params_done);
345 my @param_match = grep (/$root->{parameter}->{$key}->{attributes}->{name}\b/i, @params_done);
346 my $num_matches = @param_match;
347
348 if ($num_matches eq 0 && $root->{parameter}->{$key}->{documentation}->{attributes}->{for_docs} ne "no")
349 {
350 # For the current parameter, create its description. This will
351 # always start with the documentation string from the XML, but may
352 # also include a reference to the object that is created when
353 # the parameter is activated.
354
355 my $description = $root->{parameter}->{$key}->{documentation}->{data};
356
357
358
359 # if this parameter has a number of fixed possible values, then list them with links
360 # to the objects that are created as a result
361
362 my $num_options_so_far = 0;
363
364 foreach my $option (@{$root->{parameter}->{$key}->{option_list}})
365 {
366
367 my $fortran_name = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{fortran};
368 my $option_object = $option;
369
370
371 # have a look at the object created by selecting this option.
372 # does it have any associated parameters?
373 # if so, create a link to the page associated with it
374
375 foreach my $mag_object (keys %{$info->{magics}->{class}})
376 {
377 if ($option_object eq $mag_object)
378 {
379 $values = $values . "$fortran_name";
380 }
381 }
382
383 $num_options_so_far = $num_options_so_far + 1;
384 }
385
386
387 my $xml_name = $root->{parameter}->{$key}->{attributes}->{name};
388 my $xml_from = $root->{parameter}->{$key}->{attributes}->{from};
389 my $xml_doc = $root->{parameter}->{$key}->{documentation}->{data};
390 my $xml_default = translate_default($root->{parameter}->{$key}->{attributes}->{default});
391
392 $xml_name = lc $xml_name; # ensure all parameter names are lower-case
393
394 if ($xml_default eq "")
395 {
396 $xml_default = "No default";
397 }
398
399
400 $result = $result .
401 "
402 <row>
403 <entry>$xml_name</entry>
404 <entry>$xml_from</entry>
405 <entry>$xml_doc</entry>
406 <entry>$xml_default</entry>
407 </row>
408 ";
409
410
411 # $result = $result .
412 # "
413 # <row>
414 # <entry><literallayout>$root->{parameter}->{$key}->{attributes}->{name}
415 # <emphasis>$root->{parameter}->{$key}->{attributes}->{xml}</emphasis></literallayout></entry>
416 # <entry>$root->{parameter}->{$key}->{attributes}->{from}</entry>
417 # <entry>$root->{parameter}->{$key}->{documentation}->{data}</entry>
418 # <entry>$root->{parameter}->{$key}->{attributes}->{default}</entry>
419 # </row>
420 # ";
421 #
422
423
424 # dip recursively into the parameter's base class ... ?
425
426 foreach my $option (@{$root->{parameter}->{$key}->{option_list}})
427 {
428
429 my $fortran_name = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{fortran};
430 my $base = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{name};
431 my $docdive = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{docdive};
432 my $option_object = $option;
433
434 if ($docdive ne "no") # sometimes we don't want to recurse
435 {
436 $result = $result . object_parameters_recursive ($info->{magics}->{class}->{$base},
437 $object_name,
438 $info->{magics}->{class}->{$base}->{attributes}->{name},
439 $dorecursive);
440 }
441 }
442
443
444
445
446 # Note: it might be nice to reintroduce the release version for various parameters once
447 # Magics++ has been 'live' for a while. We should either strip the word 'Magics++' from
448 # the release version info in the XML files or else do it here so we can check the
449 # version as a number.
450
451
452 # if ($current->{parameter}->{$key}->{release_info}->{data} ne "")
453 # {
454 # $default = $default . "<br> $current->{parameter}->{$key}->{release_info}->{data}\n";
455 # }
456
457
458 # $default = $default . "\t\t\t<td bgcolor=\"#ffffff\"> $current->{parameter}->{$key}->{attributes}->{to} </td> \n";
459 # $default = $default . "\t\t\t<td bgcolor=\"#ffffff\"> $current->{parameter}->{$key}->{migration}->{data} </td> \n";
460
461 @params_done = (@params_done, $root->{parameter}->{$key}->{attributes}->{name});
462 }
463 }
464 }
465
466
467 # we have an attribute called 'doc_include' which means that we just include the
468 # parameters from the included object
469
470 # if ($root->{attributes}->{doc_includes} ne "")
471 # {
472 # my @include_list = split(/\//, $root->{attributes}->{doc_includes});
473 #
474 # foreach my $include (@include_list)
475 # {
476 # $result = $result . object_parameters_recursive ($info->{magics}->{class}->{$include},
477 # "Dummy",
478 # $info->{magics}->{class}->{$include}->{attributes}->{name},
479 # $dorecursive);
480 # }
481 # }
482
483
484
485 return $result;
486 }
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509 sub expand_base_class
510 {
511 local($base) = @_[0];
512
513
514 # go through the list of MAGICS objects and see which ones are derived from this one
515
516 foreach my $mag_class (keys %{$info->{magics}->{static}})
517 {
518 if ($info->{magics}->{static}->{$mag_class}->{attributes}->{base} eq $base)
519 {
520 # print (" child 1");
521 generate_list_of_tables_recursive ($info->{magics}->{static}->{$mag_class}->{attributes}->{class});
522 }
523 }
524 }
525
526
527
528 sub generate_list_of_tables_recursive
529 {
530 local($root) = @_[0];
531
532 $depth = $depth + 1;
533
534
535 # first deal with this object
536
537 # print (" $depth sub: $root\n");
538 local ($current) = $info->{magics}->{class}->{$root};
539
540 if ($info->{magics}->{class}->{$root} ne "")
541 {
542 write_table_reference ($root);
543 }
544
545
546 # if it's a base class, then expand its descendants
547
548 # expand_base_class ($root);
549
550
551 # any children?
552
553 if ($current->{attributes}->{embedded_objects} ne "")
554 {
555 my @ObjectList = split(/\//, $current->{attributes}->{embedded_objects});
556
557 foreach my $subobject (@ObjectList)
558 {
559 # print (" child 2");
560 generate_list_of_tables_recursive ($subobject);
561 }
562 }
563
564
565 $depth = $depth - 1;
566
567 return $default;
568 }
569
570
571 sub write_table_reference
572 {
573 local ($object_name) = @_[0];
574 my $table_ref;
575
576 my $table_id = "table_" . $object_name . "_parameters";
577 my $table_file = "$object_name.xml";
578
579 $table_ref =
580 "
581 <xi:include href=\"$table_file\"
582 xmlns:xi=\"http://www.w3.org/2001/XInclude\" />
583 ";
584
585 print HTML $table_ref;
586 }
587
588
589
590
591 # -----------------------------------------------------------------------------
592 # Code entry point. This is where we actually start to generate the XML tables.
593 # We parse the magics.xml file and split it into its classes.
594 # -----------------------------------------------------------------------------
595
596 my $xml= new XML::Parser(Style=>"Tree");
597
598 system ('perl -s ../../tools/mergexml.pl -XMLDir=\'../../src/xml\'');
599
600 parse ($info, $xml->parsefile('../../src/xml/magics.xml'));
601
602
603
604 # generate a table for each action routine
605 # ----------------------------------------
606
607 foreach my $action (sort keys %{$info->{magics}->{actionroutine}})
608 {
609 $actionroutine = $info->{magics}->{actionroutine}->{$action};
610 $actionname = $actionroutine->{attributes}->{name};
611 my $actiontitle = uc ($actionname);
612 my $root_object = $actionroutine->{attributes}->{root_object};
613 my $file_header =
614 "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
615 <section id=\"${actionname}_tables\">
616 <title>$actiontitle Parameters</title>
617 ";
618 my $file_footer = "</section>";
619
620 $current = $info->{magics}->{class}->{$root_object};
621 @params_done = ();
622
623
624 $/ = undef;
625 my $text = generate_tables_for_action_routine("do-recursive", $actionname);
626
627 open HTML, ">paramtables/${actionname}_tables.xml";
628 print HTML $file_header;
629 print HTML $text;
630 print HTML $file_footer;
631 close HTML;
632
633 }
634
635
636
637 # generate a table for each driver
638 # ----------------------------------------
639
640 foreach my $action (sort keys %{$info->{magics}->{driver}})
641 {
642 my $driver = $info->{magics}->{driver}->{$action};
643 my $drivername = $driver->{attributes}->{name};
644 my $drivertitle = $drivername;
645 my $root_object = $driver->{attributes}->{root_object};
646 my $recursive_flag = $driver->{attributes}->{recursive_docs};
647 my $file_header =
648 "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
649 <section id=\"${drivername}_tables\">
650 <title>$drivertitle Parameters</title>
651 ";
652 my $file_footer = "</section>";
653
654 $current = $info->{magics}->{class}->{$root_object};
655 @params_done = ();
656
657
658 $/ = undef;
659 my $text = generate_tables_for_action_routine($recursive_flag, $drivername);
660
661 open HTML, ">paramtables/${drivername}_tables.xml";
662 print HTML $file_header;
663 print HTML $text;
664 print HTML $file_footer;
665 close HTML;
666 }
667
668
669
670 #foreach my $magclass (keys %{$info->{magics}->{class}})
671 #{
672 # $current = $info->{magics}->{class}->{$magclass};
673 #
674 ## print ($current->{attributes}->{name}, "\n");
675 #
676 # $/ = undef;
677 # my $text = generate_tables_for_class("");
678 #
679 # open HTML, ">paramtables/$magclass.xml";
680 # print HTML $text;
681 # close HTML;
682 #
683 #}
684 #
685
686 ## generate a list of tables for each action routine
687 ## -------------------------------------------------
688 #
689 #foreach my $action (sort keys %{$info->{magics}->{actionroutine}})
690 #{
691 #
692 # $actionroutine = $info->{magics}->{actionroutine}->{$action};
693 # $actionname = $actionroutine->{attributes}->{name};
694 # my $root_object = $actionroutine->{attributes}->{root_object};
695 # my $table_list_file = "paramtables/${actionname}_tables.xml";
696 # my $file_header =
697 #"<?xml version=\"1.0\" encoding=\"UTF-8\"?>
698 #<section id=\"${actionname}_tables\">
699 # <title>Parameters</title>
700 #";
701 # my $file_footer = "</section>";
702 #
703 #
704 # $depth = 0;
705 # open HTML, ">$table_list_file";
706 # print HTML $file_header;
707 # generate_list_of_tables_for_action_routine ("");
708 # print HTML $file_footer;
709 # close HTML;
710 #
711 #
712 #}
713
714
715 ## We have a bit of a special case with the Data Input tables
716 ## since the parameters are not necessarily associated with
717 ## action routines. Process them separately here.
718 #
719 #my $table_list_file = "paramtables/data_input_tables.xml";
720 #my $file_header =
721 #"<?xml version=\"1.0\" encoding=\"UTF-8\"?>
722 #<section id=\"data_input_tables\">
723 # <title>Parameters</title>
724 #";
725 #my $file_footer = "</section>";
726 #
727 #open HTML, ">$table_list_file";
728 #print HTML $file_header;
729 #
730 #foreach my $di_class ('GribDecoder', 'NetcdfDecoder', 'OdbDecoder', 'ArrayDecoder', 'ObsDecoder', 'SymbolInput', 'PpmDecoder')
731 #{
732 # $depth = 0;
733 # generate_list_of_tables_recursive ($di_class);
734 #}
735 #
736 #print HTML $file_footer;
737 #close HTML;
738 #