NAME
Perinci::Access::InProcess - Use Rinci access protocol (Riap) to access Perl code
VERSION
version 0.09
SYNOPSIS
# in Your/Module.pm
package My::Module;
our %SPEC;
$SPEC{mult2} = {
v => 1.1,
summary => 'Multiple two numbers',
args => {
a => { schema=>'float*', req=>1, pos=>0 },
b => { schema=>'float*', req=>1, pos=>1 },
},
examples => [
{args=>{a=>2, b=>3}, result=>6},
],
};
sub mult {
my %args = @_;
[200, "OK", $args{a} * $args{b}];
}
$SPEC{multn} = {
v => 1.1,
summary => 'Multiple many numbers',
args => {
n => { schema=>[array=>{of=>'float*'}], req=>1, pos=>0, greedy=>1 },
},
};
sub multn {
my %args = @_;
my @n = @{$args{n}};
my $res = 0;
if (@n) {
$res = shift(@n);
$res *= $_ while $_ = shift(@n);
}
return [200, "OK", $res];
}
1;
# in another file
use Perinci::Access::InProcess;
my $pa = Perinci::Access::Process->new();
# list all functions in package
my $res = $pa->request(list => '/My/Module/', {type=>'function'});
# -> [200, "OK", ['/My/Module/mult2', '/My/Module/mult2']]
# call function
my $res = $pa->request(call => '/My/Module/mult2', {args=>{a=>2, b=>3}});
# -> [200, "OK", 6]
# get function metadata
$res = $pa->request(meta => '/Foo/Bar/multn');
# -> [200, "OK", {v=>1.1, summary=>'Multiple many numbers', ...}]DESCRIPTION
This class implements Rinci access protocol (Riap) to access local Perl code. This might seem like a long-winded and slow way to access things that are already accessible from Perl like functions and metadata (in %SPEC). Indeed, if you do not need Riap, you can access your module just like any normal Perl module.
The abstraction provides some benefits, still. For example, you can actually place metadata not in %SPEC but elsewhere, like in another file or even database, or even by merging from several sources. By using this module, you don't have to change client code. This class also does some function wrapping to convert argument passing style or produce result envelope, so you get a consistent interface.
Location of metadata
By default, the metadata should be put in %SPEC package variable, in a key with the same name as the URI path leaf (use :package) for the package itself). For example, metadata for /Foo/Bar/$var should be put in $Foo::Bar::SPEC{'$var'}, /Foo/Bar/ in $Foo::Bar::SPEC{':package'}. The metadata for the top-level namespace (/) should be put in $main::SPEC{':package'}.
If you want to put metadata elsewhere, you can pass meta_accessor => 'Custom_Class' to constructor argument, or set this in your module:
our $PERINCI_META_ACCESSOR = 'Custom::Class';The default accessor class is Perinci::Access::InProcess::MetaAccessor. Alternatively, you can simply devise your own system to retrieve metadata which you can put in %SPEC at the end.
METHODS
PKG->new(%opts) => OBJ
Instantiate object. Known options:
meta_accessor => STR (default 'Perinci::Access::InProcess::MetaAccessor')
load => STR (default 1)
Whether attempt to load modules using
require.after_load => CODE
If set, code will be executed the first time Perl module is successfully loaded.
$pa->request($action => $uri, \%extra) => $res
Process Riap request and return enveloped result. This method will in turn parse URI and other Riap request keys into $req hash, and then call action_ACTION methods.
Some notes:
Metadata returned by the 'meta' action has normalized schemas in them
Schemas in metadata (like in the
argsandreturnproperty) are normalized by Perinci::Sub::Wrapper.
FAQ
Why %SPEC?
The name was first chosen when during Sub::Spec era, so it stuck.
SEE ALSO
AUTHOR
Steven Haryanto <stevenharyanto@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.