head	1.13;
access;
symbols
	UUID_1_6_2:1.12
	UUID_1_6_1:1.12
	UUID_1_6_0:1.12
	UUID_1_5_1:1.11
	UUID_1_5_0:1.11
	UUID_1_4_2:1.10
	UUID_1_4_1:1.10
	UUID_1_4_0:1.10
	UUID_1_3_2:1.9
	UUID_1_3_1:1.9
	UUID_1_3_0:1.9
	UUID_1_2_1:1.7
	UUID_1_2_0:1.6
	UUID_1_1_2:1.5
	UUID_1_1_1:1.4
	UUID_1_1_0:1.3;
locks; strict;
comment	@# @;


1.13
date	2008.07.05.12.58.22;	author rse;	state dead;
branches;
next	1.12;
commitid	XLXN7vUmABwPcC9t;

1.12
date	2007.01.01.18.14.57;	author rse;	state Exp;
branches;
next	1.11;
commitid	jOXiIO8S8v7xFP0s;

1.11
date	2006.05.11.09.37.30;	author rse;	state Exp;
branches;
next	1.10;
commitid	u4EPMISJDipjmAwr;

1.10
date	2006.01.13.06.44.33;	author rse;	state Exp;
branches;
next	1.9;
commitid	hYfQc9JIMh4bcphr;

1.9
date	2005.09.02.14.00.05;	author rse;	state Exp;
branches;
next	1.8;

1.8
date	2005.08.31.08.55.18;	author rse;	state Exp;
branches;
next	1.7;

1.7
date	2005.08.30.20.00.32;	author rse;	state Exp;
branches;
next	1.6;

1.6
date	2005.01.23.12.38.10;	author rse;	state Exp;
branches;
next	1.5;

1.5
date	2004.12.31.19.20.39;	author rse;	state Exp;
branches;
next	1.4;

1.4
date	2004.11.03.19.00.50;	author rse;	state Exp;
branches;
next	1.3;

1.3
date	2004.11.03.18.44.40;	author rse;	state Exp;
branches;
next	1.2;

1.2
date	2004.11.03.18.28.54;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	2004.11.03.14.52.09;	author rse;	state Exp;
branches;
next	;


desc
@@


1.13
log
@remove OSSP uuid from CVS -- it is now versioned controlled in a Monotone repository
@
text
@##
##  OSSP uuid - Universally Unique Identifier
##  Copyright (c) 2004-2007 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2004-2007 The OSSP Project <http://www.ossp.org/>
##
##  This file is part of OSSP uuid, a library for the generation
##  of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  uuid.pod: Perl Binding (Perl/POD part)
##

=pod

=head1 NAME

OSSP::uuid - B<OSSP uuid> Perl Binding

=head1 DESCRIPTION

B<OSSP uuid> is a ISO-C:1999 application programming interface (API)
and corresponding command line interface (CLI) for the generation of
DCE 1.1, ISO/IEC 11578:1996 and RFC 4122 compliant I<Universally Unique
Identifier> (UUID). It supports DCE 1.1 variant UUIDs of version 1 (time
and node based), version 3 (name based, MD5), version 4 (random number
based) and version 5 (name based, SHA-1). Additional API bindings are
provided for the languages ISO-C++:1998, Perl:5 and PHP:4/5. Optional
backward compatibility exists for the ISO-C DCE-1.1 and Perl Data::UUID
APIs.

B<OSSP::uuid> is the Perl binding to the B<OSSP uuid> API.
Three variants are provided:

=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 regular programming.

=over 4

=item C<use OSSP::uuid;>

=item C<my $uuid = >B<new>C< OSSP::uuid;>

=item C<$uuid-E<gt>>B<load>C<($name);>

=item C<$uuid-E<gt>>B<make>C<($mode, ...);>

=item C<$result = $uuid-E<gt>>B<isnil>C<();>

=item C<$result = $uuid-E<gt>>B<compare>C<($uuid2);>

=item C<$uuid-E<gt>>B<import>C<($fmt, $data_ptr);>

=item C<$data_ptr = $uuid-E<gt>>B<export>C<($fmt);>

=item C<[(]$str[, $rc)] = $uuid-E<gt>>B<error>C<();>

=item C<$ver = $uuid-E<gt>>B<version>C<();>

=item C<undef $uuid;>

=back

Additionally, the strings C<"v1">, C<"v3">, C<"v4">, C<"v5"> and C<"mc">
can be used in C<$mode> and the strings C<"bin">, C<"str">, and C<"txt">
can be used for C<$fmt>.

=head2 C-STYLE API

The C-style API is a direct mapping
of the B<OSSP uuid> ISO-C API to Perl and is intended for low-level
programming. See uuid(3) for a description of the functions and
their expected arguments.

=over 4

=item C<use OSSP::uuid qw(:all);>

=item C<my $uuid; $rc = >B<uuid_create>C<($uuid);>

=item C<$rc = >B<uuid_load>C<($uuid, $name);>

=item C<$rc = >B<uuid_make>C<($uuid, $mode, ...);>

=item C<$rc = >B<uuid_isnil>C<($uuid, $result);>

=item C<$rc = >B<uuid_compare>C<($uuid, $uuid2, $result);>

=item C<$rc = >B<uuid_import>C<($uuid, $fmt, $data_ptr, $data_len);>

=item C<$rc = >B<uuid_export>C<($uuid, $fmt, $data_ptr, $data_len);>

=item C<$str = >B<uuid_error>C<($rc);>

=item C<$ver = >B<uuid_version>C<();>

=item C<$rc = >B<uuid_destroy>C<($uuid);>

=back

Additionally, the following constants are exported for use in C<$rc>, C<$mode>, C<$fmt> and C<$ver>:

C<UUID_VERSION>,
C<UUID_LEN_BIN>,
C<UUID_LEN_STR>,
C<UUID_RC_OK>,
C<UUID_RC_ARG>,
C<UUID_RC_MEM>,
C<UUID_RC_SYS>,
C<UUID_RC_INT>,
C<UUID_RC_IMP>,
C<UUID_MAKE_V1>,
C<UUID_MAKE_V3>,
C<UUID_MAKE_V4>,
C<UUID_MAKE_V5>,
C<UUID_MAKE_MC>,
C<UUID_FMT_BIN>,
C<UUID_FMT_STR>,
C<UUID_FMT_SIV>,
C<UUID_FMT_TXT>.

=head1 EXAMPLES

The following two examples create the version 3 UUID
C<02d9e6d5-9467-382e-8f9b-9300a64ac3cd>, both via the OO-style and the
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;
  my $uuid_ns = new OSSP::uuid;
  $uuid_ns->load("ns:URL");
  $uuid->make("v3", $uuid_ns, "http://www.ossp.org/");
  undef $uuid_ns;
  my $str = $uuid->export("str");
  undef $uuid;
  print "$str\n";

  #   C-style API (low-level)
  use OSSP::uuid qw(:all);
  my $uuid;    uuid_create($uuid);
  my $uuid_ns; uuid_create($uuid_ns);
  uuid_load($uuid_ns, "ns:URL");
  uuid_make($uuid, UUID_MAKE_V3, $uuid_ns, "http://www.ossp.org/");
  uuid_destroy($uuid_ns);
  my $str; uuid_export($uuid, UUID_FMT_STR, $str, undef);
  uuid_destroy($uuid);
  print "$str\n";

=head1 SEE ALSO

uuid(1), uuid-config(1), uuid(3).

=head1 HISTORY

The Perl binding B<OSSP::uuid> to B<OSSP uuid> was implemented in
November 2004 by Ralf S. Engelschall E<lt>rse@@engelschall.comE<gt>.

=cut

@


1.12
log
@Adjust copyright messages for new year 2007.
@
text
@@


1.11
log
@Add full support for Single Integer Value (SIV) UUID representation
for both importing and exporting in C/C++/Perl/PHP APIs.
@
text
@d3 2
a4 2
##  Copyright (c) 2004-2006 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2004-2006 The OSSP Project <http://www.ossp.org/>
@


1.10
log
@Adjust copyright messages for new year 2006.
@
text
@d156 1
@


1.9
log
@new official description now also mentioning PHP
@
text
@d3 2
a4 2
##  Copyright (c) 2004-2005 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2004-2005 The OSSP Project <http://www.ossp.org/>
@


1.8
log
@Add a functionality-reduced TIE-style Perl API OSSP::uuid::tie,
intended for very high-level convenience programming.
@
text
@d38 3
a40 5
B<OSSP::uuid> is the Perl binding to the B<OSSP uuid> API.

B<OSSP uuid> is an ISO-C and Perl application programming interface
(API) and corresponding command line interface (CLI) for the generation
of DCE 1.1 and ISO/IEC 11578:1996 compliant I<Universally Unique
d43 4
a46 1
based) and version 5 (name based, SHA-1).
d48 2
a49 1
B<OSSP::uuid> provides three Perl APIs:
@


1.7
log
@fix typo
@
text
@d47 20
a66 1
B<OSSP::uuid> provides two Perl APIs:
d71 1
a71 1
high-level and regular programming.
d163 9
@


1.6
log
@add support for version 5 UUIDs also to Perl API
@
text
@d27 1
a27 1
##  uuid.pm: Perl Binding (Perl/POD part)
@


1.5
log
@Adjust copyright messages for new year 2005.
@
text
@d44 2
a45 2
and node based), version 3 (name based) and version 4 (random number
based).
d80 3
a82 3
Additionally, the strings C<"v1">, C<"v2">, C<"v3"> and C<"mc"> can be
used in C<$mode> and the strings C<"bin">, C<"str">, and C<"txt"> can be
used for C<$fmt>.
d131 1
@


1.4
log
@strip trailing whitespaces
@
text
@d3 2
a4 2
##  Copyright (c) 2004 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2004 The OSSP Project <http://www.ossp.org/>
@


1.3
log
@polish comments
@
text
@d27 1
a27 1
##  uuid.pm: Perl Binding (Perl/POD part) 
d92 1
a92 1
 
@


1.2
log
@link manpaged together
@
text
@d40 6
a45 5
B<OSSP uuid> is an ISO-C application programming interface (API) and
corresponding command line interface (CLI) for the generation of DCE
1.1 and ISO/IEC 11578:1996 compliant I<Universally Unique Identifier>
(UUID). It supports DCE 1.1 variant UUIDs of version 1 (time and node
based), version 3 (name based) and version 4 (random number based).
d169 1
a169 1
=head1 AUTHOR
d171 2
a172 1
Ralf S. Engelschall, E<lt>rse@@engelschall.comE<gt>
@


1.1
log
@Add Perl language binding providing both a C-style and OO-style API.
@
text
@d166 1
a166 2
uuid(3),
http://www.ossp.org/pkg/lib/uuid/
@