NAME Data::Object::Space ABSTRACT Namespace Class for Perl 5 SYNOPSIS package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/bar'); DESCRIPTION This package provides methods for parsing and manipulating package namespaces. INHERITS This package inherits behaviors from: Data::Object::Name LIBRARIES This package uses type constraints from: Types::Standard METHODS This package implements the following methods: append append(Str @args) : Object The append method modifies the object by appending to the package namespace parts. append example #1 # given: synopsis $space->append('baz'); # 'Foo/Bar/Baz' append example #2 # given: synopsis $space->append('baz', 'bax'); # $space->package; # 'Foo/Bar/Baz/Bax' array array(Str $arg1) : ArrayRef The array method returns the value for the given package array variable name. array example #1 # given: synopsis package Foo::Bar; our @handler = 'start'; package main; $space->array('handler') # ['start'] arrays arrays() : ArrayRef The arrays method searches the package namespace for arrays and returns their names. arrays example #1 # given: synopsis package Foo::Bar; our @handler = 'start'; our @initial = ('next', 'prev'); package main; $space->arrays # ['handler', 'initial'] base base() : Str The base method returns the last segment of the package namespace parts. base example #1 # given: synopsis $space->base # Bar bless 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. bless example #1 # given: synopsis package Foo::Bar; sub import; package main; $space->bless # bless({}, 'Foo::Bar') bless example #2 # given: synopsis package Foo::Bar; sub import; package main; $space->bless({okay => 1}) # bless({okay => 1}, 'Foo::Bar') build build(Any @args) : Object The build method attempts to call new on the package namespace and if successful returns the resulting object. build example #1 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') build example #2 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 call(Any @args) : Any The call method attempts to call the given subroutine on the package namespace and if successful returns the resulting value. call example #1 # 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 child child(Str $arg1) : Object The child method returns a new Data::Object::Space object for the child package namespace. child example #1 # given: synopsis $space->child('baz'); # $space->package; # Foo::Bar::Baz children 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). children example #1 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 cop(Any @args) : CodeRef The cop method attempts to curry the given subroutine on the package namespace and if successful returns a closure. cop example #1 # 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(..., @_) } 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. destroy example #1 package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->load; # Data/Dumper $space->destroy; eval eval(Str @args) : Any The eval method takes a list of strings and evaluates them under the namespace represented by the instance. eval example #1 package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo'); $space->eval('our $VERSION = 0.01'); functions functions() : ArrayRef The functions method searches the package namespace for functions and returns their names. functions example #1 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 hash(Str $arg1) : HashRef The hash method returns the value for the given package hash variable name. hash example #1 # given: synopsis package Foo::Bar; our %settings = ( active => 1 ); package main; $space->hash('settings') # {active => 1} hashes hashes() : ArrayRef The hashes method searches the package namespace for hashes and returns their names. hashes example #1 # given: synopsis package Foo::Bar; our %defaults = ( active => 0 ); our %settings = ( active => 1 ); package main; $space->hashes # ['defaults', 'settings'] id id() : Str The id method returns the fully-qualified package name as a label. id example #1 # given: synopsis $space->id # Foo_Bar included included() : Str The included method returns the path of the namespace if it exists in %INC. included example #1 package main; my $space = Data::Object::Space->new('Data/Object/Space'); $space->included; # lib/Data/Object/Space.pm inherits inherits() : ArrayRef The inherits method returns the list of superclasses the target package is derived from. inherits example #1 package Bar; package main; my $space = Data::Object::Space->new('bar'); $space->inherits # [] inherits example #2 package Foo; package Bar; use base 'Foo'; package main; my $space = Data::Object::Space->new('bar'); $space->inherits # ['Foo'] 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. load example #1 package main; use Data::Object::Space; my $space = Data::Object::Space->new('c_p_a_n'); $space->load # CPAN loaded loaded() : Int The loaded method checks whether the package namespace is already loaded returns truthy or falsy. loaded example #1 package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->loaded; # 0 loaded example #2 package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->load; $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. locate example #1 package main; use Data::Object::Space; my $space = Data::Object::Space->new('brianne_spinka'); $space->locate; # '' locate example #2 package main; use Data::Object::Space; my $space = Data::Object::Space->new('data/dumper'); $space->locate; # /path/to/Data/Dumper.pm methods methods() : ArrayRef The methods method searches the package namespace for methods and returns their names. methods example #1 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 name() : Str The name method returns the fully-qualified package name. name example #1 # given: synopsis $space->name # Foo::Bar parent parent() : Object The parent method returns a new Data::Object::Space object for the parent package namespace. parent example #1 # given: synopsis $space->parent; # $space->package; # Foo parse parse() : ArrayRef The parse method parses the string argument and returns an arrayref of package namespace segments (parts). parse example #1 my $space = Data::Object::Space->new('Foo::Bar'); $space->parse; # ['Foo', 'Bar'] parse example #2 my $space = Data::Object::Space->new('Foo/Bar'); $space->parse; # ['Foo', 'Bar'] parse example #3 my $space = Data::Object::Space->new('Foo\Bar'); $space->parse; # ['Foo', 'Bar'] parse example #4 my $space = Data::Object::Space->new('foo-bar'); $space->parse; # ['FooBar'] parse example #5 my $space = Data::Object::Space->new('foo_bar'); $space->parse; # ['FooBar'] parts parts() : ArrayRef The parts method returns an arrayref of package namespace segments (parts). parts example #1 my $space = Data::Object::Space->new('foo'); $space->parts; # ['Foo'] parts example #2 my $space = Data::Object::Space->new('foo/bar'); $space->parts; # ['Foo', 'Bar'] parts example #3 my $space = Data::Object::Space->new('foo_bar'); $space->parts; # ['FooBar'] prepend prepend(Str @args) : Object The prepend method modifies the object by prepending to the package namespace parts. prepend example #1 # given: synopsis $space->prepend('etc'); # 'Etc/Foo/Bar' prepend example #2 # given: synopsis $space->prepend('etc', 'tmp'); # 'Etc/Tmp/Foo/Bar' rebase 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. rebase example #1 # given: synopsis $space->rebase('zoo'); # Zoo/Bar 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. root example #1 # given: synopsis $space->root # Foo routine routine(Str $arg1) : CodeRef The routine method returns the subroutine reference for the given subroutine name. routine example #1 package Foo; sub cont { [@_] } sub abort { [@_] } package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo'); $space->routine('cont') # sub { ... } routines routines() : ArrayRef The routines method searches the package namespace for routines and returns their names. routines example #1 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 scalar(Str $arg1) : Any The scalar method returns the value for the given package scalar variable name. scalar example #1 # given: synopsis package Foo::Bar; our $root = '/path/to/file'; package main; $space->scalar('root') # /path/to/file scalars scalars() : ArrayRef The scalars method searches the package namespace for scalars and returns their names. scalars example #1 # given: synopsis package Foo::Bar; our $root = 'root'; our $base = 'path/to'; our $file = 'file'; package main; $space->scalars # ['root', 'base', 'file'] sibling sibling(Str $arg1) : Object The sibling method returns a new Data::Object::Space object for the sibling package namespace. sibling example #1 # given: synopsis $space->sibling('baz') # Foo::Baz siblings 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). siblings example #1 package main; use Data::Object::Space; my $space = Data::Object::Space->new('encode/m_i_m_e'); $space->siblings # [ # 'Encode/Alias', # 'Encode/Config' # ... # ] 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. used example #1 package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/xyz'); $space->used # '' used example #2 package main; use Data::Object::Space; my $space = Data::Object::Space->new('c_p_a_n'); $space->load; $space->used # 'CPAN' used example #3 package Foo::Bar; sub import; package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/bar'); $space->used # 'Foo/Bar' variables variables() : ArrayRef[Tuple[Str, ArrayRef]] The variables method searches the package namespace for variables and returns their names. variables example #1 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 version() : Maybe[Str] The version method returns the VERSION declared on the target package, if any. version example #1 package Foo::Boo; package main; use Data::Object::Space; my $space = Data::Object::Space->new('foo/boo'); $space->version # undef version example #2 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' AUTHOR Al Newkirk, awncorp@cpan.org LICENSE 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" <https://github.com/iamalnewkirk/data-object-space/blob/master/LICENSE>. PROJECT Wiki <https://github.com/iamalnewkirk/data-object-space/wiki> Project <https://github.com/iamalnewkirk/data-object-space> Initiatives <https://github.com/iamalnewkirk/data-object-space/projects> Milestones <https://github.com/iamalnewkirk/data-object-space/milestones> Contributing <https://github.com/iamalnewkirk/data-object-space/blob/master/CONTRIBUTE.md> Issues <https://github.com/iamalnewkirk/data-object-space/issues>