Venus::Space - Space Class
Space Class for Perl 5
package main; use Venus::Space; my $space = Venus::Space->new('foo/bar'); # $space->package; # Foo::Bar
This package provides methods for parsing and manipulating package namespaces.
This package inherits behaviors from:
Venus::Name
This package provides the following methods:
all(Str $method, Any @args) (ArrayRef[Tuple[Str, Any]])
The all method executes any available method on the instance and all instances representing packages inherited by the package represented by the invocant. This method supports dispatching, i.e. providing a method name and arguments whose return value will be acted on by this method.
Since 0.01
0.01
package main; use Venus::Space; my $space = Venus::Space->new('Venus'); my $all = $space->all('id'); # [["Venus", "Venus"]]
package main; use Venus::Space; my $space = Venus::Space->new('Venus/Space'); my $all = $space->all('inherits'); # [ # [ # "Venus::Space", ["Venus::Name"] # ], # [ # "Venus::Name", ["Venus::Kind::Utility"] # ], # ]
package main; use Venus::Space; my $space = Venus::Space->new('Venus/Space'); my $all = $space->all('locate'); # [ # [ # "Venus::Space", # "/path/to/lib/Venus/Space.pm", # ], # [ # "Venus::Name", # "/path/to/lib/Venus/Name.pm", # ], # ]
append(Str @path) (Space)
The append method modifies the object by appending to the package namespace parts.
# given: synopsis; my $append = $space->append('baz'); # bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
# given: synopsis; my $append = $space->append('baz', 'bax'); # bless({ value => "Foo/Bar/Baz/Bax" }, "Venus::Space")
array(Str $name, Any @data) (ArrayRef)
The array method gets or sets the value for the given package array variable name.
# given: synopsis; package Foo::Bar; our @handler = 'start'; package main; my $array = $space->array('handler'); # ["start"]
# given: synopsis; package Foo::Bar; our @handler = 'start'; package main; my $array = $space->array('handler', 'restart'); # ["restart"]
arrays() (ArrayRef)
The arrays method searches the package namespace for arrays and returns their names.
# given: synopsis; package Foo::Bar; our @handler = 'start'; our @initial = ('next', 'prev'); package main; my $arrays = $space->arrays; # ["handler", "initial"]
attributes() (ArrayRef)
The attributes method searches the package namespace for attributes and returns their names. This will not include attributes from roles, mixins, or superclasses.
Since 1.02
1.02
package Foo::Attrs; use Venus::Class 'attr'; attr 'start'; attr 'abort'; package main; use Venus::Space; my $space = Venus::Space->new('foo/attrs'); my $attributes = $space->attributes; # ["start", "abort"]
package Foo::Base; use Venus::Class 'attr', 'base'; attr 'start'; attr 'abort'; package Foo::Attrs; use Venus::Class 'attr'; attr 'show'; attr 'hide'; package main; use Venus::Space; my $space = Venus::Space->new('foo/attrs'); my $attributes = $space->attributes; # ["show", "hide"]
authority() (Maybe[Str])
The authority method returns the AUTHORITY declared on the target package, if any.
AUTHORITY
package Foo::Boo; package main; use Venus::Space; my $space = Venus::Space->new('foo/boo'); my $authority = $space->authority; # undef
package Foo::Boo; our $AUTHORITY = 'cpan:CPANERY'; package main; use Venus::Space; my $space = Venus::Space->new('foo/boo'); my $authority = $space->authority; # "cpan:CPANERY"
basename() (Str)
The basename method returns the last segment of the package namespace parts.
# given: synopsis; my $basename = $space->basename; # "Bar"
blessed(Ref $data) (Self)
The blessed method blesses the given value into the package namespace and returns an object. If no value is given, an empty hashref is used.
# given: synopsis; package Foo::Bar; sub import; package main; my $blessed = $space->blessed; # bless({}, "Foo::Bar")
# given: synopsis; package Foo::Bar; sub import; package main; my $blessed = $space->blessed({okay => 1}); # bless({ okay => 1 }, "Foo::Bar")
build(Any @args) (Self)
The build method attempts to call new on the package namespace and if successful returns the resulting object.
new
# given: synopsis; package Foo::Bar::Baz; sub new { bless {}, $_[0]; } package main; my $build = $space->child('baz')->build; # bless({}, "Foo::Bar::Baz")
# given: synopsis; package Foo::Bar::Bax; sub new { bless $_[1], $_[0]; } package main; my $build = $space->child('bax')->build({okay => 1}); # bless({ okay => 1 }, "Foo::Bar::Bax")
# given: synopsis; package Foo::Bar::Bay; sub new { bless $_[1], $_[0]; } package main; my $build = $space->child('bay')->build([okay => 1]); # bless(["okay", 1], "Foo::Bar::Bay")
call(Any @args) (Any)
The call method attempts to call the given subroutine on the package namespace and if successful returns the resulting value.
package Foo; sub import; sub start { 'started' } package main; use Venus::Space; my $space = Venus::Space->new('foo'); my $result = $space->call('start'); # "started"
package Zoo; sub import; sub AUTOLOAD { bless {}; } sub DESTROY { ; # noop } package main; use Venus::Space; my $space = Venus::Space->new('zoo'); my $result = $space->call('start'); # bless({}, "Zoo")
package main; use Venus::Space; my $space = Venus::Space->new('foo'); my $result = $space->call('missing'); # Exception! Venus::Space::Error (isa Venus::Error)
chain(Str | Tuple[Str, Any] @steps) (Any)
The chain method chains one or more method calls and returns the result.
package Chu::Chu0; sub import; package main; use Venus::Space; my $space = Venus::Space->new('Chu::Chu0'); my $result = $space->chain('blessed'); # bless({}, "Chu::Chu0")
package Chu::Chu1; sub new { bless pop; } sub frame { [@_] } package main; use Venus::Space; my $space = Venus::Space->new('Chu::Chu1'); my $result = $space->chain(['blessed', {1..4}], 'frame'); # [bless({ 1 => 2, 3 => 4 }, "Chu::Chu1")]
package Chu::Chu2; sub new { bless pop; } sub frame { [@_] } package main; use Venus::Space; my $space = Venus::Space->new('Chu::Chu2'); my $chain = $space->chain('blessed', ['frame', {1..4}]); # [bless({}, "Chu::Chu2"), { 1 => 2, 3 => 4 }]
child(Str @path) (Space)
The child method returns a new Venus::Space object for the child package namespace.
# given: synopsis; my $child = $space->child('baz'); # bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
children() (ArrayRef[Object])
The children method searches %INC and @INC and retuns a list of Venus::Space objects for each child namespace found (one level deep).
%INC
@INC
package main; use Venus::Space; my $space = Venus::Space->new('c_p_a_n'); my $children = $space->children; # [ # bless({ value => "CPAN/Author" }, "Venus::Space"), # bless({ value => "CPAN/Bundle" }, "Venus::Space"), # bless({ value => "CPAN/CacheMgr" }, "Venus::Space"), # ... # ]
cop(Str $method, Any @args) (CodeRef)
The cop method attempts to curry the given subroutine on the package namespace and if successful returns a closure. This method supports dispatching, i.e. providing a method name and arguments whose return value will be acted on by this method.
package Foo::Bar; sub import; sub handler { [@_] } package main; use Venus::Space; my $space = Venus::Space->new('foo/bar'); my $code = $space->cop('handler', $space->blessed); # sub { Foo::Bar::handler(..., @_) }
package main; use Venus::Space; my $space = Venus::Space->new('foo/bar'); my $code = $space->cop('missing', $space->blessed); # Exception! Venus::Space::Error (isa Venus::Error)
data() (Str)
The data method attempts to read and return any content stored in the DATA section of the package namespace.
DATA
# given: synopsis; my $data = $space->data; # ""
eval(Str @data) (Any)
The eval method takes a list of strings and evaluates them under the namespace represented by the instance.
package main; use Venus::Space; my $space = Venus::Space->new('foo'); my $eval = $space->eval('our $VERSION = 0.01'); # 0.01
package main; use Venus::Space; my $space = Venus::Space->new('foo'); my $eval = $space->eval('die'); # Exception! Venus::Space::Error (isa Venus::Error)
explain() (Str)
The explain method returns the package name and is used in stringification operations.
# given: synopsis; my $explain = $space->explain; # "Foo::Bar"
hash(Str $name, Any @data) (HashRef)
The hash method gets or sets the value for the given package hash variable name.
# given: synopsis; package Foo::Bar; our %settings = ( active => 1 ); package main; my $hash = $space->hash('settings'); # { active => 1 }
# given: synopsis; package Foo::Bar; our %settings = ( active => 1 ); package main; my $hash = $space->hash('settings', inactive => 1); # { inactive => 1 }
hashes() (ArrayRef)
The hashes method searches the package namespace for hashes and returns their names.
# given: synopsis; package Foo::Bar; our %defaults = ( active => 0 ); our %settings = ( active => 1 ); package main; my $hashes = $space->hashes; # ["defaults", "settings"]
id() (Str)
The id method returns the fully-qualified package name as a label.
# given: synopsis; my $id = $space->id; # "Foo_Bar"
included() (Str | Undef)
The included method returns the path of the namespace if it exists in %INC.
package main; use Venus::Space; my $space = Venus::Space->new('Venus/Space'); my $included = $space->included; # "/path/to/lib/Venus/Space.pm"
inherits() (ArrayRef)
The inherits method returns the list of superclasses the target package is derived from.
package Bar; package main; use Venus::Space; my $space = Venus::Space->new('bar'); my $inherits = $space->inherits; # []
package Foo; sub import; package Bar; use base 'Foo'; package main; use Venus::Space; my $space = Venus::Space->new('bar'); my $inherits = $space->inherits; # ["Foo"]
init() (Str)
The init method ensures that the package namespace is loaded and, whether created in-memory or on-disk, is flagged as being loaded and loadable.
package main; use Venus::Space; my $space = Venus::Space->new('kit'); my $init = $space->init; # "Kit"
inject(Str $name, Maybe[CodeRef] $coderef) (Any)
The inject method monkey-patches the package namespace, installing a named subroutine into the package which can then be called normally, returning the fully-qualified subroutine name.
package main; use Venus::Space; my $space = Venus::Space->new('kit'); my $inject = $space->inject('build', sub { 'finished' }); # *Kit::build
integrates() (ArrayRef)
The integrates method returns the list of roles integrated into the target package.
Since 1.30
1.30
# given: synopsis package main; my $integrates = $space->integrates; # []
package main; use Venus::Space; my $space = Venus::Space->new('Venus::Test'); my $integrates = $space->integrates; # [...]
lfile() (Str)
The lfile method returns a .pm file path for the underlying package.
.pm
# given: synopsis package main; my $lfile = $space->lfile; # "Foo/Bar.pm"
load() (Str)
The load method checks whether the package namespace is already loaded and if not attempts to load the package. If the package is not loaded and is not loadable, this method will throw an exception using confess. If the package is loadable, this method returns truthy with the package name. As a workaround for packages that only exist in-memory, if the package contains a new, with, meta, or import routine it will be recognized as having been loaded.
with
meta
import
package main; use Venus::Space; my $space = Venus::Space->new('c_p_a_n'); my $load = $space->load; # "CPAN"
package main; use Venus::Space; my $space = Venus::Space->new('no/thing'); my $load = $space->load; # Exception! Venus::Space::Error (isa Venus::Error)
loaded() (Bool)
The loaded method checks whether the package namespace is already loaded and returns truthy or falsy.
package main; use Venus::Space; my $space = Venus::Space->new('Kit'); $space->init; $space->unload; my $loaded = $space->loaded; # 0
package main; use Venus::Space; my $space = Venus::Space->new('Kit'); $space->init; my $loaded = $space->loaded; # 1
locate() (Str)
The locate method checks whether the package namespace is available in @INC, i.e. on disk. This method returns the file if found or an empty string.
package main; use Venus::Space; my $space = Venus::Space->new('xyz'); my $locate = $space->locate; # ""
package main; use Venus::Space; my $space = Venus::Space->new('data/dumper'); $space->load; my $locate = $space->locate; # "/path/to/lib/Data/Dumper.pm"
meta() (Meta)
The meta method returns a Venus::Meta object representing the underlying package namespace. To access the meta object for the instance itself, use the superclass' "META" in Venus::Core method.
# given: synopsis package main; my $meta = $space->meta; # bless({'name' => 'Foo::Bar'}, 'Venus::Meta')
# given: synopsis package main; my $meta = $space->META; # bless({'name' => 'Venus::Space'}, 'Venus::Meta')
mock() (Space)
The mock method returns a Venus::Space object representing an anonymous package that derives from the invoking package.
Since 1.50
1.50
# given: synopsis package main; my $mock = $space->mock; # bless({'name' => 'Venus::Space::Mock::0001::Foo::Bar'}, 'Venus::Space') # $mock->isa('Foo::Bar') # true
name() (Str)
The name method returns the fully-qualified package name.
# given: synopsis; my $name = $space->name; # "Foo::Bar"
parent() (Space)
The parent method returns a new Venus::Space object for the parent package namespace.
# given: synopsis; my $parent = $space->parent; # bless({ value => "Foo" }, "Venus::Space")
parse() (ArrayRef)
The parse method parses the string argument and returns an arrayref of package namespace segments (parts).
# given: synopsis; my $parse = $space->parse; # ["Foo", "Bar"]
package main; use Venus::Space; my $space = Venus::Space->new('Foo/Bar'); my $parse = $space->parse; # ["Foo", "Bar"]
package main; use Venus::Space; my $space = Venus::Space->new('Foo\Bar'); my $parse = $space->parse; # ["Foo", "Bar"]
package main; use Venus::Space; my $space = Venus::Space->new('Foo-Bar'); my $parse = $space->parse; # ["FooBar"]
package main; use Venus::Space; my $space = Venus::Space->new('Foo_Bar'); my $parse = $space->parse; # ["FooBar"]
parts() (ArrayRef)
The parts method returns an arrayref of package namespace segments (parts).
package main; use Venus::Space; my $space = Venus::Space->new('Foo'); my $parts = $space->parts; # ["Foo"]
package main; use Venus::Space; my $space = Venus::Space->new('Foo/Bar'); my $parts = $space->parts; # ["Foo", "Bar"]
package main; use Venus::Space; my $space = Venus::Space->new('Foo_Bar'); my $parts = $space->parts; # ["FooBar"]
pfile() (Str)
The pfile method returns a .pod file path for the underlying package.
.pod
# given: synopsis package main; my $pfile = $space->pfile; # "Foo/Bar.pod"
prepend(Str @path) (Space)
The prepend method modifies the object by prepending to the package namespace parts.
# given: synopsis; my $prepend = $space->prepend('etc'); # bless({ value => "Etc/Foo/Bar" }, "Venus::Space")
# given: synopsis; my $prepend = $space->prepend('etc', 'tmp'); # bless({ value => "Etc/Tmp/Foo/Bar" }, "Venus::Space")
purge() (Self)
The purge method purges a package space by expunging its symbol table and removing it from %INC.
package main; use Venus::Space; # Bar::Gen is generated with $VERSION as 0.01 my $space = Venus::Space->new('Bar/Gen'); $space->load; my $purge = $space->purge; # bless({ value => "Bar::Gen" }, "Venus::Space") # Bar::Gen->VERSION was 0.01, now undef # Symbol table is gone, $space->visible is 0
rebase(Str @path) (Space)
The rebase method returns an object by prepending the package namespace specified to the base of the current object's namespace.
# given: synopsis; my $rebase = $space->rebase('zoo'); # bless({ value => "Zoo/Bar" }, "Venus::Space")
reload() (Str)
The reload method attempts to delete and reload the package namespace using the "load" method. Note: Reloading is additive and will overwrite existing symbols but does not remove symbols.
package main; use Venus::Space; # Foo::Gen is generated with $VERSION as 0.01 my $space = Venus::Space->new('Foo/Gen'); my $reload = $space->reload; # Foo::Gen # Foo::Gen->VERSION is 0.01
package main; use Venus::Space; # Foo::Gen is generated with $VERSION as 0.02 my $space = Venus::Space->new('Foo/Gen'); my $reload = $space->reload; # Foo::Gen # Foo::Gen->VERSION is 0.02
require(Str $target) (Any)
The require method executes a require statement within the package namespace specified.
require
# given: synopsis; my $require = $space->require('Venus'); # 1
root() (Str)
The root method returns the root package namespace segments (parts). Sometimes separating the root from the parts helps identify how subsequent child objects were derived.
root
parts
# given: synopsis; my $root = $space->root; # "Foo"
routine(Str $name, CodeRef $code) (CodeRef)
The routine method gets or sets the subroutine reference for the given subroutine name.
package Foo; sub cont { [@_] } sub abort { [@_] } package main; use Venus::Space; my $space = Venus::Space->new('foo'); my $routine = $space->routine('cont'); # sub { ... }
package Foo; sub cont { [@_] } sub abort { [@_] } package main; use Venus::Space; my $space = Venus::Space->new('foo'); my $routine = $space->routine('report', sub{[@_]}); # sub { ... }
routines() (ArrayRef)
The routines method searches the package namespace for routines and returns their names.
package Foo::Subs; sub start { 1 } sub abort { 1 } package main; use Venus::Space; my $space = Venus::Space->new('foo/subs'); my $routines = $space->routines; # ["abort", "start"]
scalar(Str $name, Any @data) (Any)
The scalar method gets or sets the value for the given package scalar variable name.
# given: synopsis; package Foo::Bar; our $root = '/path/to/file'; package main; my $scalar = $space->scalar('root'); # "/path/to/file"
# given: synopsis; package Foo::Bar; our $root = '/path/to/file'; package main; my $scalar = $space->scalar('root', '/tmp/path/to/file'); # "/tmp/path/to/file"
scalars() (ArrayRef)
The scalars method searches the package namespace for scalars and returns their names.
# given: synopsis; package Foo::Bar; our $root = 'root'; our $base = 'path/to'; our $file = 'file'; package main; my $scalars = $space->scalars; # ["base", "file", "root"]
sibling(Str $path) (Space)
The sibling method returns a new Venus::Space object for the sibling package namespace.
# given: synopsis; my $sibling = $space->sibling('baz'); # bless({ value => "Foo/Baz" }, "Venus::Space")
siblings() (ArrayRef[Object])
The siblings method searches %INC and @INC and retuns a list of Venus::Space objects for each sibling namespace found (one level deep).
package main; use Venus::Space; my $space = Venus::Space->new('encode/m_i_m_e'); my $siblings = $space->siblings; # [ # bless({ value => "Encode/MIME/Header" }, "Venus::Space"), # bless({ value => "Encode/MIME/Name" }, "Venus::Space"), # ... # ]
splice(Int $offset, Int $length, Any @list) (Space)
The splice method perform a Perl "splice" in perlfunc operation on the package namespace.
Since 0.09
0.09
package main; use Venus::Space; my $space = Venus::Space->new('foo/baz'); my $splice = $space->splice(1, 0, 'bar'); # bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
package main; use Venus::Space; my $space = Venus::Space->new('foo/baz'); my $splice = $space->splice(1, 1); # bless({ value => "Foo" }, "Venus::Space")
package main; use Venus::Space; my $space = Venus::Space->new('foo/baz'); my $splice = $space->splice(-2, 1); # bless({ value => "Baz" }, "Venus::Space")
package main; use Venus::Space; my $space = Venus::Space->new('foo/baz'); my $splice = $space->splice(1); # bless({ value => "Foo" }, "Venus::Space")
tfile() (Str)
The tfile method returns a .t file path for the underlying package.
.t
# given: synopsis package main; my $tfile = $space->tfile; # "Foo_Bar.t"
tryload() (Bool)
The tryload method attempt to load the represented package using the "load" method and returns truthy/falsy based on whether the package was loaded.
load
package main; use Venus::Space; my $space = Venus::Space->new('c_p_a_n'); my $tryload = $space->tryload; # 1
package main; use Venus::Space; my $space = Venus::Space->new('n_a_p_c'); my $tryload = $space->tryload; # 0
unload() (Self)
The unload method unloads a package space by nullifying its symbol table and removing it from %INC.
package main; use Venus::Space; # Bar::Gen is generated with $VERSION as 0.01 my $space = Venus::Space->new('Bar/Gen'); $space->load; my $unload = $space->unload; # bless({ value => "Bar::Gen" }, "Venus::Space") # Bar::Gen->VERSION was 0.01, now undef # Symbol table remains, $space->visible is 1
use(Str | Tuple[Str, Str] $target, Any @params) (Space)
The use method executes a use statement within the package namespace specified.
use
package main; use Venus::Space; my $space = Venus::Space->new('foo/goo'); my $use = $space->use('Venus'); # bless({ value => "foo/goo" }, "Venus::Space")
package main; use Venus::Space; my $space = Venus::Space->new('foo/hoo'); my $use = $space->use('Venus', 'error'); # bless({ value => "foo/hoo" }, "Venus::Space")
package main; use Venus::Space; my $space = Venus::Space->new('foo/foo'); my $use = $space->use(['Venus', 9.99], 'error');
variables() (ArrayRef[Tuple[Str, ArrayRef]])
The variables method searches the package namespace for variables and returns their names.
package Etc; our $init = 0; our $func = 1; our @does = (1..4); our %sets = (1..4); package main; use Venus::Space; my $space = Venus::Space->new('etc'); my $variables = $space->variables; # [ # ["arrays", ["does"]], # ["hashes", ["sets"]], # ["scalars", ["func", "init"]], # ]
version() (Maybe[Str])
The version method returns the VERSION declared on the target package, if any.
VERSION
package Foo::Boo; sub import; package main; use Venus::Space; my $space = Venus::Space->new('foo/boo'); my $version = $space->version; # undef
package Foo::Boo; our $VERSION = 0.01; package main; use Venus::Space; my $space = Venus::Space->new('foo/boo'); my $version = $space->version; # 0.01
visible() (Bool)
The visible method returns truthy is the package namespace is visible, i.e. has symbols defined.
# given: synopsis package main; my $visible = $space->visible; # 1
package Foo::Fe; package main; use Venus::Space; my $space = Venus::Space->new('foo/fe'); my $visible = $space->visible; # 0
package Foo::Fe; our $VERSION = 0.01; package main; use Venus::Space; my $space = Venus::Space->new('foo/fe'); my $visible = $space->visible; # 1
package Foo::Fi; sub import; package main; use Venus::Space; my $space = Venus::Space->new('foo/fi'); my $visible = $space->visible; # 1
To install Venus, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Venus
CPAN shell
perl -MCPAN -e shell install Venus
For more information on module installation, please visit the detailed CPAN module installation guide.