NAME

Data::Object::Export

ABSTRACT

Data-Object Exportable Functions

SYNOPSIS

  use Data::Object::Export 'cast';

  my $array = cast []; # Data::Object::Array

DESCRIPTION

Data::Object::Export is an exporter that provides various useful utility functions and function-bundles.

EXPORTS

This package can export the following functions.

all

  use Data::Object::Export ':all';

The all export tag will export all exportable functions.

core

  use Data::Object::Export ':core';

The core export tag will export the exportable functions cast, codify, const, deduce, deduce_deep, deduce_type, detract, detract_deep, dispatch, dump, immutable, load, prototype, and throw exclusively.

data

  use Data::Object::Export ':data';

The data export tag will export the exportable functions data_any, data_array, data_code, data_float, data_hash, data_integer, data_number, data_regexp, data_scalar, data_string, and data_undef.

plus

  use Data::Object::Export ':plus';

The plus export tag will export the exportable functions carp, confess cluck croak, class_file, class_name, class_path, library, namespace, path_class, path_name, registry, and reify.

type

  use Data::Object::Export ':type';

The type export tag will export the exportable functions type_any, type_array, type_code, type_float, type_hash, type_integer, type_number, type_regexp, type_scalar, type_string, and type_undef.

vars

  use Data::Object::Export ':vars';

The vars export tag will export the exportable variable $dispatch.

FUNCTIONS

This package implements the following functions.

cast

  cast(Any $arg1) : Any

The cast function returns a Data::Object for the data provided. If the data passed is blessed then that same object will be returned.

cast example
  # given [1..4]

  my $array = cast([1..4]); # Data::Object::Array

class_file

  class_file(Str $arg1) : Str

The class_file function convertss a class name to a class file.

class_file example
  # given 'Foo::Bar'

  class_file('Foo::Bar'); # foo_bar

class_name

  class_name(Str $arg1) : Str

The class_name function converts a string to a class name.

class_name example
  # given 'foo-bar'

  class_name('foo-bar'); # Foo::Bar

class_path

  class_path(Str $arg1) : Str

The class_path function converts a class name to a class file.

class_path example
  # given 'Foo::BarBaz'

  class_path('Foo::BarBaz'); 'Foo/BarBaz.pm'

codify

  codify(Str $arg1) : CodeRef

The codify function returns a parameterized coderef from a string.

codify example
  my $coderef = codify('$a + $b + $c', 1, 2);

  # $coderef->(3) returns 6

const

  const(Str $arg1, Any $arg2) : CodeRef

The const function creates a constant function using the name and expression supplied to it. A constant function is a function that does not accept any arguments and whose result(s) are deterministic.

const example
  # given 1.098765;

  const VERSION => 1.098765;

data_any

  data_any(Any $arg1) : Object

The data_any function returns a Data::Object::Any instance which wraps the provided data type and can be used to perform operations on the data. The type_any function is an alias to this function.

data_any example
  # given 0;

  $object = data_any 0;
  $object->isa('Data::Object::Any');

data_array

  data_array(ArrayRef $arg1) : ArrayObject

The data_array function returns a Data::Object::Array instance which wraps the provided data type and can be used to perform operations on the data. The type_array function is an alias to this function.

data_array example
  # given [2..5];

  $data = data_array [2..5];
  $data->isa('Data::Object::Array');

data_code

  data_code(CodeRef $arg1) : CodeObject

The data_code function returns a Data::Object::Code instance which wraps the provided data type and can be used to perform operations on the data. The type_code function is an alias to this function.

data_code example
  # given sub { 1 };

  $object = data_code sub { 1 };
  $object->isa('Data::Object::Code');

data_data

  data_data(Str $arg1) : Object

The data_data function returns a Data::Object::Data instance which parses pod-ish data in files and packages.

data_data example
  # given Foo::Bar;

  $object = data_data 'Foo::Bar';
  $object->isa('Data::Object::Data');

data_dispatch

  data_dispatch(Str $arg1) : Object

The data_dispatch function returns a Data::Object::Dispatch instance which extends Data::Object::Code and dispatches to routines in the given package.

data_dispatch example
  # given Foo::Bar;

  $object = data_dispatch 'Foo::Bar';
  $object->isa('Data::Object::Dispatch');

data_exception

  data_exception(Any @args) : Object

The data_exception function returns a Data::Object::Exception instance which can be thrown.

data_exception example
  # given {,...};

  $object = data_exception {,...};
  $object->isa('Data::Object::Exception');

data_float

  data_float(Str $arg1) : FloatObject

The data_float function returns a Data::Object::Float instance which wraps the provided data type and can be used to perform operations on the data. The type_float function is an alias to this function.

data_float example
  # given 5.25;

  $object = data_float 5.25;
  $object->isa('Data::Object::Float');

data_hash

  data_hash(HashRef $arg1) : HashObject

The data_hash function returns a Data::Object::Hash instance which wraps the provided data type and can be used to perform operations on the data. The type_hash function is an alias to this function.

data_hash example
  # given {1..4};

  $object = data_hash {1..4};
  $object->isa('Data::Object::Hash');

data_integer

  data_integer(Int $arg1) : IntObject

The data_integer function returns a Data::Object::Object instance which wraps the provided data type and can be used to perform operations on the data. The type_integer function is an alias to this function.

data_integer example
  # given -100;

  $object = data_integer -100;
  $object->isa('Data::Object::Integer');

data_json

  data_json(Any @args) : Any

The data_json function encodes Perl data to JSON or decodes JSON strings to Perl.

data_json example
  # given $string

  my $data = data_json($string);

  # given $data

  my $string = data_json($data);

data_number

  data_number(Num $arg1) : NumObject

The data_number function returns a Data::Object::Number instance which wraps the provided data type and can be used to perform operations on the data. The type_number function is an alias to this function.

data_number example
  # given 100;

  $object = data_number 100;
  $object->isa('Data::Object::Number');

data_path

  data_path(Any @args) : Any

The data_path function returns a Data::Object::Path object for the given path.

data_path example
  # given $filepath

  my $path = data_path($filepath);

data_regexp

  data_regexp(RegexpRef $arg1) : RegexpObject

The data_regexp function returns a Data::Object::Regexp instance which wraps the provided data type and can be used to perform operations on the data. The type_regexp function is an alias to this function.

data_regexp example
  # given qr/test/;

  $object = data_regexp qr/test/;
  $object->isa('Data::Object::Regexp');

data_scalar

  data_scalar(Any $arg1) : ScalarObject

The data_scalar function returns a Data::Object::Scalar instance which wraps the provided data type and can be used to perform operations on the data. The type_scalar function is an alias to this function.

data_scalar example
  # given \*main;

  $object = data_scalar \*main;
  $object->isa('Data::Object::Scalar');

data_space

  data_space(Str $arg1) : Object

The data_space function returns a Data::Object::Space instance which provides methods for operating on package and namespaces.

data_space example
  # given Foo::Bar;

  $object = data_space 'Foo::Bar';
  $object->isa('Data::Object::Space');

data_string

  data_string(Str $arg1) : StrObject

The data_string function returns a Data::Object::String instance which wraps the provided data type and can be used to perform operations on the data. The type_string function is an alias to this function.

data_string example
  # given 'abcdefghi';

  $object = data_string 'abcdefghi';
  $object->isa('Data::Object::String');

data_tmpl

  data_tmpl(Any @args) : Any

The data_tmpl function returns a Data::Object::Template object.

data_tmpl example
  # given ($content, $variables)

  my $tmpl = data_tmpl;

  my $data = $tmpl->render($content, $variables);

data_undef

  data_undef(Undef $arg1) : UndefObject

The data_undef function returns a Data::Object::Undef instance which wraps the provided data type and can be used to perform operations on the data. The type_undef function is an alias to this function.

data_undef example
  # given undef;

  $object = data_undef undef;
  $object->isa('Data::Object::Undef');

data_yaml

  data_yaml(Any @args) : Any

The data_yaml function encodes Perl data to YAML or decodes YAML strings to Perl.

data_yaml example
  # given $string

  my $data = data_yaml($string);

  # given $data

  my $string = data_yaml($data);

deduce

  deduce(Any $arg1) : Any

The deduce function returns a data type object instance based upon the deduced type of data provided.

deduce example
  # given qr/\w+/;

  $object = deduce qr/\w+/;
  $object->isa('Data::Object::Regexp');

deduce_blessed

  deduce_blessed(Any $arg1) : Int

The deduce_blessed function returns truthy if the argument is blessed.

deduce_blessed example
  # given $data

  deduce_blessed($data);

deduce_deep

  deduce_deep(Any $arg1) : Any

The deduce_deep function returns a data type object. If the data provided is complex, this function traverses the data converting all nested data to objects. Note: Blessed objects are not traversed.

deduce_deep example
  # given {1,2,3,{4,5,6,[-1]}}

  $deep = deduce_deep {1,2,3,{4,5,6,[-1]}};

  # Data::Object::Hash {
  #   1 => Data::Object::Number ( 2 ),
  #   3 => Data::Object::Hash {
  #      4 => Data::Object::Number ( 5 ),
  #      6 => Data::Object::Array [ Data::Object::Integer ( -1 ) ],
  #   },
  # }

deduce_defined

  deduce_defined(Any $arg1) : Int

The deduce_defined function returns truthy if the argument is defined.

deduce_defined example
  # given $data

  deduce_defined($data);

deduce_numberlike

  deduce_numberlike(Any $arg1) : Int

The deduce_numberlike function returns truthy if the argument is numberlike.

deduce_numberlike example
  # given $data

  deduce_numberlike($data);

deduce_references

  deduce_references(Any $arg1) : Int

The deduce_references function returns a Data::Object object based on the type of argument reference provided.

deduce_references example
  # given $data

  deduce_references($data);

deduce_stringlike

  deduce_stringlike(Any $arg1) : Int

The deduce_stringlike function returns truthy if the argument is stringlike.

deduce_stringlike example
  # given $data

  deduce_stringlike($data);

deduce_type

  deduce_type(Any $arg1) : Str

The deduce_type function returns a data type description for the type of data provided, represented as a string in capital letters.

deduce_type example
  # given qr/\w+/;

  $type = deduce_type qr/\w+/; # REGEXP

detract

  detract(Any $arg1) : Any

The detract function returns a value of native type, based upon the underlying reference of the data type object provided.

detract example
  # given bless({1..4}, 'Data::Object::Hash');

  $object = detract $object; # {1..4}

detract_deep

  detract_deep(Any $arg1) : Any

The detract_deep function returns a value of native type. If the data provided is complex, this function traverses the data converting all nested data type objects into native values using the objects underlying reference. Note: Blessed objects are not traversed.

detract_deep example
  # given {1,2,3,{4,5,6,[-1, 99, bless({}), sub { 123 }]}};

  my $object = deduce_deep $object;
  my $revert = detract_deep $object; # produces ...

  # {
  #   '1' => 2,
  #   '3' => {
  #     '4' => 5,
  #     '6' => [ -1, 99, bless({}, 'main'), sub { ... } ]
  #     }
  # }

dispatch

  dispatch(Str $arg1) : Object

The dispatch function return a Data::Object::Dispatch object which is a handle that let's you call into other packages.

dispatch example
  my $dispatch = dispatch('main');

  # $dispatch->('run') calls main::run

do

  do(Str $arg1, Any @args) : Any

The do function is a special constructor function that is automatically exported into the consuming package. It overloads and extends the core do function, supporting the core functionality and adding a new feature, and exists to dispatch to exportable Data-Object functions and other dispatchers.

do example
  # given file syntax

  do 'file.pl'

  # given block syntax

  do { @{"${class}::ISA"} }

  # given func-args syntax

  do('any', [1..4]); # Data::Object::Any

dump

  dump(Any $arg1) : Str

The dump function returns a string representation of the data passed.

dump example
  # given {1..8}

  say dump {1..8};

immutable

  immutable(Any $arg1) : Any

The immutable function makes the data type object provided immutable. This function loads Data::Object::Immutable and returns the object provided as an argument.

immutable example
  # given [1,2,3];

  $object = immutable data_array [1,2,3];
  $object->isa('Data::Object::Array); # via Data::Object::Immutable

library

  library() : Object

The library function returns the default Type::Library object where all core type constraints are registered.

library example
  library; # Type::Library

load

  load(Str $arg1) : ClassName

The load function attempts to dynamically load a module and either dies or returns the package name of the loaded module.

load example
  # given 'List::Util';

  $package = load 'List::Util'; # List::Util if loaded

namespace

  namespace(ClassName $arg1, ClassName $arg2) : Str

The namespace function registers a type library with a namespace in the registry so that typed operations know where to look for type context-specific constraints.

namespace example
  # given Types::Standard

  namespace('App', 'Types::Standard');

path_class

  path_class(Str $arg1) : Str

The path_class function converts a path to a class name.

path_class example
  # given 'foo/bar_baz'

  path_class('foo/bar_baz'); # Foo::BarBaz

path_name

  path_name(Str $arg1) : Str

The path_name function converts a class name to a path.

path_name example
  # given 'Foo::BarBaz'

  path_name('Foo::BarBaz'); # foo-bar_baz

prototype

  prototype(Any @args) : Object

The prototype function returns a prototype object which can be used to generate classes, objects, and derivatives. This function loads Data::Object::Prototype and returns an object based on the arguments provided.

prototype example
  # given ('$name' => [is => 'ro']);

  my $proto  = data_prototype '$name' => [is => 'ro'];
  my $class  = $proto->create; # via Data::Object::Prototype
  my $object = $class->new(name => '...');

registry

  registry() : Object

The registry function returns the registry singleton object where mapping between namespaces and type libraries are registered.

registry example
  registry; # Data::Object::Registry

reify

  reify(Str $arg1) : Object

The reify function will construct a Type::Tiny type constraint object for the type expression provided.

reify example
  # given 'Str';

  $type = reify 'Str'; # Type::Tiny

throw

  throw(Any @args) : Object

The throw function will dynamically load and throw an exception object. This function takes all arguments accepted by the Data::Object::Exception class.

throw example
  # given $message;

  throw $message; # An exception (...) was thrown in -e at line 1