[perl-Cairo] Make "use Cairo x.yyy" work

[Torsten SchÃnfeld <tsch src gnome org>]

commit f4ea540acbfb5bea6e6adf39238dcf5418eb5c9b
Author: Torsten SchÃnfeld <kaffeetisch gmx de>
Date:   Fri Jan 6 19:15:57 2012 +0100

    Make "use Cairo x.yyy" work
    
    This required renaming the old Cairo::VERSION, a wrapper for
    CAIRO_VERSION, to Cairo::LIB_VERSION -- but we kept the old way of
    calling it working.  Cairo::version, Cairo::version_string and
    Cairo::VERSION_ENCODE got the same treatment for consistency.
    
    https://rt.cpan.org/Ticket/Display.html?id=72783

 Cairo.xs       |   13 ++++++++++---
 NEWS           |   10 +++++++++-
 lib/Cairo.pm   |   30 +++++++++++++++++++++++-------
 t/00-loading.t |   35 +++++++++++++++++++++++++++++++++++
 t/Cairo.t      |   12 ++----------
 5 files changed, 79 insertions(+), 21 deletions(-)
---
diff --git a/Cairo.xs b/Cairo.xs
index 7e35f4a..536e1b5 100644
--- a/Cairo.xs
+++ b/Cairo.xs
@@ -425,13 +425,16 @@ BOOT:
 	call_atexit ((ATEXIT_t) cairo_debug_reset_static_data, NULL);
 #endif
 
-int VERSION (class=NULL)
+# The VERSION fallback is implemented in lib/Cairo.pm.
+int LIB_VERSION (...)
     CODE:
 	RETVAL = CAIRO_VERSION;
     OUTPUT:
 	RETVAL
 
-int VERSION_ENCODE (...)
+int LIB_VERSION_ENCODE (...)
+    ALIAS:
+	VERSION_ENCODE = 1
     PREINIT:
 	int major, minor, micro;
     CODE:
@@ -444,7 +447,7 @@ int VERSION_ENCODE (...)
 		minor = SvIV (ST (2));
 		micro = SvIV (ST (3));
 	} else {
-		croak ("Usage: Cairo::VERSION_ENCODE (major, minor, micro) or Cairo->VERSION_ENCODE (major, minor, micro)");
+		croak ("Usage: Cairo::LIB_VERSION_ENCODE (major, minor, micro) or Cairo->LIB_VERSION_ENCODE (major, minor, micro)");
 	}
 
 	RETVAL = CAIRO_VERSION_ENCODE (major, minor, micro);
@@ -453,11 +456,15 @@ int VERSION_ENCODE (...)
 
 # int cairo_version ();
 int cairo_version (class=NULL)
+    ALIAS:
+	lib_version = 1
     C_ARGS:
 	/* void */
 
 # const char* cairo_version_string ();
 const char* cairo_version_string (class=NULL)
+    ALIAS:
+	lib_version_string = 1
     C_ARGS:
 	/* void */
 
diff --git a/NEWS b/NEWS
index b9c2702..4bb7370 100644
--- a/NEWS
+++ b/NEWS
@@ -1,8 +1,16 @@
+Overview of changes in Cairo <NEXT UNSTABLE>
+==================================
+
+* Make "use Cairo x.yyy" work.  This required renaming the old Cairo::VERSION,
+  a wrapper for CAIRO_VERSION, to Cairo::LIB_VERSION -- but we kept the old way
+  of calling it working.  Cairo::version, Cairo::version_string and
+  Cairo::VERSION_ENCODE got the same treatment for consistency.
+
 Overview of changes in Cairo 1.082
 ==================================
 
 * Update the symbol export list for linking on win32
-  (https://bugzilla.gnome.org/show_bug.cgi?id=665265) 
+  (https://bugzilla.gnome.org/show_bug.cgi?id=665265)
 
 Overview of changes in Cairo 1.081
 ==================================
diff --git a/lib/Cairo.pm b/lib/Cairo.pm
index 2c36f53..b91aecf 100644
--- a/lib/Cairo.pm
+++ b/lib/Cairo.pm
@@ -20,9 +20,17 @@ sub dl_load_flags { $^O eq 'darwin' ? 0x00 : 0x01 }
 
 Cairo->bootstrap ($VERSION);
 
-# --------------------------------------------------------------------------- #
-
-package Cairo;
+# Our Cairo::VERSION used to be a simple wrapper around CAIRO_VERSION.  But a
+# package's VERSION sub is supposed to do Perl version checking so that things
+# like 'use Cairo 1.00' work.  To not break backwards-compatibility, we
+# dispatch according to the number of arguments passed in.
+sub VERSION {
+  if (scalar @_ == 2) {
+    shift->SUPER::VERSION (@_);
+  } else {
+    Cairo::LIB_VERSION (@_);
+  }
+}
 
 1;
 
@@ -1725,13 +1733,18 @@ For hysterical reasons, you can also use the following syntax:
 
 =over
 
-=item $version = Cairo->version
+=item $version_code = Cairo->lib_version
 
-=item $string = Cairo->version_string
+=item $version_string = Cairo->lib_version_string
 
-=item $version_code = Cairo->VERSION
+These two functions return the version of libcairo that the program is
+currently running against.
 
-=item $version_code = Cairo->VERSION_ENCODE ($major, $minor, $micro)
+=item $version_code = Cairo->LIB_VERSION
+
+Returns the version of libcairo that L<Cairo> was compiled against.
+
+=item $version_code = Cairo->LIB_VERSION_ENCODE ($major, $minor, $micro)
 
 =over
 
@@ -1743,6 +1756,9 @@ For hysterical reasons, you can also use the following syntax:
 
 =back
 
+Encodes the version C<$major.$minor.$micro> as an integer suitable for
+comparison against C<< Cairo->lib_version >> and C<< Cairo->LIB_VERSION >>.
+
 =back
 
 =cut
diff --git a/t/00-loading.t b/t/00-loading.t
new file mode 100644
index 0000000..a8e08b8
--- /dev/null
+++ b/t/00-loading.t
@@ -0,0 +1,35 @@
+#!/usr/bin/perl
+#
+# Copyright (c) 2004-2005 by the cairo perl team (see the file README)
+#
+# Licensed under the LGPL, see LICENSE file for more information.
+#
+
+use strict;
+use warnings;
+
+use Test::More tests => 18;
+
+BEGIN {
+  ok (! eval "use Cairo 2.000; 1");
+  ok (eval "use Cairo 1.000; 1");
+}
+
+ok(defined Cairo::LIB_VERSION);
+ok(defined Cairo::LIB_VERSION_ENCODE (1, 0, 0));
+ok(defined Cairo->LIB_VERSION);
+ok(defined Cairo->LIB_VERSION_ENCODE (1, 0, 0));
+ok(defined Cairo::lib_version);
+ok(defined Cairo::lib_version_string);
+ok(defined Cairo->lib_version);
+ok(defined Cairo->lib_version_string);
+
+# Deprecated names:
+ok(defined Cairo::VERSION);
+ok(defined Cairo::VERSION_ENCODE (1, 0, 0));
+ok(defined Cairo->VERSION);
+ok(defined Cairo->VERSION_ENCODE (1, 0, 0));
+ok(defined Cairo::version);
+ok(defined Cairo::version_string);
+ok(defined Cairo->version);
+ok(defined Cairo->version_string);
diff --git a/t/Cairo.t b/t/Cairo.t
index 440611e..5293d67 100644
--- a/t/Cairo.t
+++ b/t/Cairo.t
@@ -10,7 +10,7 @@
 use strict;
 use warnings;
 
-use Test::More tests => 75;
+use Test::More tests => 70;
 
 unless (eval 'use Test::Number::Delta; 1;') {
 	my $reason = 'Test::Number::Delta not available';
@@ -20,15 +20,7 @@ unless (eval 'use Test::Number::Delta; 1;') {
 use constant IMG_WIDTH => 256;
 use constant IMG_HEIGHT => 256;
 
-BEGIN {
-	use_ok ('Cairo');
-}
-
-ok(defined Cairo::version);
-ok(defined Cairo::version_string);
-
-ok(defined Cairo->version);
-ok(defined Cairo->version_string);
+use Cairo;
 
 my $surf = Cairo::ImageSurface->create ('rgb24', IMG_WIDTH, IMG_HEIGHT);
 isa_ok ($surf, 'Cairo::Surface');