From 49c9bdd992f16caf995b3840836898145305ac75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C5=8Dan?= Date: Fri, 1 May 2026 06:46:09 -0600 Subject: [PATCH] fix: improve POD accuracy and add explicit -s guard for consistency - Document CHECK_IS_NULL in the "Check helpers" section (was exported but undocumented, leaving users unaware of how to signal "file not found") - Fix NV op description: -M/-C/-A return fractional days, not integers - Document that stat hash keys accept bare forms (uid, size) in addition to st_* prefixed forms, and that unknown keys are rejected - Update outdated "very early development stage" notice - Fix two broken internal POD links (/"Mocking stat", /" Mocking all...") - Add explicit CHECK_IS_NULL guard to -s handler in _check_from_stat for consistency with -e, -M, -C, -A, -T, -B handlers (behavior was already correct via accidental undef propagation through _check) Co-Authored-By: Claude Opus 4.6 --- lib/Overload/FileCheck.pm | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/lib/Overload/FileCheck.pm b/lib/Overload/FileCheck.pm index 5034976..e95a6b5 100644 --- a/lib/Overload/FileCheck.pm +++ b/lib/Overload/FileCheck.pm @@ -368,7 +368,7 @@ sub _check_from_stat { # Existence and size (computed directly from cached stat) e => sub { return CHECK_IS_NULL unless scalar @stat; CHECK_IS_TRUE }, # file exists (stat success implies existence) - s => sub { $stat[ST_SIZE] }, # nonzero size (returns bytes); fallback breaks on symlinks + s => sub { return CHECK_IS_NULL unless scalar @stat; $stat[ST_SIZE] }, # nonzero size (returns bytes); fallback breaks on symlinks # File type checks via mode bits (using @stat — follows symlinks) f => sub { _check_mode_type( $stat[ST_MODE], S_IFREG ) }, # plain file @@ -823,14 +823,16 @@ In your callback function you should use the following helpers to return. =item B: use this constant when the test is false -=item B: use this when you the test is true +=item B: use this when the test is true + +=item B: return this when the file does not exist (the -X op returns undef to the caller, and errno is set automatically) =item B: you want to delegate the answer to Perl itself :-) =back -It's also possible to return one integer. Checks like C<-s>, C<-M>, C<-C>, C<-A> can return -any integers. +It's also possible to return a numeric value. C<-s> returns the file size in bytes. +C<-M>, C<-C>, and C<-A> return the file age in (fractional) days. Example: @@ -892,7 +894,8 @@ When mocking stat or lstat function your callback function should return one of =item or an empty ARRAY Ref, if the file does not exist =item or one HASH ref using one or more of the following keys: st_dev, st_ino, st_mode, st_nlink, - st_uid, st_gid, st_rdev, st_size, st_atime, st_mtime, st_ctime, st_blksize, st_blocks + st_uid, st_gid, st_rdev, st_size, st_atime, st_mtime, st_ctime, st_blksize, st_blocks. + The C prefix is optional and case-insensitive (e.g., C, C, and C are all equivalent) =item or return FALLBACK_TO_REAL_OP when you want to let Perl take back the control for that file @@ -980,6 +983,8 @@ Available functions are: All of these functions take some optional arguments to set: uid, gid, perms, dev, ino, nlink, rdev, size, atime, mtime, ctime, blksize, blocks. +C and C accept both numeric IDs and names (e.g., C<< gid => 'root' >>). +Unknown option keys will cause a fatal error to catch typos early. Example: use Overload::FileCheck -from-stat => \&my_stat, q{:check}; @@ -1059,7 +1064,7 @@ mock_stat provides one interface to setup a hook for all C and C ca It's slighly different than the other mock functions. As the first argument passed to the hook function would be a string 'stat' or 'lstat'. -You can get a more advanced hook sample from L. +You can get a more advanced hook sample from L. use Overload::FileCheck q(:all); @@ -1085,7 +1090,7 @@ By calling unmock_stat, you would disable any previous hook set using mock_stat By providing a single hook for 'stat' and 'lstat' you let OverLoad::FileCheck take care of mocking all other -X checks. -read L for sample usage. +read L for sample usage. =head2 stat_as_directory( %OPTS ) @@ -1125,7 +1130,8 @@ view stat_as_directory and L for some sample usages =head1 Notice -This is a very early development stage and some behavior might change before the release of a more stable build. +The API is stabilizing but may still evolve in minor ways. Please report +issues at the GitHub repository. =head1 Known Limitations