NAME
Web::VWF::Utils - Random subroutines for VWF
DESCRIPTION
Utility module for cache management and geospatial calculations. Provides cross-driver cache initialization and Haversine formula implementation.
VERSION
Version 0.003.0
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)
File-based drivers store their files in $CACHEDIR, or failing that $CACHE_DIR, when either is set (the directory is created if need be); otherwise in the first of $root_dir, the root_dir argument and the configured root_dir.
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
env_cache_dir
The directory that the environment says the caches are to be kept in: the value of $CACHEDIR or, if that is unset or empty, of $CACHE_DIR. Returns undef when neither is set. File-based cache drivers use it in preference to root_dir, which lets an administrator keep the caches outside the site; it is created if it does not exist. It is exported on request.
use Web::VWF::Utils qw(env_cache_dir);
my $dir = env_cache_dir();
API SPECIFICATION
INPUT
{}
OUTPUT
{ type => 'string', optional => 1 }
redact_config
A copy of a configuration, safe to write to a log: the value of any key whose name contains secret, password, passwd, key, token or credential is replaced by [REDACTED], at any depth. The original is not changed. Debug logs get pasted into bug reports, and the configuration holds the CSRF secret, the reCAPTCHA secret and the DKIM key path.
API SPECIFICATION
INPUT
{ config => { type => [ 'hashref', 'arrayref', 'string', 'undef' ] } }
OUTPUT
{ type => [ 'hashref', 'arrayref', 'string', 'undef' ] } # a plain, unblessed copy
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
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 Web::VWF::Utils
LICENSE AND COPYRIGHT
VWF is licensed under GPL2.0 for personal use only. Commercial users must apply in writing for a licence.
SEE ALSO
CHI, Math::Trig, DBI