use SVN::Client;
    my $ctx = new SVN::Client(
              auth => [SVN::Client::get_simple_provider(),
              SVN::Client::get_simple_prompt_provider(\&simple_prompt,2),
              SVN::Client::get_username_provider()]
              );

    $ctx->cat (\*STDOUT, 'http://svn.collab.net/repos/svn/trunk/README', 
               'HEAD');

    sub simple_prompt {
      my $cred = shift;
      my $realm = shift;
      my $default_username = shift;
      my $may_save = shift;
      my $pool = shift;

      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);
    }

SVN::Client wraps the highest level of functions provided by subversion to accomplish specific tasks in an object oriented API. Methods are similar to the functions provided by the C API and as such the documentation for it may be helpful in understanding this interface.

There are a few notable differences from the C API. Most C function calls take a svn_client_ctx_t pointer as the next to last parameter. The Perl method calls take a SVN::Client object as the first parameter. This allows method call invocation of the methods to be possible. For example, the following are equivalent:

  SVN::Client::add($ctx,$path, $recursive, $pool);
  $ctx->add($path, $recursive, $pool);

Many of the C API calls also take a apr_pool_t pointer as their last argument. The Perl bindings generally deal with this for you and you do not need to pass a pool parameter. However, you may still pass a pool parameter as the last parameter to override the automatic handling of this for you.

Users of this interface should not directly manipulate the underlying hash values but should use the respective attribute methods. Many of these attribute methods do other things, especially when setting an attribute, besides simply manipulating the value in the hash.

The following methods are available: This class method constructs a new CWSVN::Client object and returns a reference to it. Key/value pair arguments may be provided to set up the initial state of the user agent. The following methods correspond to attribute methods described below:

    KEY                    DEFAULT
    ----------             ----------------------------------------
    auth                   auth_baton initiated with providers that
                           read cached authentication options from
                           the subversion config only.

    cancel                 undef

    config                 Hash containing the config from the 
                           default subversion config file location.

    log_msg                undef

    notify                 undef

    pool                   A new pool is created for the context.

Schedule a working copy CW$path for addition to the repository. $path's parent must be under revision control already, but CW$path is not. If CW$recursive is set, then assuming CW$path is a directory, all of its contents will be scheduled for addition as well. Calls the notify callback for each added item. Important: this is a scheduling operation. No changes will happen to the repository until a commit occurs. This scheduling can be removed with CW$ctx->revert(). No return. Invoke \&receiver subroutine on each line-blame item associated with revision CW$end of CW$target, using CW$start as the default source of all blame. An Error will be raised if either CW$start or CW$end is undef. No return. The blame receiver subroutine receives the following arguments: CW$line_no, CW$revision, CW$author, CW$date, CW$line, CW$pool $line_no is the line number of the file (starting with 0). The line was last changed in revision number CW$revision by CW$author on CW$date and the contents were CW$line. The blame receiver subroutine can return an svn_error_t object to return an error. All other returns will be ignored. You can create an svn_error_t object with SVN::Error::create(). Outputs the content of the file identified by CW$target and CW$revision to the FILEHANDLE. FILEHANDLE is a reference to a filehandle. If CW$target is not a local path and if CW$revision is 'PREV' (or some other kind that requires a local path), then an error will be raised, because the desired revision can not be determined. Checkout a working copy of CW$url at CW$revision using CW$path as the root directory of the newly checked out working copy. $revision must be a number, 'HEAD', or a date. If CW$revision does not meet these requirements the CW$SVN::Error::CLIENT_BAD_REVISION is raised. Returns the value of the revision actually checked out of the repository. Recursively cleanup a working copy directory, CW$dir, finishing any incomplete operations, removing lockfiles, etc. Commit files or directories referenced by target. Will use the log_msg callback to obtain the log message for the commit. If CW$targets contains no paths (zero elements), then does nothing and immediately returns without error. Calls the notify callback as the commit progresses with any of the following actions: CW$SVN::Wc::Notify::Action::commit_modified, CW$SVN::Wc::Notify::Action::commit_added, CW$SVN::Wc::Notify::Action::commit_deleted, CW$SVN::Wc::Notify::Action::commit_replaced, CW$SVN::Wc::Notify::Action::commit_postfix_txdelta. Use CW$nonrecursive to indicate that subdirectories of directory targets should be ignored. Returns a svn_client_commit_info_t object. If the revision member of the commit information object is CW$SVN::Core::INVALID_REVNUM and no error was raised, then the commit was a no-op; nothing needed to be committed. Copies CW$src_target to CW$dst_target. $src_target must be a file or directory under version control, or the URL of a versioned item in the repository. If CW$src_target is a URL, CW$src_revision is used to choose the revision from which to copy the CW$src_target. CW$dst_path must be a file or directory under version control, or a repository URL, existing or not. If CW$dst_target is a URL, immediately attempt to commit the copy action to the repository. The log_msg callback will be called to query for a commit log message. If the commit succeeds, return a svn_client_commit_info_t object. If CW$dst_target is not a URL, then this is just a variant of CW$ctx->add(), where the CW$dst_path items are scheduled for addition as copies. No changes will happen to the repository until a commit occurs. This scheduling can be removed with CW$ctx->revert(). undef will be returned in this case. Calls the notify callback for each item added at the new location, passing the new, relative path of the added item. Delete items from a repository or working copy. If the paths in CW$targets are URLs, immediately attempt to commit a deletion of the URLs from the repository. The log_msg callback will be called to query for a commit log message. If the commit succeeds, return a svn_client_commit_info_t object. Every path must belong to the same repository. Else, schedule the working copy paths in CW$targets for removal from the repository. Each path's parent must be under revision control. This is just a scheduling operation. No changes will happen to the repository until a commit occurs. This scheduling can be removed with CW$ctx->revert(). If a path is a file it is immediately removed from the working copy. If the path is a directory it will remain in the working copy but all the files, and all unversioned items it contains will be removed. If CW$force is not set then this operation will fail if any path contains locally modified and/or unversioned items. If CW$force is set such items will be deleted. The notify callback is called for each item deleted with the path of the deleted item. Has no return. Produces diff output which describes the delta between CW$target1 at CW$revision1 and CW$target2 at CW$revision2. They both must represent the same node type (i.e. they most both be directories or files). The revisions must not be undef. Prints the output of the diff to the filename or filehandle passed as CW$outfile, and any errors to the filename or filehandle passed as CW$errfile. Use CW$ignore_ancestry to control whether or not items being diffed will be checked for relatedness first. Unrelated items are typically transmitted to the editor as a deletion of one thing and the addition of another, but if this flag is true, unrelated items will be diffed as if they were related. If CW$no_diff_deleted is true, then no diff output will be generated on deleted files. $diff_options is a reference to an array of additional arguments to pass to diff process invoked to compare files. You'll usually just want to use [] to pass an empty array to return a unified context diff (like `diff -u`). Has no return. Export the contents of either a subversion repository or a subversion working copy into a 'clean' directory (meaning a directory with no administrative directories). $from is either the path to the working copy on disk, or a URL to the repository you wish to export. $to is the path to the directory where you wish to create the exported tree. $revision is the revision that should be exported, which is only used when exporting from a repository. It may be undef otherwise. The notify callback will be called for the items exported. Returns the value of the revision actually exported or CW$SVN::Core::INVALID_REVNUM for local exports. Import file or directory CW$path into repository directory CW$url at head. If some components of CW$url do not exist then create parent directories as necessary. If CW$path is a directory, the contents of that directory are imported directly into the directory identified by CW$url. Note that the directory CW$path itself is not imported; that is, the basename of CW$path is not part of the import. If CW$path is a file, then the dirname of CW$url is the directory receiving the import. The basename of CW$url is the filename in the repository. In this case if CW$url already exists, raise an error. The notify callback (if defined) will be called as the import progresses, with any of the following actions: CW$SVN::Wc::Notify::Action::commit_added, CW$SVN::Wc::Notify::Action::commit_postfix_txdelta. Use CW$nonrecursive to indicate that imported directories should not recurse into any subdirectories they may have. Uses the log_msg callback to determine the log message for the commit when one is needed. Returns a svn_client_commit_info_t object. Invoke the log_receiver subroutine on each log_message from CW$start to CW$end in turn, inclusive (but will never invoke receiver on a given log message more than once). $targets is a reference to an array containing all the paths or URLs for which the log messages are desired. The log_receiver is only invoked on messages whose revisions involved a change to some path in CW$targets. If CW$discover_changed_paths is set, then the changed_paths argument to the log_receiver routine will be passed on each invocation. If CW$strict_node_history is set, copy history (if any exists) will not be traversed while harvesting revision logs for each target. If CW$start or CW$end is undef the arp_err code will be set to: CW$SVN::Error::CLIENT_BAD_REVISION. Special case for repositories at revision 0: If CW$start is 'HEAD' and CW$end is 1, then handle an empty (no revisions) repository specially: instead of erroring because requested revision 1 when the highest revision is 0, just invoke CW$log_receiver on revision 0, passing undef to changed paths and empty strings for the author and date. This is because that particular combination of CW$start and CW$end usually indicates the common case of log invocation; the user wants to see all log messages from youngest to oldest, where the oldest commit is revision 1. That works fine, except there are no commits in the repository, hence this special case. Calls the notify subroutine with a CW$SVN::Wc::Notify::Action::skip signal on any unversioned targets. The log_receiver takes the following arguments: CW$changed_paths, CW$revision, CW$author, CW$date, CW$message, CW$pool It is called once for each log CW$message from the CW$revision on CW$date by CW$author. CW$author, CW$date or CW$message may be undef. If CW$changed_paths is defined it references a hash with the keys every path committed in CW$revision; the values are svn_log_changed_path_t objects. Returns a hash of svn_dirent_t objects for CW$target at CW$revision. If CW$target is a directory, returns entries for all of the directories' contents. If CW$recursive is true, it will recurse subdirectories in CW$target. If CW$target is a file only return an entry for the file. If CW$target is non-existent, raises the CW$SVN::Error::FS_NOT_FOUND error. Merge changes from CW$src1/$rev1 to CW$src2/$rev2 into the working-copy path CW$target_wcpath. $src1 and CW$src2 are either URLs that refer to entries in the repository, or paths to entries in the working copy. By 'merging', we mean: apply file differences and schedule additions & deletions when appropriate. $src1 and CW$src2 must both represent the same node kind; that is, if CW$src1 is a directory, CW$src2 must also be, and if CW$src1 is a file, CW$src2 must also be. If either CW$rev1 or CW$rev2 is undef raises the CW$SVN::Error::CLIENT_BAD_REVISION error. If CW$recursive is true (and the URLs are directories), apply changes recursively; otherwise, only apply changes in the current directory. Use CW$ignore_ancestry to control whether or not items being diffed will be checked for relatedness first. Unrelated items are typically transmitted to the editor as a deletion of one thing and the addition of another, but if this flag is true, unrelated items will be diffed as if they were related. If CW$force is not set and the merge involves deleting locally modified or unversioned items the operation will raise an error. If CW$force is set such items will be deleted. Calls the notify callback once for each merged target, passing the targets local path. If CW$dry_run is true the merge is carried out, and the full notification feedback is provided, but the working copy is not modified. Has no return. Create a directory, either in a repository or a working copy. If CW$targets contains URLs, immediately attempts to commit the creation of the directories in CW$targets in the repository. Returns a svn_client_commit_info_t object. Else, create the directories on disk, and attempt to schedule them for addition. In this case returns undef. Calls the notify callback when the directory has been created (successfully) in the working copy, with the path of the new directory. Note this is only called for items added to the working copy. Move CW$src_path to CW$dst_path. $src_path must be a file or directory under version control, or the URL of a versioned item in the repository. If CW$src_path is a repository URL: * CW$dst_path must also be a repository URL (existent or not). * CW$src_revision is used to choose the revision from which to copy the CW$src_path. * The log_msg callback will be called for the commit log message. * The move operation will be immediately committed. If the commit succeeds, returns a svn_client_commit_info_t object. If CW$src_path is a working copy path * CW$dst_path must also be a working copy path (existent or not). * CW$src_revision is ignored and may be undef. The log_msg callback will not be called. * This is a scheduling operation. No changes will happen to the repository until a commit occurs. This scheduling can be removed with CW$ctx->revert(). If CW$src_path is a file it is removed from the working copy immediately. If CW$src_path is a directory it will remain in the working copy but all files, and unversioned items, it contains will be removed. * If CW$src_path contains locally modified and/or unversioned items and CW$force is not set, the copy will raise an error. If CW$force is set such items will be removed. The notify callback will be called twice for each item moved, once to indicate the deletion of the moved node, and once to indicate the addition of the new location of the node. Returns a reference to a hash containing paths or URLs, prefixed by CW$target (a working copy or URL), of items for which the property CW$propname is set, and whose values represent the property value for CW$propname at that path. Returns a reference to an array of svn_client_proplist_item_t objects. For each item the node_name member of the proplist_item object contains the name relative to the same base as CW$target. If CW$revision is undef, then get properties from the working copy, if CW$target is a working copy, or from the repository head if CW$target is a URL. Else get the properties as of CW$revision. If CW$recursive is false, or CW$target is a file, the returned array will only contain a single element. Otherwise, it will contain one entry for each versioned entry below (and including) CW$target. If CW$target is not found, raises the CW$SVN::Error::ENTRY_NOT_FOUND error. Set CW$propname to CW$propval on CW$target (a working copy or URL path). If CW$recursive is true, then CW$propname will be set recursively on CW$target and all children. If CW$recursive is false, and CW$target is a directory, CW$propname will be set on only CW$target. A CW$propval of undef will delete the property. If CW$propname is an svn-controlled property (i.e. prefixed with svn:), then the caller is responsible for ensuring that CW$propval is UTF8-encoded and uses LF line-endings. Modify a working copy directory CW$dir, changing any repository URLs that begin with CW$from to begin with CW$to instead, recursing into subdirectories if CW$recursive is true. Has no return. Removed the 'conflicted' state on a working copy path. This will not semantically resolve conflicts; it just allows CW$path to be committed in the future. The implementation details are opaque. If CW$recursive is set, recurse below CW$path, looking for conflicts to resolve. If CW$path is not in a state of conflict to begin with, do nothing. If CW$path's conflict state is removed, call the notify callback with the CW$path. Restore the pristine version of a working copy CW$paths, effectively undoing any local mods. For each path in CW$paths, if it is a directory and CW$recursive is true, this will be a recursive operation. Returns two values, the first of which is the value of CW$propname on revision CW$revision in the repository represented by CW$url. The second value is the actual revision queried. Note that unlike its cousin CW$ctx->propget(), this routine doesn't affect working copy at all; it's a pure network operation that queries an unversioned property attached to a revision. This can be used to query log messages, dates, authors, and the like. Returns two values, the first of which is a reference to a hash containing the properties attached to CW$revision in the repository represented by CW$url. The second value is the actual revision queried. Note that unlike its cousin CW$ctx->proplist(), this routine doesn't read a working copy at all; it's a pure network operation that reads unversioned properties attached to a revision. Set CW$propname to CW$propval on revision CW$revision in the repository represented by CW$url. Returns the actual revision affected. A CW$propval of undef will delete the property. If CW$force is true, allow newlines in the author property. If CW$propname is an svn-controlled property (i.e. prefixed with svn:), then the caller is responsible for ensuring that the value is UTF8-encoded and uses LF line-endings. Note that unlike its cousin CW$ctx->propset(), this routine doesn't affect the working copy at all; it's a pure network operation that changes an unversioned property attached to a revision. This can be used to tweak log messages, dates, authors, and the like. Be careful: it's a lossy operation, meaning that any existing value is replaced with the new value, with no way to retrieve the prior value. Also note that unless the administrator creates a pre-revprop-change hook in the repository, this feature will fail. Given CW$path to a working copy directory (or single file), call status_func() with a set of svn_wc_status_t objects which describe the status of CW$path and its children. If CW$recursive is true, recurse fully, else do only immediate children. If CW$get_all is set, retrieve all entries; otherwise, retrieve only 'interesting' entries (local mods and/or out-of-date). If CW$update is set, contact the repository and augment the status objects with information about out-of-dateness (with respect to CW$revision). Also, will return the value of the actual revision against with the working copy was compared. (The return will be undef if CW$update is not set). The function recurses into externals definitions ('svn:externals') after handling the main target, if any exist. The function calls the notify callback with CW$SVN::Wc::Notify::Action::status_external action before handling each externals definition, and with CW$SVN::Wc::Notify::Action::status_completed after each. The status_func subroutine takes the following parameters: CW$path, CW$status $path is the pathname of the file or directory which status is being reported. CW$status is a svn_wc_status_t object. The return of the status_func subroutine is ignored. Switch working tree CW$path to CW$url at CW$revision. $revision must be a number, 'HEAD', or a date, otherwise it raises the CW$SVN::Error::CLIENT_BAD_REVISION error. Calls the notify callback on paths affected by the switch. Also invokes the callback for files that may be restored from the text-base because they were removed from the working copy. Summary of purpose: This is normally used to switch a working directory over to another line of development, such as a branch or a tag. Switching an existing working directory is more efficient than checking out CW$url from scratch. Returns the value of the revision to which the working copy was actually switched. Update a working copy CW$path to CW$revision. $revision must be a revision number, 'HEAD', or a date or this method will raise the CW$SVN::Error::CLIENT_BAD_REVISION error. Calls the notify callback for each item handled by the update, and also for files restored from the text-base. Returns the revision to which the working copy was actually updated. Returns the URL for CW$target. If CW$target is already a URL it returns CW$target. If CW$target is a versioned item, it returns CW$target's entry URL. If CW$target is unversioned (has no entry), returns undef. Return the repository uuid for working-copy CW$path, allocated in CW$pool. Use CW$adm_access to retrieve the uuid from CW$path's entry; if not present in the entry, then call CW$ctx->uuid_from_url() to retrieve, using the entry's URL. Note: The only reason this function falls back on CW$ctx->uuid_from_url is for compatibility purposes. Old working copies may not have uuids in the entries files. Note: This method probably doesn't work right now without a lot of pain, because SVN::Wc is incomplete and it requires an adm_access object from it. Return repository uuid for url.

The following functions get authentication providers for you. They come in two forms. Standard or File versions, which look for authentication information in the subversion configuration directory that was previously cached, or Prompt versions which call a subroutine to allow you to prompt the user for the information.

The functions that return the svn_auth_provider_object_t for prompt style providers take a reference to a Perl subroutine to use for the callback. The first parameter each of these subroutines receive is a credential object. The subroutines return the response by setting members of that object. Members may be set like so: CW$cred->username(breser); These functions and credential objects always have a may_save member which specifies if the authentication data will be cached.

The providers are as follows:

        NAME                WHAT IT HANDLES
        ----------------    ----------------------------------------
        simple              username and password pairs

        username            username only

        ssl_server_trust    server certificates and failures
                            authenticating them

        ssl_client_cert     client side certificate files

        ssl_client_cert_pw  password for a client side certificate file.

SVN::Client::get_simple_provider

Returns a simple provider that returns information from previously cached sessions. Takes no parameters or one pool parameter.

SVN::Client::get_simple_prompt_provider

Returns a simple provider that prompts the user via a callback. Takes two or three parameters, the first is the callback subroutine, the 2nd is the number of retries to allow, the 3rd is optionally a pool. The subroutine gets called with the following parameters: a svn_auth_cred_simple_t object, a realm string, a default username, may_save, and a pool. The svn_auth_cred_simple has the following members: username, password, and may_save.

SVN::Client::get_username_provider

Returns a username provider that returns information from a previously cached sessions. Takes no parameters or one pool parameter.

SVN::Client::get_username_prompt_provider

Returns a username provider that prompts the user via a callback. Takes two or three parameters, the first is the callback subroutine, the 2nd is the number of retries to allow, the 3rd is optionally a pool. The subroutine gets called with the following parameters: a svn_auth_cred_username_t object, a realm string, a default username, may_save, and a pool. The svn_auth_cred_username has the following members: username and may_save.

SVN::Client::get_ssl_server_trust_file_provider

Returns a server trust provider that returns information from previously cached sessions. Takes no parameters or optionally a pool parameter.

SVN::Client::get_ssl_server_trust_prompt_provider

Returns a server trust provider that prompts the user via a callback. Takes one or two parameters the callback subroutine and optionally a pool parameter. The subroutine gets called with the following parameters. A svn_auth_cred_ssl_server_trust_t object, a realm string, an integer specifying how the certificate failed authentication, a svn_auth_ssl_server_cert_info_t object, may_save, and a pool. The svn_auth_cred_ssl_server_trust_t object has the following members: may_save and accepted_failures. The svn_auth_ssl_server_cert_info_t object has the following members (and behaves just like cred objects though you can't modify it): hostname, fingerprint, valid_from, valid_until, issuer_dname, ascii_cert. The masks used for determining the failures are in SVN::Auth::SSL and are named: $SVN::Auth::SSL::NOTYETVALID CW$SVN::Auth::SSL::EXPIRED CW$SVN::Auth::SSL::CNMISMATCH CW$SVN::Auth::SSL::UNKNOWNCA CW$SVN::Auth::SSL::OTHER You reply by setting the accepted_failures of the cred object with an integer of the values for what you want to accept bitwise AND'd together.

SVN::Client::get_ssl_cert_file_provider

Returns a client certificate provider that returns information from previously cached sessions. Takes no parameters or optionally a pool parameter.

SVN::Client::get_ssl_cert_prompt_provider

Returns a client certificate provider that prompts the user via a callback. Takes two or three parameters: the first is the callback subroutine, the 2nd is the number of retries to allow, the 3rd is optionally a pool parameter. The subroutine gets called with the following parameters. A svn_auth_cred_ssl_client_cert object, a realm string, may_save, and a pool. The svn_auth_cred_ssl_client_cert the following members: cert_file and may_save.

SVN::Client::get_ssl_cert_pw_file_provider

Returns a client certificate password provider that returns information from previously cached sessions. Takes no parameters or optionally a pool parameter.

SVN::Client::get_ssl_cert_pw_prompt_provider

Returns a client certificate password provider that prompts the user via a callback. Takes two or three parameters, the first is the callback subroutine, the 2nd is the number of retries to allow, the 3rd is optionally a pool parameter. The subroutine gets called with the following parameters. A svn_auth_cred_ssl_client_cert_pw object, a realm string, may_save, and a pool. The svn_auth_cred_ssl_client_cert_pw has the following members: password and may_save.