This is an automated email from the git hooks/post-receive script. gregoa pushed a commit to annotated tag release-0.001 in repository libclass-tiny-perl.
commit 7e0235a09e3dd3a5dc85b3ae1b0f00265fc672cf Author: David Golden <dagol...@cpan.org> Date: Thu Aug 15 22:57:32 2013 -0400 write initial documentation --- META.json | 1 + README.pod | 137 +++++++++++++++++++++++++++++++++++++++++++++++++----- lib/Class/Tiny.pm | 116 ++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 232 insertions(+), 22 deletions(-) diff --git a/META.json b/META.json index 7d03c2a..8477fad 100644 --- a/META.json +++ b/META.json @@ -57,6 +57,7 @@ "Test::FailWarnings" : "0", "Test::Fatal" : "0", "Test::More" : "0.96", + "base" : "0", "lib" : "0" } } diff --git a/README.pod b/README.pod index 3398adb..ffb3b84 100644 --- a/README.pod +++ b/README.pod @@ -12,33 +12,148 @@ version 0.001 =head1 SYNOPSIS - package MyClass; +In F<Person.pm>: - use Class::Tiny qw( name color ); + package Person; + + use Class::Tiny qw( name ); + + 1; + +In F<Employee.pm>: + + package Employee; + use parent 'Person'; + + use Class::Tiny qw( ssn ); 1; - package main; +In F<example.pl>: - MyClass->new( name => "Larry", color => "orange" ); + use Employee; + + my $obj = Employee->new( name => "Larry", ssn => "111-22-3333" ); + + # unknown attributes are fatal: + eval { Employee->new( name => "Larry", OS => "Linux" ) }; =head1 DESCRIPTION -This module might be cool, but you'd never know it from the lack -of documentation. +This module offers a minimalist class construction kit in under 100 lines of +code. Here is a list of features: + +=over 4 + +=item * + +defines attributes via import arguments + +=item * + +generates accessors for all attributes + +=item * + +superclass provides a standard C<new> constructor + +=item * + +C<new> takes a hash reference or list of key/value pairs + +=item * + +C<new> throws an error for unknown attributes + +=item * + +may be subclassed + +=back + +It uses no non-core modules (except on Perls older than 5.10, where it requires +L<MRO::Compat> from CPAN). + +=head2 Why this instead of Object::Tiny or Class::Accessor or something else? -This is inspired by L<Object::Tiny::RW> with just a couple more features -to make it useful for class hierarchies. +I wanted something so simple that it could be potentially used by core Perl +modules I help maintain, most of which either use L<Class::Struct> or +roll-their-own OO framework for each one. + +L<Object::Tiny> and L<Object::Tiny::RW> were close to what I wanted, but +lacking some features I deemed necessary, and their maintainers have an even +more strict philsophy against feature creep that I have. + +Compared to everything else, this is smaller in implmentation and simpler in +API. (The only API is a list of attributes!) =for Pod::Coverage method_names_here =head1 USAGE -Good luck! +=head2 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: + + $obj->name( "John Doe" ); + +Attribute names must be valid subroutine identifiers or an exception will +be thrown. + +=head2 Subclassing + +Define subclasses as normal. It's best to define them with L<base>, L<parent> +or L<superclass> before defining attributes with Class::Tiny so the C<@ISA> +array is populated at compile-time: + + package Foo::Bar::More; + + use parent 'Foo::Bar'; + + use Class::Tiny qw( shoe_size ); + +If your class does not already inherit from some class, then Class::Tiny will +be added to your C<@ISA> to provide C<new>. + +If your class B<does> inherit from something, then no additional inheritance is +set up. If the parent subclasses Class::Tiny, then all is well. If not, then +you'll get accessors set up but no constructor (or features that come with it +like attribute validation). Don't do that unless you really have a special +need for it. + +=head2 Object construction + +If your class inherits from Class::Tiny (which it will by default), it provides +the C<new> constructor for you. + +Object 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 dereferenceable as a +hash or an exception is thrown. A shallow copy is made of the reference provided. + +=head2 BUILD + +To be implemented... -=head1 SEE ALSO +=head2 DEMOLISH -Maybe other modules do related things. +To be implemented... =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan diff --git a/lib/Class/Tiny.pm b/lib/Class/Tiny.pm index 09f8f11..9b6dbcd 100644 --- a/lib/Class/Tiny.pm +++ b/lib/Class/Tiny.pm @@ -69,32 +69,126 @@ sub new { =head1 SYNOPSIS - package MyClass; +In F<Person.pm>: - use Class::Tiny qw( name color ); + package Person; + + use Class::Tiny qw( name ); 1; - package main; +In F<Employee.pm>: + + package Employee; + use parent 'Person'; + + use Class::Tiny qw( ssn ); + + 1; - MyClass->new( name => "Larry", color => "orange" ); +In F<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" ) }; =head1 DESCRIPTION -This module might be cool, but you'd never know it from the lack -of documentation. +This module offers a minimalist class construction kit in under 100 lines of +code. Here is a list of features: + +=for :list +* defines attributes via import arguments +* generates accessors for all attributes +* superclass provides a standard C<new> constructor +* C<new> takes a hash reference or list of key/value pairs +* C<new> throws an error for unknown attributes +* may be subclassed + +It uses no non-core modules (except on Perls older than 5.10, where it requires +L<MRO::Compat> from CPAN). -This is inspired by L<Object::Tiny::RW> with just a couple more features -to make it useful for class hierarchies. +=head2 Why this instead of Object::Tiny or Class::Accessor or something else? + +I wanted something so simple that it could be potentially used by core Perl +modules I help maintain, most of which either use L<Class::Struct> or +roll-their-own OO framework for each one. + +L<Object::Tiny> and L<Object::Tiny::RW> were close to what I wanted, but +lacking some features I deemed necessary, and their maintainers have an even +more strict philsophy against feature creep that I have. + +Compared to everything else, this is smaller in implmentation and simpler in +API. (The only API is a list of attributes!) =head1 USAGE -Good luck! +=head2 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: + + $obj->name( "John Doe" ); + +Attribute names must be valid subroutine identifiers or an exception will +be thrown. + +=head2 Subclassing + +Define subclasses as normal. It's best to define them with L<base>, L<parent> +or L<superclass> before defining attributes with Class::Tiny so the C<@ISA> +array is populated at compile-time: + + package Foo::Bar::More; + + use parent 'Foo::Bar'; + + use Class::Tiny qw( shoe_size ); + +If your class does not already inherit from some class, then Class::Tiny will +be added to your C<@ISA> to provide C<new>. + +If your class B<does> inherit from something, then no additional inheritance is +set up. If the parent subclasses Class::Tiny, then all is well. If not, then +you'll get accessors set up but no constructor (or features that come with it +like attribute validation). Don't do that unless you really have a special +need for it. + +=head2 Object construction + +If your class inherits from Class::Tiny (which it will by default), it provides +the C<new> constructor for you. + +Object 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 dereferenceable as a +hash or an exception is thrown. A shallow copy is made of the reference provided. + +=head2 BUILD + +To be implemented... -=head1 SEE ALSO +=head2 DEMOLISH -Maybe other modules do related things. +To be implemented... =cut -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libclass-tiny-perl.git _______________________________________________ Pkg-perl-cvs-commits mailing list Pkg-perl-cvs-commits@lists.alioth.debian.org http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-perl-cvs-commits