[libclass-tiny-perl] 09/22: write initial documentation

[gregor herrmann]

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 <dagolden at 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