From: Richard Jones <rjones@redhat.com>
Date: Thu, 2 Sep 2010 09:58:28 +0000 (+0100)
Subject: perl: Add documentation about testing availability of methods and features.
X-Git-Tag: 1.4.5~6
X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=1fa68d080a66a70ec4879e2e6b5e5b8acb36b542;p=libguestfs.git

perl: Add documentation about testing availability of methods and features.
(cherry picked from commit 0f24424f357e854a9da382de11e4fe81305c8743)
---

diff --git a/src/generator.ml b/src/generator.ml
index b31b3c9..b61e43c 100755
--- a/src/generator.ml
+++ b/src/generator.ml
@@ -9251,6 +9251,37 @@ when the final reference is cleaned up is OK).
 
 =back
 
+=head1 AVAILABILITY
+
+From time to time we add new libguestfs APIs.  Also some libguestfs
+APIs won't be available in all builds of libguestfs (the Fedora
+build is full-featured, but other builds may disable features).
+How do you test whether the APIs that your Perl program needs are
+available in the version of C<Sys::Guestfs> that you are using?
+
+To test if a particular function is available in the C<Sys::Guestfs>
+class, use the ordinary Perl UNIVERSAL method C<can(METHOD)>
+(see L<perlobj(1)>).  For example:
+
+ use Sys::Guestfs;
+ if (defined (Sys::Guestfs->can (\"set_verbose\"))) {
+   print \"\\$h->set_verbose is available\\n\";
+ }
+
+To test if particular features are supported by the current
+build, use the L</available> method like the example below.  Note
+that the appliance must be launched first.
+
+ $h->available ( [\"augeas\"] );
+
+Since the L</available> method croaks if the feature is not supported,
+you might also want to wrap this in an eval and return a boolean.
+In fact this has already been done for you: use
+L<Sys::Guestfs::Lib(3)/feature_available>.
+
+For further discussion on this topic, refer to
+L<guestfs(3)/AVAILABILITY>.
+
 =head1 COPYRIGHT
 
 Copyright (C) %s Red Hat Inc.