Data::Object::Space

Namespace Class

Namespace Class for Perl 5

method: all method: append method: array method: arrays method: authority method: base method: bless method: build method: call method: chain method: child method: children method: cop method: data method: destroy method: eval method: functions method: hash method: hashes method: id method: included method: inherits method: init method: inject method: load method: loaded method: locate method: methods method: name method: parent method: parse method: parts method: prepend method: rebase method: require method: reload method: root method: routine method: routines method: scalar method: scalars method: sibling method: siblings method: tryload method: use method: used method: variables method: version

Data::Object::Name

Types::Standard

package main;

use Data::Object::Space;

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

This package provides methods for parsing and manipulating package namespaces.

The all method executes any available method on the instance and all instances representing packages inherited by the package represented by the invocant.

all(Str $name, Any @args) : ArrayRef[Tuple[Str, Any]]

=example-1 all

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('data/object/space');

$space->all('id');

# [
#   ['Data::Object::Space', 'Data_Object_Space'],
#   ['Data::Object::Name', 'Data_Object_Name'],
# ]

The append method modifies the object by appending to the package namespace parts.

append(Str @args) : Object

=example-1 append

# given: synopsis

$space->append('baz');

# 'Foo/Bar/Baz'

=example-2 append

# given: synopsis

$space->append('baz', 'bax');

# $space->package;

# 'Foo/Bar/Baz/Bax'

The array method returns the value for the given package array variable name.

array(Str $arg1) : ArrayRef

=example-1 array

# given: synopsis

package Foo::Bar;

our @handler = 'start';

package main;

$space->array('handler')

# ['start']

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

arrays() : ArrayRef

=example-1 arrays

# given: synopsis

package Foo::Bar;

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

package main;

$space->arrays

# ['handler', 'initial']

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

authority() : Maybe[Str]

=example-1 authority

package Foo::Boo;

package main;

use Data::Object::Space;

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

$space->authority

# undef

=example-2 authority

package Foo::Boo;

our $AUTHORITY = 'cpan:AWNCORP';

package main;

use Data::Object::Space;

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

$space->authority

# 'cpan:AWNCORP'

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

base() : Str

=example-1 base

# given: synopsis

$space->base

# Bar

The bless method blesses the given value into the package namespace and returns an object. If no value is given, an empty hashref is used.

bless(Any $arg1 = {}) : Object

=example-1 bless

# given: synopsis

package Foo::Bar;

sub import;

package main;

$space->bless

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

=example-2 bless

# given: synopsis

package Foo::Bar;

sub import;

package main;

$space->bless({okay => 1})

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

The build method attempts to call new on the package namespace and if successful returns the resulting object.

build(Any @args) : Object

=example-1 build

package Foo::Bar::Baz;

sub new {
  bless {}, $_[0]
}

package main;

use Data::Object::Space;

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

$space->build

# bless({}, 'Foo::Bar::Baz')

=example-2 build

package Foo::Bar::Bax;

sub new {
  bless $_[1], $_[0]
}

package main;

use Data::Object::Space;

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

$space->build({okay => 1})

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

The call method attempts to call the given subroutine on the package namespace and if successful returns the resulting value.

call(Any @args) : Any

=example-1 call

# given: synopsis

package Foo;

sub import;

sub start {
  'started'
}

package main;

use Data::Object::Space;

$space = Data::Object::Space->new('foo');

$space->call('start')

# started

=example-2 call

# given: synopsis

package Zoo;

sub import;

sub AUTOLOAD {
  bless {};
}

sub DESTROY {
  ; # noop
}

package main;

use Data::Object::Space;

$space = Data::Object::Space->new('zoo');

$space->call('start')

# bless({}, 'Zoo')

The chain method chains one or more method calls and returns the result.

chain(Str | Tuple[Str, Any] @steps) : Any

=example-1 chain

package Chu::Chu0;

sub import;

package main;

my $space = Data::Object::Space->new('Chu::Chu0');

$space->chain('bless');

=example-2 chain

package Chu::Chu1;

sub import;

sub new {
  bless pop;
}

sub frame {
  [@_]
}

package main;

my $space = Data::Object::Space->new('Chu::Chu1');

$space->chain(['bless', {1..4}], 'frame');

# [ bless( { '1' => 2, '3' => 4 }, 'Chu::Chu1' ) ]

=example-3 chain

package Chu::Chu2;

sub import;

sub new {
  bless pop;
}

sub frame {
  [@_]
}

package main;

my $space = Data::Object::Space->new('Chu::Chu2');

$space->chain('bless', ['frame', {1..4}]);

# [ bless( {}, 'Chu::Chu2' ), { '1' => 2, '3' => 4 } ]

The child method returns a new Data::Object::Space object for the child package namespace.

child(Str $arg1) : Object

=example-1 child

# given: synopsis

$space->child('baz');

# $space->package;

# Foo::Bar::Baz

The children method searches %INC and @INC and retuns a list of Data::Object::Space objects for each child namespace found (one level deep).

children() : ArrayRef[Object]

=example-1 children

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('c_p_a_n');

$space->children

# [
#   'CPAN/Author',
#   'CPAN/Bundle',
#   'CPAN/CacheMgr',
#   ...
# ]

The cop method attempts to curry the given subroutine on the package namespace and if successful returns a closure.

cop(Any @args) : CodeRef

=example-1 cop

# given: synopsis

package Foo::Bar;

sub import;

sub handler {
  [@_]
}

package main;

use Data::Object::Space;

$space = Data::Object::Space->new('foo/bar');

$space->cop('handler', $space->bless)

# sub { Foo::Bar::handler(..., @_) }

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

data() : Str

=example-1 data

package main;

use Data::Object::Space;

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

$space->data; # ''

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.

destroy() : Object

=example-1 destroy

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('data/dumper');

$space->load; # Data/Dumper

$space->destroy;

The eval method takes a list of strings and evaluates them under the namespace represented by the instance.

eval(Str @args) : Any

=example-1 eval

package main;

use Data::Object::Space;

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

$space->eval('our $VERSION = 0.01');

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

functions() : ArrayRef

=example-1 functions

package Foo::Functions;

use routines;

fun start() {
  1
}

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('foo/functions');

$space->functions

# ['start']

The hash method returns the value for the given package hash variable name.

hash(Str $arg1) : HashRef

=example-1 hash

# given: synopsis

package Foo::Bar;

our %settings = (
  active => 1
);

package main;

$space->hash('settings')

# {active => 1}

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

hashes() : ArrayRef

=example-1 hashes

# given: synopsis

package Foo::Bar;

our %defaults = (
  active => 0
);

our %settings = (
  active => 1
);

package main;

$space->hashes

# ['defaults', 'settings']

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

id() : Str

=example-1 id

# given: synopsis

$space->id

# Foo_Bar

The included method returns the path of the namespace if it exists in %INC.

included() : Str

=example-1 included

package main;

my $space = Data::Object::Space->new('Data/Object/Space');

$space->included;

# lib/Data/Object/Space.pm

The inherits method returns the list of superclasses the target package is derived from.

inherits() : ArrayRef

=example-1 inherits

package Bar;

package main;

my $space = Data::Object::Space->new('bar');

$space->inherits

# []

=example-2 inherits

package Foo;

package Bar;

use base 'Foo';

package main;

my $space = Data::Object::Space->new('bar');

$space->inherits

# ['Foo']

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.

init() : Str

=example-1 init

package main;

use Data::Object::Space;

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

$space->init

# Kit

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.

inject(Str $name, Maybe[CodeRef] $coderef) : Any

=example-1 inject

package main;

use Data::Object::Space;

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

$space->inject('build', sub { 'finished' });

# *Kit::build

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.

load() : Str

=example-1 load

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('c_p_a_n');

$space->load

# CPAN

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

loaded() : Int

=example-1 loaded

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('data/dumper');

$space->loaded;

# 0

=example-2 loaded

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('data/dumper');

$space->load;

$space->loaded;

# 1

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.

locate() : Str

=example-1 locate

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('brianne_spinka');

$space->locate;

# ''

=example-2 locate

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('data/dumper');

$space->locate;

# /path/to/Data/Dumper.pm

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

methods() : ArrayRef

=example-1 methods

package Foo::Methods;

use routines;

method start() {
  1
}

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('foo/methods');

$space->methods

# ['start']

The name method returns the fully-qualified package name.

name() : Str

=example-1 name

# given: synopsis

$space->name

# Foo::Bar

The parent method returns a new Data::Object::Space object for the parent package namespace.

parent() : Object

=example-1 parent

# given: synopsis

$space->parent;

# $space->package;

# Foo

The parse method parses the string argument and returns an arrayref of package namespace segments (parts).

parse() : ArrayRef

=example-1 parse

my $space = Data::Object::Space->new('Foo::Bar');

$space->parse;

# ['Foo', 'Bar']

=example-2 parse

my $space = Data::Object::Space->new('Foo/Bar');

$space->parse;

# ['Foo', 'Bar']

=example-3 parse

my $space = Data::Object::Space->new('Foo\Bar');

$space->parse;

# ['Foo', 'Bar']

=example-4 parse

my $space = Data::Object::Space->new('foo-bar');

$space->parse;

# ['FooBar']

=example-5 parse

my $space = Data::Object::Space->new('foo_bar');

$space->parse;

# ['FooBar']

The parts method returns an arrayref of package namespace segments (parts).

parts() : ArrayRef

=example-1 parts

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

$space->parts;

# ['Foo']

=example-2 parts

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

$space->parts;

# ['Foo', 'Bar']

=example-3 parts

my $space = Data::Object::Space->new('foo_bar');

$space->parts;

# ['FooBar']

The prepend method modifies the object by prepending to the package namespace parts.

prepend(Str @args) : Object

=example-1 prepend

# given: synopsis

$space->prepend('etc');

# 'Etc/Foo/Bar'

=example-2 prepend

# given: synopsis

$space->prepend('etc', 'tmp');

# 'Etc/Tmp/Foo/Bar'

The rebase method returns an object by prepending the package namespace specified to the base of the current object's namespace.

rebase(Str @args) : Object

=example-1 rebase

# given: synopsis

$space->rebase('zoo');

# Zoo/Bar

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

require(Str $target) : Any

=example-1 require

# given: synopsis

$space->require('Moo');

# 1

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.

reload() : Str

=example-1 reload

package main;

use Data::Object::Space;

# Foo::Gen is generate with $VERSION as 0.01

my $space = Data::Object::Space->new('foo/gen');

$space->reload;

# Foo::Gen
# Foo::Gen->VERSION is 0.01

=example-2 reload

package main;

use Data::Object::Space;

# Foo::Gen is regenerated with $VERSION as 0.02

my $space = Data::Object::Space->new('foo/gen');

$space->reload;

# Foo::Gen
# Foo::Gen->VERSION is 0.02

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() : Str

=example-1 root

# given: synopsis

$space->root;

# Foo

The routine method returns the subroutine reference for the given subroutine name.

routine(Str $arg1) : CodeRef

=example-1 routine

package Foo;

sub cont {
  [@_]
}

sub abort {
  [@_]
}

package main;

use Data::Object::Space;

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

$space->routine('cont')

# sub { ... }

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

routines() : ArrayRef

=example-1 routines

package Foo::Routines;

sub start {
  1
}

sub abort {
  1
}

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('foo/routines');

$space->routines

# ['start', 'abort']

The scalar method returns the value for the given package scalar variable name.

scalar(Str $arg1) : Any

=example-1 scalar

# given: synopsis

package Foo::Bar;

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

package main;

$space->scalar('root')

# /path/to/file

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

scalars() : ArrayRef

=example-1 scalars

# given: synopsis

package Foo::Bar;

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

package main;

$space->scalars

# ['root', 'base', 'file']

The sibling method returns a new Data::Object::Space object for the sibling package namespace.

sibling(Str $arg1) : Object

=example-1 sibling

# given: synopsis

$space->sibling('baz')

# Foo::Baz

The siblings method searches %INC and @INC and retuns a list of Data::Object::Space objects for each sibling namespace found (one level deep).

siblings() : ArrayRef[Object]

=example-1 siblings

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('encode/m_i_m_e');

$space->siblings

# [
#   'Encode/Alias',
#   'Encode/Config'
#   ...
# ]

The tryload method attempt to load the represented package using the "load" method and returns truthy/falsy based on whether the package was loaded.

tryload() : Bool

=example-1 tryload

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('c_p_a_n');

$space->tryload

# 1

=example-2 tryload

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('brianne_spinka');

$space->tryload

# 0

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

use(Str | Tuple[Str, Str] $target, Any @params) : Object

=example-1 use

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('foo/goo');

$space->use('Moo');

# $self

=example-2 use

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('foo/hoo');

$space->use('Moo', 'has');

# $self

=example-3 use

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('foo/ioo');

$space->use(['Moo', 9.99], 'has');

# $self

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.

used() : Str

=example-1 used

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('foo/xyz');

$space->used

# ''

=example-2 used

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('c_p_a_n');

$space->load;
$space->used

# 'CPAN'

=example-3 used

package Foo::Bar;

sub import;

package main;

use Data::Object::Space;

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

$space->used

# 'Foo/Bar'

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

variables() : ArrayRef[Tuple[Str, ArrayRef]]

=example-1 variables

package Etc;

our $init = 0;
our $func = 1;

our @does = (1..4);
our %sets = (1..4);

package main;

use Data::Object::Space;

my $space = Data::Object::Space->new('etc');

$space->variables

# [
#   ['arrays', ['does']],
#   ['hashes', ['sets']],
#   ['scalars', ['func', 'init']],
# ]

The version method returns the VERSION declared on the target package, if any.

version() : Maybe[Str]

=example-1 version

package Foo::Boo;

package main;

use Data::Object::Space;

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

$space->version

# undef

=example-2 version

package Foo::Boo;

our $VERSION = 0.01;

package main;

use Data::Object::Space;

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

$space->version

# '0.01'

cpanm Data::Object::Space

perl -MCPAN -e shell
install Data::Object::Space