Index: ossp-pkg/uuid/ChangeLog RCS File: /v/ossp/cvs/ossp-pkg/uuid/Attic/ChangeLog,v rcsdiff -q -kk '-r1.78' '-r1.79' -u '/v/ossp/cvs/ossp-pkg/uuid/Attic/ChangeLog,v' 2>/dev/null --- ChangeLog 2005/08/30 20:34:35 1.78 +++ ChangeLog 2005/08/31 08:55:18 1.79 @@ -11,7 +11,11 @@ This is a list of all changes to OSSP uuid. For a more brief summary please have a look at the NEWS file. - Changes between 1.2.1 and 1.2.2 (30-Aug-2005 to xx-Sep-2005) + Changes between 1.2.1 and 1.3.0 (30-Aug-2005 to xx-Sep-2005) + + o Add a functionality-reduced TIE-style Perl API OSSP::uuid::tie, + intended for very high-level convenience programming. + [Ralf S. Engelschall] o Reference the new officially published RFC 4122. [Ralf S. Engelschall] Index: ossp-pkg/uuid/perl/uuid.pm RCS File: /v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.pm,v rcsdiff -q -kk '-r1.9' '-r1.10' -u '/v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.pm,v' 2>/dev/null --- uuid.pm 2005/08/30 20:11:47 1.9 +++ uuid.pm 2005/08/31 08:55:18 1.10 @@ -27,19 +27,96 @@ ## uuid.pm: Perl Binding (Perl part) ## -package OSSP::uuid; +## +## High-Level Perl Module TIE-style API +## (just a functionality-reduced TIE wrapper around the OO-style API) +## + +package OSSP::uuid::tie; use 5.008; use strict; use warnings; use Carp; -use XSLoader; -use Exporter; + +# inhert from Tie::Scalar +require Tie::Scalar; +our @ISA = qw(Tie::Scalar); + +# helper function +sub mode_sanity { + my ($mode) = @_; + if (not ( defined($mode) + and ref($mode) eq 'ARRAY' + and ( (@{$mode} == 1 and $mode->[0] =~ m|^v[14]$|) + or (@{$mode} == 3 and $mode->[0] =~ m|^v[35]$|)))) { + return (undef, "invalid UUID generation mode specification"); + } + if ($mode->[0] =~ m|^v[35]$|) { + my $uuid_ns = new OSSP::uuid; + $uuid_ns->load($mode->[1]) + or return (undef, "failed to load UUID $mode->[0] namespace"); + $mode->[1] = $uuid_ns; + } + return ($mode, undef); +} + +# constructor +sub TIESCALAR { + my ($class, @args) = @_; + my $self = {}; + bless ($self, $class); + $self->{-uuid} = new OSSP::uuid + or croak "failed to create OSSP::uuid object"; + my ($mode, $error) = mode_sanity(defined($args[0]) ? [ @args ] : [ "v1" ]); + croak $error if defined($error); + $self->{-mode} = $mode; + return $self; +} + +# destructor +sub DESTROY { + my ($self) = @_; + delete $self->{-uuid}; + delete $self->{-mode}; + return; +} + +# fetch value from scalar +# (applied semantic: export UUID in string format) +sub FETCH { + my ($self) = @_; + $self->{-uuid}->make(@{$self->{-mode}}) + or croak "failed to generate new UUID"; + my $value = $self->{-uuid}->export("str") + or croak "failed to export new UUID"; + return $value; +} + +# store value into scalar +# (applied semantic: configure new UUID generation mode) +sub STORE { + my ($self, $value) = @_; + my ($mode, $error) = mode_sanity($value); + croak $error if defined($error); + $self->{-mode} = $mode; + return; +} ## -## API Definition +## High-Level Perl Module OO-style API +## (just an OO wrapper around the C-style API) ## +package OSSP::uuid; + +use 5.008; +use strict; +use warnings; +use Carp; +use XSLoader; +use Exporter; + # API version our $VERSION = do { my @v = ('1.2.1' =~ m/\d+/g); sprintf("%d.".("%02d"x$#v), @v); }; @@ -90,11 +167,6 @@ our @EXPORT_OK = @{$EXPORT_TAGS{'all'}}; our @EXPORT = (); -## -## High-Level Perl Module OO-style API -## (just an OO wrapper around the C-style API) -## - # constructor sub new { my $proto = shift; Index: ossp-pkg/uuid/perl/uuid.pod RCS File: /v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.pod,v rcsdiff -q -kk '-r1.7' '-r1.8' -u '/v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.pod,v' 2>/dev/null --- uuid.pod 2005/08/30 20:00:32 1.7 +++ uuid.pod 2005/08/31 08:55:18 1.8 @@ -44,12 +44,31 @@ and node based), version 3 (name based, MD5), version 4 (random number based) and version 5 (name based, SHA-1). -B provides two Perl APIs: +B provides three Perl APIs: + +=head2 TIE-STYLE API + +The TIE-style API is a functionality-reduced wrapper around the OO-style +API and intended for very high-level convenience programming: + +=over 4 + +=item C + +=item BC< my $uuid, 'OSSP::uuid::tie', $mode, ...;> + +=item C<$uuid = [ $mode, ... ];> + +=item C + +=item C + +=back =head2 OO-STYLE API The OO-style API is a wrapper around the C-style API and intended for -high-level and regular programming. +high-level regular programming. =over 4 @@ -141,6 +160,15 @@ C-style API. Error handling is omitted here for easier reading, but has to be added for production-quality code. + # TIE-style API (very high-level) + use OSSP::uuid; + tie my $uuid, 'OSSP::uuid::tie'; + $uuid = [ "v1" ]; + print "UUIDs: $uuid, $uuid, $uuid\n"; + $uuid = [ "v3", "ns:URL", "http://www.ossp.org/" ]; + print "UUIDs: $uuid, $uuid, $uuid\n"; + untie $uuid; + # OO-style API (high-level) use OSSP::uuid; my $uuid = new OSSP::uuid; Index: ossp-pkg/uuid/perl/uuid.ts RCS File: /v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.ts,v rcsdiff -q -kk '-r1.2' '-r1.3' -u '/v/ossp/cvs/ossp-pkg/uuid/perl/Attic/uuid.ts,v' 2>/dev/null --- uuid.ts 2004/12/31 19:20:39 1.2 +++ uuid.ts 2005/08/31 08:55:18 1.3 @@ -27,14 +27,14 @@ ## uuid.ts: Perl Binding (Perl test suite part) ## -use Test::More tests => 31; +use Test::More tests => 35; ## ## Module Loading ## BEGIN { - use_ok('OSSP::uuid') + use_ok('OSSP::uuid'); }; BEGIN { use OSSP::uuid qw(:all); @@ -142,3 +142,26 @@ undef $uuid; undef $uuid_ns; +## +## TIE API +## + +$uuid = new OSSP::uuid; + +tie my $var, 'OSSP::uuid::tie'; + +my $val_get1 = $var; +my $val_get2 = $var; +ok($val_get1 ne $val_get2, "subsequent generation"); + +$uuid->import("str", $val_get1); +my $val_cmp1 = $uuid->export("str"); +$uuid->import("str", $val_get2); +my $val_cmp2 = $uuid->export("str"); +ok($val_get1 eq $val_cmp1, "validity comparison 1"); +ok($val_get2 eq $val_cmp2, "validity comparison 2"); + +$var = [ "v3", "ns:URL", "http://www.ossp.org/" ]; +$val_get1 = $var; +ok($val_get1 eq "02d9e6d5-9467-382e-8f9b-9300a64ac3cd", "generation of UUID v3"); +