NAME
    Class::Tiny - Minimalist class construction

VERSION
    version 0.004

SYNOPSIS
    In Person.pm:

      package Person;

      use Class::Tiny qw( name );

      1;

    In Employee.pm:

      package Employee;
      use parent 'Person';

      use Class::Tiny qw( ssn );

      1;

    In example.pl:

      use Employee;

      my $obj = Employee->new( name => "Larry", ssn => "111-22-3333" );

      # unknown attributes are fatal:
      eval { Employee->new( name => "Larry", OS => "Linux" ) };
      die "Error creating Employee: $@" if $@;

DESCRIPTION
    This module offers a minimalist class construction kit in around 100
    lines of code. Here is a list of features:

    *   defines attributes via import arguments

    *   generates read-write accessors

    *   supports custom accessors

    *   superclass provides a standard "new" constructor

    *   "new" takes a hash reference or list of key/value pairs

    *   "new" has heuristics to catch constructor attribute typos

    *   "new" calls "BUILD" for each class from parent to child

    *   superclass provides a "DESTROY" method

    *   "DESTROY" calls "DEMOLISH" for each class from child to parent

    It uses no non-core modules for any recent Perl. On Perls older than
    v5.10 it requires MRO::Compat. On Perls older than v5.14, it requires
    Devel::GlobalDestruction.

  Why this instead of Object::Tiny or Class::Accessor or something else?
    I wanted something so simple that it could potentially be used by core
    Perl modules I help maintain (or hope to write), most of which either
    use Class::Struct or roll-their-own OO framework each time.

    Object::Tiny and Object::Tiny::RW were close to what I wanted, but
    lacking some features I deemed necessary, and their maintainers have an
    even more strict philosophy against feature creep than I have.

    Compared to everything else, this is smaller in implementation and
    simpler in API. (The only API is a list of attributes!)

    I looked for something like it on CPAN, but after checking a dozen class
    creators I realized I could implement it exactly how I wanted faster
    than I could search CPAN for something merely sufficient.

USAGE
  Defining attributes
    Define attributes as a list of import arguments:

        package Foo::Bar;

        use Class::Tiny qw(
            name
            id
            height
            weight
        );

    For each item, a read-write accessor is created unless a subroutine of
    that name already exists:

        $obj->name;               # getter
        $obj->name( "John Doe" ); # setter

    Attribute names must be valid subroutine identifiers or an exception
    will be thrown.

    To make your own custom accessors, just pre-declare the method name
    before loading Class::Tiny:

        package Foo::Bar;

        use subs 'id';

        use Class::Tiny qw( name id );

        sub id { ... }

    By declaring "id" also with Class::Tiny, you include it in the list of
    allowed constructor parameters.

  Class::Tiny::Object is your base class
    If your class does not already inherit from some class, then
    Class::Tiny::Object will be added to your @ISA to provide "new" and
    "DESTROY".

    If your class does inherit from something, then no additional
    inheritance is set up. If the parent subclasses Class::Tiny::Object,
    then all is well. If not, then you'll get accessors set up but no
    constructor or destructor. Don't do that unless you really have a
    special need for it.

    Define subclasses as normal. It's best to define them with base, parent
    or superclass before defining attributes with Class::Tiny so the @ISA
    array is already populated at compile-time:

        package Foo::Bar::More;

        use parent 'Foo::Bar';

        use Class::Tiny qw( shoe_size );

  Object construction
    If your class inherits from Class::Tiny::Object (as it should if you
    followed the advice above), it provides the "new" constructor for you.

    Objects can be created with attributes given as a hash reference or as a
    list of key/value pairs:

        $obj = Foo::Bar->new( name => "David" );

        $obj = Foo::Bar->new( { name => "David" } );

    If a reference is passed as a single argument, it must be able to be
    dereferenced as a hash or an exception is thrown. A shallow copy is made
    of the reference provided.

    In order to help catch typos in constructor arguments, any argument that
    it is not also a valid method (e.g. an accessor or other method) will
    result in a fatal exception. This is not perfect, but should catch
    typical transposition typos. Also see "BUILD" for how to explicitly hide
    non-attribute, non-method arguments if desired.

  BUILD
    If your class or any superclass defines a "BUILD" method, it will be
    called by the constructor from the furthest parent class down to the
    child class after the object has been created.

    It is passed the constructor arguments as a hash reference. The return
    value is ignored. Use "BUILD" for validation or setting default values.

        sub BUILD {
            my ($self, $args) = @_;
            $self->foo(42) unless defined $self->foo;
            croak "Foo must be non-negative" if $self->foo < 0;
        }

    If you want to hide a non-attribute constructor argument from
    validation, delete it from the passed-in argument hash reference.

        sub BUILD {
            my ($self, $args) = @_;

            if ( delete $args->{do_something_special} ) {
                ...
            }
        }

    The argument reference is a copy, so deleting elements won't affect data
    in the object. You have to delete it from both if that's what you want.

        sub BUILD {
            my ($self, $args) = @_;

            if ( delete $args->{do_something_special} ) {
                delete $self->{do_something_special};
                ...
            }
        }

  DEMOLISH
    Class::Tiny provides a "DESTROY" method. If your class or any superclass
    defines a "DEMOLISH" method, they will be called from the child class to
    the furthest parent class during object destruction. It is provided a
    single boolean argument indicating whether Perl is in global
    destruction. Return values and errors are ignored.

        sub DEMOLISH {
            my ($self, $global_destruct) = @_;
            $self->cleanup();
        }

  Introspection and internals
    You can retrieve an unsorted list of valid attributes known to
    Class::Tiny for a class and its superclasses with the
    "get_all_attributes_for" class method.

        my @attrs = Class::Tiny->get_all_attributes_for("Employee");
        # @attrs contains qw/name ssn/

    The "import" method uses two class methods, "prepare_class" and
    "create_attributes" to set up the @ISA array and attributes. Anyone
    attempting to extend Class::Tiny itself should use these instead of
    mocking up a call to "import".

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://github.com/dagolden/class-tiny/issues>. You will be notified
    automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/dagolden/class-tiny>

      git clone git://github.com/dagolden/class-tiny.git

AUTHOR
    David Golden <dagolden@cpan.org>

CONTRIBUTORS
    *   Karen Etheridge <ether@cpan.org>

    *   Matt S Trout <mstrout@cpan.org>

    *   Olivier Mengué <dolmen@cpan.org>

    *   Toby Inkster <inkster@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2013 by David Golden.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004