#!/usr/bin/env perl # (C) Copyright 1996-2016 ECMWF. # # This software is licensed under the terms of the Apache Licence Version 2.0 # which can be obtained at http://www.apache.org/licenses/LICENSE-2.0. # In applying this licence, ECMWF does not waive the privileges and immunities # granted to it by virtue of its status as an intergovernmental organisation nor # does it submit to any jurisdiction. # use common::mpp_utils; use XML::Parser; use Data::Dumper; my $Author="Sylvie Lamy-Thepaut, Iain Russell"; my $info = {}; my $element = {}; my @params_done; # this will be a variable in which we maintain a list # of all parameters dealt with so far... # translate_default # performs a translation on certain default parameters - for example, sometimes a # default may be 'floatarray()' - in this case, we want to display something more meaningful. sub translate_default { my $string = $_[0]; my %map = (); $map{"floatarray()"} = "list of floats, e.g. /1,2,3.5/"; $map{"stringarray()"} = "list of strings, e.g. /'a','b','c'/"; $map{"intarray()"} = "list of integers, e.g. /1,2,3/"; my $translated = $map{$string}; if ($translated eq "") { return $string; } else { return $translated; } } sub parse { my $def = shift; my $node = shift; while ( defined ( $element = shift @{ $node } ) ) { my $child = shift @{ $node }; if ( ref $child ) { my $attr = \%{ shift @{ $child } }; my $name = $attr->{name}; if ($name ne "") { $def->{$element}->{$name} = {}; my $list = $element . "_list"; push( @{$def->{$list}}, $name); foreach my $a (keys %{$attr}) { $def->{$element}->{$name}->{attributes}->{$a} = $attr->{$a}; } parse($def->{$element}->{$name}, $child); } else { $def->{$element} = {}; foreach my $a (keys %{$attr}) { $def->{$element}->{attributes}->{$a} = $attr->{$a}; } parse($def->{$element}, $child); } } else { $def->{data} = $child; } } } #sub generate_tables_for_class { # # my ($default) = @_; # # # # start the table off, creating its title and header section # # my $table_name = "table_" . $current->{attributes}->{name} . "_parameters"; # my $table_title = $current->{attributes}->{name} . " Parameters"; # # # # $default = #" # # $table_title # # # # # # # # Parameter #XML # Type # Function # Default # # # #"; # # # # # # for each parameter... # # foreach my $key (@{$current->{parameter_list}}) # { # # # For the current parameter, create its description. This will # # always start with the documentation string from the XML, but may # # also include a reference to the object that is created when # # the parameter is activated. # # # # if this parameter has not been implemented, then do not document it # # next if $current->{parameter}->{$key}->{attributes}->{implemented} eq 'no'; # # # $default = $default . #" # # $current->{parameter}->{$key}->{attributes}->{name} #$current->{parameter}->{$key}->{attributes}->{xml} # $current->{parameter}->{$key}->{attributes}->{from} # $current->{parameter}->{$key}->{documentation}->{data} # $current->{parameter}->{$key}->{attributes}->{default} # #"; # # } # # # $default = $default . #" # # #
"; # # return $default; # #} # #sub generate_list_of_tables_for_action_routine #{ # # # start recursively from the root object # ## print (" root: $actionroutine->{attributes}->{root_object}\n"); # # generate_list_of_tables_recursive ($actionroutine->{attributes}->{root_object}); #} sub generate_tables_for_action_routine { my ($dorecursive) = $_[0]; my ($actionroutine) = $_[1]; my ($default) = @_; # First: a paragraph describing these parameters my ($action_desc) = ($actionroutine eq "") ? "" : "Action routine: '$actionroutine', "; # my ($intro_desc) = "${action_desc}'$current->{attributes}->{name}'"; my ($into_title) = "Description"; # $intro_desc; # "Notes"; my ($intro) = (($current->{documentation}->{attributes}->{for_docs} eq "no") || ($current->{documentation}->{data} eq "")) ? "" # do not add a section describing this class : "$into_title" . $current->{documentation}->{data} . ""; # start the table off, creating its title and header section my $table_name = "table_" . $current->{attributes}->{name} . "_parameters"; my $table_title = $actionroutine . " Parameters"; $default = $intro . " $table_title Parameter Type Function Default "; # $default = #"
# $table_title # # # # # # # # Parameter #MagML # Type # Function # Default # # # #"; # start recursively from the root object $default = $default . object_parameters_recursive ($current, $current{attributes}->{name}, "", $dorecursive); # # write the table footer $default = $default . "
"; } # -------------------------------------------- # object_parameters_recursive # Recursively processes an obect's parameters # -------------------------------------------- sub object_parameters_recursive { my ($root) = $_[0]; my ($object_name) = $_[1]; my ($baseclass) = $_[2]; my ($dorecursive) = $_[3]; my ($result) = ""; if ($dorecursive eq "do-recursive") { # construct a list of all classes from which we inherit attributes # - starting with the base class my @base_classes; if ( ($baseclass ne $root->{attributes}->{name}) && ($baseclass ne "")) { @base_classes = ($baseclass); } if ($root->{attributes}->{inherits} ne "" || $root->{attributes}->{doc_inherits} ne "") { my @base_list = split(/\//, $root->{attributes}->{inherits}); @base_list = (@base_list, split(/\//, $root->{attributes}->{doc_inherits})); foreach my $base (@base_list) { @base_classes = (@base_classes, $base); } } # for each of the base classes from which we inherit attributes, process them in # order to print their attributes foreach my $base (@base_classes) { my $base_result = object_parameters_recursive ($info->{magics}->{class}->{$base}, $object_name, $info->{magics}->{class}->{$base}->{attributes}->{name}, $dorecursive); $result = $result . $base_result; } } foreach my $key (@{$root->{parameter_list}}) { # only document those parameters that have been implemented my $implemented = $root->{parameter}->{$key}->{attributes}->{implemented}; if ($implemented ne "no") { # only document a parameter if it has not yet been documented # my @param_match = grep (/contour_max_level\b/i, @params_done); my @param_match = grep (/$root->{parameter}->{$key}->{attributes}->{name}\b/i, @params_done); my $num_matches = @param_match; if ($num_matches eq 0 && $root->{parameter}->{$key}->{documentation}->{attributes}->{for_docs} ne "no") { # For the current parameter, create its description. This will # always start with the documentation string from the XML, but may # also include a reference to the object that is created when # the parameter is activated. my $description = $root->{parameter}->{$key}->{documentation}->{data}; # if this parameter has a number of fixed possible values, then list them with links # to the objects that are created as a result my $num_options_so_far = 0; foreach my $option (@{$root->{parameter}->{$key}->{option_list}}) { my $fortran_name = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{fortran}; my $option_object = $option; # have a look at the object created by selecting this option. # does it have any associated parameters? # if so, create a link to the page associated with it foreach my $mag_object (keys %{$info->{magics}->{class}}) { if ($option_object eq $mag_object) { $values = $values . "$fortran_name"; } } $num_options_so_far = $num_options_so_far + 1; } my $xml_name = $root->{parameter}->{$key}->{attributes}->{name}; my $xml_from = $root->{parameter}->{$key}->{attributes}->{from}; my $xml_doc = $root->{parameter}->{$key}->{documentation}->{data}; my $xml_default = translate_default($root->{parameter}->{$key}->{attributes}->{default}); $xml_name = lc $xml_name; # ensure all parameter names are lower-case if ($xml_default eq "") { $xml_default = "No default"; } $result = $result . " $xml_name $xml_from $xml_doc $xml_default "; # $result = $result . # " # # $root->{parameter}->{$key}->{attributes}->{name} # $root->{parameter}->{$key}->{attributes}->{xml} # $root->{parameter}->{$key}->{attributes}->{from} # $root->{parameter}->{$key}->{documentation}->{data} # $root->{parameter}->{$key}->{attributes}->{default} # # "; # # dip recursively into the parameter's base class ... ? foreach my $option (@{$root->{parameter}->{$key}->{option_list}}) { my $fortran_name = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{fortran}; my $base = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{name}; my $docdive = $root->{parameter}->{$key}->{option}->{$option}->{attributes}->{docdive}; my $option_object = $option; if ($docdive ne "no") # sometimes we don't want to recurse { $result = $result . object_parameters_recursive ($info->{magics}->{class}->{$base}, $object_name, $info->{magics}->{class}->{$base}->{attributes}->{name}, $dorecursive); } } # Note: it might be nice to reintroduce the release version for various parameters once # Magics++ has been 'live' for a while. We should either strip the word 'Magics++' from # the release version info in the XML files or else do it here so we can check the # version as a number. # if ($current->{parameter}->{$key}->{release_info}->{data} ne "") # { # $default = $default . "
$current->{parameter}->{$key}->{release_info}->{data}\n"; # } # $default = $default . "\t\t\t $current->{parameter}->{$key}->{attributes}->{to} \n"; # $default = $default . "\t\t\t $current->{parameter}->{$key}->{migration}->{data} \n"; @params_done = (@params_done, $root->{parameter}->{$key}->{attributes}->{name}); } } } # we have an attribute called 'doc_include' which means that we just include the # parameters from the included object # if ($root->{attributes}->{doc_includes} ne "") # { # my @include_list = split(/\//, $root->{attributes}->{doc_includes}); # # foreach my $include (@include_list) # { # $result = $result . object_parameters_recursive ($info->{magics}->{class}->{$include}, # "Dummy", # $info->{magics}->{class}->{$include}->{attributes}->{name}, # $dorecursive); # } # } return $result; } sub expand_base_class { local($base) = @_[0]; # go through the list of MAGICS objects and see which ones are derived from this one foreach my $mag_class (keys %{$info->{magics}->{static}}) { if ($info->{magics}->{static}->{$mag_class}->{attributes}->{base} eq $base) { # print (" child 1"); generate_list_of_tables_recursive ($info->{magics}->{static}->{$mag_class}->{attributes}->{class}); } } } sub generate_list_of_tables_recursive { local($root) = @_[0]; $depth = $depth + 1; # first deal with this object # print (" $depth sub: $root\n"); local ($current) = $info->{magics}->{class}->{$root}; if ($info->{magics}->{class}->{$root} ne "") { write_table_reference ($root); } # if it's a base class, then expand its descendants # expand_base_class ($root); # any children? if ($current->{attributes}->{embedded_objects} ne "") { my @ObjectList = split(/\//, $current->{attributes}->{embedded_objects}); foreach my $subobject (@ObjectList) { # print (" child 2"); generate_list_of_tables_recursive ($subobject); } } $depth = $depth - 1; return $default; } sub write_table_reference { local ($object_name) = @_[0]; my $table_ref; my $table_id = "table_" . $object_name . "_parameters"; my $table_file = "$object_name.xml"; $table_ref = " "; print HTML $table_ref; } # ----------------------------------------------------------------------------- # Code entry point. This is where we actually start to generate the XML tables. # We parse the magics.xml file and split it into its classes. # ----------------------------------------------------------------------------- my $xml= new XML::Parser(Style=>"Tree"); system ('perl -s ../../tools/mergexml.pl -XMLDir=\'../../src/xml\''); parse ($info, $xml->parsefile('../../src/xml/magics.xml')); # generate a table for each action routine # ---------------------------------------- foreach my $action (sort keys %{$info->{magics}->{actionroutine}}) { $actionroutine = $info->{magics}->{actionroutine}->{$action}; $actionname = $actionroutine->{attributes}->{name}; my $actiontitle = uc ($actionname); my $root_object = $actionroutine->{attributes}->{root_object}; my $file_header = "
$actiontitle Parameters "; my $file_footer = "
"; $current = $info->{magics}->{class}->{$root_object}; @params_done = (); $/ = undef; my $text = generate_tables_for_action_routine("do-recursive", $actionname); open HTML, ">paramtables/${actionname}_tables.xml"; print HTML $file_header; print HTML $text; print HTML $file_footer; close HTML; } # generate a table for each driver # ---------------------------------------- foreach my $action (sort keys %{$info->{magics}->{driver}}) { my $driver = $info->{magics}->{driver}->{$action}; my $drivername = $driver->{attributes}->{name}; my $drivertitle = $drivername; my $root_object = $driver->{attributes}->{root_object}; my $recursive_flag = $driver->{attributes}->{recursive_docs}; my $file_header = "
$drivertitle Parameters "; my $file_footer = "
"; $current = $info->{magics}->{class}->{$root_object}; @params_done = (); $/ = undef; my $text = generate_tables_for_action_routine($recursive_flag, $drivername); open HTML, ">paramtables/${drivername}_tables.xml"; print HTML $file_header; print HTML $text; print HTML $file_footer; close HTML; } #foreach my $magclass (keys %{$info->{magics}->{class}}) #{ # $current = $info->{magics}->{class}->{$magclass}; # ## print ($current->{attributes}->{name}, "\n"); # # $/ = undef; # my $text = generate_tables_for_class(""); # # open HTML, ">paramtables/$magclass.xml"; # print HTML $text; # close HTML; # #} # ## generate a list of tables for each action routine ## ------------------------------------------------- # #foreach my $action (sort keys %{$info->{magics}->{actionroutine}}) #{ # # $actionroutine = $info->{magics}->{actionroutine}->{$action}; # $actionname = $actionroutine->{attributes}->{name}; # my $root_object = $actionroutine->{attributes}->{root_object}; # my $table_list_file = "paramtables/${actionname}_tables.xml"; # my $file_header = #" #
# Parameters #"; # my $file_footer = "
"; # # # $depth = 0; # open HTML, ">$table_list_file"; # print HTML $file_header; # generate_list_of_tables_for_action_routine (""); # print HTML $file_footer; # close HTML; # # #} ## We have a bit of a special case with the Data Input tables ## since the parameters are not necessarily associated with ## action routines. Process them separately here. # #my $table_list_file = "paramtables/data_input_tables.xml"; #my $file_header = #" #
# Parameters #"; #my $file_footer = "
"; # #open HTML, ">$table_list_file"; #print HTML $file_header; # #foreach my $di_class ('GribDecoder', 'NetcdfDecoder', 'OdbDecoder', 'ArrayDecoder', 'ObsDecoder', 'SymbolInput', 'PpmDecoder') #{ # $depth = 0; # generate_list_of_tables_recursive ($di_class); #} # #print HTML $file_footer; #close HTML; #