# NAME

Data::Object - Object Orientation for Perl 5

# VERSION

version 0.52

# SYNOPSIS

    package Person;

    use Data::Object::Class;
    use Data::Object::Class::Syntax;

    extends 'Entity';
    with    'Identity';

    alt id => is required, ro;

    has ['firstname', 'lastname'] => is required, ro;

    has address1  => is required, rw;
    has address2  => is optional, rw;

    has ['city', 'state', 'zip'] => is required, rw;

    def city  => 'San Franscisco';
    def state => 'CA';

    1;

# DESCRIPTION

Data::Object is a framework for writing structured and highly object-oriented
Perl 5 software programs. Additionally, this distribution provides classes
which wrap Perl 5 native data types and provides methods for operating on the
data.

# EXPORTS

## all

    use Data::Object qw(:all);

The all export tag will export all exportable functions.

## core

    use Data::Object qw(:core);

The core export tag will export the exportable functions `const`, `deduce`,
`deduce_deep`, `detract`, `detract_deep`, `immutable`, `load`, `prototype`,
and `throw` exclusively.

## data

    use Data::Object qw(:data);

The data export tag will export all exportable functions whose names are
prefixed with the word "data".

## type

    use Data::Object qw(:type);

The type export tag will export all exportable functions whose names are
prefixed with the word "type".

# FUNCTIONS

## const

    # given 1.098765;

    const VERSION => 1.098765;

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.

## data\_array

    # given [2..5];

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

The data\_array function returns a [Data::Object::Array](https://metacpan.org/pod/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\_code

    # given sub { 1 };

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

The data\_code function returns a [Data::Object::Code](https://metacpan.org/pod/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\_float

    # given 5.25;

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

The data\_float function returns a [Data::Object::Float](https://metacpan.org/pod/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\_hash

    # given {1..4};

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

The data\_hash function returns a [Data::Object::Hash](https://metacpan.org/pod/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\_integer

    # given -100;

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

The data\_integer function returns a [Data::Object::Object](https://metacpan.org/pod/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\_number

    # given 100;

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

The data\_number function returns a [Data::Object::Number](https://metacpan.org/pod/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\_regexp

    # given qr/test/;

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

The data\_regexp function returns a [Data::Object::Regexp](https://metacpan.org/pod/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\_scalar

    # given \*main;

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

The data\_scalar function returns a [Data::Object::Scalar](https://metacpan.org/pod/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\_string

    # given 'abcdefghi';

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

The data\_string function returns a [Data::Object::String](https://metacpan.org/pod/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\_undef

    # given undef;

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

The data\_undef function returns a [Data::Object::Undef](https://metacpan.org/pod/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\_universal

    # given 0;

    $object = data_universal 0;
    $object->isa('Data::Object::Universal');

The data\_universal function returns a [Data::Object::Universal](https://metacpan.org/pod/Data::Object::Universal) instance which
wraps the provided data type and can be used to perform operations on the data.
The `type_universal` function is an alias to this function.

## deduce

    # given qr/\w+/;

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

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

## deduce\_deep

    # 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 ) ],
    #     },
    # }

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\_type

    # given qr/\w+/;

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

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

## detract

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

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

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

## detract\_deep

    # 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 { ... } ]
    #       }
    # }

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.

## immutable

    # given [1,2,3];

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

The immutable function makes the data type object provided immutable. This
function loads [Data::Object::Immutable](https://metacpan.org/pod/Data::Object::Immutable) and returns the object provided as an
argument.

## load

    # given 'List::Util';

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

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

## prototype

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

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

The prototype function returns a prototype object which can be used to
generate classes, objects, and derivatives. This function loads
[Data::Object::Prototype](https://metacpan.org/pod/Data::Object::Prototype) and returns an object based on the arguments
provided.

## throw

    # given $message;

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

The throw function will dynamically load and throw an exception object. This
function takes all arguments accepted by the [Data::Object::Exception](https://metacpan.org/pod/Data::Object::Exception) class.

# SEE ALSO

- [Data::Object::Array](https://metacpan.org/pod/Data::Object::Array)
- [Data::Object::Class](https://metacpan.org/pod/Data::Object::Class)
- [Data::Object::Class::Syntax](https://metacpan.org/pod/Data::Object::Class::Syntax)
- [Data::Object::Code](https://metacpan.org/pod/Data::Object::Code)
- [Data::Object::Float](https://metacpan.org/pod/Data::Object::Float)
- [Data::Object::Hash](https://metacpan.org/pod/Data::Object::Hash)
- [Data::Object::Integer](https://metacpan.org/pod/Data::Object::Integer)
- [Data::Object::Number](https://metacpan.org/pod/Data::Object::Number)
- [Data::Object::Role](https://metacpan.org/pod/Data::Object::Role)
- [Data::Object::Role::Syntax](https://metacpan.org/pod/Data::Object::Role::Syntax)
- [Data::Object::Regexp](https://metacpan.org/pod/Data::Object::Regexp)
- [Data::Object::Scalar](https://metacpan.org/pod/Data::Object::Scalar)
- [Data::Object::String](https://metacpan.org/pod/Data::Object::String)
- [Data::Object::Undef](https://metacpan.org/pod/Data::Object::Undef)
- [Data::Object::Universal](https://metacpan.org/pod/Data::Object::Universal)
- [Data::Object::Autobox](https://metacpan.org/pod/Data::Object::Autobox)
- [Data::Object::Library](https://metacpan.org/pod/Data::Object::Library)
- [Data::Object::Prototype](https://metacpan.org/pod/Data::Object::Prototype)
- [Data::Object::Signatures](https://metacpan.org/pod/Data::Object::Signatures)

# AUTHOR

Al Newkirk <anewkirk@ana.io>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Al Newkirk.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.