From: Dagfinn Ilmari Mannsåker Date: Fri, 17 Aug 2012 13:06:42 +0000 (+0200) Subject: Document new roles, types and utility functions X-Git-Tag: v0.11013_01~6 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=4e43db0de64bf300a54d87386dc7910e933aa134;p=dbsrgits%2FSQL-Translator.git Document new roles, types and utility functions --- diff --git a/lib/SQL/Translator/Role/BuildArgs.pm b/lib/SQL/Translator/Role/BuildArgs.pm index bf5a375..4212f2b 100644 --- a/lib/SQL/Translator/Role/BuildArgs.pm +++ b/lib/SQL/Translator/Role/BuildArgs.pm @@ -1,4 +1,23 @@ package SQL::Translator::Role::BuildArgs; + +=head1 NAME + +SQL::Translator::Role::BuildArgs - Remove undefined constructor arguments + +=head1 SYNOPSIS + + package Foo; + use Moo; + with qw(SQL::Translator::Role::BuildArgs); + +=head1 DESCRIPTION + +This L wraps BUILDARGS to remove C constructor +arguments for backwards compatibility with the old L-based +L. + +=cut + use Moo::Role; around BUILDARGS => sub { diff --git a/lib/SQL/Translator/Role/Error.pm b/lib/SQL/Translator/Role/Error.pm index df1a58c..00a7524 100644 --- a/lib/SQL/Translator/Role/Error.pm +++ b/lib/SQL/Translator/Role/Error.pm @@ -1,4 +1,37 @@ package SQL::Translator::Role::Error; + +=head1 NAME + +SQL::Translator::Role::Error - Error setter/getter for objects and classes + +=head1 SYNOPSIS + +In the class consuming the role: + + package Foo; + use Moo; + with qw(SQL::Translator::Role::Error); + + sub foo { + ... + return $self->error("Something failed") + unless $some_condition; + ... + } + +In code using the class: + + Foo->foo or die Foo->error; + # or + $foo->foo or die $foo->error; + +=head1 DESCRIPTION + +This L provides a method for getting and setting error on a +class or object. + +=cut + use Moo::Role; use Sub::Quote qw(quote_sub); @@ -9,6 +42,19 @@ has _ERROR => ( default => quote_sub(q{ '' }), ); +=head1 METHODS + +=head2 $object_or_class->error([$message]) + +If called with an argument, sets the error message and returns undef, +otherwise returns the message. + +As an implementation detail, for compatibility with L, the +message is stored in C<< $object->{_ERROR} >> or C<< $Class::ERROR >>, +depending on whether the invocant is an object. + +=cut + around error => sub { my ($orig, $self) = (shift, shift); @@ -25,4 +71,16 @@ around error => sub { return undef; }; +=head1 SEE ALSO + +=over + +=item * + +L + +=back + +=cut + 1; diff --git a/lib/SQL/Translator/Role/ListAttr.pm b/lib/SQL/Translator/Role/ListAttr.pm index 5635f49..3a54101 100644 --- a/lib/SQL/Translator/Role/ListAttr.pm +++ b/lib/SQL/Translator/Role/ListAttr.pm @@ -1,4 +1,24 @@ package SQL::Translator::Role::ListAttr; + +=head1 NAME + +SQL::Translator::Role::ListAttr - context-sensitive list attributes + +=head1 SYNOPSIS + + package Foo; + use Moo; + use SQL::Translator::Role::ListAttr; + + with ListAttr foo => ( uniq => 1, append => 1 ); + +=head1 DESCRIPTION + +This package provides a variable L for context-sensitive list +attributes. + +=cut + use strictures 1; use SQL::Translator::Utils qw(parse_list_arg ex2err); use List::MoreUtils qw(uniq); @@ -11,6 +31,50 @@ use Package::Variant ( subs => [qw(has around)], ); +=head1 FUNCTIONS + +=head2 ListAttr $name => %parameters; + +Returns a L providing an arrayref attribute named C<$name>, +and wrapping the accessor to provide context-sensitivity both for +setting and getting. If no C or C is provided, the +default value is the empty list. + +On setting, the arguments are parsed using +L, and the accessor will return +an array reference or a list, depending on context. + +=head3 Parameters + +=over + +=item append + +If true, the setter will append arguments to the existing ones, rather +than replacing them. + +=item uniq + +If true, duplicate items will be removed, keeping the first one seen. + +=item may_throw + +If accessing the attribute might L +an exception (e.g. from a C or C check), this should be +set to make the accessor store the exception using +L and return undef. + +=item undef_if_empty + +If true, and the list is empty, the accessor will return C +instead of a reference to an empty in scalar context. + +=back + +Unknown parameters are passed through to the has call L for +the attribute. + +=cut sub make_variant { my ($class, $target_package, $name, %arguments) = @_; @@ -49,4 +113,16 @@ sub make_variant { }); } +=head1 SEE ALSO + +=over + +=item L + +=item L + +=back + +=cut + 1; diff --git a/lib/SQL/Translator/Schema/Role/Compare.pm b/lib/SQL/Translator/Schema/Role/Compare.pm index ae67d47..6e5a363 100644 --- a/lib/SQL/Translator/Schema/Role/Compare.pm +++ b/lib/SQL/Translator/Schema/Role/Compare.pm @@ -1,9 +1,27 @@ package SQL::Translator::Schema::Role::Compare; -use Moo::Role; -sub equals { +=head1 NAME + +SQL::Translator::Schema::Role::Compare - compare objects + +=head1 SYNOPSIS + + package Foo; + use Moo; + with qw(SQL::Translator::Schema::Role::Compare); + + $obj->equals($other); + +=head1 DESCRIPTION -=pod +This L provides a method to compare if two objects are the +same. + +=cut + +use Moo::Role; + +=head1 METHODS =head2 equals @@ -13,6 +31,7 @@ Determines if this object is the same as another. =cut +sub equals { my $self = shift; my $other = shift; diff --git a/lib/SQL/Translator/Schema/Role/Extra.pm b/lib/SQL/Translator/Schema/Role/Extra.pm index 6525abd..f87fd86 100644 --- a/lib/SQL/Translator/Schema/Role/Extra.pm +++ b/lib/SQL/Translator/Schema/Role/Extra.pm @@ -1,12 +1,27 @@ package SQL::Translator::Schema::Role::Extra; + +=head1 NAME + +SQL::Translator::Schema::Role::Extra - "extra" attribute for schema classes + +=head1 SYNOPSIS + + package Foo; + use Moo; + with qw(SQL::Translator::Schema::Role::Extra); + +=head1 DESCRIPTION + +This role provides methods to set and get a hashref of extra attributes +for schema objects. + +=cut + use Moo::Role; use Sub::Quote qw(quote_sub); -=head1 Methods - -The following methods are defined here, therefore all schema objects -using this role will have them. +=head1 METHODS =head2 extra diff --git a/lib/SQL/Translator/Types.pm b/lib/SQL/Translator/Types.pm index 02a5b8a..e76db93 100644 --- a/lib/SQL/Translator/Types.pm +++ b/lib/SQL/Translator/Types.pm @@ -1,4 +1,25 @@ package SQL::Translator::Types; + +=head1 NAME + +SQL::Translator::Types - Type checking functions + +=head1 SYNOPSIS + + package Foo; + use Moo; + use SQL::Translator::Types qw(schema_obj); + + has foo => ( is => 'rw', isa => schema_obj('Trigger') ); + +=head1 DESCRIPTIONS + +This module exports fuctions that return coderefs suitable for L +C type checks. +Errors are reported using L. + +=cut + use strictures 1; use SQL::Translator::Utils qw(throw); @@ -7,6 +28,15 @@ use Scalar::Util qw(blessed); use Exporter qw(import); our @EXPORT_OK = qw(schema_obj); +=head1 FUNCTIONS + +=head2 schema_obj($type) + +Returns a coderef that checks that its arguments is an object of the +class C<< SQL::Translator::Schema::I<$type> >>. + +=cut + sub schema_obj { my ($class) = @_; my $name = lc $class; diff --git a/lib/SQL/Translator/Utils.pm b/lib/SQL/Translator/Utils.pm index a258bb3..fa67a7b 100644 --- a/lib/SQL/Translator/Utils.pm +++ b/lib/SQL/Translator/Utils.pm @@ -482,6 +482,27 @@ Takes a version string (X.Y.Z) or perl style (XX.YYYZZZ) and a target ('perl' or 'native') transforms the string to the given target style. to +=head2 throw + +Throws the provided string as an object that will stringify back to the +original string. This stops it from being mangled by L's C +code. + +=head2 ex2err + +Wraps an attribute accessor to catch any exception raised using +L and store them in C<< $self->error() >>, finally returning +undef. A reference to this function can be passed directly to +L. + + around foo => \&ex2err; + + around bar => sub { + my ($orig, $self) = (shift, shift); + return ex2err($orig, $self, @_) if @_; + ... + }; + =head1 AUTHORS Darren Chamberlain Edarren@cpan.orgE,