Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,5 @@ pm_to_blib
inc/inc_*
inc/latest*
Params-Util-*
t/pp/
t/xs/
95 changes: 95 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development environment

All Perl/build operations run inside the Docker dev container. Do not install Perl, cpanm, or build deps on the host.

```sh
docker ps # confirm params-util-dev-1 is running
docker exec params-util-dev-1 sh -ec 'cd /workspace && <command>'
```

The container mounts the repo read-write at `/workspace`. The `perl-5.30`...`perl-5.42` Compose services exist for cross-version testing but mount the workspace **read-only** (and `cp -a` to `/tmp/build` first), so use the `dev` service for active work.

## Common commands

```sh
# Inside the container (`docker exec params-util-dev-1 sh -ec 'cd /workspace && ...'`):
perl Makefile.PL # regenerates t/pp and t/xs from t/inline (see below)
make # compiles XS
make test # full suite incl. xt/ author tests
make manifest # regenerate MANIFEST after adding files
make realclean # nukes generated tests + build artifacts

prove -lbv t/xs/02_main.t # single test file (after `make`)
prove -lbv t/inline/10_leaks.t # leak tests need Test::LeakTrace

perltidy -b <file> # in-place tidy; remove the .bak afterwards
podchecker lib/Params/Util/<f> # POD validation
```

## Architecture

### Dual PP/XS implementation

`Params::Util` ships both a Pure-Perl backend (`lib/Params/Util/PP.pm`) and an XS backend (`Util.xs`). The loader in `lib/Params/Util.pm` falls back to PP for any function not present in the XS module:

```perl
Params::Util->can($_) or *$_ = Params::Util::PP->can($_) for (@EXPORT_OK);
```

`PERL_PARAMS_UTIL_PP=1` forces PP at runtime. **Any new predicate must exist in PP**; XS is an optional accelerator.

### XS uses ALIAS groups (ADR-005)

Functions that share logic differing only by the called Perl method or by a small validation switch live in one C body, dispatched via `ix`:

- Group 1 (`_IDENTIFIER`/`_CLASS`) — string validators
- Group 2 (`_POSINT`/`_NONNEGINT`) — numeric validators
- Group 3 (`_CLASSISA`/`_CLASSDOES`/`_CLASSCAN`/`_SUBCLASS`) — class + `call_method`
- Group 4 (`_INSTANCE`/`_INSTANCEDOES`/`_INSTANCECAN`) — `sv_isobject` + `call_method`
- Group 5 (`_INVOCANT`/`_INVOCANTCAN`) — invocant check + optional `call_method`

When adding a sibling predicate to one of these groups, add an `ALIAS:` line and an entry in the static `methods[]` table — do **not** copy a whole new XSUB.

`_HANDLE`, `_DRIVER`, `_SET`, `_SET0` are intentionally PP-only (see ADR-005).

### Tests are generated — `t/inline/` is canonical (ADR-001)

`t/pp/` and `t/xs/` are gitignored. They are regenerated by `Sandbox/Tumble.pm` at every `perl Makefile.PL` run and shipped in `MANIFEST` so CPAN consumers do not need `Test::WriteVariants`.

**Edit only `t/inline/*.t`.** Variants differ solely in the `BEGIN { $ENV{PERL_PARAMS_UTIL_PP} = 0|1; }` preamble that Tumble injects.

After adding a test file: `make manifest` to register `t/inline/`, `t/pp/`, and `t/xs/` versions.

The test fixture classes at the tail of `t/inline/02_main.t` are deliberately asymmetric:

- `Foo` — has `sub foo`
- `Bar` — `@ISA = 'Foo'` (real inheritance, inherits `foo`)
- `Baz` — overrides `isa` to fake `isa('Foo')` but has **no** `foo` method
- `Bad` — unrelated, only has `sub bad`

`Baz` is the discriminator between `_ISA` (which trusts the faked `isa`) and `_CAN`/`_DOES` (which see no actual method). Tests that exercise `_CAN`/`_DOES` against `@objects` must filter — e.g. `grep { $_->can('foo') } @objects` — or they will fail on the three Baz blessings.

### Architecture Decision Records

`lib/Params/Util/ADR-NNN.pod` (Nygard format: Status / Context / Decision / Consequences). Existing ADRs cover Test::WriteVariants (001), multi-method `_CAN`/`_DOES` deferral (002), `Params::Util::Assert` deferral (003), `Test::Params::Util` as separate dist (004), XS ALIAS consolidation (005). When making a non-trivial design choice, write an ADR rather than burying the rationale in a commit.

## Author-test gates

`make test` runs `xt/*.t` which can fail on otherwise-correct code:

- **`xt/perltidy.t`** — generated `t/pp`/`t/xs` are excluded; `Sandbox/`, inline tests, and ADR pods are checked. Run `perltidy -b <file>` to fix; perltidy's brace placement is the authority, do not hand-format.
- **`xt/spelling.t`** — every novel proper noun (`ADR`, `arity`, `validators`, ...) needs a stopword in `xt/spelling.t`'s `__DATA__` block.
- **`xt/manifest.t`** — run `make manifest` after adding/renaming files.
- **`xt/pod.t`/`pod-coverage.t`** — keep the SYNOPSIS predicate list in `lib/Params/Util.pm` synchronised with `@EXPORT_OK`.

POD with em-dashes/curly quotes fails podchecker without an `=encoding` line. Stick to ASCII (`--`, `'`, `"`) in pods.

## Conventions

- **Commits** use `git commit --signoff`, Chris Beams style (imperative subject ≤ 50 chars, body explains *why*). Pass multi-line messages via a `.git-commit-msg` file (HEREDOC corrupts the backticks); delete the file after committing. Include the `Co-Authored-By: Claude Opus <noreply@anthropic.com>` trailer.
- **No emoji** in code, comments, or pods unless explicitly requested.
- The leak-test suite (`t/inline/10_leaks.t`) must stay green for every XS change that touches `call_method`/stack handling.
26 changes: 26 additions & 0 deletions Changes
Original file line number Diff line number Diff line change
@@ -1,5 +1,31 @@
Revision history for Perl extension Params-Util

1.105_001 2026-05-02
- Bump to 1.105_001 to get over shadowing ETHER/1.103_01
- add _CLASSCAN, _INSTANCECAN and _INVOCANTCAN predicates to
resolve the UNIVERSAL::can debacle by calling ->can as a method
rather than as a function, respecting any overridden can() in
the invocant's class hierarchy.
- consolidate the XS layer using XSUB ALIAS groups (ADR-005):
string validators (_IDENTIFIER/_CLASS), numeric validators
(_POSINT/_NONNEGINT), class dispatchers (_CLASSISA/_CLASSDOES/
_CLASSCAN/_SUBCLASS), instance dispatchers (_INSTANCE/
_INSTANCEDOES/_INSTANCECAN), and invocant dispatchers
(_INVOCANT/_INVOCANTCAN). All previously PP-only predicates
except _SET/_SET0/_HANDLE/_DRIVER now have XS accelerators.
- replace hand-maintained t/pp and t/xs trees with a
Test::WriteVariants pipeline driven by Sandbox/Tumble.pm
(ADR-001). Canonical tests live in t/inline/; backend variants
are generated at `perl Makefile.PL` time and shipped in the
distribution so CPAN consumers do not need Test::WriteVariants.
- add memory-leak coverage (t/inline/10_leaks.t) exercising both
success and failure paths through call_method to verify
ENTER/SAVETMPS/FREETMPS/LEAVE handling is leak-free.
- document open design decisions as ADRs in lib/Params/Util/
(ADR-001..005, Nygard format).
- update SUPPORT section to point to GitHub Issues as the primary
bug tracker; RT remains as historical reference.

1.103_001 2026-05-01
- fix #3 / RT#75561: XS variants of _HASH/_HASH0/_ARRAY/_ARRAY0
now reject blessed references, matching the documented "raw and
Expand Down
2 changes: 1 addition & 1 deletion MANIFEST.SKIP
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ _Inline/.*
^tmp/
^testdata/
^blib/
^sandbox/
^[Ss]andbox/
^pm_to_blib$
^cover_db/
nytprof*/
Expand Down
15 changes: 14 additions & 1 deletion Makefile.PL
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,17 @@ BEGIN
use inc::latest 'Capture::Tiny';
use inc::latest 'Config::AutoConf';

if (-d 'Sandbox')
{
eval "use Sandbox::Tumble ();";
$@ and die $@;
eval "use File::Path ();";
File::Path->import;
-d 't/pp' and rmtree('t/pp');
-d 't/xs' and rmtree('t/xs');
Sandbox::Tumble->tumble(qw(t));
}

unless (-f "META.yml")
{
if (inc::latest->can("write"))
Expand Down Expand Up @@ -98,6 +109,7 @@ WriteMakefile1(
'Test::Pod::Coverage' => 0,
'Test::Pod::Spelling::CommonMistakes' => 0,
'Test::Spelling' => 0,
'Test::WriteVariants' => '0.014',
},
},
configure => {
Expand All @@ -122,7 +134,8 @@ WriteMakefile1(
depend => {'$(FIRST_MAKEFILE)' => '$(VERSION_FROM)'},
test => {TESTS => join(' ', 't/pp/*.t', ($loadable_xs ? 't/xs/*.t' : ()), 'xt/*.t')},
# Otherwise 'cxinc' isn't defined
($] < 5.012 ? (DEFINE => '-DPERL_EXT') : (),),
($] < 5.012 ? (DEFINE => '-DPERL_EXT') : (),),
(-d 'Sandbox' ? (realclean => {FILES => join(' ', 't/pp', 't/xs', 'inc/latest* inc/inc_*', 'config.log', 'M*.bak')}) : ()),
);

sub WriteMakefile1
Expand Down
60 changes: 60 additions & 0 deletions Sandbox/Tumble.pm
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
package Sandbox::Tumble;

use strict;
use warnings;

use Cwd qw();
use File::Spec qw();
use Test::WriteVariants 0.014;

use FindBin qw();

$| = 1;

sub tumble
{
my ($class, $output_dir) = @_;

my $template_dir = Cwd::abs_path(File::Spec->catdir($FindBin::RealBin, "t"));
my $test_writer = Test::WriteVariants->new();
$test_writer->allow_dir_overwrite(1);
$test_writer->allow_file_overwrite(1);

$test_writer->write_test_variants(
input_tests => $test_writer->find_input_inline_tests(
search_patterns => ["*.t"],
search_dirs => ["t/inline"],
),
variant_providers => ["PU::TestVariants"],
output_dir => $output_dir,
);
}

package PU::TestVariants::Backend;

use strict;
use warnings;

sub provider
{
my ($self, $path, $context, $tests, $variants) = @_;
my $strict = $context->new_module_use(strict => [qw(subs vars refs)]);
my $warnings = $context->new_module_use(warnings => ['all']);

$variants->{pp} = $context->new(
$context->new_env_var(
PERL_PARAMS_UTIL_PP => 1,
),
$warnings,
$strict,
);
$variants->{xs} = $context->new(
$context->new_env_var(
PERL_PARAMS_UTIL_PP => 0,
),
$warnings,
$strict,
);
}

1;
Loading