Differences

This shows you the differences between two versions of the page.

--- bufr.pm:bufrresolve_source [2010-02-24 12:49:12]
pals created
+++ bufr.pm:bufrresolve_source [2023-02-05 10:15:44] (current)
pals
@@ Line 1: / Line 1: @@
-<code>
+<code perl>
-#!/usr/bin/perl -w
+#!/usr/bin/perl
-# (C) Copyright 2010, met.no
+# (C) Copyright 2010-2023 MET Norway
 #
 # This program is free software; you can redistribute it and/or modify
@@ Line 19: / Line 19: @@
 # 02110-1301, USA.
-# Usage 1: $0 <descriptor(s)> [options]
+# pod included at end of file
-# Resolve the given descriptor(s) fully into table B descriptors, with
-# name, unit, scale, reference value and width written on each line.
-# With option --noexpand no expansion of D descriptors and replication
-# is done. With option --partial table D descriptors are expanded only
-# once and replication ignored. Option --simple is like --partial, but
-# all descriptors are listed on one line without any info.
-# The tables used can be chosen by the user with options --bufrtable
-# and --tablepath. Default is DEFAULT_TABLE in directory
-# DEFAULT_TABLE_PATH or in directory $ENV{BUFR_TABLES} if this is set.
-# Usage 2: $0 --code <code_table> [options]
-# Print the content of code or flag table <code_table>
-# Usage 3: $0 --flag <value> --code <flag_table> [options]
-# Display the bits set for flag value <value> in flag table <flag_table>.
-# It is supposed the code and flag tables are contained in a file with
-# same name as corresponding B and D tables except for having prefix C
-# instead of B or D.
-# Author: P.Sannes met.no August 2008
 use strict;
+use warnings;
 use Getopt::Long;
+use Pod::Usage qw(pod2usage);
+use Geo::BUFR;
-# metno module
+# This is actually default in BUFR.pm, but provided here to make it
-use BUFR;
+# easier for users to change to 'ECCODES' if preferred
+use constant DEFAULT_TABLE_FORMAT => 'BUFRDC';
-use constant DEFAULT_TABLE_PATH => '/usr/local/lib/emos/bufrtables';
+# Will be used if neither --tablepath nor $ENV{BUFR_TABLES} is set
-use constant DEFAULT_TABLE => 'B0000000000098013001';
+use constant DEFAULT_TABLE_PATH_BUFRDC => '/usr/local/lib/bufrtables';
+use constant DEFAULT_TABLE_PATH_ECCODES => '/usr/local/share/eccodes/definitions/bufr/tables';
+# Ought to be your most up-to-date B table
+use constant DEFAULT_TABLE_BUFRDC => 'B0000000000000037000';
+use constant DEFAULT_TABLE_ECCODES => '0/wmo/37';
 # Parse command line options
@@ Line 60: / Line 43: @@
 GetOptions(
            \%option,
-           'tablepath=s',# Set BUFR table path
+           'bufrtable=s',# Set BUFR tables
-           'code=s',     # Print the content of code table
+           'code=s',     # Print the contents of code table
            'flag=i',     # Resolve the flag value given
            'help',       # Print help information and exit
@@ Line 69: / Line 52: @@
            'simple',     # Like 'partial', but displaying the resulting
                          # descriptors on one line
-           'bufrtable=s',# Set BUFR tables
+           'tableformat=s',  # Set BUFR table format
-           'verbose',    # Display path and tables used
+           'tablepath=s',# Set BUFR table path
-       ) or die "Wrong option(s), execute $0 without arguments for Usage\n";
+           'verbose=i',  # Display path and tables used
+       ) or pod2usage(-verbose => 0);
 # User asked for help
-usage() if $option{help};
+pod2usage(-verbose => 1) if $option{help};
 # No arguments if --code or --flag, else there should be at least one argument
 if (defined $option{code} or defined $option{flag}) {
-    usage() if @ARGV;
+    pod2usage(-verbose => 0) if @ARGV;
 } else {
-    usage() if not @ARGV;
+    pod2usage(-verbose => 0) if not @ARGV;
 }
 # If --flag is set, user must also provide code table
-usage() if defined $option{flag} and !defined $option{code};
+pod2usage(-verbose => 0) if defined $option{flag} and !defined $option{code};
+# All arguments must be integers
+foreach (@ARGV) {
+    pod2usage("All arguments must be integers!") unless /^\d+$/;
+}
+if (defined $option{code} && $option{code} !~ /^\d+$/) {
+    pod2usage("Code table is not a (positive) integer!");
+}
+if (defined $option{flag} && $option{flag} !~ /^\d+$/) {
+    pod2usage("Flag value is not a (positive) integer!");
+}
 # Set verbosity level for the BUFR module
 my $verbose = $option{verbose} ? 1 : 0;
-BUFR->set_verbose($verbose);
+Geo::BUFR->set_verbose($verbose);
+# From version 1.32 a descriptor sequence ending in e.g. 106000 031001
+# will be allowed unless strict checking is set, and we really want
+# bufrresolve.pl to complain in this case
+Geo::BUFR->set_strict_checking(2);
+# Set BUFR table format
+my $tableformat = (defined $option{tableformat}) ? uc $option{tableformat} : DEFAULT_TABLE_FORMAT;
+Geo::BUFR->set_tableformat($tableformat);
 # Set BUFR table path
 if ($option{tablepath}) {
     # Command line option --tablepath overrides all
-    BUFR->set_tablepath($option{tablepath});
+    Geo::BUFR->set_tablepath($option{tablepath});
 } elsif ($ENV{BUFR_TABLES}) {
     # If no --tablepath option, use the BUFR_TABLES environment variable
-    BUFR->set_tablepath($ENV{BUFR_TABLES});
+    Geo::BUFR->set_tablepath($ENV{BUFR_TABLES});
 } else {
-    # If all else fails, use the libemos bufrtables
+    # If all else fails, use the default tablepath in BUFRDC/ECCODES
-    BUFR->set_tablepath(DEFAULT_TABLE_PATH);
+    if ($tableformat eq 'BUFRDC') {
+        Geo::BUFR->set_tablepath(DEFAULT_TABLE_PATH_BUFRDC);
+    } elsif ($tableformat eq 'ECCODES')  {
+        Geo::BUFR->set_tablepath(DEFAULT_TABLE_PATH_ECCODES);
+    }
 }
-print 'BUFR tablepath: ', BUFR->get_tablepath(), "\n" if $verbose;
 # BUFR table file to use
-my $table = $option{bufrtable} || DEFAULT_TABLE;
+my $table = $option{bufrtable} ||
+    ($tableformat eq 'BUFRDC' ? DEFAULT_TABLE_BUFRDC : DEFAULT_TABLE_ECCODES);
-my $bufr = BUFR->new();
+my $bufr = Geo::BUFR->new();
 if (defined $option{code}) {
@@ Line 112: / Line 122: @@
     my $code_table = $option{code};
     if (defined $option{flag}) {
-        print $bufr->resolve_flagvalue($option{flag}, $code_table, $table);
+        if ($option{flag} == 0) {
+            print "No bits are set\n";
+        } else {
+            print $bufr->resolve_flagvalue($option{flag}, $code_table, $table);
+        }
     } else {
         print $bufr->dump_codetable($code_table, $table);
@@ Line 130: / Line 144: @@
 }
+=pod
-sub usage {
+=encoding utf8
-    print <<"EOF";
-Usage 1: $0 <descriptor(s)> [options]
+=head1 SYNOPSIS
-  where options (may be abbreviated, e.g. --h or -h for --help) are
+) bufrresolve.pl <descriptor(s)>
+     [--partial]
+     [--simple]
+     [--noexpand]
+     [--bufrtable <name of BUFR table]
+     [--tableformat <BUFRDC|ECCODES>]
+     [--tablepath <path to BUFR tables>]
+     [--verbose n]
+     [--help]
-        [--partial]                    Expand D descriptors only once, ignoring
+) bufrresolve.pl --code <code or flag table>
-                                       replication
+     [--bufrtable <name of BUFR table>]
-        [--simple]                     Like --partial, but displaying the resulting
+     [--tableformat <BUFRDC|ECCODES>]
-                                       descriptors on one line
+     [--tablepath <path to BUFR tables>]
-        [--noexpand]                   Don't expand D descriptors at all
+     [--verbose n]
-        [--bufrtable <name of BUFR B or D table]  Set BUFR tables
-        [--tablepath <path to BUFR tables>]  Set BUFR table path
-        [--verbose]                    Display path and tables used
-        [--help]                       Print this help info and exit
-  --simple, --noexpand and --partial are mutually exclusive (full expansion is default).
+) bufrresolve.pl --flag <value> --code <flag table>
-  Without --simple will display each B descriptor with name, unit, scale,
+     [--bufrtable <name of BUFR table]
-  reference value and data width (in bits).
+     [--tableformat <BUFRDC|ECCODES>]
+     [--tablepath <path to BUFR tables>]
+     [--verbose n]
-Usage 2: $0 --code <code_table> [options]
+=head1 DESCRIPTION
-  Print the content of code or flag table <code_table> to screen.
+Utility program for fetching info from BUFR tables.
-Usage 3: $0 --flag <value> --code <flag_table> [options]
+Execute without arguments for Usage, with option C<--help> for some
+additional info. See also L<https://wiki.met.no/bufr.pm/start> for
+examples of use.
-  Display the bits set for flag value <value> for flag table <flag_table>.
+The tables used can be selected by the user with options
+C<--bufrtable>, C<--tablepath> and C<--tableformat>. Default
+tableformat in Geo::BUFR is BUFRDC, while default tablepath in
+bufrresolve.pl will be overridden if the environment variable
+BUFR_TABLES is set. You should consider edit the source code of
+bufrresolve.pl if you are not satisfied with the defaults chosen for
+tablepath and bufrtable (search for 'DEFAULT').
-For Usage 2 and 3 the only useful options are --bufrtable, --tablepath and --verbose.
+For tableformat ECCODES, see
+L<http://search.cpan.org/dist/Geo-BUFR/lib/Geo/BUFR.pm#BUFR-TABLE-FILES>
+for more info on how to set C<--tablepath>.
-EOF
+For the table name in C<--bufrtable> in BUFRDC, use basename of B
-    exit 0;
+table, e.g.  B0000000000098013001.TXT. Replacing B with D or C, or
-}
+omitting this prefix altogether, or even omitting the trailing '.TXT'
+(i.e. 0000000000098013001) will also work.
+For the table name in C<--bufrtable> in ECCODES, use last significant part
+of table location, e.g. '0/wmo/29' for WMO master tables or
+'0/local/8/78/236' for local tables on Unix-like systems. For looking
+up local sequence descriptors, you might need to provide both a master
+and the local table to get the full expansion, e.g.
+'0/wmo/29,0/local/8/78/236'.
+See also L</"CAVEAT"> below for more about the C<--bufrtable> option.
+=head1 OPTIONS
+   --partial    Expand D descriptors only once, ignoring replication
+   --simple     Like --partial, but displaying the resulting
+                descriptors on one line
+   --noexpand   Don't expand D descriptors at all
+   --bufrtable <name of BUFR B or D table>  Set BUFR tables
+   --tableformat Currently supported are BUFRDC and ECCODES (default is BUFRDC)
+   --tablepath <path to BUFR tables>  Set BUFR table path
+   --verbose n  Display path and tables used if n > 0
+   --help       Display Usage and explain the options used. Almost
+                the same as consulting perldoc bufrresolve.pl
+Usage 1): Resolves the given descriptor(s) fully into table B
+descriptors, with name, unit, scale, reference value and width (in
+bits) written on each line (except for --simple). --partial, --simple
+and --noexpand are mutually exclusive (full expansion is default).
+Usage 2): Prints the contents of the requested code or flag table
+(named by the table B descriptor).
+Usage 3): Displays the bits set when the data value for the requested
+flag table is <value>.
+Options may be abbreviated, e.g. C<--h> or C<-h> for C<--help>
+=head1 CAVEAT
+The C<--bufrtable> option could be considered mandatory, since there
+is no guarantee that the same BUFR descriptor resolves the same way
+for different BUFR tables. However, as soon as a new BUFR descriptor
+is introduced in a BUFR table, it is extremely rare that the
+descriptor is redefined in later versions. So for convenience,
+bufrresolve.pl uses a default table (adding option C<--verbose 1> will
+show you the tables used). If this is the wrong table for your purpose
+(most common case will be if the descriptor was added in a higher
+version than that of the default table), you should definitely use
+C<--bufrtable> with the appropriate table.
+=head1 AUTHOR
+Pål Sannes E<lt>pal.sannes@met.noE<gt>
+=head1 COPYRIGHT
+Copyright (C) 2010-2023 MET Norway
+=cut
 </code>