=begin comment

***********************************************************************

This document lists some possible modifictions to parent.pm (as
retrieved from the Perl "blead" source distribution in October 2020). It
is part of the deliverables from the Perl documentation standardization
project by Jason McIntosh
(https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7).

All edits are accompanied by comment blocks, such as this one.

***********************************************************************

=end comment

=cut

package parent;
use strict;

our $VERSION = '0.238';

sub import {
    my $class = shift;

    my $inheritor = caller(0);

    if ( @_ and $_[0] eq '-norequire' ) {
        shift @_;
    } else {
        for ( my @filename = @_ ) {
            s{::|'}{/}g;
            require "$_.pm"; # dies if the file is not found
        }
    }

    {
        no strict 'refs';
        push @{"$inheritor\::ISA"}, @_; # dies if a loop is detected
    };
};

1;

__END__

=encoding utf8

=head1 NAME

parent - Establish an ISA relationship with base classes at compile time

=head1 SYNOPSIS

=begin comment

***********************************************************************

Replacing "Baz inherits from Foo and Bar" in the example with the more
meaningful "Cat inherits from Mammal and Domestic". Also adding in a
comment to make very clear what's happening.

***********************************************************************

=end comment

    package Cat;

    use parent qw(Mammal Domestic);

    # Now every Cat instance will inherit from the Mammal and Domestic
    # classes, as well.

=head1 DESCRIPTION

Allows you to both load one or more modules, while setting up
inheritance from those modules at the same time.

You can think of it as a shortcut to calling C<require> on parent
classes, and then manually pushing them onto the special C<@ISA> array.
Thus, the single C<use parent> line in L</SYNOPSIS>, above, is
equivalent to the following C<BEGIN> block:

    BEGIN { require Mammal; require Domestic; push @ISA, qw(Mammal
    Domestic); }

=begin comment

***********************************************************************

Moving documentation of the module's one optional switch into a separate
"OPTIONS" section, and beginning it with an example-template code block.

***********************************************************************

=end comment


=head1 OPTIONS

=head2 -norequire

 use parent -norequire, $parent_class1, $parent_class2, [...]

By default, every base class needs to live in a file of its own. If you
want to have a subclass and its parent class in the same file, you can
tell C<parent> not to load any modules by using the C<-norequire>
switch:

=begin comment

***********************************************************************

Removing "lolcat" meme jokes, which were amusing to those in the know
circa 2008, but confusing to everyone else (which only gets truer with
each passing year). Also adopting the cat-based class names from before.

***********************************************************************

=end comment

  package Cat; sub exclaim { "Meow!" }

  package Tabby; use parent -norequire, 'Cat', 'Striped';
  # will not go looking for Cat.pm or Striped.pm

This is equivalent to the following code:

  package Cat; sub exclaim { "Meow!" }

  package Tabby; push @Tabby::ISA, 'Cat', 'Striped';

This is also helpful for the case where a package lives within a
differently named file:

  package MyHash; use Tie::Hash; use parent -norequire, 'Tie::StdHash';

This is equivalent to the following code:

  package MyHash; require Tie::Hash; push @ISA, 'Tie::StdHash';

If you want to load a subclass from a file that C<require> would not
consider an eligible filename (that is, it does not end in either C<.pm>
or C<.pmc>), use the following code:

  package MySecondPlugin; require './plugins/custom.plugin'; # contains
  Plugin::Custom use parent -norequire, 'Plugin::Custom';

=begin comment

***********************************************************************

Removing "HISTORY", and moving its information into the "base" entry of
the SEE ALSO section. Also rewording its content for clarity, cleaning
up the use of "hacker" jargon ("cruft").

***********************************************************************

=end comment

=begin comment

***********************************************************************

Removing a "CAVEATS" section that was empty.

***********************************************************************

=end comment

=head1 SEE ALSO

=over 4

=item L<base>

The predecessor of L<parent>, with more options at the cost of less
efficiency.

=item L<parent::versioned>

A fork of L<parent> that provides version checking in parent class
modules.

=begin comment

***********************************************************************

Adding a cross-reference to Perl's OO man page.

***********************************************************************

=end comment

=item L<perlobj>

=back

=head1 AUTHORS AND CONTRIBUTORS

Rafaël Garcia-Suarez, Bart Lateur, Max Maischein, Anno Siegel, Michael
Schwern

=head1 MAINTAINER

Max Maischein C< corion@cpan.org >

Copyright (c) 2007-2017 Max Maischein C<< <corion@cpan.org> >> Based on
the idea of C<base.pm>, which was introduced with Perl 5.004_04.

=head1 LICENSE

This module is released under the same terms as Perl itself.

=cut
