[libclass-tiny-perl] 17/22: improve documentation and fix up perl critic complaints
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 f9dc9516023f3584fbe4d734d53368f3e8980c28
Author: David Golden <dagolden at cpan.org>
Date: Fri Aug 16 09:38:05 2013 -0400
improve documentation and fix up perl critic complaints
---
README.pod | 35 ++++++++++++++++++++---------------
dist.ini | 1 +
lib/Class/Tiny.pm | 39 ++++++++++++++++++++++-----------------
3 files changed, 43 insertions(+), 32 deletions(-)
diff --git a/README.pod b/README.pod
index baaa1e3..1944104 100644
--- a/README.pod
+++ b/README.pod
@@ -52,7 +52,7 @@ defines attributes via import arguments
=item *
-generates read-write accessors for attributes
+generates read-write accessors
=item *
@@ -89,22 +89,22 @@ L<MRO::Compat> from CPAN).
=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.
+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
+L<Class::Struct> or roll-their-own OO framework each time.
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.
+more strict philosophy against feature creep than I have.
-Compared to everything else, this is smaller in implmentation and simpler in
+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 exactly how I wanted it faster than I
-could search CPAN for something sufficient.
+creators I realized I could implement it exactly how I wanted faster than I
+could search CPAN for something merely sufficient.
-=for Pod::Coverage method_names_here
+=for Pod::Coverage new
=head1 USAGE
@@ -124,7 +124,8 @@ Define attributes as a list of import arguments:
For each item, a read-write accessor is created unless a subroutine of that
name already exists:
- $obj->name( "John Doe" );
+ $obj->name; # getter
+ $obj->name( "John Doe" ); # setter
Attribute names must be valid subroutine identifiers or an exception will
be thrown.
@@ -140,6 +141,9 @@ loading Class::Tiny:
sub id { ... }
+By declaring C<id> also with Class::Tiny, you include it in the list
+of allowed constructor parameters.
+
=head2 Class::Tiny is your base class
If your class does not already inherit from some class, then Class::Tiny will
@@ -163,10 +167,10 @@ array is already populated at compile-time:
=head2 Object construction
-If your class inherits from Class::Tiny, it provides the C<new> constructor for
-you.
+If your class inherits from Class::Tiny (as it should if you followed the
+advice above), it provides the C<new> constructor for you.
-Object can be created with attributes given as a hash reference or as a list
+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" );
@@ -187,14 +191,15 @@ ignored. Use them for validation or setting default values.
sub BUILD {
my $self = shift;
$self->foo(42) unless defined $self->foo;
+ croak "Foo must be non-negative" if $self->foo < 0;
}
=head2 DEMOLISH
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
+defines a C<DEMOLISH> method, they will be called from the
child class to the furthest parent class during object destruction. No
-arguments are provided and the return value is ignored.
+arguments are provided. Return values and errors are ignored.
=for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan
diff --git a/dist.ini b/dist.ini
index a7ab5a5..37a0ea6 100644
--- a/dist.ini
+++ b/dist.ini
@@ -8,6 +8,7 @@ copyright_year = 2013
:version = 0.045
AutoMetaResources.bugtracker.rt = 0
AutoMetaResources.bugtracker.github = user:dagolden
+stopwords = destructor
[RemovePrereqs]
remove = MRO::Compat
diff --git a/lib/Class/Tiny.pm b/lib/Class/Tiny.pm
index 14fc736..053044a 100644
--- a/lib/Class/Tiny.pm
+++ b/lib/Class/Tiny.pm
@@ -9,7 +9,7 @@ package Class::Tiny;
use Carp ();
if ( $] >= 5.010 ) {
- require "mro.pm"; # hack to hide from perl minimum version & prereq scanners
+ require "mro.pm"; ## no critic: hack to hide from perl minimum version & prereq scanners
}
else {
require MRO::Compat;
@@ -26,7 +26,7 @@ sub import {
my @attr = @_;
$CLASS_ATTRIBUTES{$pkg} = { map { $_ => 1 } @attr };
my $child = !!@{"${pkg}::ISA"};
- eval join "\n",
+ eval join "\n", ## no critic: intentionally eval'ing subs here
"package $pkg;", ( $child ? () : "\@${pkg}::ISA = 'Class::Tiny';" ), map {
defined and !ref and /^[^\W\d]\w*$/s
or Carp::croak "Invalid accessor name '$_'";
@@ -97,7 +97,7 @@ sub DESTROY {
1;
-=for Pod::Coverage method_names_here
+=for Pod::Coverage new
=head1 SYNOPSIS
@@ -135,7 +135,7 @@ code. Here is a list of features:
=for :list
* defines attributes via import arguments
-* generates read-write accessors for attributes
+* generates read-write accessors
* supports custom accessors
* superclass provides a standard C<new> constructor
* C<new> takes a hash reference or list of key/value pairs
@@ -149,20 +149,20 @@ L<MRO::Compat> from CPAN).
=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.
+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
+L<Class::Struct> or roll-their-own OO framework each time.
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.
+more strict philosophy against feature creep than I have.
-Compared to everything else, this is smaller in implmentation and simpler in
+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 exactly how I wanted it faster than I
-could search CPAN for something sufficient.
+creators I realized I could implement it exactly how I wanted faster than I
+could search CPAN for something merely sufficient.
=head1 USAGE
@@ -182,7 +182,8 @@ Define attributes as a list of import arguments:
For each item, a read-write accessor is created unless a subroutine of that
name already exists:
- $obj->name( "John Doe" );
+ $obj->name; # getter
+ $obj->name( "John Doe" ); # setter
Attribute names must be valid subroutine identifiers or an exception will
be thrown.
@@ -198,6 +199,9 @@ loading Class::Tiny:
sub id { ... }
+By declaring C<id> also with Class::Tiny, you include it in the list
+of allowed constructor parameters.
+
=head2 Class::Tiny is your base class
If your class does not already inherit from some class, then Class::Tiny will
@@ -221,10 +225,10 @@ array is already populated at compile-time:
=head2 Object construction
-If your class inherits from Class::Tiny, it provides the C<new> constructor for
-you.
+If your class inherits from Class::Tiny (as it should if you followed the
+advice above), it provides the C<new> constructor for you.
-Object can be created with attributes given as a hash reference or as a list
+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" );
@@ -245,14 +249,15 @@ ignored. Use them for validation or setting default values.
sub BUILD {
my $self = shift;
$self->foo(42) unless defined $self->foo;
+ croak "Foo must be non-negative" if $self->foo < 0;
}
=head2 DEMOLISH
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
+defines a C<DEMOLISH> method, they will be called from the
child class to the furthest parent class during object destruction. No
-arguments are provided and the return value is ignored.
+arguments are provided. Return values and errors are 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