expose OFCOM update date/time and libphonenumber release in methods a…

…nd doco

.gitignore

@@ -60,3 +60,4 @@ AllBlocksAugmentedReport.zip
 869.xml
 876.xml
 939.xml
+lib/Number/Phone/Data.pm

CHANGELOG

@@ -1,6 +1,8 @@
 XXXX-XX-XX      XXXXXX  Windows doesn't properly support fork() so skip the tests for it;
                         Use data from a tagged release of libphonenumber instead of whatever
                           is in master, so builds are more reproducible;
+                        Expose that in libphonenumber_tag method;
+                        Expose OFCOM update date/time in N::P::UK->data_source method;
                         Data updates
 
 2020-09-04      3.6006  Data updates

MANIFEST

@@ -335,3 +335,5 @@ lib/Number/Phone/StubCountry/YT.pm
 lib/Number/Phone/StubCountry/ZA.pm
 lib/Number/Phone/StubCountry/ZM.pm
 lib/Number/Phone/StubCountry/ZW.pm
+lib/Number/Phone/Data.pm
+t/source_data.t

build-data.sh

@@ -50,12 +50,13 @@ if [ "$FORCE" == "1" ]; then
     rm share/Number-Phone-UK-Data.db
     rm share/Number-Phone-NANP-Data.db
     rm lib/Number/Phone/NANP/Data.pm
+    rm lib/Number/Phone/Data.pm
     rm lib/Number/Phone/Country/Data.pm
     rm lib/Number/Phone/StubCountry/KZ.pm
     rm t/example-phone-numbers.t
 fi
 
-# switch to our desired tag, and cache it
+# switch to our desired tag, and cache it for a future --previoustag build
 (cd libphonenumber; git checkout -q $TAG)
 echo $TAG > .libphonenumber-tag
 
@@ -101,7 +102,7 @@ unzip -q COCodeStatus_ALL.zip
 unzip -q AllBlocksAugmentedReport.zip
 
 # stash the Unix epoch of the OFCOM data
-perl -e 'print +(stat(shift))[9]' $(ls -rt sabc.txt *.xlsx|tail -1) > .ofcom-epoch
+OFCOMDATETIME=$(perl -e 'print +(stat(shift))[9]' $(ls -rt sabc.txt *.xlsx|tail -1))
 
 # if share/Number-Phone-UK-Data.db doesn't exist, or OFCOM's stuff is newer ...
 if test ! -e share/Number-Phone-UK-Data.db -o \
@@ -197,6 +198,31 @@ else
   echo t/example-phone-numbers.t is up-to-date
 fi
 
+# update Number::Phone::Data with OFCOM update date/time and libphonenumber tag
+OLD_N_P_DATE_MD5=$(md5 lib/Number/Phone/Data.pm 2>/dev/null)
+(
+    echo \# automatically generated file, don\'t edit
+    echo package Number::Phone::Data\;
+    echo \*Number::Phone::libphonenumber_tag = sub { \"$TAG\" }\;
+    echo \*Number::Phone::UK::data_source = sub { \"OFCOM at \".gmtime\($OFCOMDATETIME\) }\;
+    echo 1\;
+    echo
+    echo =head1 NAME
+    echo
+    echo Number::Phone::Data
+    echo
+    echo =head1 DATA SOURCES
+    echo
+    echo UK data derived from OFCOM at $(perl -e "print ''.gmtime($OFCOMDATETIME)")
+    echo
+    echo Most other data derived from libphonenumber $TAG
+    echo
+    echo =cut
+)>lib/Number/Phone/Data.pm
+if [ "$OLD_N_P_DATE_MD5" != "$(md5 lib/Number/Phone/Data.pm)" ]; then
+    EXITSTATUS=1
+fi
+
 # finally look for out of date files and yell about them
 echo
 for file in `grep -ri next.check.due lib build-* t|grep -v build-data.sh|sed 's/:.*//'|sort|uniq`; do

lib/Number/Phone.pm

@@ -10,6 +10,7 @@ use Cwd qw(abs_path);
 use Scalar::Util 'blessed';
 
 use Number::Phone::Country qw(noexport);
+use Number::Phone::Data;
 use Number::Phone::StubCountry;
 
 # MUST be in format N.NNNN, see https://github.com/DrHyde/perl-modules-Number-Phone/issues/58
@@ -62,7 +63,7 @@ foreach my $method (
     @is_methods, qw(
         country_code regulator areacode areaname
         subscriber operator operator_ported translates_to
-        format location
+        format location data_source
     )
 ) {
     no strict 'refs';
@@ -544,6 +545,28 @@ The superclass implementation returns undef.
 
 =back
 
+=head2 DATA SOURCES
+
+=over
+
+=item data_source
+
+Class method, return some hopefully useful text about the source of the data
+(if any) that drives a country-specific module. The implementation in the base
+class returns undef as the base class itself has no data source.
+
+=item libphonenumber_tag
+
+Class method which you should not over-ride, implemented in the base class.
+Returns the version of libphonenumber whose metadata was used for this release
+of Number::Phone. NB that this is derived from their most recent git tag, so
+may occasionally be a little ahead of the most recent libphonenumber release as
+the tag gets created before their release is built.
+
+The current version of this is also documented in L<Number::Phone::Data>.
+
+=back
+
 =head2 HOW TO DIAL FROM ONE NUMBER TO ANOTHER
 
 =over

lib/Number/Phone/UK.pm

@@ -7,7 +7,7 @@ use Number::Phone::UK::Data;
 
 use base 'Number::Phone';
 
-our $VERSION = '1.69';
+our $VERSION = '1.70';
 
 my $cache = {};
 
@@ -65,6 +65,14 @@ The following methods from Number::Phone are overridden:
 The constructor, you should never have to call this yourself. To create an
 object the canonical incantation is C<< Number::Phone->new('+44 ...') >>.
 
+=item data_source
+
+Returns a string telling where and when the data that drives this class was last updated, looking something like:
+
+    "OFCOM at Wed Sep 30 10:37:39 2020"
+
+The current value of this is also documented in L<Number::Phone::Data>.
+
 =item is_valid
 
 The number is valid within the national numbering scheme.  It may or may

t/source_data.t

@@ -0,0 +1,18 @@
+use strict;
+use warnings;
+
+use Number::Phone::UK;
+
+use Test::More;
+
+# eg Wed Sep 30 10:37:39 2020
+ok(Number::Phone::UK->data_source() =~ /^OFCOM at (Mon|Tue|Wed|Thu|Fri|Sat|Sun).*202\d$/,
+    "N::P::UK->data_source() ".Number::Phone::UK->data_source()." looks vaguely plausible");
+ok(!defined(Number::Phone->data_source()),
+    "N::P->data_source() is undef");
+
+# eg v8.12.10
+ok(Number::Phone->libphonenumber_tag() =~ /^v\d+\.\d+\.\d+$/,
+    "N::P->libphonenumber_tag() ".Number::Phone->libphonenumber_tag()." looks vaguely plausible");
+
+done_testing();