|
Check-in Number:
|
5131 | |
| Date: |
2005-Aug-31 10:55:18 (local)
2005-Aug-31 08:55:18 (UTC) |
| User: | rse |
| Branch: | |
| Comment: |
Add a functionality-reduced TIE-style Perl API OSSP::uuid::tie,
intended for very high-level convenience programming. |
| Tickets: |
|
| Inspections: |
|
| Files: |
|
ossp-pkg/uuid/ChangeLog 1.78 -> 1.79
--- 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]
|
|
ossp-pkg/uuid/perl/uuid.pm 1.9 -> 1.10
--- 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;
|
|
ossp-pkg/uuid/perl/uuid.pod 1.7 -> 1.8
--- 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<OSSP::uuid> provides two Perl APIs:
+B<OSSP::uuid> 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<use OSSP::uuid;>
+
+=item B<tie>C< my $uuid, 'OSSP::uuid::tie', $mode, ...;>
+
+=item C<$uuid = [ $mode, ... ];>
+
+=item C<print "UUID=$uuid\n";>
+
+=item C<untie $uuid;>
+
+=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;
|
|
ossp-pkg/uuid/perl/uuid.ts 1.2 -> 1.3
--- 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");
+
|
|
