File Coverage

blib/lib/meta.pm

Criterion	Covered	Total	%
statement	5	5	100.0
branch			n/a
condition			n/a
subroutine	2	2	100.0
pod			n/a
total	7	7	100.0

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2023 -- [e-mail]

package meta;

use v5.14;
use warnings;

# We must do this hackery because `package NAME VER` does not work with _ in VER
#   https://github.com/Perl/perl5/issues/21499
our $VERSION = '0.001_001';

require XSLoader;
XSLoader::load( __PACKAGE__, $VERSION );

# Squash out the _ but only after loading XS
$VERSION =~ s/_//g;

=head1 NAME

C - meta-programming API

=head1 SYNOPSIS

   use v5.14;
   use meta;

   my $metapkg = meta::get_package( "MyApp::Some::Package" );

   $metapkg->add_symbol(
      '&a_function' => sub { say "New function was created" }
   );

   MyApp::Some::Package::a_function();

=head1 DESCRIPTION

This package provides an API for metaprogramming; that is, allowing code to
inspect or manipulate parts of its own program structure.  Parts of the perl
interpreter itself can be accessed by means of "meta"-objects provided by this
package.  Methods on these objects allow inspection of details, as well as
creating new items or removing existing ones.

The intention of this API is to provide a nicer replacement for existing
tricks such as C and using globrefs, and also to be a more
consistent place to add new abilities, such as more APIs for inspection and
alteration of internal structures, metaprogramming around the new C<'class'>
feature, and other such uses.

=cut

=head1 FUNCTIONS

=head2 get_package

   $metapkg = meta::get_package( $pkgname );

Returns a metapackage reference representing the given package name, creating
it if it did not previously exist.

=cut

=head1 METHODS ON METAPACKAGES

=head2 name

   $name = $metapkg->name;

Returns the name of the package being represented.

=head2 get_glob

   $metaglob = $metapkg->get_glob( $name );

Returns a metaglob reference representing the given symbol name within the
package, if it exists. Throws an exception if not.

=head2 can_glob

   $metaglob = $metapkg->can_glob( $name );

Similar to L but returns undef if the glob does not exist.

=head2 get_symbol

   $metasym = $metapkg->get_symbol( $name );

Returns a metasymbol reference representing the given symbol name within the
package. The symbol name should include the leading sigil; one of the
characters C<*>, C<$>, C<@>, C<%> or C<&>. Throws an exception if the symbol
does not exist.

=head2 can_symbol

   $metasym = $metapkg->can_symbol( $name );

Similar to L but returns undef if the symbol does ont exist.

=head2 add_symbol

   $metasym = $metapkg->add_symbol( $name, $valueref );

Creates a new symbol of the given name in the given package. The new symbol
will refer to the item given by reference, whose type must match the sigil
of the symbol name. Returns a metasymbol reference as per L. If
a symbol already existed of the given name then an exception is thrown.

To only conditionally add a symbol if it doesn't already exist, test for it
first by using L:

   $metapkg->can_symbol( '$variable' ) or
      $metapkg->add_symbol( '$variable', \my $tmp );

I that this does not create a copy of a variable, but stores an alias
to the referred item itself within the symbol table.

   $metapkg->add_symbol( '@things', \my @array );

   push @array, "more", "values";
   # these values are now visible in the @things array

=head2 remove_symbol

   $metapkg->remove_symbol( $name );

Removes a symbol of the given name from the given package. If the symbol was
the last item in the glob then the glob too is removed from the package. If
the named symbol did not previously exist then an exception is thrown.

To only conditionally remove a symbol if it already exists, test for it first
by using L:

   $metapkg->can_symbol( '$variable' ) and
      $metapkg->remove_symbol( '$variable' );

=cut

=head1 METHODS ON METASYMBOLS

=head2 is_glob, is_scalar, ...

   $bool = $metasym->is_glob;
   $bool = $metasym->is_scalar;
   $bool = $metasym->is_array;
   $bool = $metasym->is_hash;
   $bool = $metasym->is_subroutine;

Returns true if the symbol being referred to is of the given type, or false if
not.

=head2 reference

   $ref = $metasym->reference;

Returns a regular Perl reference to the symbol being represented.

=cut

=head1 METHODS ON METAGLOBS

=cut

@meta::glob::ISA = qw( meta::symbol );

=head2 name

   $name = $metaglob->basename;

Returns the name of the glob I.

=head2 get_scalar, get_array, ...

   $metasym = $metaglob->get_scalar;
   $metasym = $metaglob->get_array;
   $metasym = $metaglob->get_hash;
   $metasym = $metaglob->get_code;

Returns a metasymbol reference representing the symbol in the given slot of
the glob, if it exists. Throws an exception if not.

=head2 can_scalar, can_array, ...

Similar to L, L, etc... but returns undef if the
given slot does not exist.

=cut

=head1 METHODS ON METAVARIABLES

=cut

@meta::variable::ISA = qw( meta::symbol );

=head2 value

   $scalar = $metavar->value;
   @array  = $metavar->value;
   %hash   = $metavar->value;

   $count = scalar $metavar->value;

Returns the current value of the variable, as if it appeared in regular Perl
code.

=cut

=head1 METHODS ON METASUBROUTINES

=cut

@meta::subroutine::ISA = qw( meta::symbol );

=head2 subname

   $name = $metasub->subname;

Returns the (fully-qualified) name of the subroutine.

=head2 prototype

   $proto = $metasub->prototype;

Returns the prototype of the subroutine.

=cut

=head1 AUTHOR

Paul Evans

=cut

0x55AA;