Michael Robinton

NAME

Geo::CountryFlags::Util - Makefile.PL and update utilities

SYNOPSIS

  require Geo::CountryFlags::Util;
  my $gcu = new Geo::CountryFlags::Util;

  

DESCRIPTION

Methods and functions to facilitate the update and rebuild the various cross reference tables in these modules as the CIA and ISO committees update the country codes and country flags.

  • $rv = remdir($dir);

    Recursive decent directory and file removal. USE WITH CAUTION This function removes all the files and directories BELOW its argument but does not remove the directory itself. If the function returns DEFINED, the argument directory may safely be removed with:

      rmdir $dir;
    
      input:        directory/path
      returns:      number of files & dirs removed
                    or undef on error

    If an error is returned, the delete may be partially complete.

    NOTE: an error is considered to be a non-existent directory or a file that is not a real file or directory. i.e. a link, pipe, etc...

  • $newversion = mkversion($oldversion);

    Return an updated version number. Called from within this module

      input:        [optional] old version number
      returns:      new or updated version number
  • $gcu = new Geo::CountryFlags::Util;

    Return a method pointer to the Geo::CountryFlags::Util package.

      input:        none
      returns:      method pointer
  • $rv = $gcu->is_obsolete($firstfile,$secondfile);

    Compare files and return true if the second file is missing or the modification time of the second file is older than the modification time of the first file.

      input:        path/to/firstfile,
                    path/to/secondfile
      return:       true/false
                    returns false if
                    first file is missing
  • $rv = $gcu->is_current($file,$timestamp);

    Check that file exists and that its modification time is not less than timestamp.

      input:        path/to/file,
                    timestamp       seconds since epoch
      returns:      false, file missing
                    true, file && timestamp missing
                    true if current
                    else false
  • $path = mkmodule($hp,$mtitle);

  • blessed $hp->mkmodule($mtitle);

    Remake a module for this distribution. A module of name:

      Geo::CountryFlags::${mtitle}.pm

    is made or updated in the lib/Geo/CountryFlags directory.

      input:        hash pointer to contents
                    module title (short version),
      creates:      new module in lib/Geo/CountryFlags
      returns:      path to module

    |. $package .q| is autogenerated by Makefile.PL

    Last updated |. (scalar gmtime()) .q| GMT

NAME

|. $package .'::'. $mt .q| - hash to map values

SYNOPSIS

|. $package .q| provides a variety of methods and functions to lookup values either as hash-like constants (recommended) or directly from a hash array.

    require $|. $package .q|;
    my $|. $gcv .q| = new |. $package .q|;
    $value = $|. $gcv .q|->KEY;

  Perl 5.6 or greater can use syntax
    $value = $|. $gcv .q|->$key;

  or
    $subref = subref |. $package .q|;
    $value = $subref->($key);
    $value = &$subref($key);

  or
    $value = value |. $package .q|($key);
    |. $package .q|->value($key);

  to return a reference to the map directly

  $hashref = hashptr |. $package .q|($class);
  $value = $hashref->{$key};

DESCRIPTION

|. $package .q| maps |. $mt .q| values.

Values may be returned directly by designating the KEY as a method or subroutine of the form:

    $value = |. $package .q|::KEY;
    $value = |. $package .q|->KEY;
  or in Perl 5.6 and above
    $value = |. $package .q|->$key;
  or
    $|. $gcv .q| = new |. $package .q|;
    $value = $|. $gcv .q|->KEY;
  or in Perl 5.6 and above
    $value= =  $|. $gcv .q|->$key;
  • $|. $gcv .q| = new |. $package .q|;

    Return a reference to the modules in this package.

  • $hashptr = hashptr |. $package .q|($class);

    Return a blessed reference to a copy of the hash in this package.

      input:        [optional] class or class ref
      returns:      a reference blessed into $class
                    if $class is present otherwise
                    blessed into |. $package .q|
  • $value = value |. $package .q|($key);

  • $value = $|. $gcv .q|->value($key);

    Return the value in the map hash or undef if it does not exist.

  • $subref = subref |. $package .q|;

  • $subref = $|. $gcv .q|->subref;

    Return a subroutine reference that will return the value of a key or undef if the key is not present.

      $value = $subref->($key);
      $value = &$subref($key);

EXPORTs

Nothing

AUTHOR

Michael Robinton michael@bizsystems.com

COPYRIGHT and LICENSE

  Copyright 2006 Michael Robinton, michael@bizsystems.com

This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version,

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

SEE ALSO

  • $timestamp = $gcu->url_date($name);

    Return the last modified time for the web page designated by $name.

      input:        CIA or ISO
      returns:      seconds since the epoch
                    or false on error
  • $hashptr = $gcu->xcp_fetch($path_to_file);

    Fetch the Map_Exceptions file and extract the contents, returning a hash pointer of the form:

         ISO compressed name    CIA short name
     i.e.   'korea republic' => 'korea south',

    The ISO compressed name is 'exactly' as produced by Makefile.PL when rebuilding the ISO/CIA flag cross reference. The CIA short names are at least enough of the compressed name produced by Makefile.PL to uniquely identify the entry.

      input:        [optional] path to file
      returns:      blessed reference
                or  undef on failure
  • $hashptr = $gcu->url_fetch($path_to_file);

    Fetch the Valid_Urls file and extract the contents, returning a hash pointer of the form:

      keys               vals
      CIA           CIA factbook flags page URL
      CIAFLAGS      CIA flags file directory URL
      ISO           ISO country code file URL
    
      input:        [optional] path to file
      returns:      blessed reference
                or  undef on failure
  • $hashptr = $gcu->cia_fetch($url);

    Fetch the page text from the CIA web site, parse it and return a hash pointer of the form:

        keys          vals
      country_code  country_name
    
      input:        [optional] cia page url
      returns:      blessed reference
                or  undef on failure
  • $hashptr = $gcu->iso_fetch($url);

    Fetch the page text from the ISO web site, parse it and return a hash pointer of the form:

        keys          vals
      country_code  country_name
    
      input:        [optional] iso page url
      returns:      blessed reference
                or  undef on failure

ISO to CIA flag mapping functions

These methods/functions are used to create the ISO => CIA flag map and are mostly used within this module.

  • mapexceptions($rgci,$excp);

  • $rgci->mapexceptions($excp);

    Map the known exceptions into the reverse ISO hash

      input:        ref to reverse ISO hash,
                    ref to exceptions hash
      returns:      nothing

    Replaces the original keys with the exception keys

  • $revhp = revcomp($hashptr);

  • $revhp = $hashptr->revcomp;

    Return a new blessed reference to hash with the keys and values reversed and compressed where the values are all lowercased and all non-alphanumeric characters and extra spaces are removed. The fill words of the and de da are deleted from the key string.

      i.e.          vals => keys
    
      input:        ref to blessed hash
      returns:      blessed reference to 
                    compressed/reversed hash
  • $crossref = matcheq($rgci,$rgcc,$crossref);

  • $crossref = $rgci->matcheq($rgcc,$crossref);

    Return or update a cross reference hash of the form:

      val rgci  =>  val rgcc

    where the keys in rgci and rgcc match exactly

      input:        ISO reverse hash,
                    CIA reverse hash,
                    [optional] cross ref hash
      returns:      blessed reference to
                    cross reference hash
  • $rv = pars_can($rgci,$rgcc,$crossref,\@candidates,$ikey,$regexp);

  • $rv = $rgci->pars_can($rgcc,$crossref,\@candidates,$ikey,$regexp);

    Parse the key values in @candidates for matches in $rgcc keys to the regular expression supplied in $regexp. If only one match is found, update the $cross->{hash} and delete the entry in $rgci pointed to by $ikey and the match entry in $rgcc, then return true. If no match is found or more than one match is found, return false.

      input:        ptr to reverse gci hash
                    ptr to reverse gcc hash
                    ptr to  cross reference hash
                    ptr to candidates array
                    reverse gci key
                    regular expression
    
      returns:      true if unique match found
                    else returns false
  • parsBYword($rgci,$rgcc,$crossref);

  • $rgci->parsBYword($rgcc,$crossref);

    Look for near matches of $rgci keys to $rgcc keys by doing a string match a word at a time using the key values in $rgci checked against all keys in $rgcc.

      i.e.  @words = split(/\s/,$rgcikey)
    
      first $rgcckey =~ /word[0]/;
      then  $rgcckey =~ /word[0] word[1]/
      and so on...
    
      input:        ptr to reverse gci hash
                    ptr to reverse gcc hash
                    ptr to cross reference
      returns:      nothing

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 267:

You forgot a '=back' before '=head1'

Around line 385:

'=item' outside of any '=over'