File Coverage

=head1 NAME

Sub::Protected - Enforce protected subroutine access (Java/C++ semantics)

=head1 VERSION

0.03

=head1 SYNOPSIS

    package Foo;
    use Sub::Protected;              # enables the :Protected attribute

    sub new { bless {}, shift }

    # Attribute form (preferred: protection lives next to the definition)
    sub _helper :Protected {
        ...
    }

    sub public_method {
        my $self = shift;
        $self->_helper;              # OK -- same package
    }

    # ----------------------------------------------------------------

    package Bar;
    use Sub::Protected qw(_other _private);   # declarative form

    sub _other   { 'other'   }
    sub _private { 'private' }

=head1 DESCRIPTION

Enforces Java/C++-style "protected" access at runtime: a subroutine
decorated with C<:Protected> (or named in C<use Sub::Protected qw(...)>)
may only be called from within its defining package or from a subclass of
that package.  Any other caller causes a C<Carp::croak> with a descriptive
message.

=head2 Two usage forms

=over 4

=item Attribute form (preferred)

    sub _helper :Protected { ... }

The C<:Protected> attribute is registered in C<UNIVERSAL> via
L<Attribute::Handlers> when C<Sub::Protected> is loaded, so every package
has access to it without any further C<use> or inheritance.  The sub is
wrapped at C<CHECK> time, or, if the module is loaded after C<CHECK> (Perl
5.14 or later), at the end of the file being compiled.  This form is preferred because the protection
declaration sits next to the definition and wrapping happens at compile time
(making pre-wrap raw-coderef captures impossible).

=item Declarative form

    use Sub::Protected qw(_helper _other);

Each named sub is looked up in the caller's stash and wrapped at C<CHECK>
time (or immediately if the module is loaded at runtime via C<require>).
All named subs must be defined before C<CHECK> fires -- i.e. they must be
compile-time named subs in the same file, not generated at runtime.

=back

=head2 Bypass for testing

Either condition alone (OR logic) disables all access checks:

=over 4

=item * C<$Sub::Protected::BYPASS> set to a true value.  Use C<local> in tests.

=item * C<$ENV{HARNESS_ACTIVE}> set (the convention used by L<Test::Harness>/prove).

=back

C<$Sub::Protected::BYPASS> is the recommended form for new test code;
it is explicit and does not depend on the test runner.
C<HARNESS_ACTIVE> is a zero-config convenience.

The HARNESS_ACTIVE bypass can be disabled by setting:

    $Sub::Protected::config{harness_bypass} = 0;

=head2 Configuration

The module exposes C<%Sub::Protected::config> for runtime configuration:

=over 4

=item C<harness_bypass> (default: 1)

When true, access checks are skipped whenever C<$ENV{HARNESS_ACTIVE}> is
set.  Set to 0 to test protection behaviour from within a test harness.

=back

The hash is compatible with L<Object::Configure> for dependency-injection
scenarios.

=head2 Error message format

    _helper() is a protected method of Foo and cannot be called from Bar

The error is raised with L<Carp/croak>, so it reports the file and line of
the offending call, not a line inside Sub::Protected.

=head2 How access is decided

=over 4

=item * Only the immediate caller counts

The decision is made on the package of the code that called the protected
sub.  If C<Bar::run> calls C<Foo::public>, which calls C<Foo::_helper>, the
call is allowed: the immediate caller is C<Foo>.  If C<Foo::public> instead
calls a C<Bar> method that calls C<Foo::_helper>, it is blocked, however
deep the chain.

=item * Subclasses are allowed

A caller whose package C<isa> the owner is allowed, so calls through
C<SUPER::>, C<< $self->can('_helper') >> and ordinary inherited method
calls all work from a subclass.

=item * The wrapper is invisible

The wrapper hands over with C<goto &sub>, so inside the protected sub
C<caller()> reports the real caller, not Sub::Protected.  Arguments
(including aliasing of C<@_>), calling context (list, scalar or void) and
return values, including false ones, pass through unchanged.

=back

=head1 PUBLIC INTERFACE

=head2 import

    use Sub::Protected;                    # attribute form -- no arguments
    use Sub::Protected qw(_a _b _c);      # declarative form

=head3 Purpose

Called automatically by C<use Sub::Protected>.

With B<no arguments>: does nothing beyond making the C<:Protected> attribute
globally available (which happens when the module is first loaded).

With B<one or more sub names>: registers those subs in the calling
package for wrapping at C<CHECK> time.  If C<CHECK> has already fired
(e.g. the module was loaded via runtime C<require>, a plugin loader or a
string C<eval>), wrapping is applied immediately.
Each named sub must be defined before C<CHECK> fires (for pre-CHECK loads)
or before C<import> is called (for post-CHECK loads), so a module loaded at
run time should call C<< Sub::Protected->import(...) >> at the end of the
file, after its subs are defined.

Run-time loading needs Perl 5.14 or later.  On older Perls the module must
be loaded at compile time (C<use>, or C<require> inside C<BEGIN>).

=head3 Arguments

=over 4

=item C<$class> (positional, required)

The name of the importing class.  Set automatically by the C<use> mechanism.
Must be a non-empty string.

=item C<@subs> (positional, optional)

Zero or more sub names to protect in the calling package.  Each must be a
valid Perl identifier: matching C</\A[_a-zA-Z]\w*\z/>.

These calls are equivalent:

    Sub::Protected->import(qw(_a _b));
    Sub::Protected->import([ qw(_a _b) ]);
    Sub::Protected->import({ subs => [ qw(_a _b) ] });

A plain list is always a list of names, so C<qw(subs _x)> protects both
C<subs> and C<_x>.  A single arrayref or hashref is normalised by
L<Params::Get>.

=back

=head3 Returns

C<$class> (the importing class name).  The return value is ignored by the
C<use> mechanism; it is provided for optional method chaining at the class
level.

=head3 Side effects

=over 4

=item *

Each supplied sub name is appended to an internal pending list (if pre-CHECK)
or wrapped immediately (if post-CHECK).

=item *

The pending list is consumed and cleared when the CHECK block fires.

=item *

C<$@>, C<$!> and C<$_> are left unchanged, as are any pending C<alarm()>
timers.

=back

=head3 Example

    package Foo;
    use Sub::Protected qw(_helper _init);

    sub _helper { ... }   # will be protected
    sub _init   { ... }   # will be protected

=head3 API SPECIFICATION

=head4 Input

    # Params::Get::get_params / Params::Validate::Strict schema
    {
        # class is the implicit first argument, set by Perl's 'use' mechanism
        subs => {
            type     => 'array',
            required => 0,
            each     => {
                type  => 'string',
                regex => qr/\A[_a-zA-Z]\w*\z/,
            },
        },
    }

=head4 Output

    # Return::Set schema
    {
        type    => 'string',
        desc    => 'The importing class name ($class), for optional chaining.',
    }

=head3 MESSAGES

The following table lists every error or warning this method can produce.

    Message                                     Meaning
    ----------------------------------------    -------------------------------------
    "Sub::Protected->import: 'NAME' is not a    A sub name passed to import() failed
     valid Perl identifier"                      the identifier regex.  Use a name
                                                 matching /\A[_a-zA-Z]\w*\z/.
                                                 NAME is shown as '' when the
                                                 name was undef or a reference.

    "Sub::Protected: PKG::NAME is not defined"  The named sub was not found in the
                                                 package stash at wrap time.  For
                                                 pre-CHECK loads, ensure the sub is
                                                 a compile-time named sub.  For
                                                 post-CHECK/runtime loads, ensure
                                                 the sub is defined before import().

Calling a protected sub from outside its package or subclasses croaks
with the message shown in L</Error message format>.

=encoding utf8

=head3 FORMAL SPECIFICATION

    ValidName ≙ { n : seq CHAR | n matches /\A[_a-zA-Z]\w*\z/ }

    â”Œâ”€ Import ──────────────────────────────────────────
    â”‚ ΔRegistry
    â”‚ class? : Package ; caller? : Package
    â”‚ names? : seq SubName ; postCheck : 𝔹
    â”‚ result! : Package
    â”œâ”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€â”€
    â”‚ ∀ n ∈ ran names? • n ∈ ValidName
    â”‚ postCheck ⇒ (∀ n ∈ ran names? • defined(caller?, n))
    â”‚ postCheck ⇒ protected′ = protected ∪ { n : ran names? • (caller?, n) }
    â”‚ ¬postCheck ⇒ pending′ = pending ⁀ ⟨ n : names? • (caller?, n) ⟩
    â”‚ result! = class?
    â””───────────────────────────────────────────────────

    -- Failure cases (croak, Registry unchanged):
    --   âˆƒ n ∈ ran names? • n ∉ ValidName
    --     â‡’ "Sub::Protected->import: 'n' is not a valid Perl identifier"
    --   postCheck ∧ ∃ n ∈ ran names? • ¬defined(caller?, n)
    --     â‡’ "Sub::Protected: caller?::n is not defined"

=cut