File Coverage

=head1 NAME

Sub::Private - Private subroutines and methods

=head1 VERSION

Version 0.07

=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 it for your package only, in the C<use> line:

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

This is the recommended form for modules.  Other packages keep the mode
they chose, or the global C<$Sub::Private::config{mode}>.

The older form sets the mode for every package in the program, and must
stay set until C<CHECK>, so it changes how other modules' C<:Private>
subs are handled.  Use it only in a program, not in a module:

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

=back

=head2 Behaviour of wrapped subs (enforce mode)

=over 4

=item * The wrapper hands over with C<goto &sub>, so it does not appear
on the call stack: C<caller> inside a private sub sees its real caller.

=item * Arguments, C<@_> aliasing and calling context (list, scalar or
void) are passed through unchanged.

=item * C<$_> is left untouched, whether the call is allowed or blocked.

=item * A blocked call croaks; it does not fall through to C<AUTOLOAD>.

=item * Works with L<Moo> and L<Moose> classes; use the declarative form
after C<use Moo> or C<use Moose>.

=back

=head2 Loading at run time

Packages that use C<Sub::Private> may be loaded at run time (C<require>,
a plugin loader, a string C<eval>), and C<Sub::Private> itself may be
loaded for the first time that way.  The private subs are then wrapped
(or removed, in C<namespace> mode) when the enclosing scope, normally the
rest of the file, has been compiled.

=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

    use Sub::Private { mode => 'enforce' };  -- this package only (recommended)
    $Sub::Private::config{mode}            -- 'namespace' (default) or 'enforce',
                                              for packages that chose no mode
    $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)
    use Sub::Private { mode => 'enforce' };              # mode for this package
    use Sub::Private { mode => 'enforce' }, qw(_a _b);   # both

=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<a hash reference first>: sets options for the calling package
only.  The one option is C<mode>, C<'namespace'> or C<'enforce'>.  It
decides what happens to that package's C<:Private> subs and whether it
may use the declarative form, whatever C<$Sub::Private::config{mode}>
says.  The global mode is not changed, so other packages are not
affected.  The mode applies to subs in the package that made the C<use>
call, so put the C<use> line inside the package.

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 (for example the package is loaded with C<require> at
run time), the subs are wrapped as soon as the enclosing scope (normally
the rest of the file) has been compiled, so the C<use> line can still
come before the subs it names.  A direct C<< Sub::Private->import(...) >>
call at run time wraps immediately.  Requires the package's mode (see
above), or else C<$Sub::Private::config{mode}>, to equal C<'enforce'>;
croaks otherwise.

=head3 Arguments

=over 4

=item C<\%options> (optional)

A hash reference, before any sub names.  The only key allowed is
C<mode>, whose value must be C<'namespace'> or C<'enforce'>.

=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 * With C<\%options>: records the mode for the calling package.  A
later call from the same package replaces it.

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

=item * Post-CHECK, during compilation: installs wrapper closures in the
calling package's stash when the enclosing scope has been compiled.

=item * Post-CHECK, at run time: 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 }

Enforce mode for one package, leaving every other package alone:

    package MyClass;
    use Sub::Private { mode => 'enforce' };

    sub new        { bless {}, shift }
    sub _helper :Private { ... }    # wrapped at CHECK time
    sub run        { (shift)->_helper }

=head3 API SPECIFICATION

=head4 Input

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

    # Options, first in the list (optional):
    {
        options => {
            type     => 'hashref',
            optional => 1,
            schema   => {
                mode => {
                    type     => 'string',
                    memberof => [ 'namespace', 'enforce' ],
                    optional => 1,
                },
            },
        }
    }

    # 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'"                                  the package's mode is not 'enforce'.  Use
                                                         use Sub::Private { mode => 'enforce' },
                                                         qw(...) instead.

    "Sub::Private->import: unknown option 'KEY'"         The options hash has a key other than mode.

    "Sub::Private: unknown mode 'MODE' -- use            The mode option, or $config{mode}, is not
     'namespace' or 'enforce'"                           one of the two modes.

    "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, before CHECK fires, or (after CHECK)
                                                         before the end of the enclosing scope.
                                                         After CHECK, the location reported is the
                                                         "use Sub::Private" line.

=cut