| 1 | package Genealogy::Wills; | ||||||||||||||||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||||||||||||||||
| 3 | 13 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 4 | 13 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 5 | 13 | ▶ | use autodie qw(:all); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||||||||||||||||
| 7 | # Carp is intentionally NOT imported into this namespace. All calls must be | ||||||||||||||||||||||||||||||||||||||||||
| 8 | # fully-qualified (Carp::croak, Carp::carp) so that Test::Carp can intercept | ||||||||||||||||||||||||||||||||||||||||||
| 9 | # them at runtime. Bare imported aliases are compile-time copies and bypass | ||||||||||||||||||||||||||||||||||||||||||
| 10 | # the runtime override that Test::Carp installs. | ||||||||||||||||||||||||||||||||||||||||||
| 11 | 13 | ▶ | use Carp (); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 12 | 13 | ▶ | use Data::Reuse; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 13 | 13 | ▶ | use Readonly; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 14 | 13 | ▶ | use File::Spec; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 15 | 13 | ▶ | use Genealogy::Wills::wills; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 16 | 13 | ▶ | use Object::Configure 0.23; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 17 | 13 | ▶ | use Params::Get 0.16; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 18 | 13 | ▶ | use Params::Validate::Strict 0.37; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 19 | 13 | ▶ | use Return::Set 0.05; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 20 | 13 | ▶ | use Scalar::Util qw(blessed); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 21 | 13 | ▶ | use Sub::Protected 0.02; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||||||||||||||||
| 23 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||||||||||||||||
| 25 | Genealogy::Wills - Search a local database of historical wills | ||||||||||||||||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||||||||||||||||
| 27 | =head1 VERSION | ||||||||||||||||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||||||||||||||||
| 29 | Version 0.11 | ||||||||||||||||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||||||||||||||||
| 31 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 32 | |||||||||||||||||||||||||||||||||||||||||||
| 33 | 13 | our $VERSION = '0.11'; | |||||||||||||||||||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||||||||||||||||||||
| 35 | # Named constants remove all magic literals from the code body. | ||||||||||||||||||||||||||||||||||||||||||
| 36 | # Readonly enforces immutability at runtime; any attempted mutation dies. | ||||||||||||||||||||||||||||||||||||||||||
| 37 | 13 | Readonly my $DEFAULT_CACHE_DURATION => '1 day'; | |||||||||||||||||||||||||||||||||||||||||
| 38 | 13 | Readonly my $MIN_LAST_NAME_LENGTH => 1; | |||||||||||||||||||||||||||||||||||||||||
| 39 | 13 | Readonly my $MAX_LAST_NAME_LENGTH => 100; | |||||||||||||||||||||||||||||||||||||||||
| 40 | # Computed once at module load so the year boundary stays current without | ||||||||||||||||||||||||||||||||||||||||||
| 41 | # redeployment. See LIMITATIONS for the year-boundary edge case. | ||||||||||||||||||||||||||||||||||||||||||
| 42 | 13 | Readonly my $MAX_WILL_YEAR => (localtime)[5] + 1900; | |||||||||||||||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||||||||||||||||
| 44 | # __FILE__ is resolved by the compiler; this never changes at runtime. | ||||||||||||||||||||||||||||||||||||||||||
| 45 | # Replaces Module::Info->new_from_loaded(__PACKAGE__)->file() which scans | ||||||||||||||||||||||||||||||||||||||||||
| 46 | # %INC and allocates a Module::Info object on every new() call that omits | ||||||||||||||||||||||||||||||||||||||||||
| 47 | # 'directory'. Computing it here gives zero per-call overhead. | ||||||||||||||||||||||||||||||||||||||||||
| 48 | 13 | my $MODULE_DATA_DIR = do { | |||||||||||||||||||||||||||||||||||||||||
| 49 | 13 | (my $dir = __FILE__) =~ s/\.pm\z//; | |||||||||||||||||||||||||||||||||||||||||
| 50 | 13 | File::Spec->catfile($dir, 'data'); | |||||||||||||||||||||||||||||||||||||||||
| 51 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 52 | |||||||||||||||||||||||||||||||||||||||||||
| 53 | # Shared templates for the three optional free-text fields (first, middle, town). | ||||||||||||||||||||||||||||||||||||||||||
| 54 | # Extracted to eliminate three copies of { type => 'string', optional => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 55 | # min => 1, max => 100 } and two copies of the name character-class regex. | ||||||||||||||||||||||||||||||||||||||||||
| 56 | 13 | my %_FIELD_BASE = (type => 'string', optional => 1, min => 1, max => 100); | |||||||||||||||||||||||||||||||||||||||||
| 57 | 13 | my $_OPT_NAME_RE = qr/^[\w '.-]+\z/; # word chars, space, apostrophe (O'Brien), period, hyphen | |||||||||||||||||||||||||||||||||||||||||
| 58 | 13 | my $_OPT_TOWN_RE = qr/^[\w ',.-]+\z/; # same + comma for "Town, County, Country" format | |||||||||||||||||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||||||||||||||||
| 60 | # The PVS schema is static. Allocating it once here avoids creating | ||||||||||||||||||||||||||||||||||||||||||
| 61 | # 6 anonymous hashrefs (the outer schema + 5 field specs) on every search() | ||||||||||||||||||||||||||||||||||||||||||
| 62 | # call. At 1000 searches/sec that eliminates 6000 transient allocations/sec. | ||||||||||||||||||||||||||||||||||||||||||
| 63 | 13 | my $SEARCH_SCHEMA = { | |||||||||||||||||||||||||||||||||||||||||
| 64 | 'last' => { | ||||||||||||||||||||||||||||||||||||||||||
| 65 | type => 'string', | ||||||||||||||||||||||||||||||||||||||||||
| 66 | min => $MIN_LAST_NAME_LENGTH, | ||||||||||||||||||||||||||||||||||||||||||
| 67 | max => $MAX_LAST_NAME_LENGTH, | ||||||||||||||||||||||||||||||||||||||||||
| 68 | # \z = strict end-of-string (not before \n); [-] at end = unambiguous literal | ||||||||||||||||||||||||||||||||||||||||||
| 69 | # hyphen without escaping; /a = restrict \w to ASCII [0-9A-Za-z_], blocking | ||||||||||||||||||||||||||||||||||||||||||
| 70 | # Unicode homograph queries (Cyrillic "Smith" silently returning zero results). | ||||||||||||||||||||||||||||||||||||||||||
| 71 | matches => qr/^[\w-]+\z/a | ||||||||||||||||||||||||||||||||||||||||||
| 72 | }, | ||||||||||||||||||||||||||||||||||||||||||
| 73 | # Defence-in-depth: matches constraints reject injection metacharacters before | ||||||||||||||||||||||||||||||||||||||||||
| 74 | # reaching the DB layer. Primary defence is parameterised queries (Database::Abstraction). | ||||||||||||||||||||||||||||||||||||||||||
| 75 | # Allows: word chars (Unicode \w), space, apostrophe (O'Brien), period (St. John), hyphen. | ||||||||||||||||||||||||||||||||||||||||||
| 76 | # Blocks: ; = | & < > \r \n \0 ` and other shell/SQL injection metacharacters. | ||||||||||||||||||||||||||||||||||||||||||
| 77 | 'first' => { %_FIELD_BASE, matches => $_OPT_NAME_RE }, | ||||||||||||||||||||||||||||||||||||||||||
| 78 | 'middle' => { %_FIELD_BASE, matches => $_OPT_NAME_RE }, | ||||||||||||||||||||||||||||||||||||||||||
| 79 | 'town' => { %_FIELD_BASE, matches => $_OPT_TOWN_RE }, # adds comma for "Town, County" | ||||||||||||||||||||||||||||||||||||||||||
| 80 | 'year' => { | ||||||||||||||||||||||||||||||||||||||||||
| 81 | type => 'integer', | ||||||||||||||||||||||||||||||||||||||||||
| 82 | optional => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 83 | min => 1, | ||||||||||||||||||||||||||||||||||||||||||
| 84 | max => $MAX_WILL_YEAR | ||||||||||||||||||||||||||||||||||||||||||
| 85 | }, | ||||||||||||||||||||||||||||||||||||||||||
| 86 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||||||||||||||||||
| 88 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||||||||
| 89 | |||||||||||||||||||||||||||||||||||||||||||
| 90 | A "will" (short for "last will and testament") is a legal document in which a | ||||||||||||||||||||||||||||||||||||||||||
| 91 | person states who should receive their money and property after they die. Courts | ||||||||||||||||||||||||||||||||||||||||||
| 92 | record when a will is officially accepted (called "probate"). This module gives | ||||||||||||||||||||||||||||||||||||||||||
| 93 | you a simple way to search those records. | ||||||||||||||||||||||||||||||||||||||||||
| 94 | |||||||||||||||||||||||||||||||||||||||||||
| 95 | The data comes from the B<Kent Wills Transcript>, a free online collection of | ||||||||||||||||||||||||||||||||||||||||||
| 96 | wills proved in Kent, covering roughly the 1500s through the 1900s. | ||||||||||||||||||||||||||||||||||||||||||
| 97 | That data is stored in a local SQLite file (C<wills.sql>), so B<no internet | ||||||||||||||||||||||||||||||||||||||||||
| 98 | connection is needed> when you run a search. The database is built once by | ||||||||||||||||||||||||||||||||||||||||||
| 99 | running C<perl bin/create_db.PL>. | ||||||||||||||||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||||||||||||||||
| 101 | Each record in the database describes one will and contains: | ||||||||||||||||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||||||||||||||||
| 103 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||||||||||||||||||||
| 105 | =item * The person's first name, optional middle name, and last name (surname). | ||||||||||||||||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||||||||||||||||
| 107 | =item * The town where the person lived or died. | ||||||||||||||||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||||||||||||||||
| 109 | =item * The year the will was proved (officially accepted by the court). | ||||||||||||||||||||||||||||||||||||||||||
| 110 | |||||||||||||||||||||||||||||||||||||||||||
| 111 | =item * A URL linking to the original entry on the Kent Wills Transcript website. | ||||||||||||||||||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||||||||||||||||
| 113 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||||||||||||||||
| 115 | Using the module is a two-step process: create one C<Genealogy::Wills> object | ||||||||||||||||||||||||||||||||||||||||||
| 116 | with C<new()>, then call C<search()> as many times as you like. | ||||||||||||||||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||||||||||||||||
| 118 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||||||||||||||||
| 120 | use Genealogy::Wills; | ||||||||||||||||||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||||||||||||||||
| 122 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 123 | # Example 1: Find all records for a given last name. | ||||||||||||||||||||||||||||||||||||||||||
| 124 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 125 | my $wills = Genealogy::Wills->new(); | ||||||||||||||||||||||||||||||||||||||||||
| 126 | die "Could not load wills database" unless defined $wills; | ||||||||||||||||||||||||||||||||||||||||||
| 127 | |||||||||||||||||||||||||||||||||||||||||||
| 128 | my @smiths = $wills->search(last => 'Smith'); | ||||||||||||||||||||||||||||||||||||||||||
| 129 | for my $r (@smiths) { | ||||||||||||||||||||||||||||||||||||||||||
| 130 | printf "%s %s, %s (%d)\n %s\n\n", | ||||||||||||||||||||||||||||||||||||||||||
| 131 | $r->{first}, $r->{last}, | ||||||||||||||||||||||||||||||||||||||||||
| 132 | $r->{town}, $r->{year}, | ||||||||||||||||||||||||||||||||||||||||||
| 133 | $r->{url}; | ||||||||||||||||||||||||||||||||||||||||||
| 134 | } | ||||||||||||||||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||||||||||||||||
| 136 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 137 | # Example 2: Short form -- pass just the last name as a plain string. | ||||||||||||||||||||||||||||||||||||||||||
| 138 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 139 | my @joneses = $wills->search('Jones'); | ||||||||||||||||||||||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||||||||||||||||||||
| 141 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 142 | # Example 3: Narrow by first name, town, and year. | ||||||||||||||||||||||||||||||||||||||||||
| 143 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 144 | my @johns = $wills->search( | ||||||||||||||||||||||||||||||||||||||||||
| 145 | first => 'John', | ||||||||||||||||||||||||||||||||||||||||||
| 146 | last => 'Smith', | ||||||||||||||||||||||||||||||||||||||||||
| 147 | town => 'Canterbury, Kent, England', | ||||||||||||||||||||||||||||||||||||||||||
| 148 | year => 1750, | ||||||||||||||||||||||||||||||||||||||||||
| 149 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 150 | |||||||||||||||||||||||||||||||||||||||||||
| 151 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 152 | # Example 4: Scalar context -- get only the first matching record. | ||||||||||||||||||||||||||||||||||||||||||
| 153 | # Use this when you want one result, not a list. | ||||||||||||||||||||||||||||||||||||||||||
| 154 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 155 | my $will = $wills->search(last => 'Carlton'); | ||||||||||||||||||||||||||||||||||||||||||
| 156 | if (defined $will) { | ||||||||||||||||||||||||||||||||||||||||||
| 157 | print "First match: $will->{first} $will->{last} ($will->{year})\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 158 | print "See: $will->{url}\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 159 | } else { | ||||||||||||||||||||||||||||||||||||||||||
| 160 | print "No record found.\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 161 | } | ||||||||||||||||||||||||||||||||||||||||||
| 162 | |||||||||||||||||||||||||||||||||||||||||||
| 163 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 164 | # Example 5: Check whether anything was found. | ||||||||||||||||||||||||||||||||||||||||||
| 165 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 166 | my @results = $wills->search(last => 'Xyz'); | ||||||||||||||||||||||||||||||||||||||||||
| 167 | if (@results) { | ||||||||||||||||||||||||||||||||||||||||||
| 168 | print scalar(@results), " records found.\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 169 | } else { | ||||||||||||||||||||||||||||||||||||||||||
| 170 | print "No records found.\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 171 | } | ||||||||||||||||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||||||||||||||||
| 173 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 174 | # Example 6: Point at a different database directory. | ||||||||||||||||||||||||||||||||||||||||||
| 175 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 176 | my $wills2 = Genealogy::Wills->new(directory => '/var/data/wills'); | ||||||||||||||||||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||||||||||||||||
| 178 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 179 | # Example 7: Load settings from a config file. | ||||||||||||||||||||||||||||||||||||||||||
| 180 | # The YAML key must use double underscores: Genealogy__Wills | ||||||||||||||||||||||||||||||||||||||||||
| 181 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 182 | # Contents of /etc/wills.yml: | ||||||||||||||||||||||||||||||||||||||||||
| 183 | # Genealogy__Wills: | ||||||||||||||||||||||||||||||||||||||||||
| 184 | # directory: /var/data/wills | ||||||||||||||||||||||||||||||||||||||||||
| 185 | my $wills3 = Genealogy::Wills->new(config_file => '/etc/wills.yml'); | ||||||||||||||||||||||||||||||||||||||||||
| 186 | |||||||||||||||||||||||||||||||||||||||||||
| 187 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 188 | # Example 8: Clone an existing object, changing one setting. | ||||||||||||||||||||||||||||||||||||||||||
| 189 | # ------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||||||||||
| 190 | my $wills4 = $wills->new(cache_duration => '12 hours'); | ||||||||||||||||||||||||||||||||||||||||||
| 191 | |||||||||||||||||||||||||||||||||||||||||||
| 192 | =head1 SUBROUTINES/METHODS | ||||||||||||||||||||||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||||||||||||||||||||
| 194 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||||||||||||||||
| 196 | Creates and returns a C<Genealogy::Wills> object. | ||||||||||||||||||||||||||||||||||||||||||
| 197 | |||||||||||||||||||||||||||||||||||||||||||
| 198 | No arguments are required. All arguments are optional and may be passed in any | ||||||||||||||||||||||||||||||||||||||||||
| 199 | of these forms: | ||||||||||||||||||||||||||||||||||||||||||
| 200 | |||||||||||||||||||||||||||||||||||||||||||
| 201 | Genealogy::Wills->new() # no arguments | ||||||||||||||||||||||||||||||||||||||||||
| 202 | Genealogy::Wills->new(key => value, ...) # flat key-value list | ||||||||||||||||||||||||||||||||||||||||||
| 203 | Genealogy::Wills->new({ key => value, ... }) # hash reference | ||||||||||||||||||||||||||||||||||||||||||
| 204 | Genealogy::Wills->new('/path/to/data') # single string = directory | ||||||||||||||||||||||||||||||||||||||||||
| 205 | |||||||||||||||||||||||||||||||||||||||||||
| 206 | B<Returns> the new object on success, or C<undef> on failure (for example, | ||||||||||||||||||||||||||||||||||||||||||
| 207 | if the database directory does not exist). A warning is printed to explain | ||||||||||||||||||||||||||||||||||||||||||
| 208 | what went wrong. | ||||||||||||||||||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||||||||||||||||
| 210 | B<Always check the return value> before calling C<search()>. If C<new()> | ||||||||||||||||||||||||||||||||||||||||||
| 211 | returns C<undef> and you ignore it, a call to C<search()> will crash your | ||||||||||||||||||||||||||||||||||||||||||
| 212 | program later with a confusing error. | ||||||||||||||||||||||||||||||||||||||||||
| 213 | |||||||||||||||||||||||||||||||||||||||||||
| 214 | my $wills = Genealogy::Wills->new(); | ||||||||||||||||||||||||||||||||||||||||||
| 215 | die "Could not load database" unless defined $wills; | ||||||||||||||||||||||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||||||||||||||||||||
| 217 | =head3 ARGUMENTS | ||||||||||||||||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||||||||||||||||
| 219 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||||||||||||||||
| 221 | =item * C<directory> (optional, string) | ||||||||||||||||||||||||||||||||||||||||||
| 222 | |||||||||||||||||||||||||||||||||||||||||||
| 223 | The path to the directory that contains the C<wills.sql> file. | ||||||||||||||||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||||||||||||||||
| 225 | If you do not provide this, the module uses its own built-in data directory, | ||||||||||||||||||||||||||||||||||||||||||
| 226 | which is set up when you run C<perl bin/create_db.PL>. | ||||||||||||||||||||||||||||||||||||||||||
| 227 | |||||||||||||||||||||||||||||||||||||||||||
| 228 | You can also pass a single bare string as a shortcut: | ||||||||||||||||||||||||||||||||||||||||||
| 229 | |||||||||||||||||||||||||||||||||||||||||||
| 230 | Genealogy::Wills->new('/path/to/data') | ||||||||||||||||||||||||||||||||||||||||||
| 231 | # is the same as | ||||||||||||||||||||||||||||||||||||||||||
| 232 | Genealogy::Wills->new(directory => '/path/to/data') | ||||||||||||||||||||||||||||||||||||||||||
| 233 | |||||||||||||||||||||||||||||||||||||||||||
| 234 | =item * C<config_file> (optional, string) | ||||||||||||||||||||||||||||||||||||||||||
| 235 | |||||||||||||||||||||||||||||||||||||||||||
| 236 | Path to a configuration file in C<YAML>, C<XML>, C<INI>, or another format | ||||||||||||||||||||||||||||||||||||||||||
| 237 | supported by L<Object::Configure>. | ||||||||||||||||||||||||||||||||||||||||||
| 238 | |||||||||||||||||||||||||||||||||||||||||||
| 239 | The file must have a top-level section named C<Genealogy__Wills> (the class | ||||||||||||||||||||||||||||||||||||||||||
| 240 | name with C<::> replaced by C<__>). For example: | ||||||||||||||||||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||||||||||||||||||
| 242 | # /etc/wills.yml | ||||||||||||||||||||||||||||||||||||||||||
| 243 | Genealogy__Wills: | ||||||||||||||||||||||||||||||||||||||||||
| 244 | directory: /var/data/wills | ||||||||||||||||||||||||||||||||||||||||||
| 245 | |||||||||||||||||||||||||||||||||||||||||||
| 246 | Environment variables of the form C<Genealogy__Wills__key> override values | ||||||||||||||||||||||||||||||||||||||||||
| 247 | read from the file. For example, setting | ||||||||||||||||||||||||||||||||||||||||||
| 248 | C<Genealogy__Wills__directory=/tmp/wills> in the shell overrides the | ||||||||||||||||||||||||||||||||||||||||||
| 249 | C<directory> from the file. | ||||||||||||||||||||||||||||||||||||||||||
| 250 | |||||||||||||||||||||||||||||||||||||||||||
| 251 | B<Croaks> (the program stops with an error message) if you provide a | ||||||||||||||||||||||||||||||||||||||||||
| 252 | C<config_file> path that does not exist or cannot be read. | ||||||||||||||||||||||||||||||||||||||||||
| 253 | |||||||||||||||||||||||||||||||||||||||||||
| 254 | =item * C<logger> (optional, object) | ||||||||||||||||||||||||||||||||||||||||||
| 255 | |||||||||||||||||||||||||||||||||||||||||||
| 256 | An object used to write diagnostic messages. It must have both an C<info()> | ||||||||||||||||||||||||||||||||||||||||||
| 257 | method and an C<error()> method. Any L<Log::Log4perl> logger, or any object | ||||||||||||||||||||||||||||||||||||||||||
| 258 | that implements those two methods, works. | ||||||||||||||||||||||||||||||||||||||||||
| 259 | |||||||||||||||||||||||||||||||||||||||||||
| 260 | B<Croaks> if an object is provided but is missing the required methods. | ||||||||||||||||||||||||||||||||||||||||||
| 261 | |||||||||||||||||||||||||||||||||||||||||||
| 262 | =item * C<cache_duration> (optional, string) | ||||||||||||||||||||||||||||||||||||||||||
| 263 | |||||||||||||||||||||||||||||||||||||||||||
| 264 | How long the underlying C<Database::Abstraction> layer caches query results. | ||||||||||||||||||||||||||||||||||||||||||
| 265 | Default is C<'1 day'>. Accepts strings like C<'12 hours'>, C<'2 days'>. | ||||||||||||||||||||||||||||||||||||||||||
| 266 | |||||||||||||||||||||||||||||||||||||||||||
| 267 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 268 | |||||||||||||||||||||||||||||||||||||||||||
| 269 | =head3 RETURNS | ||||||||||||||||||||||||||||||||||||||||||
| 270 | |||||||||||||||||||||||||||||||||||||||||||
| 271 | On success: a C<Genealogy::Wills> object. | ||||||||||||||||||||||||||||||||||||||||||
| 272 | |||||||||||||||||||||||||||||||||||||||||||
| 273 | On failure: C<undef>, with a warning printed to STDERR naming the problem. | ||||||||||||||||||||||||||||||||||||||||||
| 274 | |||||||||||||||||||||||||||||||||||||||||||
| 275 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||
| 276 | |||||||||||||||||||||||||||||||||||||||||||
| 277 | # Minimal -- uses the bundled database | ||||||||||||||||||||||||||||||||||||||||||
| 278 | my $w = Genealogy::Wills->new(); | ||||||||||||||||||||||||||||||||||||||||||
| 279 | die "Failed to load database" unless defined $w; | ||||||||||||||||||||||||||||||||||||||||||
| 280 | |||||||||||||||||||||||||||||||||||||||||||
| 281 | # Explicit directory path | ||||||||||||||||||||||||||||||||||||||||||
| 282 | my $w = Genealogy::Wills->new(directory => '/data/kent-wills'); | ||||||||||||||||||||||||||||||||||||||||||
| 283 | |||||||||||||||||||||||||||||||||||||||||||
| 284 | # Hash-reference form (same result) | ||||||||||||||||||||||||||||||||||||||||||
| 285 | my $w = Genealogy::Wills->new({ directory => '/data/kent-wills' }); | ||||||||||||||||||||||||||||||||||||||||||
| 286 | |||||||||||||||||||||||||||||||||||||||||||
| 287 | # Single-string shortcut (treated as the directory path) | ||||||||||||||||||||||||||||||||||||||||||
| 288 | my $w = Genealogy::Wills->new('/data/kent-wills'); | ||||||||||||||||||||||||||||||||||||||||||
| 289 | |||||||||||||||||||||||||||||||||||||||||||
| 290 | # From a YAML config file | ||||||||||||||||||||||||||||||||||||||||||
| 291 | my $w = Genealogy::Wills->new(config_file => '/etc/wills.yml'); | ||||||||||||||||||||||||||||||||||||||||||
| 292 | |||||||||||||||||||||||||||||||||||||||||||
| 293 | # Clone an existing object, changing the cache duration | ||||||||||||||||||||||||||||||||||||||||||
| 294 | my $w2 = $w->new(cache_duration => '12 hours'); | ||||||||||||||||||||||||||||||||||||||||||
| 295 | |||||||||||||||||||||||||||||||||||||||||||
| 296 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||
| 297 | |||||||||||||||||||||||||||||||||||||||||||
| 298 | =head4 input | ||||||||||||||||||||||||||||||||||||||||||
| 299 | |||||||||||||||||||||||||||||||||||||||||||
| 300 | C<new()> uses C<Params::Get> to normalize its arguments but does not apply | ||||||||||||||||||||||||||||||||||||||||||
| 301 | C<Params::Validate::Strict> validation. The recognized parameters are: | ||||||||||||||||||||||||||||||||||||||||||
| 302 | |||||||||||||||||||||||||||||||||||||||||||
| 303 | # Params::Get::get_params(undef, @_) -- normalizes to a hashref. | ||||||||||||||||||||||||||||||||||||||||||
| 304 | # Accepted as: flat list, hash reference, or a single string (= directory). | ||||||||||||||||||||||||||||||||||||||||||
| 305 | { | ||||||||||||||||||||||||||||||||||||||||||
| 306 | directory => { type => 'string' }, # readable directory path | ||||||||||||||||||||||||||||||||||||||||||
| 307 | config_file => { type => 'string' }, # readable path; croaks if missing | ||||||||||||||||||||||||||||||||||||||||||
| 308 | logger => { type => 'object', | ||||||||||||||||||||||||||||||||||||||||||
| 309 | can => [ 'info', 'error' ], | ||||||||||||||||||||||||||||||||||||||||||
| 310 | optional => 1 | ||||||||||||||||||||||||||||||||||||||||||
| 311 | }, | ||||||||||||||||||||||||||||||||||||||||||
| 312 | cache_duration => { type => 'string', | ||||||||||||||||||||||||||||||||||||||||||
| 313 | default => '1 day', | ||||||||||||||||||||||||||||||||||||||||||
| 314 | optional => 1 | ||||||||||||||||||||||||||||||||||||||||||
| 315 | }, | ||||||||||||||||||||||||||||||||||||||||||
| 316 | } | ||||||||||||||||||||||||||||||||||||||||||
| 317 | |||||||||||||||||||||||||||||||||||||||||||
| 318 | =head4 output | ||||||||||||||||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||||||||||||||||
| 320 | # Return::Set is not used by new(). | ||||||||||||||||||||||||||||||||||||||||||
| 321 | { | ||||||||||||||||||||||||||||||||||||||||||
| 322 | type => 'hashref', | ||||||||||||||||||||||||||||||||||||||||||
| 323 | optional => 1 | ||||||||||||||||||||||||||||||||||||||||||
| 324 | } | ||||||||||||||||||||||||||||||||||||||||||
| 325 | |||||||||||||||||||||||||||||||||||||||||||
| 326 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||
| 327 | |||||||||||||||||||||||||||||||||||||||||||
| 328 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 329 | |||||||||||||||||||||||||||||||||||||||||||
| 330 | =item B<Can't load configuration from E<lt>pathE<gt>> | ||||||||||||||||||||||||||||||||||||||||||
| 331 | |||||||||||||||||||||||||||||||||||||||||||
| 332 | Fatal. The C<config_file> path was given but the file is missing or | ||||||||||||||||||||||||||||||||||||||||||
| 333 | unreadable. Check the path and file permissions. | ||||||||||||||||||||||||||||||||||||||||||
| 334 | |||||||||||||||||||||||||||||||||||||||||||
| 335 | =item B<Logger must be an object with info() and error() methods> | ||||||||||||||||||||||||||||||||||||||||||
| 336 | |||||||||||||||||||||||||||||||||||||||||||
| 337 | Fatal. The C<logger> argument is not an object, or is missing C<info()> | ||||||||||||||||||||||||||||||||||||||||||
| 338 | or C<error()>. Pass a compatible logger such as L<Log::Log4perl>. | ||||||||||||||||||||||||||||||||||||||||||
| 339 | |||||||||||||||||||||||||||||||||||||||||||
| 340 | =item B<Genealogy::Wills: E<lt>dirE<gt> is not a directory> | ||||||||||||||||||||||||||||||||||||||||||
| 341 | |||||||||||||||||||||||||||||||||||||||||||
| 342 | Warning (not fatal). The resolved directory does not exist or cannot be read. | ||||||||||||||||||||||||||||||||||||||||||
| 343 | C<new()> returns C<undef>. Verify the path; if using the bundled database run | ||||||||||||||||||||||||||||||||||||||||||
| 344 | C<perl bin/create_db.PL>. | ||||||||||||||||||||||||||||||||||||||||||
| 345 | |||||||||||||||||||||||||||||||||||||||||||
| 346 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 347 | |||||||||||||||||||||||||||||||||||||||||||
| 348 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 349 | |||||||||||||||||||||||||||||||||||||||||||
| 350 | 135 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=15 SCAR=27.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 351 | 135 | my $class = shift; | |||||||||||||||||||||||||||||||||||||||||
| 352 | 135 | my $params; | |||||||||||||||||||||||||||||||||||||||||
| 353 | |||||||||||||||||||||||||||||||||||||||||||
| 354 | 135 | ▶ | if((scalar(@_) == 1) && !ref($_[0])) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
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]
| |||||||||||||||||||||||||||||||||||||||||||
| 355 | 4 | $params->{'directory'} = $_[0]; | |||||||||||||||||||||||||||||||||||||||||
| 356 | } else { | ||||||||||||||||||||||||||||||||||||||||||
| 357 | 131 | $params = Params::Get::get_params(undef, \@_); | |||||||||||||||||||||||||||||||||||||||||
| 358 | } | ||||||||||||||||||||||||||||||||||||||||||
| 359 | |||||||||||||||||||||||||||||||||||||||||||
| 360 | # Premise: $class is one of three mutually exclusive types: | ||||||||||||||||||||||||||||||||||||||||||
| 361 | # (a) undef -- ::new() function form; any arg would have become $class | ||||||||||||||||||||||||||||||||||||||||||
| 362 | # (b) blessed -- called on an existing object (clone request) | ||||||||||||||||||||||||||||||||||||||||||
| 363 | # (c) string -- called as Genealogy::Wills->new() class method | ||||||||||||||||||||||||||||||||||||||||||
| 364 | 135 | ▶ | if(!defined($class)) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||||||||||||
| 365 | # (a) ::new() with no args. Params::Get returns {} for empty input, | ||||||||||||||||||||||||||||||||||||||||||
| 366 | # so no inner check is needed -- the carp branch was unreachable. | ||||||||||||||||||||||||||||||||||||||||||
| 367 | # Conclusion: default the class to this package and proceed normally. | ||||||||||||||||||||||||||||||||||||||||||
| 368 | 2 | $class = __PACKAGE__; | |||||||||||||||||||||||||||||||||||||||||
| 369 | } elsif(blessed($class)) { | ||||||||||||||||||||||||||||||||||||||||||
| 370 | # (b) Clone the object. Merge caller overrides on top of the original; | ||||||||||||||||||||||||||||||||||||||||||
| 371 | # // {} handles the no-args case where Params::Get returns undef. | ||||||||||||||||||||||||||||||||||||||||||
| 372 | 8 | ▶ | return bless { %{$class}, %{$params // {}} }, ref($class); | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$params // {}
MC/DC100%1/1
$params // {}
$params
Truth table100%2/2
A
A= $params
| |||||||||||||||||||||||||||||||||||||||||||
| 373 | } | ||||||||||||||||||||||||||||||||||||||||||
| 374 | # Post-condition: $class is now a valid package name string. | ||||||||||||||||||||||||||||||||||||||||||
| 375 | |||||||||||||||||||||||||||||||||||||||||||
| 376 | 127 | ▶ | if(defined($params->{'config_file'}) && !-r $params->{'config_file'}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $$params{"config_file"} and not -r $$params{"config_file"}
MC/DC100%2/2
defined $$params{"config_file"} and not -r $$params{"config_file"}
defined $$params{"config_file"}
not -r $$params{"config_file"}
Truth table100%3/3
A and not(B)
A= defined $$params{"config_file"}B= not -r $$params{"config_file"}
| |||||||||||||||||||||||||||||||||||||||||||
| 377 | 9 | Carp::croak("Can't load configuration from " . $params->{'config_file'}); | |||||||||||||||||||||||||||||||||||||||||
| 378 | } | ||||||||||||||||||||||||||||||||||||||||||
| 379 | |||||||||||||||||||||||||||||||||||||||||||
| 380 | # Validate the caller-supplied logger BEFORE Object::Configure::configure() | ||||||||||||||||||||||||||||||||||||||||||
| 381 | # runs. configure() always replaces the logger with its own Log::Abstraction | ||||||||||||||||||||||||||||||||||||||||||
| 382 | # instance (see LIMITATIONS, "logger argument is silently discarded"), so any | ||||||||||||||||||||||||||||||||||||||||||
| 383 | # check performed AFTER configure() would be testing the replacement object, | ||||||||||||||||||||||||||||||||||||||||||
| 384 | # not the one the caller passed. Validating here ensures that a caller who | ||||||||||||||||||||||||||||||||||||||||||
| 385 | # passes an object lacking info()/error() gets an early, actionable croak. | ||||||||||||||||||||||||||||||||||||||||||
| 386 | 118 | ▶ | if(defined $params->{'logger'}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 387 | # Modus Tollens: if the logger cannot satisfy required capabilities, reject now. | ||||||||||||||||||||||||||||||||||||||||||
| 388 | 15 | my $l = $params->{'logger'}; | |||||||||||||||||||||||||||||||||||||||||
| 389 | 15 | ▶ | Carp::croak('Logger must be an object with info() and error() methods') | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%6/6
builtin::blessed($l) and $l->can("info") and $l->can("error")
builtin::blessed($l) and $l->can("info")
MC/DC100%3/3
builtin::blessed($l) and $l->can("info") and $l->can("error")
builtin::blessed($l)
$l->can("info")
$l->can("error")
Truth table100%4/4
A and B and C
A= builtin::blessed($l)B= $l->can("info")C= $l->can("error")
| |||||||||||||||||||||||||||||||||||||||||||
| 390 | unless blessed($l) && $l->can('info') && $l->can('error'); | ||||||||||||||||||||||||||||||||||||||||||
| 391 | } | ||||||||||||||||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||||||||||||||||
| 393 | 107 | $params = Object::Configure::configure($class, $params); | |||||||||||||||||||||||||||||||||||||||||
| 394 | |||||||||||||||||||||||||||||||||||||||||||
| 395 | # use the compile-time constant; no %INC scan, no object allocation. | ||||||||||||||||||||||||||||||||||||||||||
| 396 | 107 | ▶ | $params->{'directory'} //= $MODULE_DATA_DIR; | ||||||||||||||||||||||||||||||||||||||||
|
Condition66%2/3
$$params{"directory"} //= $MODULE_DATA_DIR
MC/DC0%0/2
$$params{"directory"} //= $MODULE_DATA_DIR
$$params{"directory"}
$MODULE_DATA_DIR
Truth table66%2/3
A //= B
A= $$params{"directory"}B= $MODULE_DATA_DIR
| |||||||||||||||||||||||||||||||||||||||||||
| 397 | |||||||||||||||||||||||||||||||||||||||||||
| 398 | # -d fills the OS stat cache; -r _ reads it without a second syscall. | ||||||||||||||||||||||||||||||||||||||||||
| 399 | 107 | ▶ | unless(-d $params->{'directory'} && -r _) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
-d $$params{"directory"} and -r _
MC/DC100%2/2
-d $$params{"directory"} and -r _
-d $$params{"directory"}
-r _
Truth table100%3/3
A and B
A= -d $$params{"directory"}B= -r _
| |||||||||||||||||||||||||||||||||||||||||||
| 400 | 15 | Carp::carp(__PACKAGE__ . ': ' . $params->{'directory'} . ' is not a directory'); | |||||||||||||||||||||||||||||||||||||||||
| 401 | 15 | return; | |||||||||||||||||||||||||||||||||||||||||
| 402 | } | ||||||||||||||||||||||||||||||||||||||||||
| 403 | |||||||||||||||||||||||||||||||||||||||||||
| 404 | # cache_duration defaults to the module constant; callers may override it. | ||||||||||||||||||||||||||||||||||||||||||
| 405 | return bless { | ||||||||||||||||||||||||||||||||||||||||||
| 406 | cache_duration => $DEFAULT_CACHE_DURATION, | ||||||||||||||||||||||||||||||||||||||||||
| 407 | 92 | %{$params} | |||||||||||||||||||||||||||||||||||||||||
| 408 | }, $class; | ||||||||||||||||||||||||||||||||||||||||||
| 409 | } | ||||||||||||||||||||||||||||||||||||||||||
| 410 | |||||||||||||||||||||||||||||||||||||||||||
| 411 | =head2 search | ||||||||||||||||||||||||||||||||||||||||||
| 412 | |||||||||||||||||||||||||||||||||||||||||||
| 413 | Search the wills database for records that match the criteria you provide. | ||||||||||||||||||||||||||||||||||||||||||
| 414 | |||||||||||||||||||||||||||||||||||||||||||
| 415 | The last name (C<last>) is the only required field. All other fields are | ||||||||||||||||||||||||||||||||||||||||||
| 416 | optional and narrow the results further. If more than one field is given, a | ||||||||||||||||||||||||||||||||||||||||||
| 417 | record must match B<all> of them to be returned. | ||||||||||||||||||||||||||||||||||||||||||
| 418 | |||||||||||||||||||||||||||||||||||||||||||
| 419 | B<Important -- context matters>: what you get back depends on how you call the | ||||||||||||||||||||||||||||||||||||||||||
| 420 | method: | ||||||||||||||||||||||||||||||||||||||||||
| 421 | |||||||||||||||||||||||||||||||||||||||||||
| 422 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 423 | |||||||||||||||||||||||||||||||||||||||||||
| 424 | =item * B<List context> (C<my @results = $w-E<gt>search(...)>) | ||||||||||||||||||||||||||||||||||||||||||
| 425 | |||||||||||||||||||||||||||||||||||||||||||
| 426 | Returns B<all> matching records as a list of hash references. Returns an empty | ||||||||||||||||||||||||||||||||||||||||||
| 427 | list (C<()>) when nothing matches. | ||||||||||||||||||||||||||||||||||||||||||
| 428 | |||||||||||||||||||||||||||||||||||||||||||
| 429 | =item * B<Scalar context> (C<my $result = $w-E<gt>search(...)>) | ||||||||||||||||||||||||||||||||||||||||||
| 430 | |||||||||||||||||||||||||||||||||||||||||||
| 431 | Returns B<one> hash reference (the first match found), or C<undef> when | ||||||||||||||||||||||||||||||||||||||||||
| 432 | nothing matches. | ||||||||||||||||||||||||||||||||||||||||||
| 433 | |||||||||||||||||||||||||||||||||||||||||||
| 434 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 435 | |||||||||||||||||||||||||||||||||||||||||||
| 436 | Each returned hash reference has these keys: | ||||||||||||||||||||||||||||||||||||||||||
| 437 | |||||||||||||||||||||||||||||||||||||||||||
| 438 | first -- first name (string) | ||||||||||||||||||||||||||||||||||||||||||
| 439 | last -- last name (string) | ||||||||||||||||||||||||||||||||||||||||||
| 440 | middle -- middle name (string, or undef if not recorded) | ||||||||||||||||||||||||||||||||||||||||||
| 441 | town -- town, e.g. "Canterbury, Kent, England" (string, or undef) | ||||||||||||||||||||||||||||||||||||||||||
| 442 | year -- year the will was proved (integer, or undef) | ||||||||||||||||||||||||||||||||||||||||||
| 443 | url -- full URL to the source page, e.g. "https://freepages..." | ||||||||||||||||||||||||||||||||||||||||||
| 444 | |||||||||||||||||||||||||||||||||||||||||||
| 445 | The C<url> field always starts with C<https://>. | ||||||||||||||||||||||||||||||||||||||||||
| 446 | |||||||||||||||||||||||||||||||||||||||||||
| 447 | =head3 ARGUMENTS | ||||||||||||||||||||||||||||||||||||||||||
| 448 | |||||||||||||||||||||||||||||||||||||||||||
| 449 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 450 | |||||||||||||||||||||||||||||||||||||||||||
| 451 | =item * C<last> (required, string) | ||||||||||||||||||||||||||||||||||||||||||
| 452 | |||||||||||||||||||||||||||||||||||||||||||
| 453 | The surname (last name, family name) to search for. | ||||||||||||||||||||||||||||||||||||||||||
| 454 | |||||||||||||||||||||||||||||||||||||||||||
| 455 | Must be non-empty and contain only letters, digits, underscores (the C<\w> | ||||||||||||||||||||||||||||||||||||||||||
| 456 | set), and hyphens. Any other characters (including apostrophes) cause the | ||||||||||||||||||||||||||||||||||||||||||
| 457 | call to fail validation. For example, C<"O'Brien"> must be passed as | ||||||||||||||||||||||||||||||||||||||||||
| 458 | C<"OBrien">. | ||||||||||||||||||||||||||||||||||||||||||
| 459 | |||||||||||||||||||||||||||||||||||||||||||
| 460 | The search is B<exact-match>: C<"Smith"> finds only the exact string | ||||||||||||||||||||||||||||||||||||||||||
| 461 | C<"Smith">, not C<"Smithson">. | ||||||||||||||||||||||||||||||||||||||||||
| 462 | |||||||||||||||||||||||||||||||||||||||||||
| 463 | =item * C<first> (optional, string, 1-100 characters) | ||||||||||||||||||||||||||||||||||||||||||
| 464 | |||||||||||||||||||||||||||||||||||||||||||
| 465 | The first name (given name) to filter by. | ||||||||||||||||||||||||||||||||||||||||||
| 466 | |||||||||||||||||||||||||||||||||||||||||||
| 467 | =item * C<middle> (optional, string, 1-100 characters) | ||||||||||||||||||||||||||||||||||||||||||
| 468 | |||||||||||||||||||||||||||||||||||||||||||
| 469 | The middle name to filter by. | ||||||||||||||||||||||||||||||||||||||||||
| 470 | |||||||||||||||||||||||||||||||||||||||||||
| 471 | =item * C<town> (optional, string, 1-100 characters) | ||||||||||||||||||||||||||||||||||||||||||
| 472 | |||||||||||||||||||||||||||||||||||||||||||
| 473 | The town to filter by. Records use the format C<"Townname, Kent, England">. | ||||||||||||||||||||||||||||||||||||||||||
| 474 | Use the exact spelling seen in earlier results, or leave this out and | ||||||||||||||||||||||||||||||||||||||||||
| 475 | narrow by other fields instead. | ||||||||||||||||||||||||||||||||||||||||||
| 476 | |||||||||||||||||||||||||||||||||||||||||||
| 477 | =item * C<year> (optional, integer, 1 to current year) | ||||||||||||||||||||||||||||||||||||||||||
| 478 | |||||||||||||||||||||||||||||||||||||||||||
| 479 | The year the will was proved. Must be a positive whole number no greater | ||||||||||||||||||||||||||||||||||||||||||
| 480 | than the current calendar year. | ||||||||||||||||||||||||||||||||||||||||||
| 481 | |||||||||||||||||||||||||||||||||||||||||||
| 482 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 483 | |||||||||||||||||||||||||||||||||||||||||||
| 484 | You may pass arguments in three ways: | ||||||||||||||||||||||||||||||||||||||||||
| 485 | |||||||||||||||||||||||||||||||||||||||||||
| 486 | $w->search(last => 'Smith') # flat key-value list | ||||||||||||||||||||||||||||||||||||||||||
| 487 | $w->search({ last => 'Smith' }) # hash reference | ||||||||||||||||||||||||||||||||||||||||||
| 488 | $w->search('Smith') # bare string = last name only | ||||||||||||||||||||||||||||||||||||||||||
| 489 | |||||||||||||||||||||||||||||||||||||||||||
| 490 | =head3 RETURNS | ||||||||||||||||||||||||||||||||||||||||||
| 491 | |||||||||||||||||||||||||||||||||||||||||||
| 492 | B<List context>: a list of hash references (may be empty). | ||||||||||||||||||||||||||||||||||||||||||
| 493 | |||||||||||||||||||||||||||||||||||||||||||
| 494 | B<Scalar context>: one hash reference, or C<undef> if nothing matched. | ||||||||||||||||||||||||||||||||||||||||||
| 495 | |||||||||||||||||||||||||||||||||||||||||||
| 496 | Each hash reference has these keys: C<first>, C<last>, C<middle>, C<town>, | ||||||||||||||||||||||||||||||||||||||||||
| 497 | C<year>, C<url>. | ||||||||||||||||||||||||||||||||||||||||||
| 498 | |||||||||||||||||||||||||||||||||||||||||||
| 499 | =head3 EXAMPLE | ||||||||||||||||||||||||||||||||||||||||||
| 500 | |||||||||||||||||||||||||||||||||||||||||||
| 501 | my $w = Genealogy::Wills->new(); | ||||||||||||||||||||||||||||||||||||||||||
| 502 | |||||||||||||||||||||||||||||||||||||||||||
| 503 | # All records for the surname "Cowell" | ||||||||||||||||||||||||||||||||||||||||||
| 504 | my @all = $w->search(last => 'Cowell'); | ||||||||||||||||||||||||||||||||||||||||||
| 505 | print scalar(@all), " records found.\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 506 | |||||||||||||||||||||||||||||||||||||||||||
| 507 | # Bare string shortcut | ||||||||||||||||||||||||||||||||||||||||||
| 508 | my @smiths = $w->search('Smith'); | ||||||||||||||||||||||||||||||||||||||||||
| 509 | |||||||||||||||||||||||||||||||||||||||||||
| 510 | # Multiple filters | ||||||||||||||||||||||||||||||||||||||||||
| 511 | my @hits = $w->search( | ||||||||||||||||||||||||||||||||||||||||||
| 512 | first => 'Stephen', | ||||||||||||||||||||||||||||||||||||||||||
| 513 | last => 'Carlton', | ||||||||||||||||||||||||||||||||||||||||||
| 514 | town => 'Ash, Kent, England', | ||||||||||||||||||||||||||||||||||||||||||
| 515 | ); | ||||||||||||||||||||||||||||||||||||||||||
| 516 | |||||||||||||||||||||||||||||||||||||||||||
| 517 | # Scalar context: one result or undef | ||||||||||||||||||||||||||||||||||||||||||
| 518 | my $one = $w->search(last => 'Horne'); | ||||||||||||||||||||||||||||||||||||||||||
| 519 | if (defined $one) { | ||||||||||||||||||||||||||||||||||||||||||
| 520 | printf "%s %s (%d): %s\n", | ||||||||||||||||||||||||||||||||||||||||||
| 521 | $one->{first}, $one->{last}, $one->{year}, $one->{url}; | ||||||||||||||||||||||||||||||||||||||||||
| 522 | } | ||||||||||||||||||||||||||||||||||||||||||
| 523 | |||||||||||||||||||||||||||||||||||||||||||
| 524 | # url always starts with https:// | ||||||||||||||||||||||||||||||||||||||||||
| 525 | for my $r ($w->search(last => 'Smith')) { | ||||||||||||||||||||||||||||||||||||||||||
| 526 | print $r->{url}, "\n"; | ||||||||||||||||||||||||||||||||||||||||||
| 527 | } | ||||||||||||||||||||||||||||||||||||||||||
| 528 | |||||||||||||||||||||||||||||||||||||||||||
| 529 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||
| 530 | |||||||||||||||||||||||||||||||||||||||||||
| 531 | =head4 input | ||||||||||||||||||||||||||||||||||||||||||
| 532 | |||||||||||||||||||||||||||||||||||||||||||
| 533 | schema => { | ||||||||||||||||||||||||||||||||||||||||||
| 534 | last => { type => 'string', | ||||||||||||||||||||||||||||||||||||||||||
| 535 | min => 1, max => 100, | ||||||||||||||||||||||||||||||||||||||||||
| 536 | matches => qr/^[\w-]+\z/a }, | ||||||||||||||||||||||||||||||||||||||||||
| 537 | first => { type => 'string', | ||||||||||||||||||||||||||||||||||||||||||
| 538 | min => 1, max => 100, | ||||||||||||||||||||||||||||||||||||||||||
| 539 | optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 540 | middle => { type => 'string', | ||||||||||||||||||||||||||||||||||||||||||
| 541 | min => 1, max => 100, | ||||||||||||||||||||||||||||||||||||||||||
| 542 | optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 543 | town => { type => 'string', | ||||||||||||||||||||||||||||||||||||||||||
| 544 | min => 1, max => 100, | ||||||||||||||||||||||||||||||||||||||||||
| 545 | optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 546 | year => { type => 'integer', | ||||||||||||||||||||||||||||||||||||||||||
| 547 | min => 1, max => $MAX_WILL_YEAR, | ||||||||||||||||||||||||||||||||||||||||||
| 548 | optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 549 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 550 | |||||||||||||||||||||||||||||||||||||||||||
| 551 | C<$MAX_WILL_YEAR> is C<(localtime)[5] + 1900> computed once at module load. | ||||||||||||||||||||||||||||||||||||||||||
| 552 | C<Params::Get::get_params('last', ...)> maps a bare string argument to | ||||||||||||||||||||||||||||||||||||||||||
| 553 | C<< { last => $string } >> before validation runs. | ||||||||||||||||||||||||||||||||||||||||||
| 554 | The schema hashref itself is a module-level constant allocated once at load | ||||||||||||||||||||||||||||||||||||||||||
| 555 | time and shared across all calls; it is never modified at runtime. | ||||||||||||||||||||||||||||||||||||||||||
| 556 | |||||||||||||||||||||||||||||||||||||||||||
| 557 | =head4 output | ||||||||||||||||||||||||||||||||||||||||||
| 558 | |||||||||||||||||||||||||||||||||||||||||||
| 559 | # List context -- no Return::Set wrapping | ||||||||||||||||||||||||||||||||||||||||||
| 560 | Returns: Array of HashRef | ||||||||||||||||||||||||||||||||||||||||||
| 561 | Each HashRef: { first => { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 562 | last => { type => 'string' }, | ||||||||||||||||||||||||||||||||||||||||||
| 563 | middle => { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 564 | town => { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 565 | year => { type => 'integer', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||
| 566 | url => { type => 'string', matches => qr/^https:\/\// }, | ||||||||||||||||||||||||||||||||||||||||||
| 567 | } | ||||||||||||||||||||||||||||||||||||||||||
| 568 | Empty list when nothing matches. | ||||||||||||||||||||||||||||||||||||||||||
| 569 | |||||||||||||||||||||||||||||||||||||||||||
| 570 | # Scalar context -- wrapped by Return::Set | ||||||||||||||||||||||||||||||||||||||||||
| 571 | Return::Set::set_return($will, { type => 'hashref', min => 1 }); | ||||||||||||||||||||||||||||||||||||||||||
| 572 | Returns: HashRef (same shape) | undef | ||||||||||||||||||||||||||||||||||||||||||
| 573 | |||||||||||||||||||||||||||||||||||||||||||
| 574 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||
| 575 | |||||||||||||||||||||||||||||||||||||||||||
| 576 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 577 | |||||||||||||||||||||||||||||||||||||||||||
| 578 | =item B<search() must be called on an object> | ||||||||||||||||||||||||||||||||||||||||||
| 579 | |||||||||||||||||||||||||||||||||||||||||||
| 580 | Fatal. You called C<search()> as a class method | ||||||||||||||||||||||||||||||||||||||||||
| 581 | (C<Genealogy::Wills-E<gt>search(...)>) instead of on an object. Create the | ||||||||||||||||||||||||||||||||||||||||||
| 582 | object first with C<new()>, then call C<search()> on it. | ||||||||||||||||||||||||||||||||||||||||||
| 583 | |||||||||||||||||||||||||||||||||||||||||||
| 584 | =item B<Usage: search({ last =E<gt> $last_name })> | ||||||||||||||||||||||||||||||||||||||||||
| 585 | |||||||||||||||||||||||||||||||||||||||||||
| 586 | Fatal. C<search()> was called with no arguments at all. | ||||||||||||||||||||||||||||||||||||||||||
| 587 | Always provide at least C<last =E<gt> $name>. | ||||||||||||||||||||||||||||||||||||||||||
| 588 | |||||||||||||||||||||||||||||||||||||||||||
| 589 | =item B<Value for 'last' is mandatory> | ||||||||||||||||||||||||||||||||||||||||||
| 590 | |||||||||||||||||||||||||||||||||||||||||||
| 591 | Warning (not fatal). The C<last> argument was provided but its value was | ||||||||||||||||||||||||||||||||||||||||||
| 592 | C<undef> or an empty string. C<search()> returns no results in this case. | ||||||||||||||||||||||||||||||||||||||||||
| 593 | Supply a non-empty string. | ||||||||||||||||||||||||||||||||||||||||||
| 594 | |||||||||||||||||||||||||||||||||||||||||||
| 595 | =item B<Can't open the wills database> | ||||||||||||||||||||||||||||||||||||||||||
| 596 | |||||||||||||||||||||||||||||||||||||||||||
| 597 | Fatal. The internal database object could not be created. The database file | ||||||||||||||||||||||||||||||||||||||||||
| 598 | may be missing or corrupted. Rebuild with C<perl bin/create_db.PL -f>. | ||||||||||||||||||||||||||||||||||||||||||
| 599 | |||||||||||||||||||||||||||||||||||||||||||
| 600 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 601 | |||||||||||||||||||||||||||||||||||||||||||
| 602 | =head3 PSEUDOCODE | ||||||||||||||||||||||||||||||||||||||||||
| 603 | |||||||||||||||||||||||||||||||||||||||||||
| 604 | A plain-English description of what C<search()> does, step by step: | ||||||||||||||||||||||||||||||||||||||||||
| 605 | |||||||||||||||||||||||||||||||||||||||||||
| 606 | 1. If the caller is not a Genealogy::Wills object, die immediately. | ||||||||||||||||||||||||||||||||||||||||||
| 607 | |||||||||||||||||||||||||||||||||||||||||||
| 608 | 2. If no arguments were given, die immediately. | ||||||||||||||||||||||||||||||||||||||||||
| 609 | |||||||||||||||||||||||||||||||||||||||||||
| 610 | 3. Parse the arguments: | ||||||||||||||||||||||||||||||||||||||||||
| 611 | - A single bare string becomes { last => $string }. | ||||||||||||||||||||||||||||||||||||||||||
| 612 | - A hash reference or flat key-value list is used as-is. | ||||||||||||||||||||||||||||||||||||||||||
| 613 | |||||||||||||||||||||||||||||||||||||||||||
| 614 | 4. Validate the parsed arguments: | ||||||||||||||||||||||||||||||||||||||||||
| 615 | - 'last' must match /^[\w-]+$/ and be 1-100 characters. | ||||||||||||||||||||||||||||||||||||||||||
| 616 | - 'first', 'middle', 'town': optional strings, 1-100 characters each. | ||||||||||||||||||||||||||||||||||||||||||
| 617 | - 'year': optional integer between 1 and the current year. | ||||||||||||||||||||||||||||||||||||||||||
| 618 | |||||||||||||||||||||||||||||||||||||||||||
| 619 | 5. If 'last' is undef or empty after parsing, print a warning and return | ||||||||||||||||||||||||||||||||||||||||||
| 620 | nothing (an empty list or undef, depending on context). | ||||||||||||||||||||||||||||||||||||||||||
| 621 | |||||||||||||||||||||||||||||||||||||||||||
| 622 | 6. (Removed: sanitization was a no-op. Validation in step 4 already | ||||||||||||||||||||||||||||||||||||||||||
| 623 | enforces [\w-] only via PVS matches => qr/^[\w-]+\z/a.) | ||||||||||||||||||||||||||||||||||||||||||
| 624 | |||||||||||||||||||||||||||||||||||||||||||
| 625 | 7. If this is the first search() call on this object, open the SQLite | ||||||||||||||||||||||||||||||||||||||||||
| 626 | database. Reuse the existing connection on subsequent calls. | ||||||||||||||||||||||||||||||||||||||||||
| 627 | |||||||||||||||||||||||||||||||||||||||||||
| 628 | 8. If the database could not be opened, die immediately. | ||||||||||||||||||||||||||||||||||||||||||
| 629 | |||||||||||||||||||||||||||||||||||||||||||
| 630 | 9. Execute the query: | ||||||||||||||||||||||||||||||||||||||||||
| 631 | List context: | ||||||||||||||||||||||||||||||||||||||||||
| 632 | Fetch all matching rows. | ||||||||||||||||||||||||||||||||||||||||||
| 633 | Prepend "https://" to the url of every row. | ||||||||||||||||||||||||||||||||||||||||||
| 634 | Intern all strings (Data::Reuse::fixate) to save memory. | ||||||||||||||||||||||||||||||||||||||||||
| 635 | Return the list of hashrefs. | ||||||||||||||||||||||||||||||||||||||||||
| 636 | |||||||||||||||||||||||||||||||||||||||||||
| 637 | Scalar context: | ||||||||||||||||||||||||||||||||||||||||||
| 638 | Fetch the first matching row. | ||||||||||||||||||||||||||||||||||||||||||
| 639 | Prepend "https://" to its url. | ||||||||||||||||||||||||||||||||||||||||||
| 640 | Intern all strings. | ||||||||||||||||||||||||||||||||||||||||||
| 641 | Return the hashref (or undef if nothing matched). | ||||||||||||||||||||||||||||||||||||||||||
| 642 | |||||||||||||||||||||||||||||||||||||||||||
| 643 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 644 | |||||||||||||||||||||||||||||||||||||||||||
| 645 | 153 | ▶ | sub search { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
search: called CC=11 SCAR=24.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 646 | 153 | my $self = shift; | |||||||||||||||||||||||||||||||||||||||||
| 647 | |||||||||||||||||||||||||||||||||||||||||||
| 648 | 153 | ▶ | Carp::croak('search() must be called on an object') unless blessed($self); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 649 | 146 | ▶ | Carp::croak('Usage: search({ last => $last_name })') unless @_; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 650 | |||||||||||||||||||||||||||||||||||||||||||
| 651 | # $SEARCH_SCHEMA is the module-level constant; no per-call allocation. | ||||||||||||||||||||||||||||||||||||||||||
| 652 | # local $@ guards against Params::Validate::Strict's internal eval() calls | ||||||||||||||||||||||||||||||||||||||||||
| 653 | # resetting the caller's $@ to '' on a successful validation pass. | ||||||||||||||||||||||||||||||||||||||||||
| 654 | 140 | my $params = do { | |||||||||||||||||||||||||||||||||||||||||
| 655 | 140 | local $@; | |||||||||||||||||||||||||||||||||||||||||
| 656 | 140 | Params::Validate::Strict::validate_strict({ | |||||||||||||||||||||||||||||||||||||||||
| 657 | args => Params::Get::get_params('last', @_), | ||||||||||||||||||||||||||||||||||||||||||
| 658 | schema => $SEARCH_SCHEMA, | ||||||||||||||||||||||||||||||||||||||||||
| 659 | }); | ||||||||||||||||||||||||||||||||||||||||||
| 660 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 661 | |||||||||||||||||||||||||||||||||||||||||||
| 662 | 50 | ▶ | unless(length($params->{'last'} // '')) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition50%1/2
$$params{"last"} // ""
MC/DC0%0/1
$$params{"last"} // ""
$$params{"last"}
Truth table50%1/2
A
A= $$params{"last"}
| |||||||||||||||||||||||||||||||||||||||||||
| 663 | 0 | Carp::carp("Value for 'last' is mandatory"); | |||||||||||||||||||||||||||||||||||||||||
| 664 | 0 | return; | |||||||||||||||||||||||||||||||||||||||||
| 665 | } | ||||||||||||||||||||||||||||||||||||||||||
| 666 | # (Transitive Reduction): PVS already enforced matches => qr/^[\w-]+\z/a above. | ||||||||||||||||||||||||||||||||||||||||||
| 667 | # Any value reaching this point is structurally valid; re-sanitization is a no-op. | ||||||||||||||||||||||||||||||||||||||||||
| 668 | |||||||||||||||||||||||||||||||||||||||||||
| 669 | 50 | ▶ | $self->{'wills'} ||= Genealogy::Wills::wills->new(no_entry => 1, no_fixate => 1, %{$self}); | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%3/3
$$self{"wills"} ||= "Genealogy::Wills::wills"->new("no_entry", 1, "no_fixate", 1, %{$self;})
MC/DC100%2/2
$$self{"wills"} ||= "Genealogy::Wills::wills"->new("no_entry", 1, "no_fixate", 1, %{$self;})
$$self{"wills"}
"Genealogy::Wills::wills"->new("no_entry", 1, "no_fixate", 1, %{$self;})
Truth table100%3/3
A ||= B
A= $$self{"wills"}B= "Genealogy::Wills::wills"->new("no_entry", 1, "no_fixate", 1, %{$self;})
| |||||||||||||||||||||||||||||||||||||||||||
| 670 | |||||||||||||||||||||||||||||||||||||||||||
| 671 | 50 | ▶ | Carp::croak("Can't open the wills database") unless defined($self->{'wills'}); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 672 | |||||||||||||||||||||||||||||||||||||||||||
| 673 | 48 | ▶ | if(wantarray) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 674 | # normalize to [] so the loop and return are unconditional; | ||||||||||||||||||||||||||||||||||||||||||
| 675 | # eliminates a branch and makes the empty-result path explicit. | ||||||||||||||||||||||||||||||||||||||||||
| 676 | 39 | ▶ | my $wills = $self->{'wills'}->selectall_hashref($params) // []; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$$self{"wills"}->selectall_hashref($params) // []
MC/DC100%1/1
$$self{"wills"}->selectall_hashref($params) // []
$$self{"wills"}->selectall_hashref($params)
Truth table100%2/2
A
A= $$self{"wills"}->selectall_hashref($params)
| |||||||||||||||||||||||||||||||||||||||||||
| 677 | 38 | _decorate_will($_) for @{$wills}; | |||||||||||||||||||||||||||||||||||||||||
| 678 | 37 | return @{$wills}; | |||||||||||||||||||||||||||||||||||||||||
| 679 | } | ||||||||||||||||||||||||||||||||||||||||||
| 680 | 9 | ▶ | if(defined(my $will = $self->{'wills'}->fetchrow_hashref($params))) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 681 | 3 | return Return::Set::set_return(_decorate_will($will), { 'type' => 'hashref', 'min' => 1 }); | |||||||||||||||||||||||||||||||||||||||||
| 682 | } | ||||||||||||||||||||||||||||||||||||||||||
| 683 | 5 | return; | |||||||||||||||||||||||||||||||||||||||||
| 684 | } | ||||||||||||||||||||||||||||||||||||||||||
| 685 | |||||||||||||||||||||||||||||||||||||||||||
| 686 | # _decorate_will -- prepend the https:// scheme to a DB result and intern its strings. | ||||||||||||||||||||||||||||||||||||||||||
| 687 | # Entry: $will -- a hashref row from the DB layer (url stored without scheme) | ||||||||||||||||||||||||||||||||||||||||||
| 688 | # Side effects: mutates $will->{'url'} in place; interns all string values via fixate | ||||||||||||||||||||||||||||||||||||||||||
| 689 | # Exit: returns $will (same ref) for chaining | ||||||||||||||||||||||||||||||||||||||||||
| 690 | 1045 | ▶ | sub _decorate_will :Protected { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_decorate_will: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 691 | 1045 | my $will = shift; | |||||||||||||||||||||||||||||||||||||||||
| 692 | 1045 | $will->{'url'} = 'https://' . $will->{'url'}; | |||||||||||||||||||||||||||||||||||||||||
| 693 | 1045 | Data::Reuse::fixate(%{$will}); | |||||||||||||||||||||||||||||||||||||||||
| 694 | 1045 | return $will; | |||||||||||||||||||||||||||||||||||||||||
| 695 | 13 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 696 | |||||||||||||||||||||||||||||||||||||||||||
| 697 | =head1 COMMON PITFALLS | ||||||||||||||||||||||||||||||||||||||||||
| 698 | |||||||||||||||||||||||||||||||||||||||||||
| 699 | This section describes the most common mistakes when using this module. | ||||||||||||||||||||||||||||||||||||||||||
| 700 | Read it before reporting a bug. | ||||||||||||||||||||||||||||||||||||||||||
| 701 | |||||||||||||||||||||||||||||||||||||||||||
| 702 | =head2 List context vs. scalar context give different results | ||||||||||||||||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||||||||||||||||
| 704 | This is the single most important thing to understand. The same call returns | ||||||||||||||||||||||||||||||||||||||||||
| 705 | different things depending on whether you store the result in an array or a | ||||||||||||||||||||||||||||||||||||||||||
| 706 | scalar variable: | ||||||||||||||||||||||||||||||||||||||||||
| 707 | |||||||||||||||||||||||||||||||||||||||||||
| 708 | my @all = $wills->search(last => 'Smith'); # ALL Smiths (may be many) | ||||||||||||||||||||||||||||||||||||||||||
| 709 | my $first = $wills->search(last => 'Smith'); # ONE Smith only | ||||||||||||||||||||||||||||||||||||||||||
| 710 | |||||||||||||||||||||||||||||||||||||||||||
| 711 | If you accidentally write C<my $r = $wills-E<gt>search(...)>, you get at most | ||||||||||||||||||||||||||||||||||||||||||
| 712 | one record even if hundreds matched. Use C<my @results = ...> unless you | ||||||||||||||||||||||||||||||||||||||||||
| 713 | specifically want only the first match. | ||||||||||||||||||||||||||||||||||||||||||
| 714 | |||||||||||||||||||||||||||||||||||||||||||
| 715 | =head2 new() returns undef on failure -- it does not crash | ||||||||||||||||||||||||||||||||||||||||||
| 716 | |||||||||||||||||||||||||||||||||||||||||||
| 717 | If the directory does not exist or cannot be read, C<new()> prints a warning | ||||||||||||||||||||||||||||||||||||||||||
| 718 | and returns C<undef>. Your program does B<not> stop. If you then call | ||||||||||||||||||||||||||||||||||||||||||
| 719 | C<search()> on the C<undef> value, it will crash later with an unhelpful error. | ||||||||||||||||||||||||||||||||||||||||||
| 720 | |||||||||||||||||||||||||||||||||||||||||||
| 721 | Always check the return value: | ||||||||||||||||||||||||||||||||||||||||||
| 722 | |||||||||||||||||||||||||||||||||||||||||||
| 723 | my $wills = Genealogy::Wills->new(); | ||||||||||||||||||||||||||||||||||||||||||
| 724 | die "Could not load wills database" unless defined $wills; | ||||||||||||||||||||||||||||||||||||||||||
| 725 | |||||||||||||||||||||||||||||||||||||||||||
| 726 | =head2 No arguments is fatal; undef is only a warning | ||||||||||||||||||||||||||||||||||||||||||
| 727 | |||||||||||||||||||||||||||||||||||||||||||
| 728 | These two situations look similar but have very different consequences: | ||||||||||||||||||||||||||||||||||||||||||
| 729 | |||||||||||||||||||||||||||||||||||||||||||
| 730 | $wills->search(); # FATAL -- program stops with an exception | ||||||||||||||||||||||||||||||||||||||||||
| 731 | $wills->search(last => undef); # WARNING only -- returns no results | ||||||||||||||||||||||||||||||||||||||||||
| 732 | |||||||||||||||||||||||||||||||||||||||||||
| 733 | Always provide at least C<last =E<gt> $name>. | ||||||||||||||||||||||||||||||||||||||||||
| 734 | |||||||||||||||||||||||||||||||||||||||||||
| 735 | =head2 The url field already contains https:// | ||||||||||||||||||||||||||||||||||||||||||
| 736 | |||||||||||||||||||||||||||||||||||||||||||
| 737 | Every returned record has its C<url> field set to a full URL starting with | ||||||||||||||||||||||||||||||||||||||||||
| 738 | C<https://>. Do not add the scheme prefix yourself: | ||||||||||||||||||||||||||||||||||||||||||
| 739 | |||||||||||||||||||||||||||||||||||||||||||
| 740 | print $r->{url}; # correct: https://freepages.rootsweb.com/... | ||||||||||||||||||||||||||||||||||||||||||
| 741 | print 'https://' . $r->{url}; # WRONG: https://https://freepages... | ||||||||||||||||||||||||||||||||||||||||||
| 742 | |||||||||||||||||||||||||||||||||||||||||||
| 743 | =head2 Apostrophes and punctuation are rejected in last names | ||||||||||||||||||||||||||||||||||||||||||
| 744 | |||||||||||||||||||||||||||||||||||||||||||
| 745 | The module accepts only word characters (C<\w>) and hyphens in the C<last> | ||||||||||||||||||||||||||||||||||||||||||
| 746 | argument. Any other character -- including apostrophes -- causes validation | ||||||||||||||||||||||||||||||||||||||||||
| 747 | to fail, not silent stripping. | ||||||||||||||||||||||||||||||||||||||||||
| 748 | |||||||||||||||||||||||||||||||||||||||||||
| 749 | $wills->search(last => "O'Brien"); # FAILS validation; pass "OBrien" | ||||||||||||||||||||||||||||||||||||||||||
| 750 | |||||||||||||||||||||||||||||||||||||||||||
| 751 | If the record you are looking for has a name like C<O'Brien>, search for | ||||||||||||||||||||||||||||||||||||||||||
| 752 | C<OBrien> instead (that is how it was recorded in the database). | ||||||||||||||||||||||||||||||||||||||||||
| 753 | |||||||||||||||||||||||||||||||||||||||||||
| 754 | =head2 Search is exact-match -- no wildcards or fuzzy matching | ||||||||||||||||||||||||||||||||||||||||||
| 755 | |||||||||||||||||||||||||||||||||||||||||||
| 756 | The query looks for an exact match on every field you provide. Partial | ||||||||||||||||||||||||||||||||||||||||||
| 757 | last names and wildcard patterns (such as C<Smith*>) are not supported | ||||||||||||||||||||||||||||||||||||||||||
| 758 | through this interface. | ||||||||||||||||||||||||||||||||||||||||||
| 759 | |||||||||||||||||||||||||||||||||||||||||||
| 760 | $wills->search(last => 'Smith'); # finds "Smith" only | ||||||||||||||||||||||||||||||||||||||||||
| 761 | # Does NOT find "Smithson", "Blacksmith", "Goldsmith", etc. | ||||||||||||||||||||||||||||||||||||||||||
| 762 | |||||||||||||||||||||||||||||||||||||||||||
| 763 | =head2 The config file key uses double underscores, not colons | ||||||||||||||||||||||||||||||||||||||||||
| 764 | |||||||||||||||||||||||||||||||||||||||||||
| 765 | When using a YAML (or other) config file, the section name for this class | ||||||||||||||||||||||||||||||||||||||||||
| 766 | must use two underscores in place of each C<::> in the package name: | ||||||||||||||||||||||||||||||||||||||||||
| 767 | |||||||||||||||||||||||||||||||||||||||||||
| 768 | # CORRECT | ||||||||||||||||||||||||||||||||||||||||||
| 769 | Genealogy__Wills: | ||||||||||||||||||||||||||||||||||||||||||
| 770 | directory: /var/data/wills | ||||||||||||||||||||||||||||||||||||||||||
| 771 | |||||||||||||||||||||||||||||||||||||||||||
| 772 | # WRONG (causes the config to be silently ignored) | ||||||||||||||||||||||||||||||||||||||||||
| 773 | Genealogy::Wills: | ||||||||||||||||||||||||||||||||||||||||||
| 774 | directory: /var/data/wills | ||||||||||||||||||||||||||||||||||||||||||
| 775 | |||||||||||||||||||||||||||||||||||||||||||
| 776 | The same rule applies to environment variable overrides: | ||||||||||||||||||||||||||||||||||||||||||
| 777 | C<Genealogy__Wills__directory=/tmp/wills>. | ||||||||||||||||||||||||||||||||||||||||||
| 778 | |||||||||||||||||||||||||||||||||||||||||||
| 779 | =head2 Do not use the function-call syntax with arguments | ||||||||||||||||||||||||||||||||||||||||||
| 780 | |||||||||||||||||||||||||||||||||||||||||||
| 781 | Calling C<new()> as a plain function (C<::> instead of C<-E<gt>>) with | ||||||||||||||||||||||||||||||||||||||||||
| 782 | arguments does not work correctly. The first argument is misread as the | ||||||||||||||||||||||||||||||||||||||||||
| 783 | class name. | ||||||||||||||||||||||||||||||||||||||||||
| 784 | |||||||||||||||||||||||||||||||||||||||||||
| 785 | Genealogy::Wills->new() # correct -- arrow syntax | ||||||||||||||||||||||||||||||||||||||||||
| 786 | Genealogy::Wills::new() # tolerated -- no args, defaults to package | ||||||||||||||||||||||||||||||||||||||||||
| 787 | Genealogy::Wills::new('/data') # WRONG -- '/data' is misused as class name | ||||||||||||||||||||||||||||||||||||||||||
| 788 | |||||||||||||||||||||||||||||||||||||||||||
| 789 | =head2 The year upper limit is fixed when the module loads | ||||||||||||||||||||||||||||||||||||||||||
| 790 | |||||||||||||||||||||||||||||||||||||||||||
| 791 | The maximum allowed C<year> value is computed once the first time | ||||||||||||||||||||||||||||||||||||||||||
| 792 | C<use Genealogy::Wills> is executed. If your process runs for a very long | ||||||||||||||||||||||||||||||||||||||||||
| 793 | time and crosses a year boundary (e.g. from 31 December to 1 January), the | ||||||||||||||||||||||||||||||||||||||||||
| 794 | cap will be stale by one year until the module is reloaded. | ||||||||||||||||||||||||||||||||||||||||||
| 795 | |||||||||||||||||||||||||||||||||||||||||||
| 796 | =head1 LIMITATIONS | ||||||||||||||||||||||||||||||||||||||||||
| 797 | |||||||||||||||||||||||||||||||||||||||||||
| 798 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 799 | |||||||||||||||||||||||||||||||||||||||||||
| 800 | =item * Only data from Kent is available at the moment. | ||||||||||||||||||||||||||||||||||||||||||
| 801 | |||||||||||||||||||||||||||||||||||||||||||
| 802 | =item * B<C<::new()> with arguments is unsupported.> | ||||||||||||||||||||||||||||||||||||||||||
| 803 | |||||||||||||||||||||||||||||||||||||||||||
| 804 | C<Genealogy::Wills::new('Smith')> shifts C<'Smith'> into C<$class> and | ||||||||||||||||||||||||||||||||||||||||||
| 805 | attempts to bless into it. Only the no-argument form | ||||||||||||||||||||||||||||||||||||||||||
| 806 | C<Genealogy::Wills::new()> is partially handled (it defaults to | ||||||||||||||||||||||||||||||||||||||||||
| 807 | C<__PACKAGE__>). Always use the arrow form: C<< Genealogy::Wills->new() >>. | ||||||||||||||||||||||||||||||||||||||||||
| 808 | |||||||||||||||||||||||||||||||||||||||||||
| 809 | =item * B<Year upper bound is capped at load time.> | ||||||||||||||||||||||||||||||||||||||||||
| 810 | |||||||||||||||||||||||||||||||||||||||||||
| 811 | C<MAX_WILL_YEAR> is computed once when the module is first loaded. In the | ||||||||||||||||||||||||||||||||||||||||||
| 812 | unlikely event the module remains loaded across a year boundary the cap will | ||||||||||||||||||||||||||||||||||||||||||
| 813 | be one year stale. | ||||||||||||||||||||||||||||||||||||||||||
| 814 | |||||||||||||||||||||||||||||||||||||||||||
| 815 | =item * B<No full-text or fuzzy search.> | ||||||||||||||||||||||||||||||||||||||||||
| 816 | |||||||||||||||||||||||||||||||||||||||||||
| 817 | Searches are exact-match on the columns provided. There is no fuzzy or | ||||||||||||||||||||||||||||||||||||||||||
| 818 | phonetic matching (e.g. Soundex, Levenshtein distance). Wildcard support | ||||||||||||||||||||||||||||||||||||||||||
| 819 | depends on the C<Database::Abstraction> layer. | ||||||||||||||||||||||||||||||||||||||||||
| 820 | |||||||||||||||||||||||||||||||||||||||||||
| 821 | =item * B<The C<logger> argument is silently discarded.> | ||||||||||||||||||||||||||||||||||||||||||
| 822 | |||||||||||||||||||||||||||||||||||||||||||
| 823 | C<Object::Configure> always supplies its own C<Log::Abstraction> logger. | ||||||||||||||||||||||||||||||||||||||||||
| 824 | Any object passed as C<logger> to C<new()> is replaced before it is stored. | ||||||||||||||||||||||||||||||||||||||||||
| 825 | See the L</SECURITY> section, Finding 3. | ||||||||||||||||||||||||||||||||||||||||||
| 826 | |||||||||||||||||||||||||||||||||||||||||||
| 827 | =item * B<Single database source.> | ||||||||||||||||||||||||||||||||||||||||||
| 828 | |||||||||||||||||||||||||||||||||||||||||||
| 829 | The data comes from a single scraped source (the Kent Wills Transcript). It | ||||||||||||||||||||||||||||||||||||||||||
| 830 | does not cover wills from other counties or archives. | ||||||||||||||||||||||||||||||||||||||||||
| 831 | |||||||||||||||||||||||||||||||||||||||||||
| 832 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 833 | |||||||||||||||||||||||||||||||||||||||||||
| 834 | =head1 SECURITY | ||||||||||||||||||||||||||||||||||||||||||
| 835 | |||||||||||||||||||||||||||||||||||||||||||
| 836 | This section documents the attack surface of the module, the controls in | ||||||||||||||||||||||||||||||||||||||||||
| 837 | place, and known open findings. It is intended for developers integrating | ||||||||||||||||||||||||||||||||||||||||||
| 838 | this module into a web application or CGI script. | ||||||||||||||||||||||||||||||||||||||||||
| 839 | |||||||||||||||||||||||||||||||||||||||||||
| 840 | =head2 Attack surface summary | ||||||||||||||||||||||||||||||||||||||||||
| 841 | |||||||||||||||||||||||||||||||||||||||||||
| 842 | The module has two entry points: C<new()> and C<search()>. Neither reads | ||||||||||||||||||||||||||||||||||||||||||
| 843 | from C<%ENV>, C<STDIN>, or any HTTP source directly. In a CGI context, | ||||||||||||||||||||||||||||||||||||||||||
| 844 | the calling script is responsible for parsing HTTP inputs before passing | ||||||||||||||||||||||||||||||||||||||||||
| 845 | them to this module. | ||||||||||||||||||||||||||||||||||||||||||
| 846 | |||||||||||||||||||||||||||||||||||||||||||
| 847 | =head2 Controls in place | ||||||||||||||||||||||||||||||||||||||||||
| 848 | |||||||||||||||||||||||||||||||||||||||||||
| 849 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 850 | |||||||||||||||||||||||||||||||||||||||||||
| 851 | =item * C<last> is strictly validated | ||||||||||||||||||||||||||||||||||||||||||
| 852 | |||||||||||||||||||||||||||||||||||||||||||
| 853 | C<Params::Validate::Strict> enforces C<matches =E<gt> qr/^[\w-]+\z/a> on | ||||||||||||||||||||||||||||||||||||||||||
| 854 | the C<last> argument before any database call. This blocks SQL injection, | ||||||||||||||||||||||||||||||||||||||||||
| 855 | XSS, shell metacharacters, CRLF sequences, and null bytes for that field. | ||||||||||||||||||||||||||||||||||||||||||
| 856 | The C</a> modifier restricts C<\w> to ASCII C<[0-9A-Za-z_]>, blocking | ||||||||||||||||||||||||||||||||||||||||||
| 857 | Unicode homograph queries. The C<\z> anchor is strictly end-of-string, | ||||||||||||||||||||||||||||||||||||||||||
| 858 | unlike C<$> which matches before a trailing newline. | ||||||||||||||||||||||||||||||||||||||||||
| 859 | |||||||||||||||||||||||||||||||||||||||||||
| 860 | =item * C<year> is range-validated as an integer | ||||||||||||||||||||||||||||||||||||||||||
| 861 | |||||||||||||||||||||||||||||||||||||||||||
| 862 | C<Params::Validate::Strict> enforces C<type =E<gt> 'integer'>, C<min =E<gt> 1>, | ||||||||||||||||||||||||||||||||||||||||||
| 863 | and C<max =E<gt> MAX_WILL_YEAR>. Non-integer strings, floats, and | ||||||||||||||||||||||||||||||||||||||||||
| 864 | out-of-range values are all rejected before DB access. | ||||||||||||||||||||||||||||||||||||||||||
| 865 | |||||||||||||||||||||||||||||||||||||||||||
| 866 | =item * Directory and config-file paths are checked before use | ||||||||||||||||||||||||||||||||||||||||||
| 867 | |||||||||||||||||||||||||||||||||||||||||||
| 868 | C<new()> verifies C<-d $dir && -r _> for the data directory and C<-r> | ||||||||||||||||||||||||||||||||||||||||||
| 869 | for any C<config_file>. Paths that do not pass these checks cause C<new()> | ||||||||||||||||||||||||||||||||||||||||||
| 870 | to return C<undef> (with a warning) or croak immediately. | ||||||||||||||||||||||||||||||||||||||||||
| 871 | |||||||||||||||||||||||||||||||||||||||||||
| 872 | =item * Logger injection is blocked by Object::Configure | ||||||||||||||||||||||||||||||||||||||||||
| 873 | |||||||||||||||||||||||||||||||||||||||||||
| 874 | C<Object::Configure::configure()> always replaces the caller-supplied | ||||||||||||||||||||||||||||||||||||||||||
| 875 | C<logger> argument with its own C<Log::Abstraction> object, regardless | ||||||||||||||||||||||||||||||||||||||||||
| 876 | of what was passed. A hostile logger (missing methods, wrong type, or | ||||||||||||||||||||||||||||||||||||||||||
| 877 | carrying malicious extra methods) is discarded before any logging call | ||||||||||||||||||||||||||||||||||||||||||
| 878 | occurs. The module-level interface check C<(blessed && can 'info' && can 'error')> | ||||||||||||||||||||||||||||||||||||||||||
| 879 | runs against the C<Object::Configure>-supplied logger, which always passes. | ||||||||||||||||||||||||||||||||||||||||||
| 880 | |||||||||||||||||||||||||||||||||||||||||||
| 881 | =item * No shell operations | ||||||||||||||||||||||||||||||||||||||||||
| 882 | |||||||||||||||||||||||||||||||||||||||||||
| 883 | The module performs no C<system()>, C<exec()>, backtick, or | ||||||||||||||||||||||||||||||||||||||||||
| 884 | C<open(FH, "...|")> calls. Shell metacharacters in any field pose no | ||||||||||||||||||||||||||||||||||||||||||
| 885 | command-injection risk within this module. | ||||||||||||||||||||||||||||||||||||||||||
| 886 | |||||||||||||||||||||||||||||||||||||||||||
| 887 | =item * Database access is parameterised | ||||||||||||||||||||||||||||||||||||||||||
| 888 | |||||||||||||||||||||||||||||||||||||||||||
| 889 | All SQL is executed via C<Database::Abstraction> (v0.37+), which uses | ||||||||||||||||||||||||||||||||||||||||||
| 890 | DBI prepared statements. Values are bound as parameters, not interpolated | ||||||||||||||||||||||||||||||||||||||||||
| 891 | into SQL strings. | ||||||||||||||||||||||||||||||||||||||||||
| 892 | |||||||||||||||||||||||||||||||||||||||||||
| 893 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 894 | |||||||||||||||||||||||||||||||||||||||||||
| 895 | =head2 Known findings | ||||||||||||||||||||||||||||||||||||||||||
| 896 | |||||||||||||||||||||||||||||||||||||||||||
| 897 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 898 | |||||||||||||||||||||||||||||||||||||||||||
| 899 | =item * B<Finding 1 (fixed): C<first>, C<middle>, C<town> now have C<matches> constraints> | ||||||||||||||||||||||||||||||||||||||||||
| 900 | |||||||||||||||||||||||||||||||||||||||||||
| 901 | Previously these optional fields were validated for type and length only, | ||||||||||||||||||||||||||||||||||||||||||
| 902 | allowing SQL metacharacters (C<;>, C<=>, C<|>, C<E<lt>>, C<E<gt>>, | ||||||||||||||||||||||||||||||||||||||||||
| 903 | C<\r>, C<\n>, C<\0>) to reach the database layer verbatim. | ||||||||||||||||||||||||||||||||||||||||||
| 904 | |||||||||||||||||||||||||||||||||||||||||||
| 905 | B<Applied fix>: the schema now enforces: | ||||||||||||||||||||||||||||||||||||||||||
| 906 | |||||||||||||||||||||||||||||||||||||||||||
| 907 | first/middle: matches => qr/^[\w '.-]+\z/ | ||||||||||||||||||||||||||||||||||||||||||
| 908 | town: matches => qr/^[\w ',.-]+\z/ | ||||||||||||||||||||||||||||||||||||||||||
| 909 | |||||||||||||||||||||||||||||||||||||||||||
| 910 | These allow legitimate name characters (Unicode word chars, space, | ||||||||||||||||||||||||||||||||||||||||||
| 911 | apostrophe as in C<O'Brien>, period as in C<St. John>, hyphen as in | ||||||||||||||||||||||||||||||||||||||||||
| 912 | C<Mary-Anne>, comma in town as in C<"Canterbury, Kent, England">) while | ||||||||||||||||||||||||||||||||||||||||||
| 913 | blocking injection metacharacters. | ||||||||||||||||||||||||||||||||||||||||||
| 914 | |||||||||||||||||||||||||||||||||||||||||||
| 915 | B<Residual surface>: the pattern C<Smith'-->, which contains only | ||||||||||||||||||||||||||||||||||||||||||
| 916 | apostrophe and hyphens, passes the constraint. It is neutralised by | ||||||||||||||||||||||||||||||||||||||||||
| 917 | C<Database::Abstraction>'s parameterised queries - the value is bound | ||||||||||||||||||||||||||||||||||||||||||
| 918 | as a literal string, never interpolated into SQL. | ||||||||||||||||||||||||||||||||||||||||||
| 919 | |||||||||||||||||||||||||||||||||||||||||||
| 920 | B<Primary defence>: parameterised queries (C<Database::Abstraction>). | ||||||||||||||||||||||||||||||||||||||||||
| 921 | The C<matches> constraint is defence-in-depth only. | ||||||||||||||||||||||||||||||||||||||||||
| 922 | |||||||||||||||||||||||||||||||||||||||||||
| 923 | B<Test coverage>: C<t/cgi_security.t>, section 10. | ||||||||||||||||||||||||||||||||||||||||||
| 924 | |||||||||||||||||||||||||||||||||||||||||||
| 925 | =item * B<Finding 4: C<Genealogy__Wills__directory> environment variable can redirect the data directory> | ||||||||||||||||||||||||||||||||||||||||||
| 926 | |||||||||||||||||||||||||||||||||||||||||||
| 927 | C<Object::Configure> reads environment variables of the form | ||||||||||||||||||||||||||||||||||||||||||
| 928 | C<Genealogy__Wills__key> and merges them into the configuration before | ||||||||||||||||||||||||||||||||||||||||||
| 929 | C<new()> applies defaults. Setting | ||||||||||||||||||||||||||||||||||||||||||
| 930 | C<Genealogy__Wills__directory=/attacker/path> in the process environment | ||||||||||||||||||||||||||||||||||||||||||
| 931 | redirects C<new()> to any SQLite file the attacker can create at that | ||||||||||||||||||||||||||||||||||||||||||
| 932 | path, causing C<search()> to return results from a malicious database. | ||||||||||||||||||||||||||||||||||||||||||
| 933 | |||||||||||||||||||||||||||||||||||||||||||
| 934 | B<Conditions required>: the attacker must control the process environment | ||||||||||||||||||||||||||||||||||||||||||
| 935 | (C<%ENV>) before C<new()> is called. In a CGI context this requires | ||||||||||||||||||||||||||||||||||||||||||
| 936 | compromising the web server's environment-variable namespace, not merely | ||||||||||||||||||||||||||||||||||||||||||
| 937 | sending HTTP headers. | ||||||||||||||||||||||||||||||||||||||||||
| 938 | |||||||||||||||||||||||||||||||||||||||||||
| 939 | B<Mitigation>: ensure the web server or process supervisor sanitises | ||||||||||||||||||||||||||||||||||||||||||
| 940 | C<%ENV> before execution. The C<-d $dir && -r _> check in C<new()> | ||||||||||||||||||||||||||||||||||||||||||
| 941 | prevents non-existent paths but does not block a readable | ||||||||||||||||||||||||||||||||||||||||||
| 942 | attacker-controlled directory. | ||||||||||||||||||||||||||||||||||||||||||
| 943 | |||||||||||||||||||||||||||||||||||||||||||
| 944 | B<Test coverage>: none (requires process-level ENV control; mocked ENV | ||||||||||||||||||||||||||||||||||||||||||
| 945 | in tests does not reach C<Object::Configure>). | ||||||||||||||||||||||||||||||||||||||||||
| 946 | |||||||||||||||||||||||||||||||||||||||||||
| 947 | =item * B<Finding 2 (fixed): C<matches =E<gt> qr/^[\w-]+\z/a> - Unicode and trailing-newline issues resolved> | ||||||||||||||||||||||||||||||||||||||||||
| 948 | |||||||||||||||||||||||||||||||||||||||||||
| 949 | The C<\w> class without C</a> matched Unicode word characters (Cyrillic, | ||||||||||||||||||||||||||||||||||||||||||
| 950 | Greek, Hebrew, etc.), allowing a homograph query such as C<"\x{0430}mith"> | ||||||||||||||||||||||||||||||||||||||||||
| 951 | to pass validation silently (returning zero results, not an error). | ||||||||||||||||||||||||||||||||||||||||||
| 952 | |||||||||||||||||||||||||||||||||||||||||||
| 953 | Additionally, the former C<$> anchor matches before a trailing C<\n>, | ||||||||||||||||||||||||||||||||||||||||||
| 954 | meaning C<"Smith\n"> would have passed the pattern. | ||||||||||||||||||||||||||||||||||||||||||
| 955 | |||||||||||||||||||||||||||||||||||||||||||
| 956 | B<Applied fix>: the schema now uses C<qr/^[\w-]+\z/a>: C</a> restricts | ||||||||||||||||||||||||||||||||||||||||||
| 957 | C<\w> to ASCII C<[0-9A-Za-z_]>, and C<\z> anchors to the absolute | ||||||||||||||||||||||||||||||||||||||||||
| 958 | end-of-string with no C<\n> exception. The C<\-> escape inside C<[]> | ||||||||||||||||||||||||||||||||||||||||||
| 959 | has also been normalised to the idiomatic unescaped C<-> at the end | ||||||||||||||||||||||||||||||||||||||||||
| 960 | of the character class. | ||||||||||||||||||||||||||||||||||||||||||
| 961 | |||||||||||||||||||||||||||||||||||||||||||
| 962 | B<Test coverage>: C<t/cgi_security.t>, section 19. | ||||||||||||||||||||||||||||||||||||||||||
| 963 | |||||||||||||||||||||||||||||||||||||||||||
| 964 | =item * B<Finding 3: caller-supplied logger is silently discarded> | ||||||||||||||||||||||||||||||||||||||||||
| 965 | |||||||||||||||||||||||||||||||||||||||||||
| 966 | C<Object::Configure> always replaces the C<logger> argument with a | ||||||||||||||||||||||||||||||||||||||||||
| 967 | C<Log::Abstraction> instance. A caller who passes a custom logger (for | ||||||||||||||||||||||||||||||||||||||||||
| 968 | example, a C<Log::Log4perl> object) will find it silently ignored. The | ||||||||||||||||||||||||||||||||||||||||||
| 969 | POD documents this parameter, but its effect is a no-op. | ||||||||||||||||||||||||||||||||||||||||||
| 970 | |||||||||||||||||||||||||||||||||||||||||||
| 971 | B<Impact>: this is a usability limitation, not a security risk. | ||||||||||||||||||||||||||||||||||||||||||
| 972 | |||||||||||||||||||||||||||||||||||||||||||
| 973 | B<Test coverage>: C<t/cgi_security.t>, section 15. | ||||||||||||||||||||||||||||||||||||||||||
| 974 | |||||||||||||||||||||||||||||||||||||||||||
| 975 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 976 | |||||||||||||||||||||||||||||||||||||||||||
| 977 | =head1 AUTHOR | ||||||||||||||||||||||||||||||||||||||||||
| 978 | |||||||||||||||||||||||||||||||||||||||||||
| 979 | Nigel Horne, C<< <njh at nigelhorne.com> >> | ||||||||||||||||||||||||||||||||||||||||||
| 980 | |||||||||||||||||||||||||||||||||||||||||||
| 981 | =head1 BUGS | ||||||||||||||||||||||||||||||||||||||||||
| 982 | |||||||||||||||||||||||||||||||||||||||||||
| 983 | Please report bugs at | ||||||||||||||||||||||||||||||||||||||||||
| 984 | L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Genealogy-Wills> | ||||||||||||||||||||||||||||||||||||||||||
| 985 | or by email to C<bug-Genealogy-Wills@rt.cpan.org>. | ||||||||||||||||||||||||||||||||||||||||||
| 986 | |||||||||||||||||||||||||||||||||||||||||||
| 987 | When reporting a bug, please include: | ||||||||||||||||||||||||||||||||||||||||||
| 988 | |||||||||||||||||||||||||||||||||||||||||||
| 989 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 990 | |||||||||||||||||||||||||||||||||||||||||||
| 991 | =item * The version of this module (run C<perl -MGenealogy::Wills -e 'print $Genealogy::Wills::VERSION'>). | ||||||||||||||||||||||||||||||||||||||||||
| 992 | |||||||||||||||||||||||||||||||||||||||||||
| 993 | =item * The version of Perl (run C<perl -V>). | ||||||||||||||||||||||||||||||||||||||||||
| 994 | |||||||||||||||||||||||||||||||||||||||||||
| 995 | =item * A short script that shows the problem. | ||||||||||||||||||||||||||||||||||||||||||
| 996 | |||||||||||||||||||||||||||||||||||||||||||
| 997 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 998 | |||||||||||||||||||||||||||||||||||||||||||
| 999 | =head1 SEE ALSO | ||||||||||||||||||||||||||||||||||||||||||
| 1000 | |||||||||||||||||||||||||||||||||||||||||||
| 1001 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 1002 | |||||||||||||||||||||||||||||||||||||||||||
| 1003 | =item * The Kent Wills Transcript | ||||||||||||||||||||||||||||||||||||||||||
| 1004 | |||||||||||||||||||||||||||||||||||||||||||
| 1005 | L<https://freepages.rootsweb.com/~mrawson/genealogy/wills.html> | ||||||||||||||||||||||||||||||||||||||||||
| 1006 | |||||||||||||||||||||||||||||||||||||||||||
| 1007 | =item * L<Database::Abstraction> -- the SQL layer used internally by this module. | ||||||||||||||||||||||||||||||||||||||||||
| 1008 | |||||||||||||||||||||||||||||||||||||||||||
| 1009 | =item * L<Configure an Object at Runtime|Object::Configure> | ||||||||||||||||||||||||||||||||||||||||||
| 1010 | |||||||||||||||||||||||||||||||||||||||||||
| 1011 | =item * L<Test Dashboard|https://nigelhorne.github.io/Genealogy-Wills/coverage/> | ||||||||||||||||||||||||||||||||||||||||||
| 1012 | |||||||||||||||||||||||||||||||||||||||||||
| 1013 | =item * L<Return::Set> -- enforces return-type contracts on C<search()>. | ||||||||||||||||||||||||||||||||||||||||||
| 1014 | |||||||||||||||||||||||||||||||||||||||||||
| 1015 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 1016 | |||||||||||||||||||||||||||||||||||||||||||
| 1017 | =head1 SUPPORT | ||||||||||||||||||||||||||||||||||||||||||
| 1018 | |||||||||||||||||||||||||||||||||||||||||||
| 1019 | This module is provided as-is without any warranty. | ||||||||||||||||||||||||||||||||||||||||||
| 1020 | |||||||||||||||||||||||||||||||||||||||||||
| 1021 | You can find documentation for this module with the perldoc command: | ||||||||||||||||||||||||||||||||||||||||||
| 1022 | |||||||||||||||||||||||||||||||||||||||||||
| 1023 | perldoc Genealogy::Wills | ||||||||||||||||||||||||||||||||||||||||||
| 1024 | |||||||||||||||||||||||||||||||||||||||||||
| 1025 | Other resources: | ||||||||||||||||||||||||||||||||||||||||||
| 1026 | |||||||||||||||||||||||||||||||||||||||||||
| 1027 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||
| 1028 | |||||||||||||||||||||||||||||||||||||||||||
| 1029 | =item * MetaCPAN | ||||||||||||||||||||||||||||||||||||||||||
| 1030 | |||||||||||||||||||||||||||||||||||||||||||
| 1031 | L<https://metacpan.org/release/Genealogy-Wills> | ||||||||||||||||||||||||||||||||||||||||||
| 1032 | |||||||||||||||||||||||||||||||||||||||||||
| 1033 | =item * RT: CPAN's request tracker | ||||||||||||||||||||||||||||||||||||||||||
| 1034 | |||||||||||||||||||||||||||||||||||||||||||
| 1035 | L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Genealogy-Wills> | ||||||||||||||||||||||||||||||||||||||||||
| 1036 | |||||||||||||||||||||||||||||||||||||||||||
| 1037 | =item * CPAN Testers' Matrix | ||||||||||||||||||||||||||||||||||||||||||
| 1038 | |||||||||||||||||||||||||||||||||||||||||||
| 1039 | L<http://matrix.cpantesters.org/?dist=Genealogy-Wills> | ||||||||||||||||||||||||||||||||||||||||||
| 1040 | |||||||||||||||||||||||||||||||||||||||||||
| 1041 | =item * CPAN Testers Dependencies | ||||||||||||||||||||||||||||||||||||||||||
| 1042 | |||||||||||||||||||||||||||||||||||||||||||
| 1043 | L<http://deps.cpantesters.org/?module=Genealogy::Wills> | ||||||||||||||||||||||||||||||||||||||||||
| 1044 | |||||||||||||||||||||||||||||||||||||||||||
| 1045 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 1046 | |||||||||||||||||||||||||||||||||||||||||||
| 1047 | =encoding utf-8 | ||||||||||||||||||||||||||||||||||||||||||
| 1048 | |||||||||||||||||||||||||||||||||||||||||||
| 1049 | =head1 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||
| 1050 | |||||||||||||||||||||||||||||||||||||||||||
| 1051 | System-level Z-notation for C<Genealogy::Wills>. The C<search()> | ||||||||||||||||||||||||||||||||||||||||||
| 1052 | function's specification also appears in detail under its own section. | ||||||||||||||||||||||||||||||||||||||||||
| 1053 | |||||||||||||||||||||||||||||||||||||||||||
| 1054 | -- Scalar type definitions | ||||||||||||||||||||||||||||||||||||||||||
| 1055 | NAME == seq₁ CHAR -- non-empty character sequence | ||||||||||||||||||||||||||||||||||||||||||
| 1056 | PATHNAME == seq₁ CHAR -- non-empty filesystem path | ||||||||||||||||||||||||||||||||||||||||||
| 1057 | YEAR == 1 .. MaxYear -- positive integer up to the current year | ||||||||||||||||||||||||||||||||||||||||||
| 1058 | |||||||||||||||||||||||||||||||||||||||||||
| 1059 | -- The database object created by new() | ||||||||||||||||||||||||||||||||||||||||||
| 1060 | WillsDatabase | ||||||||||||||||||||||||||||||||||||||||||
| 1061 | directory : PATHNAME | ||||||||||||||||||||||||||||||||||||||||||
| 1062 | cache_duration : seq CHAR | ||||||||||||||||||||||||||||||||||||||||||
| 1063 | records : ℙ WillRecord | ||||||||||||||||||||||||||||||||||||||||||
| 1064 | |||||||||||||||||||||||||||||||||||||||||||
| 1065 | -- Successful construction invariant | ||||||||||||||||||||||||||||||||||||||||||
| 1066 | ┌ InitWillsDatabase ─────────────────────────────────┐ | ||||||||||||||||||||||||||||||||||||||||||
| 1067 | │ WillsDatabase │ | ||||||||||||||||||||||||||||||||||||||||||
| 1068 | │ ────────────────────────────────────────────────── │ | ||||||||||||||||||||||||||||||||||||||||||
| 1069 | │ ∃ d : PATHNAME • directory = d ∧ is_readable(d) │ | ||||||||||||||||||||||||||||||||||||||||||
| 1070 | │ cache_duration = "1 day" │ | ||||||||||||||||||||||||||||||||||||||||||
| 1071 | │ records = load_sqlite(directory ++ "/wills.sql") │ | ||||||||||||||||||||||||||||||||||||||||||
| 1072 | └─────────────────────────────────────────────────────┘ | ||||||||||||||||||||||||||||||||||||||||||
| 1073 | |||||||||||||||||||||||||||||||||||||||||||
| 1074 | =head2 search | ||||||||||||||||||||||||||||||||||||||||||
| 1075 | |||||||||||||||||||||||||||||||||||||||||||
| 1076 | The following Z-notation gives the precise mathematical meaning of C<search()>. | ||||||||||||||||||||||||||||||||||||||||||
| 1077 | Optional fields that the caller did not supply are modelled as undefined. | ||||||||||||||||||||||||||||||||||||||||||
| 1078 | |||||||||||||||||||||||||||||||||||||||||||
| 1079 | -- Type aliases | ||||||||||||||||||||||||||||||||||||||||||
| 1080 | NAME == seq₁ CHAR -- a non-empty sequence of characters | ||||||||||||||||||||||||||||||||||||||||||
| 1081 | YEAR == 1 .. MaxYear -- positive integer bounded by current year | ||||||||||||||||||||||||||||||||||||||||||
| 1082 | |||||||||||||||||||||||||||||||||||||||||||
| 1083 | -- One record stored in the database | ||||||||||||||||||||||||||||||||||||||||||
| 1084 | WillRecord | ||||||||||||||||||||||||||||||||||||||||||
| 1085 | first : NAME | ||||||||||||||||||||||||||||||||||||||||||
| 1086 | last : NAME | ||||||||||||||||||||||||||||||||||||||||||
| 1087 | middle : NAME | undefined | ||||||||||||||||||||||||||||||||||||||||||
| 1088 | town : NAME | undefined | ||||||||||||||||||||||||||||||||||||||||||
| 1089 | year : YEAR | undefined | ||||||||||||||||||||||||||||||||||||||||||
| 1090 | url : NAME -- stored without "https://"; prefixed by search() | ||||||||||||||||||||||||||||||||||||||||||
| 1091 | |||||||||||||||||||||||||||||||||||||||||||
| 1092 | -- Parameters passed to search() | ||||||||||||||||||||||||||||||||||||||||||
| 1093 | SearchParams | ||||||||||||||||||||||||||||||||||||||||||
| 1094 | last : NAME | ||||||||||||||||||||||||||||||||||||||||||
| 1095 | first : NAME | undefined | ||||||||||||||||||||||||||||||||||||||||||
| 1096 | middle : NAME | undefined | ||||||||||||||||||||||||||||||||||||||||||
| 1097 | town : NAME | undefined | ||||||||||||||||||||||||||||||||||||||||||
| 1098 | year : YEAR | undefined | ||||||||||||||||||||||||||||||||||||||||||
| 1099 | |||||||||||||||||||||||||||||||||||||||||||
| 1100 | -- Invariant: last name must be non-empty | ||||||||||||||||||||||||||||||||||||||||||
| 1101 | ┌ SearchParams ──────────────────┐ | ||||||||||||||||||||||||||||||||||||||||||
| 1102 | │ last : NAME │ | ||||||||||||||||||||||||||||||||||||||||||
| 1103 | │ ───────────────────────────── │ | ||||||||||||||||||||||||||||||||||||||||||
| 1104 | │ last ≠ ⟨⟩ │ | ||||||||||||||||||||||||||||||||||||||||||
| 1105 | └────────────────────────────────┘ | ||||||||||||||||||||||||||||||||||||||||||
| 1106 | |||||||||||||||||||||||||||||||||||||||||||
| 1107 | -- Predicate: does record r satisfy all supplied parameters? | ||||||||||||||||||||||||||||||||||||||||||
| 1108 | matches : WillRecord × SearchParams → BOOL | ||||||||||||||||||||||||||||||||||||||||||
| 1109 | matches(r, p) == | ||||||||||||||||||||||||||||||||||||||||||
| 1110 | r.last = p.last | ||||||||||||||||||||||||||||||||||||||||||
| 1111 | ∧ (p.first = undefined ∨ r.first = p.first) | ||||||||||||||||||||||||||||||||||||||||||
| 1112 | ∧ (p.middle = undefined ∨ r.middle = p.middle) | ||||||||||||||||||||||||||||||||||||||||||
| 1113 | ∧ (p.town = undefined ∨ r.town = p.town) | ||||||||||||||||||||||||||||||||||||||||||
| 1114 | ∧ (p.year = undefined ∨ r.year = p.year) | ||||||||||||||||||||||||||||||||||||||||||
| 1115 | |||||||||||||||||||||||||||||||||||||||||||
| 1116 | -- Function signature | ||||||||||||||||||||||||||||||||||||||||||
| 1117 | search : WillsDatabase × SearchParams → ℙ WillRecord | ||||||||||||||||||||||||||||||||||||||||||
| 1118 | |||||||||||||||||||||||||||||||||||||||||||
| 1119 | -- When last is non-empty, return all records that match | ||||||||||||||||||||||||||||||||||||||||||
| 1120 | ∀ db : WillsDatabase; p : SearchParams • | ||||||||||||||||||||||||||||||||||||||||||
| 1121 | p.last ≠ ⟨⟩ ⟹ | ||||||||||||||||||||||||||||||||||||||||||
| 1122 | search(db, p) = { r : WillRecord | r ∈ db.records ∧ matches(r, p) } | ||||||||||||||||||||||||||||||||||||||||||
| 1123 | |||||||||||||||||||||||||||||||||||||||||||
| 1124 | -- When last is empty, return nothing | ||||||||||||||||||||||||||||||||||||||||||
| 1125 | ∀ db : WillsDatabase; p : SearchParams • | ||||||||||||||||||||||||||||||||||||||||||
| 1126 | p.last = ⟨⟩ ⟹ | ||||||||||||||||||||||||||||||||||||||||||
| 1127 | search(db, p) = ∅ | ||||||||||||||||||||||||||||||||||||||||||
| 1128 | |||||||||||||||||||||||||||||||||||||||||||
| 1129 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||||||||||||||||||||||||
| 1130 | |||||||||||||||||||||||||||||||||||||||||||
| 1131 | Copyright 2023-2026 Nigel Horne. | ||||||||||||||||||||||||||||||||||||||||||
| 1132 | |||||||||||||||||||||||||||||||||||||||||||
| 1133 | Usage is subject to the GPL2 licence terms. | ||||||||||||||||||||||||||||||||||||||||||
| 1134 | If you use it, please let me know. | ||||||||||||||||||||||||||||||||||||||||||
| 1135 | |||||||||||||||||||||||||||||||||||||||||||
| 1136 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 1137 | |||||||||||||||||||||||||||||||||||||||||||
| 1138 | 13 | 1; | |||||||||||||||||||||||||||||||||||||||||