The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Object-Quick-0.009
/ Object::Quick

NAME

Object::Quick - Quickly turn a hash into an object.

DESCRIPTION

An object created from a hash. Every hash key can be used as a method to get/set the hash element. Creation of a new key is as simple as $obj->newkey( $val ). Essentially an object oriented interface to a hash.

Actual methods can be added to individual objects as well. Note these methods are object specific, not class specific. Adding a method to one object will not add it to others. There are some class methods in the works to help manage methods.

WHERE IS THIS USEFUL

This object is very useful in testing code. Sometimes you just need to setup a simulation of an object. Maybe you also need this simulation to have methods that return more objects. It was also fun to implement.

The fact is that in almost every case it would be better to create a proper package for the class you need. Aside from some testing scenarios I cannot think of a real-world use for this. However you may be able to find a use for it.

SYNOPSYS

Use Object-Quick with a quick-create function names. Whatever names you provide will be used as names of shortcut functions. Providing no name will not import any function. First name is quick object creation, second name is the method maker, third name is the clear helper for clearing values.

Import the class, bring in shortcut functions:

    use Object::Quick qw/obj vm clear/;

    my $obj = obj( a => 'a' );
    print $obj->a; #prints 'a'

New keys can be added trivially:

    $obj->newkey( 'new key!' );
    print $obj->newkey; #prints 'new key!'

Add a method to the object:

    $obj->do_stuff( vm { my $self = shift; $self->ran( @_ ) });
    $obj->do_stuff( 'Blah' );
    print $obj->ran; #prints 'Blah'

Remove a method from the object:

    $obj->do_stuff( clear );
    ok( !$obj->do_stuff );
    $obj->do_stuff( 'Blah' );
    print $obj->do_stuff; #prints 'Blah'

You can create objects with attributes sharing the names of class-methods

    $obj = obj( new => 'new' );
    print $obj->new; #prints 'new'

You can accomplish the same without shortcuts, but it adds a lot of typing:

    use Object::Quick;

    # Create
    my $obj = Object::Quick->new();

    # Add a custom method
    $obj->sub( Object::Quick::Method->new( sub { 'a' });
    print $obj->sub; # prints 'a'

    # and to clear
    $obj->sub( $Object::Quick::CLEAR );

EXPORTED FUNCTIONS

Nothing is exported without arguments. The first three arguments are simply shortcuts to reduce your typing. They are only exported if specified, and they take whatever name you provide.

You can use the special arguments -obj, -class, and -all as well, see below for what they do.

Argument 1 - Quick object constructor
    use Object::Quick 'obj';
    my $obj = obj( a => a );

This function is a shortcut so you don't have to keep typing Object::Quick->new( ... ). It takes any arguments new() accepts.

Argument 2 - Method creator
    use Object::Quick 'obj', 'method';
    my $obj = obj( a => 'a', m => method { 'method' });
    $obj->sub( method { my $self = shift; my @args = @_; return 'stuff' });

This function is used to create a special subref that Object::Quick recognises as a method, and as such runs it with arguments instead of returning the ref.

Argument 3 - Clearer
    use Object::Quick qw/obj method clear/;
    my $obj = obj( a => 'a', m => method { 'method' });
    $obj->sub( method { my $self = shift; my @args = @_; return 'stuff' });

    # Now we can also remove a method from an object
    $obj->sub( clear );

This is primarily used to remove methods from objects.

Argument - -obj
    use Object::Quick '-obj';
    # Same as: use Object::Quick qw/obj method clear/;

    $obj = obj( a => method { 'a' });
    $obj->a( clear );

This imports the 3 primary functions with simple names

Argument - -class
    use Object::Quick '-class';

Import all class methods in function form so you can use

    method( ... );

Instead of

    Object::Quick->method( ... );
Argument - -class

Same as:

    use Object::Quick qw/-obj -class/;

OBJECT METHODS

Anything that is a legal method name can be used. Can be used to get or set the attribute of the object. If given an Object::Quick::Method object then all future calls to that method will run the Method with any arguments provided. Methods can be cleared by using the $Object::Quick::CLEAR variable as an argument to the method, that is all the clear() shortcut function does.

At object construction the following methods are added to your object. If you do not want these methods you can override them by providing your own.

    use Object::Quick 'obj', 'method';

    # Has methods following standard perl object conventions
    my $obj = obj;

    # Leave-out or override some standard object methods.
    my $obj = obj( can => undef, DESTROY => method { ... }, ... );
$obj->new( key => 'val' )

This will create a new object with all the same methods as the original as well as any data or methods provided to new().

$obj->can( $name )

Always returns a subref, there is never a case where it will return undef on an object.

    use Object::Quick 'obj';
    my $obj = obj;

    my $sub = $obj->can( 'stuff' );
    $obj->$sub( 'value' );
$obj->isa( $package )

Works as expected

$obj->DESTROY

Currently does nothing except return true.

CLASS METHODS

They can only be used as class methods. When used as object method they will act like any other accessor. This allows for objects with attributes named 'new', 'import', and 'AUTOLOAD', etc...

When -class is provided as an argument to use, class methods are imported as functions. Heres an example:

    use Object::Quick 'obj';
    my $obj = obj();
    my $methods Object::Quick->methods( $obj );

Can also be done like this:

    use Object::Quick qw/obj -class/;
    my $obj = obj();
    my $methods = methods( $obj );

Notes:

new(), import(), and AUTOLOAD() are not imported when package is used with -class.

$obj = $class->new( $hashref )
$obj = $class->new( %hash )
$obj = $class->new()

The object constructor. Creates a new instance of an object with the provided hash. If no hash is provided an anonymous one will be created.

$clone = $class->clone( $obj )

Clone an Object::Quick object. This is not a deep copy, a new reference is created and blessed, however it goes no deeper.

$hash = $class->methods( $obj )

Returns a hash with all the Methods in the object, method names are the keys.

$class->add_methods( $obj, name => sub { ... }, nameb => sub { ... })

Add the specified methods to $obj

my $new = $class->instance( $obj )

Crate a new instance of the given object; that is create a new object with all the same methods, but none of the accessor values.

$class->inherit( $one, $two )

Give $one all the methods currently in $two.

$class->class_methods( $obj )

Give $obj object method forms of all the class methods except for new, import, and AUTOLOAD.

example:

    use Object::Quick 'obj';
    my $obj = obj();
    Object::Quick->class_methods( $obj );

    my $new = $obj->clone;
    my $methods = $obj->methods;
    $obj->inherit( $two );
    $new = $obj->instance;

MAGIC

$class->import()
$class->import( @args )

Automatically called when you use Object::Quick. The optional arguments are the names you want to use for the shortcut functions.

AUTOLOAD()

This is a special method. This is where the magic happens. Read the perldoc for AUTOLOAD for more details.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2010 Chad Granum

Object-Quick is free software; Standard perl licence.

Object-Quick is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.