/ 
Geo-Coder-Free-0.43
⭐ Starred 9 / Geo::Coder::Free::Utils

NAME

Geo::Coder::Free::Utils - Random subroutines for Geo::Coder::Free

DESCRIPTION

Utility module for cache management, geospatial calculations, and shared address-normalization helpers used by multiple backends.

VERSION

Version 0.03

SUBROUTINES/METHODS

FORMAL SPECIFICATION

[STRING, HASH, LOGGER, CHI_CACHE, COORDINATE]

CacheConfig ::= ⟨⟨ driver : STRING;
				 servers : seq STRING;
				 root_dir : STRING;
				 connect : STRING ⟩⟩

CacheArgs ::= ⟨⟨ config : HASH;
				logger : LOGGER;
				namespace : STRING;
				root_dir : STRING ⟩⟩

Point ::= ⟨⟨ latitude : COORDINATE;
			longitude : COORDINATE ⟩⟩
where
  latitude ∈ {x : ℝ | -90 ≤ x ≤ 90} ∧
  longitude ∈ {x : ℝ | -180 ≤ x ≤ 180}

Unit ::= K | N | M

CreateCache : CacheArgs → CHI_CACHE

∀ args : CacheArgs •
  let driver == args.config.driver ∨ default_driver •
  validate_driver_config(driver, args.config) ∧
  ∃ cache : CHI_CACHE • cache = CHI.new(build_chi_args(driver, args))

Distance : Point × Point × Unit → ℝ₊

∀ p1, p2 : Point; u : Unit •
  let d == great_circle_distance(p1, p2) •
  d ≥ 0 ∧
  (u = K ⟹ result = d × 1.609344) ∧
  (u = N ⟹ result = d × 0.8684) ∧
  (u = M ⟹ result = d)

create_disc_cache

Initialize a disc-based cache using the CHI module. Supports multiple cache drivers, including BerkeleyDB, DBI, and Redis.

Parameters: - config: Configuration hash reference (required) - logger: Logger object (optional) - namespace: Cache namespace (optional) - root_dir: Root directory override (optional)

Returns: CHI cache object

create_memory_cache

Initialize a memory-based cache using the CHI module. Supports multiple cache drivers, including SharedMem, Memory, and Redis.

Parameters: - config: Configuration hash reference (required) - logger: Logger object (optional) - namespace: Cache namespace (optional) - root_dir: Root directory override (optional)

Returns: CHI cache object

distance

Calculate the great circle distance between two points on Earth using the Haversine formula. More accurate than the original implementation, especially for short distances.

Parameters: - lat1, lon1: Latitude and longitude of first point (decimal degrees) - lat2, lon2: Latitude and longitude of second point (decimal degrees) - unit: 'K' for kilometers, 'N' for nautical miles, 'M' or undef for statute miles

Returns: Distance in specified units

Throws: Error on invalid input parameters

_normalize

Normalise a street name to its abbreviated canonical form. Uppercases the input, then abbreviates the second-to-last or last word (whichever is a recognised street type) using Geo::Coder::Abbreviations. Leading zeros are also stripped ("04th St" → "4th St").

Exported so that Local.pm and OpenAddresses.pm can call it without importing Geo::Coder::Free.

_abbreviate

Abbreviate a single street-type word (e.g. "Street" → "ST"). Returns the original word uppercased if no abbreviation is found.

Exported so that Local.pm and OpenAddresses.pm can call it without importing Geo::Coder::Free.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

BUGS

Please report any bugs or feature requests to the author.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Geo::Coder::Free::Utils

LICENSE AND COPYRIGHT

Geo::Coder::Free is licensed under GPL2.0 for personal use only. Commercial users must apply in writing for a licence.

SEE ALSO

CHI, Math::Trig, DBI