NAME
Sub::Spec::URI - Refer to module/sub/spec/sub call via URI string
VERSION
version 0.12
SYNOPSIS
use Sub::Spec::URI;
# refer to local subroutine
my $lsub = Sub::Spec::URI->new("pm:Mod::SubMod::func");
# refer to remote subroutine
my $rsub = Sub::Spec::URI->new("http://HOST/api/MOD/SUBMOD/FUNC");
# get URI components
print $lsub->module; # Mod::SubMod
print $rsub->sub; # FUNC
# get subroutine's spec
my $spec = $lsub->spec;
# get subroutine's spec for another module and/or sub
my $spec = $lsub->spec_other({module=>"OtherMod", sub=>"func2"});
# call subroutine
my $res = $rsub->call(arg1=>'foo', arg2=>'bar');
# call subroutine with another module and/or sub
my $res = $rsub->call_other({module=>"OtherMod", sub=>"func2"}, arg1=>1, ...);
# refer to a module
my $mod = Sub::Spec::URI->new("http://HOST/api/MOD/");
# list subroutines
my $subs = $mod->list_subs;DESCRIPTION
NOTICE: This module and the Sub::Spec standard is deprecated as of Jan 2012. Rinci is the new specification to replace Sub::Spec, it is about 95% compatible with Sub::Spec, but corrects a few issues and is more generic. Perinci::* is the Perl implementation for Rinci and many of its modules can handle existing Sub::Spec sub specs.
This module lets you create an object that can represent a remote or local module/subroutine/spec/subroutine call. This module is basically a convenience so that we can represent those things using a string (URI), e.g. from a command-line or inside another URI/URL.
Each scheme is handled by Sub::Spec::URI::<SCHEME>, e.g. Sub::Spec::URI::pm for local Perl modules/subroutines, Sub::Spec::URI::http for remote subroutines over HTTP.
METHODS
new(STR) => OBJ
Create a new object from URI string. Will die if URI can't be parsed (e.g. unknown scheme or bad syntax).
$s->proto() => STR
Return the protocol/scheme, e.g. "pm", "http", etc.
$s->module() => STR
Get the module name, or undef if not specified in URI.
$s->sub() => STR
Get the subroutine name, or undef if not specified in URI.
$s->args() => HASHREF
Get the arguments, or empty hash if none are specified in URI.
$s->list_subs() => ARRAYREF
Try to list subroutines in a module. URI must specify module. Will die if fail to retrieve, e.g. can't require module (for local modules) or connection failure (for remote modules).
$s->spec() => HASHREF
Try to get spec for subroutine. URI must specify module and subroutine name.
$s->spec_other({...}) => HASHREF
Try to get spec for another subroutine, by specifying some other SS request key(s). For example, to request spec for another subroutine in the same module:
my $spec_sub2 = $s->spec_other({sub=>'sub2'});To request spec for another subroutine in another module:
my $spec_sub2 = $s->spec_other({sub=>'sub2', module=>'Another::Module'});spec_other() (and call_other()) are useful for http URI's and the Sub::Spec::HTTP specification because there are potentially various ways to insert SS request key components into the URL. Some server might use http://HOST/api/MODULE::FUNC, some other might use http://HOST/MODULE/FUNC. Sub::Spec::URI::http knows how to deal with this, so you can use spec_other() to let it do that.
For Sub::Spec::URI::* protocol implementor: If your scheme sees no use for this and find this hard to implement, you can die() instead. Otherwise, see the source code of Sub::Spec::URI::http to see an example of how this is implemented.
$s->call(%args) => RESULT
Try to call subroutine. URI must specify module and subroutine name. If URI contains arguments, it will be merged with %args. Will die if failure happens.
$s->call_other({...}, %args) => RESULT
Try to call another subroutine. See spec_other() for the concept/reasoning behind this.
PACKAGE VARIABLES
$Sub::Spec::URI::load_module_hook can be set to a subroutine, which will be called after module is loaded. The subroutine will be called with $uri, the Sub::Spec::URI object. This can be useful e.g. in Sub::Spec::HTTP::Server, where the server wants to serve 'spec' or 'usage' command. After the module is loaded, the hook will be called which then can be used to (re-)generate the documentation from the specs.
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.