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