From: Christopher H. Laco Date: Fri, 10 Feb 2006 02:14:00 +0000 (+0000) Subject: Updated UUID* module documentation X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e78f023a580925b0bc667642f9b19865c9f1fb39;p=dbsrgits%2FDBIx-Class-Historic.git Updated UUID* module documentation --- diff --git a/lib/DBIx/Class/UUIDColumns.pm b/lib/DBIx/Class/UUIDColumns.pm index 5df4ed8..8a58527 100644 --- a/lib/DBIx/Class/UUIDColumns.pm +++ b/lib/DBIx/Class/UUIDColumns.pm @@ -5,29 +5,6 @@ __PACKAGE__->mk_classdata( 'uuid_auto_columns' => [] ); __PACKAGE__->mk_classdata( 'uuid_maker' ); __PACKAGE__->uuid_class( __PACKAGE__->_find_uuid_module ); -=head1 NAME - -DBIx::Class::UUIDColumns - Implicit uuid columns - -=head1 SYNOPSIS - - package Artist; - __PACKAGE__->load_components(qw/UUIDColumns Core DB/); - __PACKAGE__->uuid_columns( 'artist_id' ); - -=head1 DESCRIPTION - -This L component resembles the behaviour of -L, to make some columns implicitly created as uuid. - -Note that the component needs to be loaded before Core. - -=head1 METHODS - -=head2 uuid_columns - -=cut - # be compatible with Class::DBI::UUID sub uuid_columns { my $self = shift; @@ -69,13 +46,13 @@ sub get_uuid { } sub _find_uuid_module { - if ($^O ne 'openbsd' && eval{require APR::UUID}) { + if (eval{require Data::UUID}) { + return '::Data::UUID'; + } elsif ($^O ne 'openbsd' && eval{require APR::UUID}) { # APR::UUID on openbsd causes some as yet unfound nastyness for XS return '::APR::UUID'; } elsif (eval{require UUID}) { return '::UUID'; - } elsif (eval{require Data::UUID}) { - return '::Data::UUID'; } elsif (eval{ # squelch the 'too late for INIT' warning in Win32::API::Type local $^W = 0; @@ -89,14 +66,83 @@ sub _find_uuid_module { }; }; +1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDColumns - Implicit uuid columns + +=head1 SYNOPSIS + + package Artist; + __PACKAGE__->load_components(qw/UUIDColumns Core DB/); + __PACKAGE__->uuid_columns( 'artist_id' ); + +=head1 DESCRIPTION + +This L component resembles the behaviour of +L, to make some columns implicitly created as uuid. + +When loaded, C will search for a suitable uuid generation module +from the following list of supported modules: + + Data::UUID + APR::UUID* + UUID + Win32::Guidgen + Win32API::GUID + +If no supporting module can be found, an exception will be thrown. + +*APR::UUID will not be loaded under OpenBSD due to an as yet unidentified XS +issue. + +If you would like to use a specific module, you can set C: + + __PACKAGE__->uuid_class('::Data::UUID'); + __PACKAGE__->uuid_class('MyUUIDGenerator'); + +Note that the component needs to be loaded before Core. + +=head1 METHODS + +=head2 uuid_columns(@columns) + +Takes a list of columns to be filled with uuids during insert. + + __PACKAGE__->uuid_columns('id'); + +=head2 uuid_class($classname) + +Takes the name of a UUIDMaker subclass to be used for uuid value generation. +This can be a fully qualified class name, or a shortcut name starting with :: +that matches one of the available DBIx::Class::UUIDMaker subclasses: + + __PACKAGE__->uuid_class('CustomUUIDGenerator'); + # loads CustomeUUIDGenerator + + __PACKAGE->uuid_class('::Data::UUID'); + # loads DBIx::Class::UUIDMaker::Data::UUID; + +Note that C chacks to see that the specified class isa +DBIx::Class::UUIDMaker subbclass and throws and exception if it isn't. + +=head2 uuid_maker + +Returns the current UUIDMaker instance for the given module. + + my $uuid = __PACKAGE__->uuid_maker->as_string; + +=head1 SEE ALSO + +L + =head1 AUTHORS Chia-liang Kao +Chris Laco =head1 LICENSE You may distribute this code under the same terms as Perl itself. - -=cut - -1; diff --git a/lib/DBIx/Class/UUIDMaker.pm b/lib/DBIx/Class/UUIDMaker.pm index 67061ad..b9c196c 100644 --- a/lib/DBIx/Class/UUIDMaker.pm +++ b/lib/DBIx/Class/UUIDMaker.pm @@ -9,3 +9,48 @@ sub as_string { }; 1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDMaker - UUID wrapper module + +=head1 SYNOPSIS + + package CustomUUIDMaker; + use base qw/DBIx::Class::/; + + sub as_string { + my $uuid; + ...magic encantations... + return $uuid; + }; + +=head1 DESCRIPTION + +DBIx::Class::UUIDMaker is a base class used by the various uuid generation +subclasses. + +=head1 METHODS + +=head2 as_string + +Returns the new uuid as a string. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 AUTHOR + +Chris Laco + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. diff --git a/lib/DBIx/Class/UUIDMaker/APR/UUID.pm b/lib/DBIx/Class/UUIDMaker/APR/UUID.pm index 65305f0..136ec5f 100644 --- a/lib/DBIx/Class/UUIDMaker/APR/UUID.pm +++ b/lib/DBIx/Class/UUIDMaker/APR/UUID.pm @@ -7,3 +7,40 @@ sub as_string { }; 1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDMaker::APR::UUID - Create uuids using APR::UUID + +=head1 SYNOPSIS + + package Artist; + __PACKAGE__->load_components(qw/UUIDColumns Core DB/); + __PACKAGE__->uuid_columns( 'artist_id' ); + __PACKAGE__->uuid_class('::APR::UUID'); + +=head1 DESCRIPTION + +This DBIx::Class::UUIDMaker subclass uses APR::UUID to generate uuid +strings in the following format: + + 098f2470-bae0-11cd-b579-08002b30bfeb + +=head1 METHODS + +=head2 as_string + +Returns the new uuid as a string. + +=head1 SEE ALSO + +L + +=head1 AUTHOR + +Chris Laco + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. diff --git a/lib/DBIx/Class/UUIDMaker/Data/UUID.pm b/lib/DBIx/Class/UUIDMaker/Data/UUID.pm index ffa1afb..820669c 100644 --- a/lib/DBIx/Class/UUIDMaker/Data/UUID.pm +++ b/lib/DBIx/Class/UUIDMaker/Data/UUID.pm @@ -7,3 +7,40 @@ sub as_string { }; 1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDMaker::Data::UUID - Create uuids using Data::UUID + +=head1 SYNOPSIS + + package Artist; + __PACKAGE__->load_components(qw/UUIDColumns Core DB/); + __PACKAGE__->uuid_columns( 'artist_id' ); + __PACKAGE__->uuid_class('::Data::UUID'); + +=head1 DESCRIPTION + +This DBIx::Class::UUIDMaker subclass uses Data::UUID to generate uuid +strings in the following format: + + 098f2470-bae0-11cd-b579-08002b30bfeb + +=head1 METHODS + +=head2 as_string + +Returns the new uuid as a string. + +=head1 SEE ALSO + +L + +=head1 AUTHOR + +Chris Laco + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. diff --git a/lib/DBIx/Class/UUIDMaker/Data/Uniqid.pm b/lib/DBIx/Class/UUIDMaker/Data/Uniqid.pm index 61bf347..8d9a29d 100644 --- a/lib/DBIx/Class/UUIDMaker/Data/Uniqid.pm +++ b/lib/DBIx/Class/UUIDMaker/Data/Uniqid.pm @@ -7,3 +7,38 @@ sub as_string { }; 1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDMaker::Data::Uniqid - Create uuids using Data::Uniqid + +=head1 SYNOPSIS + + package Artist; + __PACKAGE__->load_components(qw/UUIDColumns Core DB/); + __PACKAGE__->uuid_columns( 'artist_id' ); + __PACKAGE__->uuid_class('::Data::Uniqid'); + +=head1 DESCRIPTION + +This DBIx::Class::UUIDMaker subclass uses Data::Uniqid to generate uuid +strings using Data::Uniqid::luniqid. + +=head1 METHODS + +=head2 as_string + +Returns the new uuid as a string. + +=head1 SEE ALSO + +L + +=head1 AUTHOR + +Chris Laco + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. diff --git a/lib/DBIx/Class/UUIDMaker/UUID.pm b/lib/DBIx/Class/UUIDMaker/UUID.pm index 28a34b9..7a647a9 100644 --- a/lib/DBIx/Class/UUIDMaker/UUID.pm +++ b/lib/DBIx/Class/UUIDMaker/UUID.pm @@ -11,3 +11,40 @@ sub as_string { }; 1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDMaker::UUID - Create uuids using UUID + +=head1 SYNOPSIS + + package Artist; + __PACKAGE__->load_components(qw/UUIDColumns Core DB/); + __PACKAGE__->uuid_columns( 'artist_id' ); + __PACKAGE__->uuid_class('::UUID'); + +=head1 DESCRIPTION + +This DBIx::Class::UUIDMaker subclass uses UUID to generate uuid +strings in the following format: + + 098f2470-bae0-11cd-b579-08002b30bfeb + +=head1 METHODS + +=head2 as_string + +Returns the new uuid as a string. + +=head1 SEE ALSO + +L + +=head1 AUTHOR + +Chris Laco + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. diff --git a/lib/DBIx/Class/UUIDMaker/Win32/Guidgen.pm b/lib/DBIx/Class/UUIDMaker/Win32/Guidgen.pm index 9afa652..3c34b9a 100644 --- a/lib/DBIx/Class/UUIDMaker/Win32/Guidgen.pm +++ b/lib/DBIx/Class/UUIDMaker/Win32/Guidgen.pm @@ -4,9 +4,46 @@ use Win32::Guidgen (); sub as_string { my $uuid = Win32::Guidgen::create(); - $uuid =~ s/(^\{|\}$)//; + $uuid =~ s/(^\{|\}$)//g; return $uuid; }; 1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDMaker::Win32:::Guidgen - Create uuids using Win32::Guidgen + +=head1 SYNOPSIS + + package Artist; + __PACKAGE__->load_components(qw/UUIDColumns Core DB/); + __PACKAGE__->uuid_columns( 'artist_id' ); + __PACKAGE__->uuid_class('::Win32::Guidgen'); + +=head1 DESCRIPTION + +This DBIx::Class::UUIDMaker subclass uses Win32::Guidgen to generate uuid +strings in the following format: + + 098f2470-bae0-11cd-b579-08002b30bfeb + +=head1 METHODS + +=head2 as_string + +Returns the new uuid as a string. + +=head1 SEE ALSO + +L + +=head1 AUTHOR + +Chris Laco + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. diff --git a/lib/DBIx/Class/UUIDMaker/Win32API/GUID.pm b/lib/DBIx/Class/UUIDMaker/Win32API/GUID.pm index 463bbba..85caad1 100644 --- a/lib/DBIx/Class/UUIDMaker/Win32API/GUID.pm +++ b/lib/DBIx/Class/UUIDMaker/Win32API/GUID.pm @@ -7,3 +7,40 @@ sub as_string { }; 1; +__END__ + +=head1 NAME + +DBIx::Class::UUIDMaker::Win32API:::GUID - Create uuids using Win32API::GUID + +=head1 SYNOPSIS + + package Artist; + __PACKAGE__->load_components(qw/UUIDColumns Core DB/); + __PACKAGE__->uuid_columns( 'artist_id' ); + __PACKAGE__->uuid_class('::Win32API::GUID'); + +=head1 DESCRIPTION + +This DBIx::Class::UUIDMaker subclass uses Win32API::GUID to generate uuid +strings in the following format: + + 098f2470-bae0-11cd-b579-08002b30bfeb + +=head1 METHODS + +=head2 as_string + +Returns the new uuid as a string. + +=head1 SEE ALSO + +L + +=head1 AUTHOR + +Chris Laco + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself.