Wills.pm

filter: Statementstmt 98.1% 104 / 106 Branchbran 96.1% 25 / 26 Conditioncond 92.5% 25 / 27 MC/DCmcdc 81.2% 13 / 16 Subroutinesub 100% 18 / 18 Podpod 100% 2 / 2 totaltotal 95.9% 187 / 195 CC 25 SCAR 21.6
CC
25
Cov
97%
new
15.0
search
11.1
BEGIN
1.0
CRAP 8.7
↑ Summary Wills/wills.pm »
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
BranchTrueFalseTotal
if (scalar @_ == 1 and not ref $_[0]) { } 4 131 135
Condition100%3/3
scalar @_ == 1 and not ref $_[0]
!ll&&!rl&&r
12744
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]
ABresult
0X0
100
111
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
BranchTrueFalseTotal
if (not defined $class) { } 2 133 135
elsif (builtin::blessed($class)) { } 8 125 133
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 // {}
l!l
62
MC/DC100%1/1
$params // {}
$params
Truth table100%2/2
A
A= $params
Aresult
11
00
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
BranchTrueFalseTotal
if (defined $$params{"config_file"} and not -r $$params{"config_file"}) 9 118 127
Condition100%3/3
defined $$params{"config_file"} and not -r $$params{"config_file"}
!ll&&!rl&&r
108109
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"}
ABresult
0X0
100
111
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
BranchTrueFalseTotal
if (defined $$params{"logger"}) 15 103 118
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
BranchTrueFalseTotal
unless builtin::blessed($l) and $l->can("info") and $l->can("error") 11 4 15
Condition100%6/6
builtin::blessed($l) and $l->can("info") and $l->can("error")
!ll&&!rl&&r
834
builtin::blessed($l) and $l->can("info")
!ll&&!rl&&r
357
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")
ABCresult
0XX0
10X0
1100
1111
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
l!l&&r!l&&!r
9890
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
ABresult
1X1
011
000
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
BranchTrueFalseTotal
unless (-d $$params{"directory"} and -r _) 15 92 107
Condition100%3/3
-d $$params{"directory"} and -r _
!ll&&!rl&&r
14192
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 _
ABresult
0X0
100
111
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
BranchTrueFalseTotal
unless builtin::blessed($self) 7 146 153
649 146 ▶ Carp::croak('Usage: search({ last => $last_name })') unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 6 140 146
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
BranchTrueFalseTotal
unless (length($$params{"last"} // "")) 0 50 50
Condition50%1/2
$$params{"last"} // ""
l!l
500
MC/DC0%0/1
$$params{"last"} // ""
$$params{"last"}
Truth table50%1/2
A
A= $$params{"last"}
Aresult
11
00
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;})
l!l&&r!l&&!r
17312
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;})
ABresult
1X1
011
000
670  
671 50 ▶ Carp::croak("Can't open the wills database") unless defined($self->{'wills'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $$self{"wills"} 2 48 50
672  
673 48 ▶ if(wantarray) {
Branch: 1 branch
BranchTrueFalseTotal
if (wantarray) 39 9 48
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) // []
l!l
371
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)
Aresult
11
00
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
BranchTrueFalseTotal
if (defined(my $will = $$self{"wills"}->fetchrow_hashref($params))) 3 5 8
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;
↑ Summary Wills/wills.pm »