| 1 | package Genealogy::Obituary::Lookup; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 3 | 16 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 4 | 16 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 5 | 16 | ▶ | use autodie qw(:all); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 6 | 16 | ▶ | use feature 'state'; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 8 | 16 | ▶ | use Carp; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 9 | 16 | ▶ | use Data::Reuse; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 10 | 16 | ▶ | use File::Spec; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 11 | 16 | ▶ | use Genealogy::Obituary::Lookup::obituaries; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 12 | 16 | ▶ | use Module::Info; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 13 | 16 | ▶ | use Object::Configure 0.12; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 14 | 16 | ▶ | use Params::Get 0.13; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 15 | 16 | ▶ | use Params::Validate::Strict 0.09; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 16 | 16 | ▶ | use Readonly; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 17 | 16 | ▶ | use Return::Set; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 18 | 16 | ▶ | use Scalar::Util; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 20 | =encoding UTF-8 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 22 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 23 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 24 | Genealogy::Obituary::Lookup - Lookup an obituary in the ODT/Rootsweb/funeral-notices database | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 26 | =head1 VERSION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 28 | Version 0.21 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 30 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 31 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 32 | 16 | our $VERSION = '0.21'; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 34 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 35 | # Constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 36 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 38 | # URLs for the two archive sources; 'L' (local/link) has no fixed base URL. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 39 | 16 | Readonly::Hash my %URLS => ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 40 | M => 'https://wayback.archive-it.org/20669/20231102044925/https://mlarchives.rootsweb.com/listindexes/emails?listname=gen-obit&page=', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 41 | F => 'https://www.freelists.org/post/obitdailytimes/Obituary-Daily-Times-', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 42 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 44 | 16 | Readonly::Scalar my $DEFAULT_CACHE_DURATION => '1 day'; # Database is rebuilt daily | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 45 | 16 | Readonly::Scalar my $MIN_LAST_NAME_LENGTH => 1; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 46 | 16 | Readonly::Scalar my $MAX_LAST_NAME_LENGTH => 100; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 48 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 49 | # Internationalisation message map | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 50 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 51 | # All user-facing error/warning text lives here. Keys are stable; templates | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 52 | # use %{name} placeholders that _i18n() fills with a hashref of named args. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 53 | 16 | my %MESSAGES = ( | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 54 | err_no_self => "search() must be called on an object", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 55 | err_no_args => 'Usage: %{package}->search(last => $val)', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 56 | err_no_last => "Value for 'last' is mandatory", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 57 | err_no_obituaries => "Can't open the obituaries database", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 58 | err_no_page => '%{package}: undefined $page', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 59 | err_no_source => '%{package}: %{page}: undefined source', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 60 | err_bad_source => "%{package}: Invalid source, '%{source}'. Valid sources are 'M', 'F' and 'L'", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 61 | err_no_newspaper => "%{package}: undefined newspaper. Newspaper must be given when source type is 'L'", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 62 | err_bad_logger => "Logger must be an object with info(), warn() and error() methods", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 63 | warn_not_dir => '%{class}: %{dir} is not a directory', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 64 | warn_bad_usage => '%{package}: use ->new() not ::new() to instantiate', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 65 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 67 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 68 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 69 | use Genealogy::Obituary::Lookup; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 71 | # --- 1. Basic search: list context, all matching records --- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 72 | my $obits = Genealogy::Obituary::Lookup->new(); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 73 | my @smiths = $obits->search(last => 'Smith'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 74 | foreach my $r (@smiths) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 75 | printf "%s %s -- %s\n", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 76 | $r->{first} // '?', $r->{last}, $r->{url}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 77 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 79 | # --- 2. Scalar context: first matching record only --- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 80 | my $hit = $obits->search({ first => 'Eric', last => 'Baal' }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 81 | print $hit->{url}, "\n" if $hit; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 83 | # --- 3. Narrow a search with optional first, middle, and age --- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 84 | my @results = $obits->search( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 85 | first => 'Jean', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 86 | middle => 'Emily', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 87 | last => 'McCarthy', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 88 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 89 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 90 | # --- 4. Clone an object to use a different data directory --- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 91 | my $prod = Genealogy::Obituary::Lookup->new(directory => '/data/obits'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 92 | my $test = $prod->new(directory => 't/data'); # clone with override | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 93 | my @test_hits = $test->search(last => 'Jones'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 94 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 95 | # --- 5. Attach a structured logger --- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 96 | use Log::Log4perl qw(:easy); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 97 | Log::Log4perl->easy_init($DEBUG); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 98 | my $logged = Genealogy::Obituary::Lookup->new( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 99 | logger => Log::Log4perl->get_logger(), | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 100 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 101 | my @hits = $logged->search(last => 'Brown'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 103 | =head1 SUBROUTINES/METHODS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 105 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 107 | Creates a L<Genealogy::Obituary::Lookup> object. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 109 | my $obits = Genealogy::Obituary::Lookup->new(); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 110 | my $clone = $obits->new(); # clone with no extra args | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 112 | Accepts the following optional arguments: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 113 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 114 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 115 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 116 | =item * C<cache> - passed to L<Database::Abstraction> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 118 | =item * C<config_file> - path to a YAML/XML/INI configuration file whose keys | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 119 | are merged into the constructor arguments at runtime, allowing deployment-time | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 120 | override without code changes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 122 | =item * C<directory> - directory that contains F<obituaries.sql>. If a single | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 123 | non-reference argument is passed to C<new()>, it is taken as C<directory>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 124 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 125 | =item * C<logger> - object with C<info()>, C<warn()> and C<error()> methods (e.g. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 126 | L<Log::Log4perl>, L<Log::Any>). All three are required: C<warn()> is used for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 127 | non-fatal directory diagnostics; C<error()> for fatal DB errors. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 129 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 131 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 132 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 133 | # Default: discovers data/ relative to the installed module file | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 134 | my $default = Genealogy::Obituary::Lookup->new(); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 136 | # Explicit directory (useful during development) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 137 | my $dev = Genealogy::Obituary::Lookup->new(directory => 't/data'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 139 | # With structured logging | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 140 | use Log::Log4perl qw(:easy); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 141 | Log::Log4perl->easy_init($DEBUG); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 142 | my $logged = Genealogy::Obituary::Lookup->new(logger => Log::Log4perl->get_logger()); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 144 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 145 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 146 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 148 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 149 | 'directory' => { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 150 | 'cache' => { type => 'any', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 151 | 'config_file' => { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 152 | 'logger' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 153 | type => 'object', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 154 | optional => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 155 | can => [ 'info', 'error' ] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 156 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 157 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 159 | =head4 DOMAIN — directory | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 160 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 161 | Valid partitions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 162 | EP-V Absent / undef Auto-discovers data/ relative to module file. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 163 | EP-V Existing readable dir Accepted; stored in $self->{directory}. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 165 | Invalid partitions (all carp + return undef) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 166 | EP-I Non-existent path Carps "not a directory". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 167 | EP-I Existing plain file Carps "not a directory". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 168 | EP-I Unreadable directory Carps "not a directory". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 169 | EP-I Empty string "" Carps "not a directory" (-d "" is false). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 170 | EP-I Path with null byte Rejected before -d (prevents "Embedded nulls" fatal). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 171 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 172 | =head4 DOMAIN — logger | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 173 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 174 | Valid partition | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 175 | EP-V Blessed object with can('info') && can('warn') && can('error') Accepted. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 176 | Additional methods beyond these three are fine. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 178 | Method roles | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 179 | info() Informational messages (progress, cache hits). Non-fatal. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 180 | warn() Non-fatal diagnostics: bad directory, null byte in path. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 181 | Called instead of error() so that new() can carp+return undef | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 182 | rather than die. Log::Abstraction::error() calls die(); using | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 183 | it here would violate the graceful-return contract. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 184 | error() Fatal-severity events from search() when the DB cannot be opened. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 185 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 186 | Invalid partitions (all croak err_bad_logger) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 187 | EP-I String Not an object. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 188 | EP-I Number Not an object. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 189 | EP-I Unblessed hashref Not blessed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 190 | EP-I Coderef Not blessed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 191 | EP-I Object missing info() Incomplete interface. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 192 | EP-I Object missing warn() Incomplete interface. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 193 | EP-I Object missing error() Incomplete interface. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 194 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 195 | =head4 DOMAIN — invocation style | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 197 | Valid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 198 | EP-V Pkg->new(...) Class method — normal invocation. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 199 | EP-V $obj->new(...) Object method — clone with optional overrides. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 200 | EP-V Pkg->new('/path') Single bare string — treated as directory. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 201 | EP-V Pkg->new({key=>val}) Hashref argument. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 202 | EP-V Pkg::new() No-arg bare call — tolerated silently. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 203 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 204 | Invalid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 205 | EP-I Pkg::new(undef, args) Croak warn_bad_usage (undef class + args detected). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 207 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 209 | On success: blessed Genealogy::Obituary::Lookup hashref | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 210 | On failure: undef (carp explains why) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 212 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 213 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 214 | warn_not_dir - <class>: <dir> is not a directory. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 215 | Resolution: pass a valid, readable directory. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 216 | warn_bad_usage - use ->new() not ::new() when passing arguments. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 217 | Resolution: call as a class method. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 218 | err_bad_logger - Logger must have info(), warn() and error() methods. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 219 | Resolution: wrap your logger in an adapter. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 221 | =head3 PSEUDOCODE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 222 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 223 | 1. Parse arguments: accept hashref, key=>value list, or single bare string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 224 | (treated as directory). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 225 | 2. If called as a function (::new) with no args, tolerate and self-correct; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 226 | croak if args were given - the invocation is ambiguous. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 227 | 3. If $class is already a blessed object, clone it: merge new args into a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 228 | copy of the existing hash and bless into the same class. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 229 | 4. Validate the logger object if provided (must have info() and error()). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 230 | 5. Merge config-file settings via Object::Configure. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 231 | 6. Resolve the data directory: explicit arg > module-relative default. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 232 | 7. For a plain-string directory: (a) reject null bytes immediately | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 233 | (logger->warn + carp + return undef); (b) untaint via regex — the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 234 | capture is guaranteed to succeed because null bytes were just excluded. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 235 | 8. Carp and call logger->warn if the directory is missing or unreadable; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 236 | return undef. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 237 | 9. Bless and return with cache_duration defaulted (overridable by caller). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 238 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 239 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 240 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 241 | sub new | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 242 | 431 | ▶ | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=29 SCAR=33.7
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 243 | 431 | my $class_in = shift; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 244 | 431 | my %args; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 245 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 246 | # Support: ->new('path'), ->new(key=>val), ->new({key=>val}) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 247 | 431 | ▶ | if((scalar(@_) == 0) && !ref($class_in) && defined($class_in) && -d $class_in) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 3 branches
Condition100%9/9
scalar @_ == 0 and not ref $class_in and defined $class_in and -d $class_in
scalar @_ == 0 and not ref $class_in and defined $class_in
scalar @_ == 0 and not ref $class_in
MC/DC100%4/4
scalar @_ == 0 and not ref $class_in and defined $class_in and -d $class_in
scalar @_ == 0
not ref $class_in
defined $class_in
-d $class_in
Truth table100%5/5
A and not(B) and C and D
A= scalar @_ == 0B= not ref $class_inC= defined $class_inD= -d $class_in
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 248 | # Called as Genealogy::Obituary::Lookup->new('/some/dir') | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 249 | # $class_in is the directory, not the class — handled below via scalar arg | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 250 | 1 | $args{'directory'} = $class_in; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 251 | 1 | $class_in = __PACKAGE__; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 252 | ▶ | } elsif((scalar(@_) == 1) && !ref($_[0])) { | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition100%3/3
scalar @_ == 1 and not ref $_[0]
MC/DC100%2/2
scalar @_ == 1 and not ref $_[0]
scalar @_ == 1
not ref $_[0]
Truth table100%3/3
A and not(B)
A= scalar @_ == 1B= not ref $_[0]
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 253 | 5 | $args{'directory'} = $_[0]; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 254 | } elsif(my $params = Params::Get::get_params(undef, @_)) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 255 | 393 | %args = %{$params}; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 256 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 257 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 258 | 431 | ▶ | if(!defined($class_in)) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 259 | # Called as Genealogy::Obituary::Lookup::new() — tolerate only if no args | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 260 | 11 | ▶ | if(%args) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 261 | 4 | Carp::croak(__PACKAGE__->_i18n('warn_bad_usage', {package => __PACKAGE__})); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 262 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 263 | 7 | $class_in = __PACKAGE__; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 264 | } elsif(Scalar::Util::blessed($class_in)) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 265 | # Clone: merge new args over existing state and re-bless | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 266 | 24 | return bless { %{$class_in}, %args }, ref($class_in); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 267 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 268 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 269 | # Validate the logger before Object::Configure can wrap it; the wrapper | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 270 | # always satisfies the interface check so we must test the original value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 271 | 403 | ▶ | if(defined $args{'logger'}) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 272 | 33 | ▶ | unless(Scalar::Util::blessed($args{'logger'}) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%9/9
builtin::blessed($args{"logger"}) and $args{"logger"}->can("info") and $args{"logger"}->can("warn") and $args{"logger"}->can("error")
builtin::blessed($args{"logger"}) and $args{"logger"}->can("info") and $args{"logger"}->can("warn")
builtin::blessed($args{"logger"}) and $args{"logger"}->can("info")
MC/DC100%4/4
builtin::blessed($args{"logger"}) and $args{"logger"}->can("info") and $args{"logger"}->can("warn") and $args{"logger"}->can("error")
builtin::blessed($args{"logger"})
$args{"logger"}->can("info")
$args{"logger"}->can("warn")
$args{"logger"}->can("error")
Truth table100%5/5
A and B and C and D
A= builtin::blessed($args{"logger"})B= $args{"logger"}->can("info")C= $args{"logger"}->can("warn")D= $args{"logger"}->can("error")
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 273 | && $args{'logger'}->can('info') | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 274 | && $args{'logger'}->can('warn') | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 275 | && $args{'logger'}->can('error')) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 276 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 277 | 23 | Carp::croak($class_in->_i18n('err_bad_logger')); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 278 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 279 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 280 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 281 | # Merge configuration file settings (YAML / XML / INI) into %args | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 282 | 380 | %args = %{Object::Configure::configure($class_in, \%args)}; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 283 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 284 | # Resolve the data directory, falling back to the module's own data/ subdirectory. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 285 | # Cache the lookup per class: Module::Info scans %INC and stats the filesystem; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 286 | # the result is stable for the process lifetime. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 287 | 379 | state %_dir_cache; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 288 | 379 | ▶ | unless(defined $args{'directory'}) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 289 | 19 | ▶ | unless(exists $_dir_cache{$class_in}) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 290 | 8 | my $info = Module::Info->new_from_loaded($class_in); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 291 | 8 | my $derived; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 292 | 8 | ▶ | if(defined $info) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 293 | 8 | (my $base = $info->file()) =~ s/\.pm\z//; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 294 | 8 | $derived = File::Spec->catfile($base, 'data'); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 295 | 8 | ▶ | $derived = undef unless -d $derived; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 296 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 297 | 8 | $_dir_cache{$class_in} = $derived; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 298 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 299 | $args{'directory'} = $_dir_cache{$class_in} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 300 | 19 | ▶ | if defined $_dir_cache{$class_in}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 301 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 302 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 303 | # Premise: directory, if provided, must be a plain string (not a ref). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 304 | # Merge the null-byte guard and untaint into one outer block — both share | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 305 | # the same defined+!ref precondition, eliminating a redundant test. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 306 | 379 | ▶ | if(defined($args{'directory'}) && !ref($args{'directory'})) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
defined $args{"directory"} and not ref $args{"directory"}
MC/DC50%1/2
defined $args{"directory"} and not ref $args{"directory"}
defined $args{"directory"}
not ref $args{"directory"}
Truth table66%2/3
A and not(B)
A= defined $args{"directory"}B= not ref $args{"directory"}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 307 | # Null bytes cause a fatal "Embedded nulls" inside stat(). Reject first. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 308 | 377 | ▶ | if(index($args{'directory'}, "\0") >= 0) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 309 | 6 | my $msg = $class_in->_i18n('warn_not_dir', | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 310 | {class => $class_in, dir => '(path contains null byte)'}); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 311 | 6 | ▶ | $args{'logger'}->warn($msg) if $args{'logger'}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 312 | 6 | Carp::carp($msg); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 313 | 6 | return; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 314 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 315 | # Conclusion: no null bytes remain, so m/\A([^\0]*)\z/ is guaranteed to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 316 | # match — the capture is infallible. Untaint for taint-mode callers. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 317 | 371 | ($args{'directory'}) = ($args{'directory'} =~ m/\A([^\0]*)\z/); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 318 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 320 | 373 | ▶ | if(defined($args{'directory'}) && !((-d $args{'directory'}) && (-r $args{'directory'}))) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition83%5/6
defined $args{"directory"} and not -d $args{"directory"} && -r $args{"directory"}
-d $args{'directory'} && -r $args{'directory'}
MC/DC66%2/3
defined $args{"directory"} and not -d $args{"directory"} && -r $args{"directory"}
defined $args{"directory"}
-d $args{'directory'}
-r $args{'directory'}
Truth table75%3/4
A and not(B && C)
A= defined $args{"directory"}B= -d $args{'directory'}C= -r $args{'directory'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 321 | my $msg = $class_in->_i18n('warn_not_dir', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 322 | 33 | {class => $class_in, dir => $args{'directory'}}); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 323 | 33 | ▶ | $args{'logger'}->warn($msg) if $args{'logger'}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 324 | 33 | Carp::carp($msg); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 325 | 33 | return; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 326 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 327 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 328 | 340 | return bless { cache_duration => $DEFAULT_CACHE_DURATION, %args }, $class_in; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 329 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 331 | =head2 search | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 332 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 333 | Searches the obituary database. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 334 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 335 | # List context: all matching records | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 336 | my @smiths = $obits->search(last => 'Smith'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 337 | print $smiths[0]->{'url'}, "\n"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 338 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 339 | # Scalar context: first matching record, or undef | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 340 | my $entry = $obits->search({ first => 'John', last => 'Smith' }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 341 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 342 | The returned hashrefs always include a C<url> key pointing to the source archive. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 343 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 344 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 345 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 346 | =item * C<List context> - array of hashrefs, empty on no match. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 347 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 348 | =item * C<Scalar context> - single hashref, or C<undef> on no match. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 349 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 350 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 351 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 352 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 353 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 354 | my @results = $obits->search(last => 'O-Brien'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 355 | foreach my $r (@results) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 356 | printf "%s %s, age %s - %s\n", | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 357 | $r->{first} // '?', $r->{last}, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 358 | $r->{age} // 'unknown', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 359 | $r->{url}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 360 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 361 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 362 | # With optional filters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 363 | my $hit = $obits->search(first => 'John', middle => 'W', last => 'Coppage'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 364 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 365 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 366 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 367 | =head4 INPUT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 368 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 369 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 370 | 'last' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 371 | type => 'string', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 372 | min => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 373 | max => 100, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 374 | matches => qr/\A[\w-]+\z/ # hyphens allowed; \z rejects trailing newlines | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 375 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 376 | 'first' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 377 | type => 'string', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 378 | optional => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 379 | min => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 380 | max => 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 381 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 382 | 'middle' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 383 | type => 'string', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 384 | optional => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 385 | min => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 386 | max => 100 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 387 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 388 | 'age' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 389 | type => 'integer', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 390 | optional => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 391 | min => 0, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 392 | max => 120 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 393 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 394 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 395 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 396 | =head4 DOMAIN — last (required) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 397 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 398 | Boundary values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 399 | BVA MIN-1 "" (0 chars) INVALID — croak err_no_last | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 400 | BVA MIN "A" (1 char) valid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 401 | BVA MAX "A"x100 (100 chars) valid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 402 | BVA MAX+1 "A"x101 (101 chars) INVALID — croak (schema max exceeded) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 403 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 404 | Equivalence partitions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 405 | EP-V "Smith" Typical ASCII surname. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 406 | EP-V "Smith-Jones" Hyphen is allowed (in [\w-]). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 407 | EP-V "Mc_Arthur" Underscore is \w. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 408 | EP-V "Smith2" Digit is \w. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 409 | EP-I undef Croak err_no_last. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 410 | EP-I "O'Brien" Apostrophe not in [\w\-] — rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 411 | EP-I "van Berg" Space not in [\w\-] — rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 412 | EP-I "Smith; DROP ..." SQL injection metacharacters rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 413 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 414 | Character-domain (format partition) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 415 | FMT German umlauts (u-umlaut, sharp-s) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 416 | Matched by \w only when string has the UTF-8 flag | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 417 | AND the calling program uses "use utf8" (or the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 418 | runtime locale enables Unicode semantics). Without | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 419 | those, the same characters are rejected. No crash | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 420 | either way; behaviour depends on runtime locale. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 421 | FMT Accented Latin (e.g. e-acute, n-tilde) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 422 | Same as German umlauts — locale-dependent. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 423 | FMT Emoji Not \w under any locale — always rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 424 | FMT Zalgo combining marks Not \w — always rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 425 | FMT RTL-override (U+202E) Not \w — always rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 426 | FMT Full-width ASCII (e.g. U+FF33) Not \w — rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 427 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 428 | Encoding note | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 429 | The field value is stored and searched as received; the module does not | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 430 | normalize Unicode (NFC/NFD) or transliterate diacritics. Ensure the caller | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 431 | and the database were built with the same normalization if non-ASCII | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 432 | surnames are used. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 433 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 434 | =head4 DOMAIN — first / middle (optional) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 435 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 436 | Boundary values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 437 | BVA MIN-1 "" (0 chars) INVALID — croak (schema min exceeded) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 438 | BVA MIN "J" (1 char) valid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 439 | BVA MAX "J"x100 (100 chars) valid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 440 | BVA MAX+1 "J"x101 (101 chars) INVALID | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 441 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 442 | Equivalence partitions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 443 | EP-V Absent Valid — field is optional. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 444 | EP-V "John" Typical value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 445 | EP-V "O'Malley" No format constraint on first/middle. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 446 | EP-I "" (empty string) INVALID (min=1). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 447 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 448 | Character-domain (format partition) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 449 | FMT ASCII text Always accepted within length limits. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 450 | FMT Non-ASCII / UTF-8 Accepted — no regex constraint on first/middle. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 451 | Diacritics, accented letters, and multibyte | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 452 | sequences are passed through unchanged. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 453 | FMT Emoji Accepted syntactically; matched literally in | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 454 | SQL LIKE comparisons (no normalization). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 455 | FMT Zalgo / RTL overrides Accepted syntactically; may produce unexpected | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 456 | SQL matches or rendering artifacts. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 457 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 458 | Encoding note | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 459 | first and middle are the safest fields for non-ASCII input: no regex | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 460 | validation is applied and UTF-8 strings are stored and searched as-is. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 461 | Length is measured in Perl characters, not bytes; a 4-byte emoji counts | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 462 | as 1 character toward the 100-character limit. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 463 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 464 | =head4 DOMAIN — age (optional integer) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 465 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 466 | Boundary values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 467 | BVA MIN-1 -1 INVALID — croak (schema min=0 exceeded) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 468 | BVA MIN 0 valid (newborn) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 469 | BVA MAX 120 valid (maximum recorded human lifespan) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 470 | BVA MAX+1 121 INVALID — croak (schema max exceeded) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 471 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 472 | Equivalence partitions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 473 | EP-V 65 Typical adult age. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 474 | EP-V Absent Valid — field is optional. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 475 | EP-I -1 Below minimum. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 476 | EP-I 121 Above maximum. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 477 | EP-I 1.5 Non-integer float — rejected (type=integer). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 478 | EP-I "old" Non-numeric string — rejected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 479 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 480 | =head4 DOMAIN — invocation style | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 481 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 482 | EP-V $obj->search(...) Normal object-method call. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 483 | EP-I Pkg->search(...) Croak err_no_self (class is not blessed). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 484 | EP-I Pkg::search(...) Croak err_no_self. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 485 | EP-I $obj->search() Croak err_no_args (zero args). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 486 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 487 | =head4 CONTEXT DOMAIN | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 488 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 489 | List context Returns list of hashrefs; empty list on no match. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 490 | Scalar context Returns single hashref (first match) or undef. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 491 | Void context No crash; result silently discarded. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 492 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 493 | =head4 OUTPUT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 494 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 495 | Argument error: croak | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 496 | No match (list): () | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 497 | No match (scalar): undef | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 498 | Match (list): ( HashRef, ... ) each has a 'url' key | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 499 | Match (scalar): HashRef has a 'url' key | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 500 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 501 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 502 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 503 | err_no_self - search() must be called on an object (->search, not ::search). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 504 | err_no_last - Value for 'last' is mandatory and must be non-empty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 505 | err_no_obituaries - Cannot open the obituaries database; check directory path. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 506 | (from _create_url) err_bad_source, err_no_page, err_no_source, err_no_newspaper. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 507 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 508 | =head3 PSEUDOCODE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 510 | 1. Croak unless $self is a blessed object. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 511 | 2. Parse args with Params::Get; validate schema with Params::Validate::Strict. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 512 | 3. Explicitly croak if 'last' is undef or empty - Params::Validate::Strict | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 513 | passes undef through for defined-but-required fields. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 514 | 4. Lazily open the obituaries DB handle (once per object lifetime). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 515 | 5. Croak if the DB handle could not be initialised. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 516 | 6. List context: fetchall, attach URL, fixate string values, return list. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 517 | 7. Scalar context: fetchone, attach URL, fixate string values, return hashref. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 518 | 8. Return undef / empty list when no rows match. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 519 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 520 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 521 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 522 | sub search | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 523 | 328 | ▶ | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
search: called CC=14 SCAR=26.7
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 524 | 328 | my $self = shift; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 525 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 526 | 328 | ▶ | Carp::croak(__PACKAGE__->_i18n('err_no_self')) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 527 | unless Scalar::Util::blessed($self); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 528 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 529 | # Guard against zero args before Params::Get, which uses confess (not croak) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 530 | # for the 0-args case, preventing Test::Carp from detecting the error type. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 531 | 320 | ▶ | Carp::croak(__PACKAGE__->_i18n('err_no_args', {package => __PACKAGE__})) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 532 | unless @_; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 533 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 534 | 314 | my $params = Params::Validate::Strict::validate_strict({ | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 535 | args => Params::Get::get_params('last', @_), | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 536 | schema => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 537 | 'last' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 538 | type => 'string', | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 539 | min => $MIN_LAST_NAME_LENGTH, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 540 | max => $MAX_LAST_NAME_LENGTH, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 541 | matches => qr/\A[\w-]+\z/, # Allow hyphens; \z rejects trailing newlines that \$ misses | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 542 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 543 | 'first' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 544 | type => 'string', optional => 1, min => 1, max => 100, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 545 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 546 | 'middle' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 547 | type => 'string', optional => 1, min => 1, max => 100, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 548 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 549 | 'age' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 550 | type => 'integer', optional => 1, min => 0, max => 120, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 551 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 552 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 553 | }); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 554 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 555 | # Params::Validate::Strict enforces schema structure but passes undef values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 556 | # for defined keys, so we check the mandatory 'last' field explicitly here. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 557 | 252 | ▶ | unless(defined($params->{'last'}) && length($params->{'last'}) > 0) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
defined $$params{"last"} and length $$params{"last"} > 0
MC/DC0%0/2
defined $$params{"last"} and length $$params{"last"} > 0
defined $$params{"last"}
length $$params{"last"} > 0
Truth table33%1/3
A and B
A= defined $$params{"last"}B= length $$params{"last"} > 0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 558 | $self->{'logger'}->error(__PACKAGE__->_i18n('err_no_last')) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 559 | 0 | ▶ | if $self->{'logger'}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 560 | 0 | Carp::croak(__PACKAGE__->_i18n('err_no_last')); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 561 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 562 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 563 | # Lazily initialise the DB handle — shared for the lifetime of the object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 564 | $self->{'obituaries'} //= Genealogy::Obituary::Lookup::obituaries->new( | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 565 | no_entry => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 566 | no_fixate => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 567 | 252 | ▶ | %{$self}, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition100%3/3
$$self{"obituaries"} //= "Genealogy::Obituary::Lookup::obituaries"->new("no_entry", 1, "no_fixate", 1, %{$self;})
MC/DC100%2/2
$$self{"obituaries"} //= "Genealogy::Obituary::Lookup::obituaries"->new("no_entry", 1, "no_fixate", 1, %{$self;})
$$self{"obituaries"}
"Genealogy::Obituary::Lookup::obituaries"->new("no_entry", 1, "no_fixate", 1, %{$self;})
Truth table100%3/3
A //= B
A= $$self{"obituaries"}B= "Genealogy::Obituary::Lookup::obituaries"->new("no_entry", 1, "no_fixate", 1, %{$self;})
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 568 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 569 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 570 | 252 | ▶ | unless(defined $self->{'obituaries'}) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 571 | $self->{'logger'}->error(__PACKAGE__->_i18n('err_no_obituaries')) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 572 | 7 | ▶ | if $self->{'logger'}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 573 | 7 | Carp::croak(__PACKAGE__->_i18n('err_no_obituaries')); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 574 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 575 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 576 | 245 | ▶ | if(wantarray) { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 577 | 164 | ▶ | my $obituaries = $self->{'obituaries'}->selectall_hashref($params) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 578 | or return; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 579 | # Iterate the arrayref directly (no intermediate grep list) and filter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 580 | # undef slots inline — eliminates one O(N) allocation for large result sets. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 581 | 156 | my @rc; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 582 | 156 | for my $obit (@{$obituaries}) { | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 583 | 180 | ▶ | next unless defined $obit; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 584 | 172 | $obit->{'url'} = _create_url($obit); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 585 | # Intern string values in the hash to reduce memory for repeated | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 586 | # strings (source, place, newspaper) across large result sets. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 587 | # fixate(%{$obit}) passes the hashref via the \[@%] prototype. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 588 | # Guard with eval: if a value is already interned (read-only) a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 589 | # second fixate call would otherwise die with "Modification of a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 590 | # read-only value". Silently tolerate that case. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 591 | 148 | { local $@; eval { Data::Reuse::fixate(%{$obit}) } }; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 592 | 148 | push @rc, $obit; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 593 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 594 | 132 | return @rc; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 595 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 596 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 597 | 81 | ▶ | my $obit = $self->{'obituaries'}->fetchrow_hashref($params) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 598 | or return; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 599 | 32 | $obit->{'url'} = _create_url($obit); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 600 | 29 | { local $@; eval { Data::Reuse::fixate(%{$obit}) } }; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 601 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 602 | 29 | return Return::Set::set_return($obit, { type => 'hashref', min => 1 }); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 603 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 604 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 605 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 606 | # Private helpers | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 607 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 608 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 609 | # Purpose: Builds the source URL for an obituary record. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 610 | # Entry: $obit — hashref with 'source' (M/F/L), 'page', and optionally | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 611 | # 'newspaper' (required for source 'L'). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 612 | # Exit: String URL. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 613 | sub _create_url | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 614 | 207 | ▶ | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_create_url: called CC=10 SCAR=23.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 615 | # Enforce privacy: only code within this package may call _create_url. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 616 | 207 | ▶ | Carp::croak("_create_url() is a private method of " . __PACKAGE__) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 617 | unless (caller)[0] eq __PACKAGE__; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 618 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 619 | 204 | my $obit = shift; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 620 | 204 | my $page = $obit->{'page'}; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 621 | 204 | my $source = $obit->{'source'}; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 622 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 623 | 204 | ▶ | Carp::croak(__PACKAGE__->_i18n('err_no_page', {package => __PACKAGE__})) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 624 | unless defined $page; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 625 | 199 | ▶ | Carp::croak(__PACKAGE__->_i18n('err_no_source', {package => __PACKAGE__, page => $page})) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 626 | unless defined $source; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 627 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 628 | # Premise: source ∈ {M, F} returns unconditionally above. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 629 | # Conclusion: the elsif below is only evaluated when source ∉ {M, F}. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 630 | 194 | ▶ | if($source eq 'M' || $source eq 'F') { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
Condition100%3/3
$source eq "M" or $source eq "F"
MC/DC100%2/2
$source eq "M" or $source eq "F"
$source eq "M"
$source eq "F"
Truth table100%3/3
A or B
A= $source eq "M"B= $source eq "F"
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 631 | 160 | return $URLS{$source} . $page; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 632 | } elsif($source eq 'L') { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 633 | # 'L' (local/link) records embed the full URL in newspaper or page | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 634 | return $obit->{'newspaper'} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 635 | 23 | ▶ | if defined($obit->{'newspaper'}) && $obit->{'newspaper'} =~ m{\Ahttps?://}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $$obit{"newspaper"} and $$obit{"newspaper"} =~ m[\Ahttps?://]
MC/DC100%2/2
defined $$obit{"newspaper"} and $$obit{"newspaper"} =~ m[\Ahttps?://]
defined $$obit{"newspaper"}
$$obit{"newspaper"} =~ m[\Ahttps?://]
Truth table100%3/3
A and B
A= defined $$obit{"newspaper"}B= $$obit{"newspaper"} =~ m[\Ahttps?://]
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 636 | 14 | ▶ | return $page | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 637 | if $page =~ m{\Ahttps?://}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 638 | 6 | Carp::croak(__PACKAGE__->_i18n('err_no_newspaper', {package => __PACKAGE__})); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 639 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 640 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 641 | 11 | Carp::croak(__PACKAGE__->_i18n('err_bad_source', | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 642 | {package => __PACKAGE__, source => $source})); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 643 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 644 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 645 | # Purpose: Looks up a user-facing message template and interpolates named | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 646 | # placeholders of the form %{key} using the supplied args hashref. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 647 | # Entry: $self_or_class — object or class name (not used yet; reserved for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 648 | # per-instance locale configuration). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 649 | # $key — key into %MESSAGES. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 650 | # $args — optional hashref of placeholder values. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 651 | # Exit: Formatted string. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 652 | sub _i18n | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 653 | 170 | ▶ | { | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_i18n: called CC=5 SCAR=16.1
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 654 | # TODO: CLAUDE.md violation — _i18n() is missing the required caller() privacy | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 655 | # guard. Adding it breaks t/function.t, t/path.t, t/edge_cases.t, and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 656 | # t/data-flow.t, which call _i18n() directly. Those tests must be refactored | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 657 | # to call through the public API before the guard can be re-introduced. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 658 | # TODO: Data Flow Anomaly - $self_or_class defined (D) but never used (D~ dead store; reserved for future per-instance locale selection) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 659 | 170 | my ($self_or_class, $key, $args) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 660 | 170 | ▶ | my $tpl = $MESSAGES{$key} | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$MESSAGES{$key} // Carp::croak("Unknown i18n key '${key}'")
MC/DC100%1/1
$MESSAGES{$key} // Carp::croak("Unknown i18n key '${key}'")
$MESSAGES{$key}
Truth table100%2/2
A
A= $MESSAGES{$key}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 661 | // Carp::croak("Unknown i18n key '$key'"); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 662 | 167 | ▶ | $args //= {}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$args //= {}
MC/DC100%1/1
$args //= {}
$args
Truth table100%2/2
A
A= $args
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 663 | # Pre-populate replacement table from template keys so the substitution | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 664 | # needs no /e modifier — eliminates any eval of replacement text entirely. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 665 | 167 | my %sub_vals; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 666 | 167 | ▶ | $sub_vals{$1} = $args->{$1} // '' while $tpl =~ m/%\{(\w+)\}/g; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%2/2
$$args{$1} // ""
MC/DC100%1/1
$$args{$1} // ""
$$args{$1}
Truth table100%2/2
A
A= $$args{$1}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 667 | 167 | (my $msg = $tpl) =~ s/%\{(\w+)\}/$sub_vals{$1}/g; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 668 | 167 | return $msg; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 669 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 670 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 671 | =head1 COMMON PITFALLS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 672 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 673 | =head2 Apostrophes are rejected in last names | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 674 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 675 | The C<last> field is validated against C<qr/\A[\w-]+\z/>. This allows letters, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 676 | digits, underscores, and hyphens, but B<not> apostrophes. A search for | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 677 | C<< last => "O'Brien" >> will croak at validation time. Use the closest | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 678 | hyphenated or unhyphenated spelling: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 679 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 680 | $obits->search(last => 'OBrien'); # OK | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 681 | $obits->search(last => "O'Brien"); # CROAKS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 682 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 683 | =head2 new() returns undef on a bad directory; it does not croak | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 684 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 685 | When C<directory> is supplied but does not exist or is not readable, C<new()> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 686 | calls C<Carp::carp> (a warning, not a fatal error) and returns C<undef>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 687 | Always check the return value before calling C<search()>: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 688 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 689 | my $obits = Genealogy::Obituary::Lookup->new(directory => $path) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 690 | or die "Could not open obituary database at $path"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 691 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 692 | =head2 Scalar vs list context returns different things | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 693 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 694 | C<search()> is context-sensitive. In list context it returns every matching | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 695 | record. In scalar context it returns only the first match. Assigning to a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 696 | plain variable is scalar context; assigning to an array is list context: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 697 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 698 | my @all = $obits->search(last => 'Smith'); # all records (list context) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 699 | my $first = $obits->search(last => 'Smith'); # one record (scalar context) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 700 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 701 | =head2 Clone semantics: the database handle is shared | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 702 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 703 | Calling C<< $obj->new(...) >> creates a I<shallow copy> of the parent. If the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 704 | parent has already run a search (and therefore opened its C<obituaries> handle), | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 705 | the clone starts out sharing that same handle object. The clone replaces the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 706 | handle on its first search call, but until then both objects reference the same | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 707 | underlying driver. This is intentional and efficient; be aware of it if you | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 708 | pass handles between threads or processes. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 709 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 710 | =head2 Search results are interned and become read-only | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 711 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 712 | After C<search()> returns, all string values inside the result hashrefs are | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 713 | interned by C<Data::Reuse::fixate>. Any attempt to modify them in place will | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 714 | die with C<"Modification of a read-only value">: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 715 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 716 | my @hits = $obits->search(last => 'Smith'); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 717 | $hits[0]->{last} = 'Jones'; # DIES -- read-only after search() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 718 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 719 | Copy the hashref or the field before modifying it: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 720 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 721 | my %copy = %{ $hits[0] }; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 722 | $copy{last} = 'Jones'; # OK | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 723 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 724 | =head2 Logger must implement info(), warn(), and error() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 725 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 726 | C<new()> validates the logger before storing it. The object must be blessed and | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 727 | must implement B<all three> of C<info()>, C<warn()>, and C<error()>. An object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 728 | missing any one of them will cause C<new()> to croak immediately: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 729 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 730 | # CROAKS: object provides info() and error() but not warn() | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 731 | my $obits = Genealogy::Obituary::Lookup->new(logger => $partial_logger); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 732 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 733 | C<warn()> is required because C<new()> uses it (not C<error()>) to report | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 734 | non-fatal events such as a missing or unreadable directory. Using C<error()> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 735 | for those events would cause loggers whose C<error()> calls C<die> (such as | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 736 | L<Log::Abstraction>) to convert a graceful C<carp + return undef> into a fatal | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 737 | exception, breaking the documented API contract. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 738 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 739 | =head2 Non-ASCII characters in last depend on runtime locale | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 740 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 741 | The C<[\w\-]+> regex matches C<\w>, which includes non-ASCII word characters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 742 | (accented letters, umlauts) when the string has the UTF-8 flag and the calling | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 743 | code uses C<use utf8>. Without that, the same input is rejected. The module | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 744 | does not set any locale; test explicitly if your data contains diacritics. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 745 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 746 | =head1 SECURITY NOTES | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 747 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 748 | =head2 Null bytes in directory paths are rejected early | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 749 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 750 | A C<directory> string containing a null byte (C<\0>) would cause Perl's | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 751 | C<stat()> to throw a fatal C<"Embedded nulls are forbidden"> exception. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 752 | C<new()> detects this before the filesystem call, calls the logger's C<warn()> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 753 | method if a logger is present, and carps gracefully instead of dying. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 754 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 755 | =head2 Taint-mode readiness | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 756 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 757 | The C<directory> argument is passed through a C<m/\A([^\0]*)\z/> capture before | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 758 | any filesystem operator sees it. This untaints the value for callers running | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 759 | under Perl's taint mode (C<perl -T>) without requiring any extra configuration. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 760 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 761 | =head2 URL construction uses percent-encoding | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 762 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 763 | The database builder (C<bin/create_db.PL>) encodes user-controlled components | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 764 | via C<URI::Escape::uri_escape> before embedding them in HTTP URLs. This | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 765 | prevents surname values from being misinterpreted as URL structure. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 766 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 767 | =head2 Path traversal is prevented in the database builder | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 768 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 769 | Environment variables C<MLARCHIVEDIR> and C<MLARCHIVE_DIR> are canonicalized | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 770 | with C<File::Spec-E<gt>canonpath()> and then checked to confirm the resolved | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 771 | path starts with the declared base directory. Any path that escapes the base | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 772 | via C<../> components is rejected with C<croak>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 773 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 774 | =head2 i18n substitution uses no eval | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 775 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 776 | The C<_i18n()> helper pre-builds a substitution table from template | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 777 | placeholders and then applies a plain C<s///g> replacement. No C</e> modifier | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 778 | or string C<eval> is used, so template values cannot execute arbitrary code. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 779 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 780 | =head1 LIMITATIONS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 781 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 782 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 783 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 784 | =item * B<Ancestry / Rootsweb archive loss.> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 785 | Only the first 18 pages of the mlarchives index are preserved on the Wayback | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 786 | Machine. Approximately 10,000+ records from later pages are unrecoverable. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 787 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 788 | =item * B<No full-text search.> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 789 | Searches are keyed on structured fields (last, first, middle, age). There is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 790 | no free-text obituary content to search. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 791 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 792 | =item * B<i18n is English-only.> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 793 | The C<%MESSAGES> map supports placeholder interpolation but is not backed by a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 794 | locale-selection mechanism. A future release should route through | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 795 | L<Locale::Maketext> or L<Locale::Simple>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 796 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 797 | =item * B<Data::Reuse fixate semantics.> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 798 | The string-interning via C<Data::Reuse::fixate> on hash-slice aliases is | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 799 | correct in theory (hash slices are lvalues) but depends on | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 800 | C<String::Intern::Internalize> modifying @_ in place. Verify with your | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 801 | installed version if memory consumption is a concern. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 802 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 803 | =item * B<Private method enforcement without Sub::Private.> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 804 | C<_create_url> and C<_i18n> enforce privacy via an inline C<caller> check. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 805 | Install L<Sub::Private> and replace the checks for a compile-time guarantee. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 806 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 807 | =item * B<Single-row scalar context.> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 808 | In scalar context, C<search()> returns the first row from the underlying | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 809 | driver. Row order depends on L<Database::Abstraction> and SQLite's query | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 810 | plan; add an explicit ORDER BY in the driver subclass if deterministic ordering | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 811 | is required. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 812 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 813 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 814 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 815 | =head1 AUTHOR | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 816 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 817 | Nigel Horne, C<< <njh at nigelhorne.com> >> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 818 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 819 | =head1 BUGS | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 820 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 821 | See L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Genealogy-Obituary-Lookup>. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 822 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 823 | =head1 SEE ALSO | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 824 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 825 | L<Database::Abstraction> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 826 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 827 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 828 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 829 | =item * The Obituary Daily Times: L<https://sites.rootsweb.com/~obituary/> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 830 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 831 | =item * Archived Rootsweb data: L<https://wayback.archive-it.org/20669/20231102044925/https://mlarchives.rootsweb.com/listindexes/emails?listname=gen-obit> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 832 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 833 | =item * Recent data: L<https://www.freelists.org/list/obitdailytimes> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 834 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 835 | =item * L<Configure an Object at Runtime|Object::Configure> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 836 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 837 | =item * L<Test Dashboard|https://nigelhorne.github.io/Genealogy-Obituary-Lookup/coverage/> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 838 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 839 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 840 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 841 | =head1 SUPPORT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 842 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 843 | This module is provided as-is without any warranty. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 844 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 845 | perldoc Genealogy::Obituary::Lookup | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 846 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 847 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 848 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 849 | =item * MetaCPAN: L<https://metacpan.org/release/Genealogy-Obituary-Lookup> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 850 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 851 | =item * RT: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Genealogy-Obituary-Lookup> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 852 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 853 | =item * CPAN Testers' Matrix: L<http://matrix.cpantesters.org/?dist=Genealogy-Obituary-Lookup> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 854 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 855 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 856 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 857 | =head1 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 858 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 859 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 860 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 861 | 𝒏𝒆𝒘 : Class × Args → (Object ∪ {⊥}) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 862 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 863 | 𝒏𝒆𝒘(C, A) ≙ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 864 | let D = A.directory ∨ dir_cache(C) { dir_cache memoises module_data_path(C) } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 865 | in A.logger ≠ ∅ ∧ ¬(can(A.logger,'info') ∧ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 866 | can(A.logger,'error')) ⟹ abort | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 867 | ∥ is_string(D) ∧ null_byte(D) ⟹ ⊥ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 868 | ∥ is_string(D) ⟹ D ← untaint(D) { guaranteed: no null bytes } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 869 | ∥ ¬readable(D) ⟹ ⊥ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 870 | ∥ otherwise ⟹ ⟨ cache_duration ↦ DEFAULT_CACHE_DURATION ⟩ ⊕ A | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 871 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 872 | where dir_cache(C) ≙ state map C ↦ module_data_path(C) { per-class, per-process } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 873 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 874 | =head2 search | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 875 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 876 | 𝒔𝒆𝒂𝒓𝒄𝒉 : Object × Params → ([Obit] ∪ Obit ∪ {undef}) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 877 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 878 | 𝒔𝒆𝒂𝒓𝒄𝒉(self, P) ≙ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 879 | pre blessed(self) ∧ P.last ≠ ∅ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 880 | post wantarray ⟹ { o : Obit | match(self.db, P) } |> map(add_url) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 881 | else ⟹ head({ o : Obit | match(self.db, P) } |> map(add_url)) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 882 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 883 | where add_url(o) ≙ o ⊕ ⟨ url ↦ _create_url(o) ⟩ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 884 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 885 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 886 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 887 | Copyright 2020-2026 Nigel Horne. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 888 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 889 | Usage is subject to the GPL2 licence terms. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 890 | If you use it, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 891 | please let me know. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 892 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 893 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 894 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 895 | 16 | 1; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||