lib/Geo/Coder/Free/Provenance.pm

        start → end → jump
        

    1: package Geo::Coder::Free::Provenance;
    2: 
    3: # The provenance of a result, and the vocabulary it speaks.  Kept out of
    4: # Geo::Coder::Free::Utils, which is tracked from VWF master: a geocoder result
    5: # has no provenance there, so an addition to that file lasts only until the next
    6: # sync with upstream.  Everything in this module is specific to this
    7: # distribution.
    8: 
    9: use strict;
   10: use warnings;
   11: 
   12: use Geo::Location::Point 0.19 ();	# Defines the accuracy vocabulary this module speaks
   13: use Exporter qw(import);
   14: our @EXPORT_OK = qw(GEOCODER ACCURACY_LEVELS);
   15: 
   16: =encoding utf-8
   17: 
   18: =head1 NAME
   19: 
   20: Geo::Coder::Free::Provenance - The provenance keys that every Geo::Coder::Free result carries
   21: 
   22: =head1 DESCRIPTION
   23: 
   24: Which distribution and which backend produced a result, how good the match was
   25: and how precise the coordinate is: the keys of section 2.1 of
   26: F<BI-Phase6-Dependency-Specs.md>, and the vocabulary they speak.
   27: 
   28:     use Geo::Coder::Free::Provenance qw(GEOCODER);
   29: 
   30:     my $point = Geo::Location::Point->new({
   31:         geocoder   => GEOCODER,
   32:         database   => 'OpenAddresses',
   33:         confidence => 1.0,
   34:         accuracy   => Geo::Location::Point::accuracy_for(qw(house_number road city)),
   35:     });
   36: 
   37: C<< Geo::Coder::Free->provenance($point) >> reads the four keys back, so a
   38: consumer does not have to know them.
   39: 
   40: These two live here rather than in L<Geo::Coder::Free::Utils> because Utils is
   41: synced from VWF master, where the provenance of a geocoder result has no
   42: meaning; an addition there would be lost the next time that sync runs.
   43: 
   44: =head1 VERSION
   45: 
   46: Version 0.51
   47: 
   48: =cut
   49: 
   50: our $VERSION = '0.51';
   51: 
   52: # The distribution that produced a result.  Every backend stamps this on the
   53: # Geo::Location::Point it hands back, so a consumer can tell a result from this
   54: # distribution from one passed on by a wrapper such as Geo::Coder::List.
   55: # Section 2.1 of BI-Phase6-Dependency-Specs.md.
   56: use constant GEOCODER => 'Geo::Coder::Free';
   57: 
   58: # How precise the coordinates behind a match can claim to be, most precise
   59: # first.  Geo::Location::Point::accuracy_for() returns one of these, and anything
   60: # that validates an accuracy (section 3.2) validates against this list.
   61: #
   62: # The vocabulary is not written down here.  Geo::Location::Point defines it and
   63: # refuses an accuracy outside it, so this module reads that one list: the levels
   64: # a backend reports and the levels a point accepts cannot drift apart, and this
   65: # constant is the same list object rather than a copy that agrees today.  The
   66: # rule that turns matched fields into a level lives there too, with the list.
   67: use constant ACCURACY_LEVELS => Geo::Location::Point::ACCURACY_LEVELS();
   68: 
   69: =head1 SUBROUTINES/METHODS
   70: 
   71: =head2 GEOCODER
   72: 
   73: The distribution that produced a result: C<Geo::Coder::Free>.  It is the
   74: C<geocoder> key of every result this distribution returns, whether the answer
   75: came from OpenAddresses, Local or MaxMind.
   76: 
   77: =head2 ACCURACY_LEVELS
   78: 
   79: A list of the accuracies a result may claim, most precise first: C<address>,
   80: C<street>, C<postcode>, C<locality>, C<city>, C<region> and C<country>.
   81: 
   82: It is C<Geo::Location::Point::ACCURACY_LEVELS()>, the list that module
   83: validates an accuracy against, re-exported here so that a backend can describe
   84: the match it made without knowing which module the vocabulary is defined in.
   85: There is one list behind both names, not a copy of it.
   86: 
   87: The rule that turns the fields a match was made on into one of these levels is
   88: C<Geo::Location::Point::accuracy_for()>, which lives beside the list it returns
   89: a level from.  This module reports the C<accuracy> key; it does not decide what
   90: the key may hold.
   91: 
   92: =cut
   93: 
   94: 1;
   95: 
   96: __END__
   97: 
   98: =head1 AUTHOR
  Mutants (Total: 2, Killed: 2, Survived: 0)
   99: 

					

					
Mutants (Total: 2, Killed: 0, Survived: 2)
					

				
BOOL_NEGATE_99_2: Negate boolean return expression
MEDIUM: Add tests asserting both true and false outcomes

								

								
🧪 Suggested Test
								
# Boolean branch test suggestion
ok( !func(INPUT), 'Verify boolean branch behaviour' );

								
							
RETURN_UNDEF_99_2: Replace return expression with undef
LOW: Mutation survived, but impact may be minor

								

								
🧪 Suggested Test
								
# Return value assertion
is( func(INPUT), EXPECTED, 'Verify correct return value' );

								
							
  100: Nigel Horne, C<< <njh at nigelhorne.com> >>

					

					
Mutants (Total: 2, Killed: 0, Survived: 2)
					

				
BOOL_NEGATE_100_2: Negate boolean return expression
MEDIUM: Add tests asserting both true and false outcomes

								

								
🧪 Suggested Test
								
# Boolean branch test suggestion
ok( !func(INPUT), 'Verify boolean branch behaviour' );

								
							
RETURN_UNDEF_100_2: Replace return expression with undef
LOW: Mutation survived, but impact may be minor

								

								
🧪 Suggested Test
								
# Return value assertion
is( func(INPUT), EXPECTED, 'Verify correct return value' );

								
							
  101: 
  Mutants (Total: 2, Killed: 2, Survived: 0)
  102: =head1 LICENSE AND COPYRIGHT

					

					
Mutants (Total: 2, Killed: 0, Survived: 2)
					

				
BOOL_NEGATE_102_2: Negate boolean return expression
MEDIUM: Add tests asserting both true and false outcomes

								

								
🧪 Suggested Test
								
# Boolean branch test suggestion
ok( !func(INPUT), 'Verify boolean branch behaviour' );

								
							
RETURN_UNDEF_102_2: Replace return expression with undef
LOW: Mutation survived, but impact may be minor

								

								
🧪 Suggested Test
								
# Return value assertion
is( func(INPUT), EXPECTED, 'Verify correct return value' );

								
							
  103: 

					

					
Mutants (Total: 2, Killed: 0, Survived: 2)
					

				
BOOL_NEGATE_103_2: Negate boolean return expression
MEDIUM: Add tests asserting both true and false outcomes

								

								
🧪 Suggested Test
								
# Boolean branch test suggestion
ok( !func(INPUT), 'Verify boolean branch behaviour' );

								
							
RETURN_UNDEF_103_2: Replace return expression with undef
LOW: Mutation survived, but impact may be minor

								

								
🧪 Suggested Test
								
# Return value assertion
is( func(INPUT), EXPECTED, 'Verify correct return value' );

								
							
  104: Copyright 2017-2026 Nigel Horne.
  105: 

					

					
Mutants (Total: 2, Killed: 0, Survived: 2)
					

				
BOOL_NEGATE_105_2: Negate boolean return expression
MEDIUM: Add tests asserting both true and false outcomes

								

								
🧪 Suggested Test
								
# Boolean branch test suggestion
ok( !func(INPUT), 'Verify boolean branch behaviour' );

								
							
RETURN_UNDEF_105_2: Replace return expression with undef
LOW: Mutation survived, but impact may be minor

								

								
🧪 Suggested Test
								
# Return value assertion
is( func(INPUT), EXPECTED, 'Verify correct return value' );

								
							
  106: This program is free software; you can redistribute it and/or modify it under
  107: the terms of the GNU General Public License, version 2.