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:

Venus::Name

METHODS

This package provides the following methods:

after

after(string $name, coderef $code) (coderef)

The after method installs a method modifier that executes after the original method, allowing you to perform actions after a method call. Note: The return value of the modifier routine is ignored; the wrapped method always returns the value from the original method. Modifiers are executed in the order they are stacked.

Since 4.15

after example 1

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('execute', sub {
  my ($self) = @_;
  return [@_];
});

my $after = $space->after('execute', sub {
  my ($self) = @_;
  $self->{executed} = 1;
});

# sub { ... }

after example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('new', sub {
  my ($class) = @_;
  return bless {}, $class;
});

$space->routine('execute', sub {
  my ($self) = @_;
  $self->{executed} = 1;
  return $self;
});

$space->after('execute', sub {
  my ($self) = @_;
  return [@_];
});

my $object = $space->build({});

my $result = $object->execute;

# bless({executed => 1}, 'Foo::Bar')

all

all(string $method, any @args) (within[arrayref, tuple[string, 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(string @path) (Venus::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")

around

around(string $name, coderef $code) (coderef)

The around method installs a method modifier that wraps around the original method. The callback provided will recieve the original routine as its first argument. This method will raise an exception if the source routine does not exist. Modifiers are executed in the order they are stacked.

Since 4.15

around example 1

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('execute', sub {
  my ($self, $value) = @_;
  return [$value];
});

my $around = $space->around('execute', sub {
  my ($orig, $self, $value) = @_;
  my $result = $self->$orig($value);
  push @$result, 'wrapped';
  return $result;
});

# sub { ... }

around example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('execute', sub {
  my ($self, $value) = @_;
  return [$value];
});

$space->around('execute', sub {
  my ($orig, $self, $value) = @_;
  my $result = $self->$orig($value);
  push @$result, 'wrapped';
  return $result;
});

my $object = $space->build({});

my $result = $object->execute('test');

# ['test', 'wrapped']

may raise Venus::Space::Error on.around.missing

package main;

use Venus::Space;

my $space = Venus::Space->new('Venus::Check');

$space->around('not_a_method');

# Error! (on.around.missing)

array

array(string $name, any @data) (arrayref)

The array method gets or sets the value for the given package array variable name.

Since 0.01

array example 1

# given: synopsis;

package Foo::Bar;

our @handler = 'start';

package main;

my $array = $space->array('handler');

# ["start"]

array example 2

# given: synopsis;

package Foo::Bar;

our @handler = 'start';

package main;

my $array = $space->array('handler', 'restart');

# ["restart"]

arrays

arrays() (arrayref)

The arrays method searches the package namespace for arrays and returns their names.

Since 0.01

arrays example 1

# given: synopsis;

package Foo::Bar;

our @handler = 'start';
our @initial = ('next', 'prev');

package main;

my $arrays = $space->arrays;

# ["handler", "initial"]

attributes

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

attributes example 1

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"]

attributes example 2

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

authority() (maybe[string])

The authority method returns the AUTHORITY declared on the target package, if any.

Since 0.01

authority example 1

package Foo::Boo;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/boo');

my $authority = $space->authority;

# undef

authority example 2

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() (string)

The basename method returns the last segment of the package namespace parts.

Since 0.01

basename example 1

# given: synopsis;

my $basename = $space->basename;

# "Bar"

before

before(string $name, coderef $code) (coderef)

The before method installs a method modifier that executes before the original method, allowing you to perform actions before a method call. Note: The return value of the modifier routine is ignored; the wrapped method always returns the value from the original method. Modifiers are executed in the order they are stacked.

Since 4.15

before example 1

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('execute', sub {
  my ($self) = @_;
  return [@_];
});

my $before = $space->before('execute', sub {
  my ($self) = @_;
  $self->{started} = 1;
});

# sub { ... }

before example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('new', sub {
  my ($class) = @_;
  return bless {tick => 1}, $class;
});

$space->routine('execute', sub {
  my ($self) = @_;
  $self->{tick} = $self->{step_1} = $self->{tick} + 1;
  return $self;
});

$space->before('execute', sub {
  my ($self) = @_;
  $self->{tick} = $self->{step_2} = $self->{tick} + 1;
  return;
});

my $object = $space->build({});

my $result = $object->execute;

# bless({step_1 => 3, step_2 => 2}, 'Foo::Bar')

blessed

blessed(Ref $data) (Venus::Space)

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

blessed example 1

# given: synopsis;

package Foo::Bar;

sub import;

package main;

my $blessed = $space->blessed;

# bless({}, "Foo::Bar")

blessed example 2

# given: synopsis;

package Foo::Bar;

sub import;

package main;

my $blessed = $space->blessed({okay => 1});

# bless({ okay => 1 }, "Foo::Bar")

build

build(any @args) (Venus::Space)

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")

call example 3

package main;

use Venus::Space;

my $space = Venus::Space->new('foo');

my $result = $space->call('missing');

# Exception! (isa Venus::Space::Error) (see error_on_call_missing)

may raise Venus::Space::Error on.call.missing

package main;

use Venus::Space;

my $space = Venus::Space->new('Venus::Check');

$space->call('not_a_method');

# Error! (on.call.missing)

chain

chain(string | tuple[string, 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(string @path) (Venus::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() (within[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(string $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(..., @_) }

cop example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

my $code = $space->cop('missing', $space->blessed);

# Exception! (isa Venus::Space::Error) (see error_on_cop_missing)

may raise Venus::Space::Error on.cop.missing

package main;

use Venus::Space;

my $space = Venus::Space->new('Venus::Check');

$space->cop('not_a_method');

# Error! (on.cop.missing)

data

data() (string)

The data method attempts to read and return any content stored in the DATA section of the package namespace.

Since 0.01

data example 1

# given: synopsis;

my $data = $space->data;

# ""

eval

eval(string @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

eval example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('foo');

my $eval = $space->eval('die');

# Exception! (isa Venus::Space::Error) (see error_on_eval)

may raise Venus::Space::Error on.eval

package main;

use Venus::Space;

my $space = Venus::Space->new('Venus::Check');

$space->eval('die');

# Error! (on.eval)

explain

explain() (string)

The explain method returns the package name and is used in stringification operations.

Since 0.01

explain example 1

# given: synopsis;

my $explain = $space->explain;

# "Foo::Bar"

handle

handle(string $name, coderef $code) (coderef)

The handle method installs a method modifier that wraps a method similar to around, providing low-level control over method execution. The modifier receives the original method as its first argument (which may be undef if the method doesn't exist), followed by the method's arguments. This is the foundation for the other method modifiers (/before, /after, /around). The modifiers are executed in the order they are stacked rather than maintaining a global registry.

Since 4.15

handle example 1

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('execute', sub {
  my ($self, $value) = @_;
  return $value;
});

my $handle = $space->handle('execute', sub {
  my ($orig, $self, $value) = @_;
  return $orig ? $self->$orig($value * 2) : 0;
});

# sub { ... }

handle example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->routine('execute', sub {
  my ($self, $value) = @_;
  return $value;
});

$space->handle('execute', sub {
  my ($orig, $self, $value) = @_;
  return $orig ? $self->$orig($value * 2) : 0;
});

my $object = $space->build({});

my $result = $object->execute(5);

# 10

handle example 3

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar');

$space->do('init');

$space->handle('missing', sub {
  my ($orig, $self) = @_;
  return 'method does not exist';
});

my $object = $space->build({});

my $result = $object->missing;

# "method does not exist"

hash

hash(string $name, any @data) (hashref)

The hash method gets or sets the value for the given package hash variable name.

Since 0.01

hash example 1

# given: synopsis;

package Foo::Bar;

our %settings = (
  active => 1
);

package main;

my $hash = $space->hash('settings');

# { active => 1 }

hash example 2

# given: synopsis;

package Foo::Bar;

our %settings = (
  active => 1
);

package main;

my $hash = $space->hash('settings', inactive => 1);

# { inactive => 1 }

hashes

hashes() (arrayref)

The hashes method searches the package namespace for hashes and returns their names.

Since 0.01

hashes example 1

# given: synopsis;

package Foo::Bar;

our %defaults = (
  active => 0
);

our %settings = (
  active => 1
);

package main;

my $hashes = $space->hashes;

# ["defaults", "settings"]

hook

hook(string $type, string $name, coderef $code) (coderef)

The hook method is a specialized method modifier helper that applies a modifier (after, around, before, or handle) to a lifecycle hook method. It automatically uppercases the hook name, making it convenient for modifying Venus lifecycle hooks like BUILD, BLESS, BUILDARGS, and AUDIT.

Since 4.15

hook example 1

package Foo::Bar::Hook;

use Venus::Class;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar/hook');

$space->routine('BUILD', sub {
  my ($self, $args) = @_;
  $self->{started} = 1;
});

my $hook = $space->hook('before', 'build', sub {
  my ($self) = @_;
  $self->{initialized} = 1;
});

# sub { ... }

hook example 2

package Foo::Bar::Hook;

use Venus::Class;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/bar/hook');

$space->routine('BUILD', sub {
  my ($self, $args) = @_;
  $self->{started} = 1;
});

$space->hook('before', 'build', sub {
  my ($self) = @_;
  $self->{initialized} = 1;
});

my $object = $space->build({});

# bless({initialized => 1, started => 1}, 'Foo::Bar')

id

id() (string)

The id method returns the fully-qualified package name as a label.

Since 0.01

id example 1

# given: synopsis;

my $id = $space->id;

# "Foo_Bar"

included

included() (string | 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;

# []

inherits example 2

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

init() (string)

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

init example 1

package main;

use Venus::Space;

my $space = Venus::Space->new('kit');

my $init = $space->init;

# "Kit"

inject

inject(string $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

integrates

integrates() (arrayref)

The integrates method returns the list of roles integrated into the target package.

Since 1.30

integrates example 1

# given: synopsis

package main;

my $integrates = $space->integrates;

# []

integrates example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('Venus::Test');

my $integrates = $space->integrates;

# [...]

lfile

lfile() (string)

The lfile method returns a .pm file path for the underlying package.

Since 1.30

lfile example 1

# given: synopsis

package main;

my $lfile = $space->lfile;

# "Foo/Bar.pm"

load

load() (string)

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"

load example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('no/thing');

my $load = $space->load;

# Exception! (isa Venus::Space::Error) (see error_on_load)

may raise Venus::Space::Error on.load

package main;

use Venus::Space;

my $space = Venus::Space->new('Fake::Package::NotReal');

$space->load;

# Error! (on.load)

loaded

loaded() (boolean)

The loaded method checks whether the package namespace is already loaded and returns truthy or falsy.

Since 0.01

loaded example 1

package main;

use Venus::Space;

my $space = Venus::Space->new('Kit');

$space->init;

$space->unload;

my $loaded = $space->loaded;

# 0

loaded example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('Kit');

$space->init;

my $loaded = $space->loaded;

# 1

locate

locate() (string)

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 1

package main;

use Venus::Space;

my $space = Venus::Space->new('xyz');

my $locate = $space->locate;

# ""

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"

mock

mock() (Venus::Space)

The mock method returns a Venus::Space object representing an anonymous package that derives from the invoking package.

Since 1.50

mock example 1

# given: synopsis

package main;

my $mock = $space->mock;

# bless({'name' => 'Venus::Space::Mock::0001::Foo::Bar'}, 'Venus::Space')

# $mock->isa('Foo::Bar') # true

name

name() (string)

The name method returns the fully-qualified package name.

Since 0.01

name example 1

# given: synopsis;

my $name = $space->name;

# "Foo::Bar"

new

new(any @args) (Venus::Space)

The new method constructs an instance of the package.

Since 4.15

new example 1

package main;

use Venus::Space;

my $new = Venus::Space->new('Foo::Bar');

# bless(..., "Venus::Space")

new example 2

package main;

use Venus::Space;

my $new = Venus::Space->new(value => 'Foo::Bar');

# bless(..., "Venus::Space")

parent

parent() (Venus::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 1

# given: synopsis;

my $parse = $space->parse;

# ["Foo", "Bar"]

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"]

patch

patch(string $name, coderef $code) (Venus::Space)

The patch method overwrites the named subroutine in the underlying package using the "swap" operation, stashing the original subroutine reference to be reset later using "unpatch".

Since 0.01

patch example 1

package Foo::Far;

use Venus::Class;

sub execute {
  1
}

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/far');

my $patch = $space->patch('execute', sub {
  $_[0]->() + 1
});

# bless(..., "Venus::Space")

# $patch->patched;

# true

# Foo::Far->new->execute;

# 2

patched

patched(string $name) (boolean)

The patched method confirms whether a subroutine in the underlying namespace has been patched using the "patch" operation. If no name is provided, this method will return true if any subroutines have been patched. If a name is provided, this method will return true only if the named subroutine has been patched, and otherwise returns false.

Since 3.55

patched example 1

package Foo::Far;

use Venus::Class;

sub execute {
  1
}

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/far');

$space->patch('execute', sub {
  $_[0]->() + 1
});

my $patched = $space->patched;

# true

patched example 2

package Foo::Far;

use Venus::Class;

sub execute {
  1
}

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/far');

$space->patch('execute', sub {
  $_[0]->() + 1
});

my $patched = $space->patched('execute');

# true

patched example 3

package Foo::Far;

use Venus::Class;

sub execute {
  1
}

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/far');

$space->patch('execute', sub {
  $_[0]->() + 1
});

my $patched = $space->patched('prepare');

# false

pfile

pfile() (string)

The pfile method returns a .pod file path for the underlying package.

Since 1.30

pfile example 1

# given: synopsis

package main;

my $pfile = $space->pfile;

# "Foo/Bar.pod"

prepend

prepend(string @path) (Venus::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")

purge

purge() (Venus::Space)

The purge method purges a package space by expunging its symbol table and removing it from %INC. Warning: This method deletes symbol table entries entirely, which may cause issues with code that holds compiled references to package variables. For safer cleanup that preserves symbol table structure, see "scrub".

Since 1.02

purge example 1

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

rebase(string @path) (Venus::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() (string)

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 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

reload example 2

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

require(string $target) (any)

The require method executes a require statement within the package namespace specified.

Since 0.01

require example 1

# given: synopsis;

my $require = $space->require('Venus');

# 1

root

root() (string)

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

root example 1

# given: synopsis;

my $root = $space->root;

# "Foo"

routine

routine(string $name, coderef $code) (coderef)

The routine method gets or sets 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 { ... }

routine example 2

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

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(string $name, any @data) (any)

The scalar method gets or sets the value for the given package scalar variable name.

Since 0.01

scalar example 1

# given: synopsis;

package Foo::Bar;

our $root = '/path/to/file';

package main;

my $scalar = $space->scalar('root');

# "/path/to/file"

scalar example 2

# 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

scalars() (arrayref)

The scalars method searches the package namespace for scalars and returns their names.

Since 0.01

scalars example 1

# given: synopsis;

package Foo::Bar;

our $root = 'root';
our $base = 'path/to';
our $file = 'file';

package main;

my $scalars = $space->scalars;

# ["base", "file", "root"]

scrub

scrub() (Venus::Space)

The scrub method cleans a package space by nullifying its typeglobs (setting them to undef) for all symbols except special variables and routines (like @ISA, DESTROY, etc.), and removes it from %INC. Unlike "purge", this method preserves the stash entries allowing compiled code holding references to remain valid. Unlike "unload", this method preserves special symbols needed for proper package operation. See also "purge" and "unload".

Since 4.15

scrub example 1

package main;

use Venus::Space;

# Bar::Gen is generated with $VERSION as 0.01

my $space = Venus::Space->new('Bar/Gen');

$space->load;

my $scrub = $space->scrub;

# bless({ value => "Bar::Gen" }, "Venus::Space")

# Bar::Gen->VERSION was 0.01, now undef

# Symbol table persists, $space->visible is 1

sibling

sibling(string $path) (Venus::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() (within[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"),
#   ...
# ]

splice

splice(number $offset, number $length, any @list) (Venus::Space)

The splice method perform a Perl "splice" in perlfunc operation on the package namespace.

Since 0.09

splice example 1

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")

splice example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/baz');

my $splice = $space->splice(1, 1);

# bless({ value => "Foo" }, "Venus::Space")

splice example 3

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/baz');

my $splice = $space->splice(-2, 1);

# bless({ value => "Baz" }, "Venus::Space")

splice example 4

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/baz');

my $splice = $space->splice(1);

# bless({ value => "Foo" }, "Venus::Space")

swap

swap(string $name, coderef $code) (coderef)

The swap method overwrites the named subroutine in the underlying package with the code reference provided and returns the original subroutine as a code reference. The code provided will be passed a reference to the original subroutine as its first argument.

Since 1.95

swap example 1

package Foo::Swap;

use Venus::Class;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/swap');

my $subroutine = $space->swap('new', sub {
  my ($next, @args) = @_;
  my $self = $next->(@args);
  $self->{swapped} = 1;
  return $self;
});

# sub { ... }

swap example 2

package Foo::Swap;

use Venus::Class;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/swap');

my $subroutine = $space->swap('something', sub {
  my ($next, @args) = @_;
  my $self = $next->(@args);
  $self->{swapped} = 1;
  return $self;
});

# Exception! (isa Venus::Space::Error) (see error_on_swap)

tfile

tfile() (string)

The tfile method returns a .t file path for the underlying package.

Since 1.30

tfile example 1

# given: synopsis

package main;

my $tfile = $space->tfile;

# "Foo_Bar.t"

tryload

tryload() (boolean)

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

unload

unload() (Venus::Space)

The unload method unloads a package space by nullifying its symbol table (setting all typeglobs to undef) and removing it from %INC. Unlike "purge", this method preserves symbol table entries, keeping the package visible. Unlike "scrub", this method nullifies entire typeglobs rather than individual slots.

Since 1.02

unload example 1

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

unloaded

unloaded() (boolean)

The unloaded method checks whether the package namespace is not loaded and returns truthy or falsy.

Since 1.02

unloaded example 1

package main;

use Venus::Space;

my $space = Venus::Space->new('Kit');

$space->init;

$space->unload;

my $unloaded = $space->unloaded;

# 1

unloaded example 2

package main;

use Venus::Space;

my $space = Venus::Space->new('Kit');

$space->init;

my $unloaded = $space->unloaded;

# 0

unpatch

unpatch(string @names) (Venus::Space)

The unpatch method restores a subroutine which has been patched using the "patch" operation to its original subroutine reference. If no name is provided, this method will restore all subroutines have been patched. If a name is provided, this method will only restore the named subroutine has been patched.

Since 3.55

unpatch example 1

package Foo::Far;

use Venus::Class;

sub execute {
  1
}

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/far');

$space->patch('execute', sub {
  $_[0]->() + 1
});

my $unpatch = $space->unpatch;

# bless(..., "Venus::Space")

unpatch example 2

package Foo::Far;

use Venus::Class;

sub execute {
  1
}

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/far');

$space->patch('execute', sub {
  $_[0]->() + 1
});

my $unpatch = $space->unpatch('execute');

# bless(..., "Venus::Space")

unpatch example 3

package Foo::Far;

use Venus::Class;

sub execute {
  1
}

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/far');

$space->patch('execute', sub {
  $_[0]->() + 1
});

my $unpatch = $space->unpatch('prepare');

# bless(..., "Venus::Space")

use

use(string | tuple[string, string] $target, any @params) (Venus::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('Venus');

# 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('Venus', 'error');

# 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(['Venus', 9.99], 'error');

variables

variables() (within[arrayref, tuple[string, 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[string])

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

visible

visible() (boolean)

The visible method returns truthy is the package namespace is visible, i.e. has symbols defined.

Since 1.02

visible example 1

# given: synopsis

package main;

my $visible = $space->visible;

# 1

visible example 2

package Foo::Fe;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/fe');

my $visible = $space->visible;

# 0

visible example 3

package Foo::Fe;

our $VERSION = 0.01;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/fe');

my $visible = $space->visible;

# 1

visible example 4

package Foo::Fi;

sub import;

package main;

use Venus::Space;

my $space = Venus::Space->new('foo/fi');

my $visible = $space->visible;

# 1

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 2163:

alternative text '/before' contains non-escaped | or /

alternative text '/after' contains non-escaped | or /

alternative text '/around' contains non-escaped | or /

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

ABSTRACT

SYNOPSIS

DESCRIPTION

INHERITS

METHODS

after

all

append

around

array

arrays

attributes

authority

basename

before

blessed

build

call

chain

child

children

cop

data

eval

explain

handle

hash

hashes

hook

id

included

inherits

init

inject

integrates

lfile

load

loaded

locate

meta

mock

name

new

parent

parse

parts

patch

patched

pfile

prepend

purge

rebase

reload

require

root

routine

routines

scalar

scalars

scrub

sibling

siblings

splice

swap

tfile

tryload

unload

unloaded

unpatch

use

variables

version

visible

AUTHORS

LICENSE

Module Install Instructions