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; # 1

DESCRIPTION

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

sub

A subroutine reference.

set_sub

Setter for subroutine reference.

subname

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); # world

fullname

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.

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.

nshift

The alias of parameters.nshift.

set_nshift($nshift)

The alias of parameters.set_nshift.

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)

is_same_interface($other_meta)

A boolean value indicating whether the subroutine's interface is same or not. Specifically, check whether subname, parameters and returns are equal.

parameters_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>

cpanm Sub::Meta

perl -MCPAN -e shell
install Sub::Meta