/ 
meta-0.003
River stage two • 17 direct dependents • 99 total dependents
/ meta

NAME

meta - meta-programming API

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();

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 no strict 'refs' 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 'class' feature, and other such uses.

This module should be considered experimental; no API stability guarantees are made at this time. Behaviour may be added, altered, or removed in later versions. Once a workable API shape has been found, it is hoped that this module will eventually become dual-life and shipped as part of Perl core, as the implementation for PPC 0022. See the link in the "SEE ALSO" section.

FUNCTIONS

get_package

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

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

get_this_package

$metapkg = meta::get_this_package;

Since version 0.02.

Returns a metapackage reference representing the package of the code that called the function.

Useful for performing meta-programming on the contents of a module during its BEGIN or loading time. Equivalent to but more efficient than the following:

meta::get_package(__PACKAGE__)

METHODS ON METAPACKAGES

name

$name = $metapkg->name;

Returns the name of the package being represented.

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.

can_glob

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

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

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 *, $, @, % or &. Throws an exception if the symbol does not exist.

can_symbol

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

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

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 "get_symbol". 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 "can_symbol":

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

Note 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

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 "can_symbol":

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

METHODS ON METASYMBOLS

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.

reference

$ref = $metasym->reference;

Returns a regular Perl reference to the symbol being represented.

METHODS ON METAGLOBS

name

$name = $metaglob->basename;

Returns the name of the glob within its package.

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.

can_scalar, can_array, ...

Similar to "get_scalar", "get_array", etc... but returns undef if the given slot does not exist.

METHODS ON METAVARIABLES

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.

METHODS ON METASUBROUTINES

subname

$name = $metasub->subname;

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

prototype

$proto = $metasub->prototype;

Returns the prototype of the subroutine.

TODO

  • Setting the subname or prototype of a subroutine, inspired by the Sub::Util functions of the same.

  • Some kind of access around the signature of a signatured sub.

  • Access to the new parts of API introduced by Perl 5.38 to deal with classes, methods, fields.

SEE ALSO

PPC 0022 "metaprogramming"

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>