Data::Object::Space - Namespace Class
Namespace Class for Perl 5
package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/bar');
This package provides methods for parsing and manipulating package namespaces.
This package inherits behaviors from:
Data::Object::Name
This package uses type constraints from:
Types::Standard
This package implements the following methods:
all(Str $name, 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.
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'], # ]
append(Str @args) : Object
The append method modifies the object by appending to the package namespace parts.
# given: synopsis $space->append('baz'); # 'Foo/Bar/Baz'
# given: synopsis $space->append('baz', 'bax'); # $space->package; # 'Foo/Bar/Baz/Bax'
array(Str $arg1) : ArrayRef
The array method returns the value for the given package array variable name.
# given: synopsis package Foo::Bar; our @handler = 'start'; package main; $space->array('handler') # ['start']
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; $space->arrays # ['handler', 'initial']
authority() : Maybe[Str]
The authority method returns the AUTHORITY declared on the target package, if any.
AUTHORITY
package Foo::Boo; package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/boo'); $space->authority # undef
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'
base() : Str
The base method returns the last segment of the package namespace parts.
# given: synopsis $space->base # Bar
bless(Any $arg1 = {}) : Object
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.
# given: synopsis package Foo::Bar; sub import; package main; $space->bless # bless({}, 'Foo::Bar')
# given: synopsis package Foo::Bar; sub import; package main; $space->bless({okay => 1}) # bless({okay => 1}, 'Foo::Bar')
build(Any @args) : Object
The build method attempts to call new on the package namespace and if successful returns the resulting object.
new
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')
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')
call(Any @args) : Any
The call method attempts to call the given subroutine on the package namespace and if successful returns the resulting value.
# 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
# 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')
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; my $space = Data::Object::Space->new('Chu::Chu0'); $space->chain('bless');
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' ) ]
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 } ]
child(Str $arg1) : Object
The child method returns a new Data::Object::Space object for the child package namespace.
# given: synopsis $space->child('baz'); # $space->package; # Foo::Bar::Baz
children() : ArrayRef[Object]
The children method searches %INC and @INC and retuns a list of Data::Object::Space objects for each child namespace found (one level deep).
%INC
@INC
package main; use Data::Object::Space; my $space = Data::Object::Space->new('c_p_a_n'); $space->children # [ # 'CPAN/Author', # 'CPAN/Bundle', # 'CPAN/CacheMgr', # ... # ]
cop(Any @args) : CodeRef
The cop method attempts to curry the given subroutine on the package namespace and if successful returns a closure.
# 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(..., @_) }
data() : Str
The data method attempts to read and return any content stored in the DATA section of the package namespace.
DATA
package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo'); $space->data; # ''
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.
package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->load; # Data/Dumper $space->destroy;
eval(Str @args) : Any
The eval method takes a list of strings and evaluates them under the namespace represented by the instance.
package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo'); $space->eval('our $VERSION = 0.01');
functions() : ArrayRef
The functions method searches the package namespace for functions and returns their names.
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']
hash(Str $arg1) : HashRef
The hash method returns the value for the given package hash variable name.
# given: synopsis package Foo::Bar; our %settings = ( active => 1 ); package main; $space->hash('settings') # {active => 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; $space->hashes # ['defaults', 'settings']
id() : Str
The id method returns the fully-qualified package name as a label.
# given: synopsis $space->id # Foo_Bar
included() : Str
The included method returns the path of the namespace if it exists in %INC.
package main; my $space = Data::Object::Space->new('Data/Object/Space'); $space->included; # lib/Data/Object/Space.pm
inherits() : ArrayRef
The inherits method returns the list of superclasses the target package is derived from.
package Bar; package main; my $space = Data::Object::Space->new('bar'); $space->inherits # []
package Foo; package Bar; use base 'Foo'; package main; my $space = Data::Object::Space->new('bar'); $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 Data::Object::Space; my $space = Data::Object::Space->new('kit'); $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 Data::Object::Space; my $space = Data::Object::Space->new('kit'); $space->inject('build', sub { 'finished' }); # *Kit::build
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 Data::Object::Space; my $space = Data::Object::Space->new('c_p_a_n'); $space->load # CPAN
loaded() : Int
The loaded method checks whether the package namespace is already loaded returns truthy or falsy.
package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->loaded; # 0
package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->load; $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 Data::Object::Space; my $space = Data::Object::Space->new('brianne_spinka'); $space->locate; # ''
package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->locate; # /path/to/Data/Dumper.pm
methods() : ArrayRef
The methods method searches the package namespace for methods and returns their names.
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']
name() : Str
The name method returns the fully-qualified package name.
# given: synopsis $space->name # Foo::Bar
parent() : Object
The parent method returns a new Data::Object::Space object for the parent package namespace.
# given: synopsis $space->parent; # $space->package; # Foo
parse() : ArrayRef
The parse method parses the string argument and returns an arrayref of package namespace segments (parts).
my $space = Data::Object::Space->new('Foo::Bar'); $space->parse; # ['Foo', 'Bar']
my $space = Data::Object::Space->new('Foo/Bar'); $space->parse; # ['Foo', 'Bar']
my $space = Data::Object::Space->new('Foo\Bar'); $space->parse; # ['Foo', 'Bar']
my $space = Data::Object::Space->new('foo-bar'); $space->parse; # ['FooBar']
my $space = Data::Object::Space->new('foo_bar'); $space->parse; # ['FooBar']
parts() : ArrayRef
The parts method returns an arrayref of package namespace segments (parts).
my $space = Data::Object::Space->new('foo'); $space->parts; # ['Foo']
my $space = Data::Object::Space->new('foo/bar'); $space->parts; # ['Foo', 'Bar']
my $space = Data::Object::Space->new('foo_bar'); $space->parts; # ['FooBar']
prepend(Str @args) : Object
The prepend method modifies the object by prepending to the package namespace parts.
# given: synopsis $space->prepend('etc'); # 'Etc/Foo/Bar'
# given: synopsis $space->prepend('etc', 'tmp'); # 'Etc/Tmp/Foo/Bar'
rebase(Str @args) : Object
The rebase method returns an object by prepending the package namespace specified to the base of the current object's namespace.
# given: synopsis $space->rebase('zoo'); # Zoo/Bar
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 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
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
require(Str $target) : Any
The require method executes a require statement within the package namespace specified.
require
# given: synopsis $space->require('Moo'); # 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 $space->root; # Foo
routine(Str $arg1) : CodeRef
The routine method returns the subroutine reference for the given subroutine name.
package Foo; sub cont { [@_] } sub abort { [@_] } package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo'); $space->routine('cont') # sub { ... }
routines() : ArrayRef
The routines method searches the package namespace for routines and returns their names.
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']
scalar(Str $arg1) : Any
The scalar method returns the value for the given package scalar variable name.
# given: synopsis package Foo::Bar; our $root = '/path/to/file'; package main; $space->scalar('root') # /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; $space->scalars # ['root', 'base', 'file']
sibling(Str $arg1) : Object
The sibling method returns a new Data::Object::Space object for the sibling package namespace.
# given: synopsis $space->sibling('baz') # Foo::Baz
siblings() : ArrayRef[Object]
The siblings method searches %INC and @INC and retuns a list of Data::Object::Space objects for each sibling namespace found (one level deep).
package main; use Data::Object::Space; my $space = Data::Object::Space->new('encode/m_i_m_e'); $space->siblings # [ # 'Encode/Alias', # 'Encode/Config' # ... # ]
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 Data::Object::Space; my $space = Data::Object::Space->new('c_p_a_n'); $space->tryload # 1
package main; use Data::Object::Space; my $space = Data::Object::Space->new('brianne_spinka'); $space->tryload # 0
use(Str | Tuple[Str, Str] $target, Any @params) : Object
The use method executes a use statement within the package namespace specified.
use
package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/goo'); $space->use('Moo'); # $self
package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/hoo'); $space->use('Moo', 'has'); # $self
package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/ioo'); $space->use(['Moo', 9.99], 'has'); # $self
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.
package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/xyz'); $space->used # ''
package main; use Data::Object::Space; my $space = Data::Object::Space->new('c_p_a_n'); $space->load; $space->used # 'CPAN'
package Foo::Bar; sub import; package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/bar'); $space->used # 'Foo/Bar'
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 Data::Object::Space; my $space = Data::Object::Space->new('etc'); $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; package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/boo'); $space->version # undef
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'
Al Newkirk, awncorp@cpan.org
awncorp@cpan.org
Copyright (C) 2011-2019, Al Newkirk, et al.
This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file".
Wiki
Project
Initiatives
Milestones
Contributing
Issues
To install Data::Object::Space, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Object::Space
CPAN shell
perl -MCPAN -e shell install Data::Object::Space
For more information on module installation, please visit the detailed CPAN module installation guide.