The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Do-1.85
River stage zero No dependents
7 ++
/ Data::Object::Space

NAME

Data::Object::Space

ABSTRACT

Data-Object Space Class

SYNOPSIS

  use Data::Object::Space;

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

  "$space"
  # Data::Object

  $space->name;
  # Data::Object

  $space->path;
  # Data/Object

  $space->file;
  # Data/Object.pm

  $space->children;
  # ['Data/Object/Array.pm', ...]

  $space->siblings;
  # ['Data/Dumper.pm', ...]

  $space->load;
  # Data::Object

DESCRIPTION

This package provides methods for parsing and manipulating package namespaces.

LIBRARIES

This package uses type constraints defined by:

Data::Object::Library

METHODS

This package implements the following methods.

append

  append(Str $arg1) : Object

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

append example
  # given $space (Foo::Bar)

  $space->append('baz');

  "$space"

  # Foo::Bar::Baz

array

  array(Str $arg1) : Any

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

array example
  # given Foo/Bar

  $space->array('EXPORT');

  # (,...)

arrays

  arrays() : ArrayRef

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

arrays example
  # given Foo/Bar

  $space->arrays();

  # [,...]

base

  base() : Str

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

base example
  # given $space (Foo::Bar)

  $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
  # given $space (Foo::Bar)

  $space->bless();

  # bless({}, '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
  # given $space (Foo::Bar)

  $space->build(@args);

  # bless(..., 'Foo::Bar')

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
  # given $space (Foo::Bar)

  $space->call(@args);

  # ...

child

  child(Str $arg1) : Object

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

child example
  # given $space (Foo::Bar)

  $space->child('baz');

  # Foo::Bar::Baz

children

  children() : ArrayRef

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
  # given $space (Foo::Bar)

  $space->children();

  # ['Foo::Bar::Baz', ...]

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
  # given $space (Foo::Bar)

  $space->cop(@args);

  # ...

file

  file(Str $arg1 = '%s') : Str

The file method returns a file string for the package namespace. This method optionally takes a format string.

file example
  # given $space (Foo::Bar)

  $space->file();

  # Foo/Bar.pm

  $space->file('lib/%s');

  # lib/Foo/Bar.pm

functions

  functions() : ArrayRef

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

functions example
  # given Foo/Bar

  $space->functions();

  # [,...]

hash

  hash(Str $arg1) : Any

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

hash example
  # given Foo/Bar

  $space->hash('EXPORT_TAGS');

  # (,...)

hashes

  hashes() : ArrayRef

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

hashes example
  # given Foo/Bar

  $space->hashes();

  # [,...]

id

  id() : Str

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

id example
  # given $space (Foo::Bar)

  $space->id;

  # Foo_Bar

load

  load() : Str

The load method check 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 croak. If the package is loadable, this method returns truthy with the package name.

load example
  # given $space (Foo::Bar)

  $space->load();

  # throws exception, unless Foo::Bar is loadable

methods

  methods() : ArrayRef

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

methods example
  # given Foo/Bar

  $space->methods();

  # [,...]

name

  name() : Str

The name method returns the fully-qualified package name.

name example
  # given $space (Foo::Bar)

  $space->name;

  # Foo::Bar

parent

  parent() : Str

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

parent example
  # given $space (Foo::Bar)

  $space->parent();

  # Foo

parse

  parse(Str $arg1) : ArrayRef

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

parse example
  # given Foo::Bar

  $space->parse('Foo::Bar');

  # ['Foo', 'Bar']

  $space->parse('Foo/Bar');

  # ['Foo', 'Bar']

  $space->parse('Foo\Bar');

  # ['Foo', 'Bar']

  $space->parse('foo-bar');

  # ['FooBar']

  $space->parse('foo_bar');

  # ['FooBar']

parts

  parts() : ArrayRef

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

parts example
  # given $space (Foo::Bar)

  $space->parts();

  # ['Foo', 'Bar']

path

  path(Str $arg1) : Str

The path method returns a path string for the package namespace. This method optionally takes a format string.

path example
  # given $space (Foo::Bar)

  $space->path();

  # Foo/Bar

  $space->path('lib/%s');

  # lib/Foo/Bar

prepend

  prepend(Str $arg1) : Object

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

prepend example
  # given $space (Foo::Bar)

  $space->prepend('via');

  "$space"

  # Via::Foo::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
  # given $space (root => 'Foo', parts => 'Bar')

  $space->root();

  # ['Foo']

routine

  routine(Str $arg1) : CodeRef

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

routine example
  # given Foo/Bar

  $space->routine('import');

  # ...

routines

  routines() : ArrayRef

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

routines example
  # given Foo/Bar

  $space->routines();

  # [,...]

scalar

  scalar(Str $arg1) : Any

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

scalar example
  # given Foo/Bar

  $space->scalar('VERSION');

  # 0.01

scalars

  scalars() : ArrayRef

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

scalars example
  # given Foo/Bar

  $space->scalars();

  # [,...]

sibling

  sibling(Str $arg1) : Object

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

sibling example
  # given $space (Foo::Bar)

  $space->sibling('Baz');

  # Foo::Baz

siblings

  siblings() : ArrayRef

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
  # given $space (Foo::Bar)

  $space->siblings();

  # ['Foo::Baz', ...]

type

  type() : Str

The type method returns the parsed filetype and defaults to pm. This value is used when calling the file method.

type example
  # given $space (Foo/Bar.pod)

  $space->type();

  # pod

used

  used() : ArrayRef | Undef

The used method searches %INC for the package namespace and if found returns the filepath and complete filepath for the loaded package, otherwise returns undef.

used example
  # given $space (Foo::Bar)

  $space->used();

  # undef, unless Foo::Bar is in %INC

variables

  variables() : ArrayRef

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

variables example
  # given Foo/Bar

  $space->variables();

  # [,...]

CREDITS

Al Newkirk, +309

Anthony Brummett, +10

Adam Hopkins, +2

José Joaquín Atria, +1

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 same terms as the Perl 5 programming language system itself.

PROJECT

Wiki

Project

Initiatives

Milestones

Contributing

Issues

SEE ALSO

To get the most out of this distribution, consider reading the following:

Do

Data::Object

Data::Object::Class

Data::Object::ClassHas

Data::Object::Role

Data::Object::RoleHas

Data::Object::Library