File Coverage

=head1 NAME

Sub::Private - Private subroutines and methods

=head1 VERSION

Version 0.05

=cut

=head1 SYNOPSIS

    package Foo;
    use Sub::Private;

    sub foo { return 42 }

    sub bar :Private {
        return foo() + 1;
    }

    sub baz {
        return bar() + 1;
    }

=head1 DESCRIPTION

Enforces strictly private access on subroutines.  A subroutine decorated
with C<:Private> (or named in C<use Sub::Private qw(...)> when in enforce
mode) may only be called from within its defining package.  Subclasses do
not inherit access: private means I<this package only>.

=head2 Two enforcement modes

=over 4

=item C<namespace> mode (default, backward-compatible)

Removes the subroutine from the package symbol table using
L<namespace::clean>.  Direct (non-method) function calls compiled before
cleanup still work because Perl optimises them to direct opcode references.
OO method dispatch (C<$self->name>) does not work for private subs in this
mode because method lookup uses the symbol table at runtime.

This is the default mode and is backward-compatible with all existing code.

=item C<enforce> mode (OO-safe, opt-in)

Replaces the subroutine with a wrapper closure that checks C<caller> at
call time and either delegates (owner package) or croaks (anyone else).
Works correctly with OO dispatch (C<$self->_helper>).

Enable before declaring your first private sub:

    BEGIN { $Sub::Private::config{mode} = 'enforce' }
    package MyClass;
    use Sub::Private;
    sub _helper :Private { ... }

=back

=head2 Bypass for testing

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

=over 4

=item * C<$Sub::Private::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::Private::BYPASS> is the recommended form for new test code.
The C<HARNESS_ACTIVE> bypass can be disabled:

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

=head2 Configuration

    $Sub::Private::config{mode}            -- 'namespace' (default) or 'enforce'
    $Sub::Private::config{harness_bypass}  -- 1 (default); set to 0 to test enforcement

=head2 Error message format (enforce mode)

    bar() is a private subroutine of Foo and cannot be called from Bar

=cut

=head1 PUBLIC INTERFACE

=head2 import

    use Sub::Private;                    # attribute form -- no arguments
    use Sub::Private qw(_a _b _c);      # declarative form (enforce mode only)

=head3 Purpose

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

With B<no arguments>: makes the C<:Private> attribute globally available
via C<UNIVERSAL>.  No other action is taken.

With B<one or more sub names>: registers those named subs in the calling
package for access-enforcement wrapping at C<CHECK> time.  If C<CHECK>
has already fired (e.g., when calling from a test), wrapping is applied
immediately.  Requires C<$Sub::Private::config{mode}> to equal
C<'enforce'>; croaks otherwise.

=head3 Arguments

=over 4

=item C<@subs> (optional)

Zero or more Perl sub names.  Each must be a defined, non-reference scalar
matching C</\A[_a-zA-Z]\w*\z/>.  C<undef>, references, empty strings, and
names starting with a digit or containing hyphens are all rejected.

=back

=head3 Returns

The class name (C<'Sub::Private'>) as a plain string in all cases.

=head3 Side effects

=over 4

=item * Pre-CHECK: appends C<[$owner_pkg, $sub_name]> pairs to the
internal C<@_pending> list.

=item * Post-CHECK: installs wrapper closures directly in the calling
package's stash.

=back

=head3 Example

    BEGIN { $Sub::Private::config{mode} = 'enforce' }
    package MyClass;
    use Sub::Private qw(_helper _init);

    sub new     { bless {}, shift }
    sub _helper { ... }    # wrapped at CHECK time
    sub _init   { ... }    # wrapped at CHECK time
    sub run     { my $s = shift; $s->_helper; $s->_init }

=head3 API specification

=head4 Input

    # No-argument form: always valid.
    Sub::Private->import();

    # Declarative form (enforce mode only):
    {
        subs => {
            type     => 'array',
            optional => 1,
            element  => {
                type  => 'string',
                regex => qr/\A[_a-zA-Z]\w*\z/,
            },
        }
    }

=head4 Output

    { type => 'string' }    # returns the class name 'Sub::Private'

=head3 MESSAGES

    Message                                              Meaning / Action
    ---------------------------------------------------  -----------------------------------------------
    "Sub::Private->import: declarative form requires     use Sub::Private qw(...) was called while
     mode => 'enforce'"                                  $config{mode} is not 'enforce'.  Set
                                                         $config{mode} = 'enforce' in a BEGIN block
                                                         before "use Sub::Private".

    "Sub::Private->import: 'NAME' is not a valid         The sub name failed the identifier regex.
     Perl identifier"                                    Check for typos, hyphens, leading digits,
                                                         undef, or reference values in the import list.

    "Sub::Private: PKG::NAME is not defined"             The named sub was not found in the stash at
                                                         wrap time.  Define the sub before import()
                                                         runs, or before CHECK fires.

=cut