NAME
Sub::Meta - handle subroutine meta information
SYNOPSIS
use Sub::Meta;
sub hello($) :mehtod { }
my $meta = Sub::Meta->new(sub => \&hello);
$meta->subname; # => hello
$meta->sub; # \&hello
$meta->subname; # hello
$meta->fullname # main::hello
$meta->stashname # main
$meta->file # path/to/file.pl
$meta->line # 5
$meta->is_constant # !!0
$meta->prototype # $
$meta->attribute # ['method']
$meta->is_method # undef
$meta->parameters # undef
$meta->returns # undef
# setter
$meta->set_subname('world');
$meta->subname; # world
$meta->fullname; # main::world
# apply to sub
$meta->apply_prototype('$@');
$meta->prototype; # $@
Sub::Util::prototype($meta->sub); # $@And you can hold meta information of parameter type and return type. See also Sub::Meta::Parameters and Sub::Meta::Returns.
$meta->set_parameters(args => ['Str']));
$meta->parameters->args; # [ Sub::Meta::Param->new({ type => 'Str' }) ]
$meta->set_args(['Str']);
$meta->args; # [ Sub::Meta::Param->new({ type => 'Str' }) ]
$meta->set_returns('Str');
$meta->returns->scalar; # 'Str'
$meta->returns->list; # 'Str'And you can compare meta informations:
my $other = Sub::Meta->new(subname => 'hello');
$meta->is_same_interface($other); # 1
$meta eq $other; # 1DESCRIPTION
Sub::Meta provides methods to handle subroutine meta information. In addition to information that can be obtained from subroutines using module B etc., subroutines can have meta information such as arguments and return values.
METHODS
new
Constructor of Sub::Meta.
use Sub::Meta;
use Types::Standard -types;
# sub Greeting::hello(Str) -> Str
Sub::Meta->new(
fullname => 'Greeting::hello',
is_constant => 0,
prototype => '$',
attribute => ['method'],
is_method => 1,
parameters => { args => [{ type => Str }]},
returns => Str,
);Others are as follows:
# sub add(Int, Int) -> Int
Sub::Meta->new(
subname => 'add',
args => [Int, Int],
returns => Int,
);
# method hello(Str) -> Str
Sub::Meta->new(
subname => 'hello',
args => [{ message => Str }],
is_method => 1,
returns => Str,
);
# sub twice(@numbers) -> ArrayRef[Int]
Sub::Meta->new(
subname => 'twice',
args => [],
slurpy => { name => '@numbers' },
returns => ArrayRef[Int],
);
# Named parameters:
# sub foo(Str :a) -> Str
Sub::Meta->new(
subname => 'foo',
args => { a => Str },
returns => Str,
);
# is equivalent to
Sub::Meta->new(
subname => 'foo',
args => [{ name => 'a', isa => Str, named => 1 }],
returns => Str,
);Another way to create a Sub::Meta is to use Sub::Meta::Creator:
use Sub::Meta::Creator;
use Sub::Meta::Finder::FunctionParameters;
my $creator = Sub::Meta::Creator->new(
finders => [ \&Sub::Meta::Finder::FunctionParameters::find_materials ],
);
use Function::Parameters;
use Types::Standard -types;
method hello(Str $msg) { }
my $meta = $creator->create(\&hello);
# =>
# Sub::Meta
# args [
# [0] Sub::Meta::Param->new(name => '$msg', type => Str)
# ],
# invocant Sub::Meta::Param->(name => '$self', invocant => 1),
# nshift 1,
# slurpy !!0ACCESSORS
sub
A subroutine reference.
set_sub
Setter for subroutine reference.
sub hello { ... }
$meta->set_sub(\&hello);
$meta->sub # => \&hellosubname
A subroutine name, e.g. hello
set_subname($subname)
Setter for subroutine name.
$meta->subname; # hello
$meta->set_subname('world');
$meta->subname; # world
Sub::Util::subname($meta->sub); # hello (NOT apply to sub)apply_subname($subname)
Sets subroutine name and apply to the subroutine reference.
$meta->subname; # hello
$meta->apply_subname('world');
$meta->subname; # world
Sub::Util::subname($meta->sub); # worldfullname
A subroutine full name, e.g. main::hello
set_fullname($fullname)
Setter for subroutine full name.
stashname
A subroutine stash name, e.g. main
set_stashname($stashname)
Setter for subroutine stash name.
subinfo
A subroutine information, e.g. ['main', 'hello']
set_subinfo([$stashname, $subname])
Setter for subroutine information.
file
A filename where subroutine is defined, e.g. path/to/main.pl.
set_file($filepath)
Setter for file.
line
A line where the definition of subroutine started, e.g. 5
set_line($line)
Setter for line.
is_constant
A boolean value indicating whether the subroutine is a constant or not.
set_is_constant($bool)
Setter for is_constant.
prototype
A prototype of subroutine reference, e.g. $@
set_prototype($prototype)
Setter for prototype.
apply_prototype($prototype)
Sets subroutine prototype and apply to the subroutine reference.
attribute
A attribute of subroutine reference, e.g. undef, ['method']
set_attribute($attribute)
Setter for attribute.
apply_attribute(@attribute)
Sets subroutine attributes and apply to the subroutine reference.
apply_meta($other_meta)
Apply subroutine subname, prototype and attributes of $other_meta.
is_method
A boolean value indicating whether the subroutine is a method or not.
set_is_method($bool)
Setter for is_method.
parameters
Parameters object of Sub::Meta::Parameters.
set_parameters($parameters)
Sets the parameters object of Sub::Meta::Parameters.
my $meta = Sub::Meta->new;
$meta->set_parameters(args => ['Str']);
$meta->parameters; # => Sub::Meta::Parameters->new(args => ['Str']);
# or
$meta->set_parameters(Sub::Meta::Parameters->new(args => ['Str']));
# alias
$meta->set_args(['Str']);args
The alias of parameters.args.
set_args($args)
The alias of parameters.set_args.
all_args
The alias of parameters.all_args.
nshift
The alias of parameters.nshift.
set_nshift($nshift)
The alias of parameters.set_nshift.
invocant
The alias of parameters.invocant.
invocants
The alias of parameters.invocants.
set_invocant($invocant)
The alias of parameters.set_invocant.
slurpy
The alias of parameters.slurpy.
set_slurpy($slurpy)
The alias of parameters.set_slurpy.
returns
Returns object of Sub::Meta::Returns.
set_returns($returns)
Sets the returns object of Sub::Meta::Returns or any object.
my $meta = Sub::Meta->new;
$meta->set_returns({ type => 'Type'});
$meta->returns; # => Sub::Meta::Returns->new({type => 'Type'});
# or
$meta->set_returns(Sub::Meta::Returns->new(type => 'Foo'));
$meta->set_returns(MyReturns->new)OTHERS
is_same_interface($other_meta)
A boolean value indicating whether the subroutine's interface is same or not. Specifically, check whether subname, is_method, parameters and returns are equal.
is_same_interface_inlined($other_meta_inlined)
Returns inlined is_same_interface string:
use Sub::Meta;
my $meta = Sub::Meta->new(subname => 'hello');
my $inline = $meta->is_same_interface_inlined('$_[0]');
# $inline looks like this:
# Scalar::Util::blessed($_[0]) && $_[0]->isa('Sub::Meta')
# && defined $_[0]->subname && 'hello' eq $_[0]->subname
# && !$_[0]->is_method
# && !$_[0]->parameters
# && !$_[0]->returns
my $check = eval "sub { $inline }";
$check->(Sub::Meta->new(subname => 'hello')); # => OK
$check->(Sub::Meta->new(subname => 'world')); # => NGparameters_class
Returns class name of parameters. default: Sub::Meta::Parameters Please override for customization.
returns_class
Returns class name of returns. default: Sub::Meta::Returns Please override for customization.
NOTE
setter
You can set meta information of subroutine. set_xxx sets xxx and does not affect subroutine reference. On the other hands, apply_xxx sets xxx and apply xxx to subroutine reference.
Setter methods of Sub::Meta returns meta object. So you can chain setting:
$meta->set_subname('foo')
->set_stashname('Some')Pure-Perl version
By default Sub::Meta tries to load an XS implementation for speed. If that fails, or if the environment variable PERL_SUB_META_PP is defined to a true value, it will fall back to a pure perl implementation.
SEE ALSO
Sub::Identify, Sub::Util, Sub::Info, Function::Paramters::Info, Function::Return::Info
LICENSE
Copyright (C) kfly8.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHOR
kfly8 <kfly@cpan.org>