[libclass-tiny-perl] 16/22: updated documentation and meta
gregor herrmann
gregoa at debian.org
Sun May 31 14:03:05 UTC 2015
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 a39e26ab0820ff52400c0bf16e55580c9e89f71b
Author: David Golden <dagolden at cpan.org>
Date: Fri Aug 16 09:20:22 2013 -0400
updated documentation and meta
---
META.json | 3 ++-
README.pod | 81 +++++++++++++++++++++++++++++++++++++++++--------------
lib/Class/Tiny.pm | 53 +++++++++++++++++++++---------------
3 files changed, 95 insertions(+), 42 deletions(-)
diff --git a/META.json b/META.json
index 8477fad..ddb8879 100644
--- a/META.json
+++ b/META.json
@@ -58,7 +58,8 @@
"Test::Fatal" : "0",
"Test::More" : "0.96",
"base" : "0",
- "lib" : "0"
+ "lib" : "0",
+ "subs" : "0"
}
}
},
diff --git a/README.pod b/README.pod
index ffb3b84..baaa1e3 100644
--- a/README.pod
+++ b/README.pod
@@ -37,6 +37,7 @@ In F<example.pl>:
# unknown attributes are fatal:
eval { Employee->new( name => "Larry", OS => "Linux" ) };
+ die "Error creating Employee: $@" if $@;
=head1 DESCRIPTION
@@ -51,7 +52,11 @@ defines attributes via import arguments
=item *
-generates accessors for all attributes
+generates read-write accessors for attributes
+
+=item *
+
+supports custom accessors
=item *
@@ -67,7 +72,15 @@ C<new> throws an error for unknown attributes
=item *
-may be subclassed
+C<new> calls C<BUILD> for each class from parent to child
+
+=item *
+
+superclass provides a C<DESTROY> method
+
+=item *
+
+C<DESTROY> calls C<DEMOLISH> for each class from child to parent
=back
@@ -87,6 +100,10 @@ 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!)
+I looked for something like it on CPAN, but after checking a dozen class
+creators I realized I could implement exactly how I wanted it faster than I
+could search CPAN for something sufficient.
+
=for Pod::Coverage method_names_here
=head1 USAGE
@@ -104,38 +121,50 @@ Define attributes as a list of import arguments:
weight
);
-For each item, a read-write accessor is created:
+For each item, a read-write accessor is created unless a subroutine of that
+name already exists:
$obj->name( "John Doe" );
Attribute names must be valid subroutine identifiers or an exception will
be thrown.
-=head2 Subclassing
+To make your own custom accessors, just pre-declare the method name before
+loading Class::Tiny:
-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;
- package Foo::Bar::More;
+ use subs 'id';
- use parent 'Foo::Bar';
+ use Class::Tiny qw( name id );
- use Class::Tiny qw( shoe_size );
+ sub id { ... }
+
+=head2 Class::Tiny is your base class
If your class does not already inherit from some class, then Class::Tiny will
-be added to your C<@ISA> to provide C<new>.
+be added to your C<@ISA> to provide C<new> and C<DESTROY>. (The superclass
+C<import> method will silently do nothing for subclasses.)
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.
+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 L<base>, L<parent>
+or L<superclass> before defining attributes with Class::Tiny so the C<@ISA>
+array is already populated at compile-time:
+
+ package Foo::Bar::More;
+
+ use parent 'Foo::Bar';
+
+ use Class::Tiny qw( shoe_size );
=head2 Object construction
-If your class inherits from Class::Tiny (which it will by default), it provides
-the C<new> constructor for you.
+If your class inherits from Class::Tiny, 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:
@@ -144,16 +173,28 @@ of key/value pairs:
$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.
+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.
=head2 BUILD
-To be implemented...
+If your class or any superclass defines a C<BUILD> method, they will be called
+by the constructor from furthest parent class down to the child class after the
+object has been created. No arguments are provided and the return value is
+ignored. Use them for validation or setting default values.
+
+ sub BUILD {
+ my $self = shift;
+ $self->foo(42) unless defined $self->foo;
+ }
=head2 DEMOLISH
-To be implemented...
+Class::Tiny provides a C<DESTROY> method. If your class or any superclass
+defines a C<DEMOLISH> method, they will be called by the constructor from the
+child class to the furthest parent class during object destruction. No
+arguments are provided and the return value is ignored.
=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 a3ddb3c..14fc736 100644
--- a/lib/Class/Tiny.pm
+++ b/lib/Class/Tiny.pm
@@ -126,6 +126,7 @@ In F<example.pl>:
# unknown attributes are fatal:
eval { Employee->new( name => "Larry", OS => "Linux" ) };
+ die "Error creating Employee: $@" if $@;
=head1 DESCRIPTION
@@ -139,7 +140,9 @@ code. Here is a list of features:
* 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
+* C<new> calls C<BUILD> for each class from parent to child
+* superclass provides a C<DESTROY> method
+* C<DESTROY> calls C<DEMOLISH> for each class from child to parent
It uses no non-core modules (except on Perls older than 5.10, where it requires
L<MRO::Compat> from CPAN).
@@ -157,6 +160,10 @@ 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!)
+I looked for something like it on CPAN, but after checking a dozen class
+creators I realized I could implement exactly how I wanted it faster than I
+could search CPAN for something sufficient.
+
=head1 USAGE
=head2 Defining attributes
@@ -191,11 +198,20 @@ loading Class::Tiny:
sub id { ... }
-=head2 Subclassing
+=head2 Class::Tiny is your base class
+
+If your class does not already inherit from some class, then Class::Tiny will
+be added to your C<@ISA> to provide C<new> and C<DESTROY>. (The superclass
+C<import> method will silently do nothing for subclasses.)
+
+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 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 L<base>, L<parent>
or L<superclass> before defining attributes with Class::Tiny so the C<@ISA>
-array is populated at compile-time:
+array is already populated at compile-time:
package Foo::Bar::More;
@@ -203,19 +219,10 @@ array is populated at compile-time:
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.
+If your class inherits from Class::Tiny, 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:
@@ -224,15 +231,16 @@ of key/value pairs:
$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.
+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.
=head2 BUILD
-If the class or any superclass defines a C<BUILD> method, they will be called
-by the constructor from furthest parent to child after the object has been
-created. No arguments are provided and the return value is ignored. Use them
-for validation or setting default values.
+If your class or any superclass defines a C<BUILD> method, they will be called
+by the constructor from furthest parent class down to the child class after the
+object has been created. No arguments are provided and the return value is
+ignored. Use them for validation or setting default values.
sub BUILD {
my $self = shift;
@@ -241,7 +249,10 @@ for validation or setting default values.
=head2 DEMOLISH
-To be implemented...
+Class::Tiny provides a C<DESTROY> method. If your class or any superclass
+defines a C<DEMOLISH> method, they will be called by the constructor from the
+child class to the furthest parent class during object destruction. No
+arguments are provided and the return value is ignored.
=cut
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libclass-tiny-perl.git
More information about the Pkg-perl-cvs-commits
mailing list