svn commit: r1566230 - /subversion/trunk/subversion/bindings/swig/perl/native/Client.pm

[br...@apache.org]

Author: breser
Date: Sun Feb  9 05:33:25 2014
New Revision: 1566230

URL: http://svn.apache.org/r1566230
Log:
swig-pl: Modernize the SYNOPSIS example and talk about canonicalization.

* subversion/bindings/swig/perl/native/Client.pm
  (SYNOPSIS): Use a more modern example that fully sets up authentication in a
    way that matches the command line client.  Also canonicalize the target
    before passing it into the APIs.
  (PARAMETER NOTES): Talk about canonicalization.

Suggested by: Anton Yuzhaninov <citrin+svn{_AT_}citrin.ru>
(at least the notion that our documentation should mention canonicalization)

Modified:
    subversion/trunk/subversion/bindings/swig/perl/native/Client.pm

Modified: subversion/trunk/subversion/bindings/swig/perl/native/Client.pm
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/bindings/swig/perl/native/Client.pm?rev=1566230&r1=1566229&r2=1566230&view=diff
==============================================================================
--- subversion/trunk/subversion/bindings/swig/perl/native/Client.pm (original)
+++ subversion/trunk/subversion/bindings/swig/perl/native/Client.pm Sun Feb  9 05:33:25 2014
@@ -41,30 +41,36 @@ SVN::Client - Subversion client function
 =head1 SYNOPSIS
 
     use SVN::Client;
-    my $client = new SVN::Client(
-      auth => [
-          SVN::Client::get_simple_provider(),
-          SVN::Client::get_simple_prompt_provider(\&simple_prompt,2),
-          SVN::Client::get_username_provider()
-      ]);
-
-    $client->cat(\*STDOUT, 
-              'http://svn.apache.org/repos/asf/subversion/trunk/README', 'HEAD');
-
-    sub simple_prompt {
-      my ($cred, $realm, $default_username, $may_save, $pool) = @_;
-
-      print "Enter authentication info for realm: $realm\n";
-      print "Username: ";
-      my $username = <>;
-      chomp($username);
-      $cred->username($username);
-      print "Password: ";
-      my $password = <>;
-      chomp($password);
-      $cred->password($password);
+    my $client = new SVN::Client();
+
+    # setup to handle authentication the same as the command line client
+    my $config_dir = undef; # use default location
+    my $config = SVN:Core::config_get_config($config_dir);
+    my $config_category = $cfg->{SVN::Core::CONFIG_CATEGORY_CONFIG};
+    $client->auth(
+      SVN::Core::cmdline_create_auth_baton(0,           #non_interactive
+                                           undef,       #username
+                                           undef,       #password
+                                           $config_dir,
+                                           0,           #no_auth_cache
+                                           0,           #trust_server_cert
+                                           $config_category,
+                                           undef,       #cancel_func
+                                           undef)       #cancel_baton
+    );
+
+    # Use first argument as target and canonicalize it before using
+    my $target;
+    if (SVN::Core::path_is_url($ARGV[0])) {
+      $target = SVN::Core::uri_canonicalize($ARGV[0]);
+    } else {
+      $target = SVN::Core::dirent_canonicalize($ARGV[0]);
     }
 
+    # fetch the head revision of the target
+    $client->cat(\*STDOUT, $target, 'HEAD');
+
+
 =head1 DESCRIPTION
 
 SVN::Client wraps the highest level of functions provided by
@@ -111,18 +117,24 @@ This is a URL to a subversion repository
 
 =item $path
 
-This is a path to a file or directory on the local file system.
+This is a path to a file or directory on the local file system.  Paths need
+to be canonicalized before being passed into the Subversion APIs.  Paths on
+the local file system are called dirents and can be canonicalized by calling
+C<SVN::Core::dirent_canonicalize>.
 
 =item $paths
 
-This argument can either be a single path to a file or directory on the local
-file system, or it can be a reference to an array of files or directories on
-the local file system.
+This argument can either be a single $path (as defined above) or a reference
+to an array of them.
 
 =item $target
 
 This is a path to a file or directory in a working copy or a URL to a file or
-directory in a subversion repository.
+directory in a subversion repository.  Both paths and URLs need to be
+canonicalized before being passed into the Subversion APIs.  Paths on the local
+file system are called dirents and can be canonicalized by calling 
+C<SVN::Core::dirent_canonicalize>.  URLs can be canonicalized by calling
+C<SVN::Core::uri_canonicalize>.
 
 =item $targets