File Coverage

=head1 NAME

Sub::Abstract - Abstract (virtual) methods for plain-Perl OO

=head1 VERSION

Version 0.01

=cut

=head1 SYNOPSIS

    package Animal;
    use Sub::Abstract;

    # Attribute form (stub body required for Attribute::Handlers)
    sub speak :Abstract { }
    sub eat   :Abstract { }

    # Declarative form (no stub body needed)
    use Sub::Abstract qw(speak eat);

    package Dog;
    our @ISA = ('Animal');
    sub speak { 'Woof' }    # satisfies the contract; wrapper never fires
    # forgot eat -- runtime croak when called

=head1 DESCRIPTION

Enforces abstract (virtual) method contracts for plain-Perl OO without
requiring Moose or Moo.  A subroutine decorated with C<:Abstract> (or
named in C<use Sub::Abstract qw(...)>) is replaced at C<CHECK> time with
a wrapper that C<Carp::croak>s whenever it is reached.

Perl's MRO ensures the wrapper is only reached when no subclass in the
call chain has provided an implementation: if C<Dog::speak> exists, the
wrapper installed in C<Animal::speak> is never called.

This module is only meaningful for plain-Perl OO or packages that do not
use a full object framework.  Moo and Moose handle abstract/required
methods in their own object systems.

=head2 Two usage forms

=over 4

=item Attribute form (preferred)

    sub speak :Abstract { }

The C<:Abstract> attribute is registered in C<UNIVERSAL> via
L<Attribute::Handlers> when C<Sub::Abstract> is loaded, so every package
has access to it without further C<use> or inheritance.  A stub body
(even an empty one) is required because C<Attribute::Handlers> needs a
C<CODE> ref.  The stub is replaced at C<CHECK> time.

=item Declarative form

    use Sub::Abstract qw(speak eat);

Each named method is installed as an abstract-croak wrapper at C<CHECK>
time (or immediately if the module is loaded past C<CHECK>).  No stub body
is needed.

=back

=head2 Bypass for testing

Either condition alone (OR logic) suppresses the croak at call time:

=over 4

=item * C<$Sub::Abstract::BYPASS> set to a true value.  Use C<local> in tests.
Checked first; short-circuits the second condition.

=item * C<$ENV{HARNESS_ACTIVE}> set (the convention used by L<Test::Harness>/prove)
B<and> C<$config{harness_bypass}> is truthy (the default).

=back

The C<HARNESS_ACTIVE> bypass can be disabled:

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

B<Important:> setting C<$BYPASS> to any truthy value takes full precedence.
Even with C<harness_bypass = 0>, a truthy C<$BYPASS> still suppresses the
croak.  The two guards use C<||> (short-circuit OR) and C<$BYPASS> is
checked first.  See L</Bypass precedence> under KNOWN LIMITATIONS.

=head2 Error message format

    speak() is an abstract method of Animal and must be implemented by Dog

=head1 PUBLIC INTERFACE

=head2 import

    use Sub::Abstract;                   # attribute form -- no arguments
    use Sub::Abstract qw(speak eat);    # declarative form

=head3 Purpose

With B<no arguments>: loads the module and makes the C<:Abstract> attribute
globally available via C<UNIVERSAL>.  No stash entries are modified.

With B<one or more method names>: installs abstract-croak wrappers for
those methods in the calling package.  Wrappers are installed at C<CHECK>
time when called during compilation, or immediately when called after
C<CHECK> has fired.  Validation is fail-fast and all-or-nothing: if any
name is invalid the entire call croaks before touching the stash.

=head3 Arguments

=over 4

=item C<$class> (required, implicit via C<use>)

The invocant.  Always C<'Sub::Abstract'> in normal usage; not validated
because Perl's C<use> mechanism enforces it.

=item C<@methods> (optional)

Zero or more Perl sub names, each matching C</\A[_a-zA-Z]\w*\z/>.
An undef or reference in this list is coerced to the empty string before
validation, producing a clear identifier-mismatch error.

=back

=head3 Returns

The class name (C<'Sub::Abstract'>) as a plain string.  All call paths
return this value, consistent with the sister modules C<Sub::Private>
and C<Sub::Protected>.

=head3 Example

    package MyBase;
    use Sub::Abstract qw(render serialize);

    package MyConcrete;
    our @ISA = ('MyBase');
    sub render    { ... }    # satisfies render contract
    sub serialize { ... }    # satisfies serialize contract

    # MyBase->new->render croaks; MyConcrete->new->render does not.

=head3 API SPECIFICATION

=head4 Input

    # import() uses positional arguments imposed by Perl's "use" mechanism;
    # named parameters are not applicable here.
    # Each element of @methods is validated individually against:
    {
        name => {
            type  => 'string',
            regex => qr/\A[_a-zA-Z]\w*\z/,
        }
    }

=head4 Output

    { type => 'string' }    # always returns the class name ('Sub::Abstract')

=head3 PSEUDOCODE

    import($class, @methods):
        IF @methods is empty
            RETURN class name      # attribute form; nothing to install
        FOR EACH name in @methods
            coerce undef/ref to empty string
            validate against /\A[_a-zA-Z]\w*\z/ via validate_strict()
            CROAK if invalid       # fail-fast; no stash modification
        END FOR
        owner_pkg <- caller package
        IF post_check flag is set  # CHECK has already fired
            FOR EACH name: _process_one(owner_pkg, name)
        ELSE                       # still compiling; queue for CHECK
            FOR EACH name: push [owner_pkg, name] onto @_pending
        END IF
        RETURN class name

=head3 MESSAGES

    Message                                              Meaning / Action
    -------                                              ----------------
    Sub::Abstract->import: 'NAME' is not a valid         NAME failed the identifier regex
    Perl identifier                                      /\A[_a-zA-Z]\w*\z/.  Common causes:
                                                         leading digit, hyphen, non-ASCII
                                                         character, undef passed where a name
                                                         was expected, or a reference in the
                                                         list.  Action: inspect the argument
                                                         list passed to "use Sub::Abstract
                                                         qw(...)".

=cut