Perinci::Access::InProcess - Use Rinci access protocol (Riap) to access Perl code
version 0.29
# 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 mult2 { 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/multn']] # 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', ...}]
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.
%SPEC
But Perinci::Access::InProcess offers several benefits:
Custom location of metadata
Metadata can be placed not in %SPEC but elsewhere, like in another file or even database, or even by merging from several sources.
Function wrapping
Can be used to convert argument passing style or produce result envelope, so you get a consistent interface.
Transaction/undo
This class implements Riap::Transaction. See Perinci::Access::InProcess::Tx for more details.
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'}.
:package
/Foo/Bar/$var
$Foo::Bar::SPEC{'$var'}
/Foo/Bar/
$Foo::Bar::SPEC{':package'}
/
$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:
meta_accessor
'Custom_Class'
our $PERINCI_META_ACCESSOR = 'Custom::Class';
The default accessor class is Perinci::MetaAccessor::Default. Alternatively, you can simply devise your own system to retrieve metadata which you can put in %SPEC at the end.
Instantiate object. Known attributes:
meta_accessor => STR (default 'Perinci::MetaAccessor::Default')
load => BOOL (default 1)
Whether attempt to load modules using require.
require
after_load => CODE
If set, code will be executed the first time Perl module is successfully loaded.
extra_wrapper_args => HASH
If set, will be passed to Perinci::Sub::Wrapper's wrap_sub() when wrapping subroutines.
Some applications of this include: adding timeout or result_postfilter properties to functions.
timeout
result_postfilter
extra_wrapper_convert => HASH
If set, will be passed to Perinci::Sub::Wrapper wrap_sub()'s convert argument when wrapping subroutines.
convert
Some applications of this include: changing default_lang of metadata.
default_lang
use_tx => BOOL (default 0)
Whether to allow transaction requests from client. Since this can cause the server to store transaction/undo data, this must be explicitly allowed.
You need to install Perinci::Tx::Manager for transaction support (unless you are using another transaction manager).
custom_tx_manager => STR|CODE
Can be set to a string (class name) or a code that is expected to return a transaction manager class.
By default, Perinci::Tx::Manager is instantiated and maintained (not reinstantiated on every request), but if custom_tx_manager is a coderef, it will be called on each request to get transaction manager. This can be used to instantiate Perinci::Tx::Manager in a custom way, e.g. specifying per-user transaction data directory and limits, which needs to be done on a per-request basis.
custom_tx_manager
Process Riap request and return enveloped result. $server_url will be used as the Riap request key 'uri', as there is no server in this case.
Some notes:
Metadata returned by the 'meta' action has normalized schemas in them
Schemas in metadata (like in the args and return property) are normalized by Perinci::Sub::Wrapper.
args
return
The name was first chosen when during Sub::Spec era, so it stuck.
Riap, Rinci
Steven Haryanto <stevenharyanto@gmail.com>
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.
To install Perinci::Access::InProcess, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perinci::Access::InProcess
CPAN shell
perl -MCPAN -e shell install Perinci::Access::InProcess
For more information on module installation, please visit the detailed CPAN module installation guide.