NAME

    Data::Object::Space - Namespace Class

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

 authority

      authority() : Maybe[Str]

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

    authority example #1

        package Foo::Boo;
      
        package main;
      
        use Data::Object::Space;
      
        my $space = Data::Object::Space->new('foo/boo');
      
        $space->authority
      
        # undef

    authority example #2

        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

      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

    call example #2

        # 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')

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

 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.

    init example #1

        package main;
      
        use Data::Object::Space;
      
        my $space = Data::Object::Space->new('kit');
      
        $space->init
      
        # Kit

 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.

    inject example #1

        package main;
      
        use Data::Object::Space;
      
        my $space = Data::Object::Space->new('kit');
      
        $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.

    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>