NAME
Venus::Space - Space Class
ABSTRACT
Space Class for Perl 5
SYNOPSIS
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo/bar'
);
# $space->package; # Foo::Bar
DESCRIPTION
This package provides methods for parsing and manipulating package namespaces.
INHERITS
This package inherits behaviors from:
METHODS
This package provides the following methods:
all
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
- all example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Venus'
);
my
$all
=
$space
->all(
'id'
);
# [["Venus", "Venus"]]
- all example 2
-
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"]
# ],
# ]
- all example 3
-
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
append(Str
@path
) (Space)
The append method modifies the object by appending to the package namespace parts.
Since 0.01
- append example 1
-
# given: synopsis;
my
$append
=
$space
->append(
'baz'
);
# bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
- append example 2
-
# given: synopsis;
my
$append
=
$space
->append(
'baz'
,
'bax'
);
# bless({ value => "Foo/Bar/Baz/Bax" }, "Venus::Space")
array
array(Str
$name
) (ArrayRef)
The array method returns the value for the given package array variable name.
Since 0.01
arrays
arrays() (ArrayRef)
The arrays method searches the package namespace for arrays and returns their names.
Since 0.01
authority
authority() (Maybe[Str])
The authority method returns the AUTHORITY
declared on the target package, if any.
Since 0.01
-
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
basename() (Str)
The basename method returns the last segment of the package namespace parts.
Since 0.01
blessed
blessed(Ref
$data
) (Object)
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.
Since 0.01
build
build(Any
@args
) (Object)
The build method attempts to call new
on the package namespace and if successful returns the resulting object.
Since 0.01
- build example 1
-
# given: synopsis;
package
Foo::Bar::Baz;
sub
new {
bless
{},
$_
[0];
}
package
main;
my
$build
=
$space
->child(
'baz'
)->build;
# bless({}, "Foo::Bar::Baz")
- build example 2
-
# 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")
- build example 3
-
# 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
call(Any
@args
) (Any)
The call method attempts to call the given subroutine on the package namespace and if successful returns the resulting value.
Since 0.01
- call example 1
-
package
Foo;
sub
import
;
sub
start {
'started'
}
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo'
);
my
$result
=
$space
->call(
'start'
);
# "started"
- call example 2
-
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")
chain
chain(Str | Tuple[Str, Any]
@steps
) (Any)
The chain method chains one or more method calls and returns the result.
Since 0.01
- chain example 1
-
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")
- chain example 2
-
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")]
- chain example 3
-
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
child(Str
@path
) (Space)
The child method returns a new Venus::Space object for the child package namespace.
Since 0.01
- child example 1
-
# given: synopsis;
my
$child
=
$space
->child(
'baz'
);
# bless({ value => "Foo/Bar/Baz" }, "Venus::Space")
children
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).
Since 0.01
- children example 1
-
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
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.
Since 0.01
- cop example 1
-
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(..., @_) }
data
data() (Str)
The data method attempts to read and return any content stored in the DATA
section of the package namespace.
Since 0.01
destroy
destroy() (Object)
The destroy method attempts to wipe out a namespace and also remove it and its children from %INC
. NOTE: This can cause catastrophic failures if used incorrectly.
Since 0.01
- destroy example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'data/dumper'
);
$space
->load;
# Data/Dumper
my
$destroy
=
$space
->destroy;
# bless({ value => "data/dumper" }, "Venus::Space")
eval
eval
(Str
@data
) (Any)
The eval method takes a list of strings and evaluates them under the namespace represented by the instance.
Since 0.01
- eval example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo'
);
my
$eval
=
$space
->
eval
(
'our $VERSION = 0.01'
);
# 0.01
explain
explain() (Str)
The explain method returns the package name and is used in stringification operations.
Since 0.01
hash
hash(Str
$name
) (HashRef)
The hash method returns the value for the given package hash variable name.
Since 0.01
hashes
hashes() (ArrayRef)
The hashes method searches the package namespace for hashes and returns their names.
Since 0.01
id
id() (Str)
The id method returns the fully-qualified package name as a label.
Since 0.01
included
included() (Str | Undef)
The included method returns the path of the namespace if it exists in %INC
.
Since 0.01
- included example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Venus/Space'
);
my
$included
=
$space
->included;
# "/path/to/lib/Venus/Space.pm"
inherits
inherits() (ArrayRef)
The inherits method returns the list of superclasses the target package is derived from.
Since 0.01
- inherits example 1
-
package
Bar;
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'bar'
);
my
$inherits
=
$space
->inherits;
# []
init
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.
Since 0.01
inject
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.
Since 0.01
- inject example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'kit'
);
my
$inject
=
$space
->inject(
'build'
,
sub
{
'finished'
});
# *Kit::build
load
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.
Since 0.01
- load example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'c_p_a_n'
);
my
$load
=
$space
->load;
# "CPAN"
loaded
loaded() (Int)
The loaded method checks whether the package namespace is already loaded returns truthy or falsy.
Since 0.01
- loaded example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'data/dumper'
);
$space
->destroy;
my
$loaded
=
$space
->loaded;
# 0
- loaded example 2
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'data/dumper'
);
$space
->load;
my
$loaded
=
$space
->loaded;
# 1
locate
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.
Since 0.01
- locate example 2
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'data/dumper'
);
$space
->load;
my
$locate
=
$space
->locate;
# "/path/to/lib/Data/Dumper.pm"
name
name() (Str)
The name method returns the fully-qualified package name.
Since 0.01
parent
parent() (Space)
The parent method returns a new Venus::Space object for the parent package namespace.
Since 0.01
- parent example 1
-
# given: synopsis;
my
$parent
=
$space
->parent;
# bless({ value => "Foo" }, "Venus::Space")
parse
parse() (ArrayRef)
The parse method parses the string argument and returns an arrayref of package namespace segments (parts).
Since 0.01
- parse example 2
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Foo/Bar'
);
my
$parse
=
$space
->parse;
# ["Foo", "Bar"]
- parse example 3
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Foo\Bar'
);
my
$parse
=
$space
->parse;
# ["Foo", "Bar"]
- parse example 4
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Foo-Bar'
);
my
$parse
=
$space
->parse;
# ["FooBar"]
- parse example 5
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Foo_Bar'
);
my
$parse
=
$space
->parse;
# ["FooBar"]
parts
parts() (ArrayRef)
The parts method returns an arrayref of package namespace segments (parts).
Since 0.01
- parts example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Foo'
);
my
$parts
=
$space
->parts;
# ["Foo"]
- parts example 2
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Foo/Bar'
);
my
$parts
=
$space
->parts;
# ["Foo", "Bar"]
- parts example 3
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'Foo_Bar'
);
my
$parts
=
$space
->parts;
# ["FooBar"]
prepend
prepend(Str
@path
) (Space)
The prepend method modifies the object by prepending to the package namespace parts.
Since 0.01
- prepend example 1
-
# given: synopsis;
my
$prepend
=
$space
->prepend(
'etc'
);
# bless({ value => "Etc/Foo/Bar" }, "Venus::Space")
- prepend example 2
-
# given: synopsis;
my
$prepend
=
$space
->prepend(
'etc'
,
'tmp'
);
# bless({ value => "Etc/Tmp/Foo/Bar" }, "Venus::Space")
rebase
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.
Since 0.01
- rebase example 1
-
# given: synopsis;
my
$rebase
=
$space
->rebase(
'zoo'
);
# bless({ value => "Zoo/Bar" }, "Venus::Space")
reload
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.
Since 0.01
- reload example 1
-
package
main;
use
Venus::Space;
# Foo::Gen is generate with $VERSION as 0.01
my
$space
= Venus::Space->new(
'Foo/Gen'
);
my
$reload
=
$space
->reload;
# Foo::Gen
# Foo::Gen->VERSION is 0.01
- reload example 2
-
package
main;
use
Venus::Space;
# Foo::Gen is generate 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
require
(Str
$target
) (Any)
The require method executes a require
statement within the package namespace specified.
Since 0.01
root
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.
Since 0.01
routine
routine(Str
$name
) (CodeRef)
The routine method returns the subroutine reference for the given subroutine name.
Since 0.01
- routine example 1
-
package
Foo;
sub
cont {
[
@_
]
}
sub
abort {
[
@_
]
}
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo'
);
my
$routine
=
$space
->routine(
'cont'
);
# sub { ... }
routines
routines() (ArrayRef)
The routines method searches the package namespace for routines and returns their names.
Since 0.01
- routines example 1
-
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
scalar
(Str
$name
) (Any)
The scalar method returns the value for the given package scalar variable name.
Since 0.01
scalars
scalars() (ArrayRef)
The scalars method searches the package namespace for scalars and returns their names.
Since 0.01
sibling
sibling(Str
$path
) (Space)
The sibling method returns a new Venus::Space object for the sibling package namespace.
Since 0.01
- sibling example 1
-
# given: synopsis;
my
$sibling
=
$space
->sibling(
'baz'
);
# bless({ value => "Foo/Baz" }, "Venus::Space")
siblings
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).
Since 0.01
- siblings example 1
-
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"),
# ...
# ]
tryload
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.
Since 0.01
- tryload example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'c_p_a_n'
);
my
$tryload
=
$space
->tryload;
# 1
- tryload example 2
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'n_a_p_c'
);
my
$tryload
=
$space
->tryload;
# 0
use
use
(Str | Tuple[Str, Str]
$target
, Any
@params
) (Space)
The use method executes a use
statement within the package namespace specified.
Since 0.01
- use example 1
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo/goo'
);
my
$use
=
$space
->
use
(
'Moo'
);
# bless({ value => "foo/goo" }, "Venus::Space")
- use example 2
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo/hoo'
);
my
$use
=
$space
->
use
(
'Moo'
,
'has'
);
# bless({ value => "foo/hoo" }, "Venus::Space")
- use example 3
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo/foo'
);
my
$use
=
$space
->
use
([
'Moo'
, 9.99],
'has'
);
used
used() (Str)
The used method searches %INC
for the package namespace and if found returns the filepath and complete filepath for the loaded package, otherwise returns falsy with an empty string.
Since 0.01
- used example 2
-
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'c_p_a_n'
);
$space
->load;
my
$used
=
$space
->used;
# "CPAN"
- used example 3
-
package
Foo::Bar;
sub
import
;
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo/bar'
);
$space
->load;
my
$used
=
$space
->used;
# "Foo/Bar"
variables
variables() (ArrayRef[Tuple[Str, ArrayRef]])
The variables method searches the package namespace for variables and returns their names.
Since 0.01
- variables example 1
-
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
version() (Maybe[Str])
The version method returns the VERSION
declared on the target package, if any.
Since 0.01
- version example 1
-
package
Foo::Boo;
sub
import
;
package
main;
use
Venus::Space;
my
$space
= Venus::Space->new(
'foo/boo'
);
my
$version
=
$space
->version;
# undef
- version example 2
-
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
AUTHORS
Cpanery, cpanery@cpan.org
LICENSE
Copyright (C) 2021, Cpanery
Read the "license" file.