#lang scribble/doc
@(require
	scribble/manual
	(for-label "../apr.ss")
	(for-label "../client.ss"))

@title[#:tag "client" #:style '(toc)]{Subversion Client}

@local-table-of-contents[]

@defmodule[(planet "client.ss" ("murphy" "svn.plt" 1 1))]{

	This module provides high-level functions to deal with Subversion
	working copies.

}

@section{Client Contexts}

@deftogether[(
@defthing[_client ctype?]
@defthing[_client/null ctype?]
)]{

	C pointer type representing client contexts.

}

@defproc[(client? [obj any/c])
				 any]{

	Checks whether the given @scheme[obj] is a client context.

}

@defproc[(make-client) client?]{

	Creates a new client context. Reads and sets a default configuration
	for the context. Creates and sets a non-interactive set of
	authentication providers for the client context, initialized with the
	current user's login name and no password or with the username
	@scheme["nobody"] if the current user's login name cannot be
	determined.

}

@section{Client Configuration}

@defproc[(make-client-config [path (or/c path-string? #f)]) apr-hash?]{

	Creates a new client configuration, read from the configuration files
	found at @scheme[path] or from default places if @scheme[path] is
	@scheme[#f].

}

@deftogether[(
@defproc[(client-config [client client?]) apr-hash?]
@defproc[(set-client-config! [client client?] [config apr-hash?]) void?]
@defform[#:id set!/client-config #:literals (set! client-config) (set! (client-config client) config)]
)]{

	Retrieves or sets the configuration for a client context.

}

@section{Authentication Provider Sets}

@deftogether[(
@defthing[_client-auth ctype?]
@defthing[_client-auth/null ctype?]
)]{

	C pointer type representing client authentication provider sets.

}

@defproc[(client-auth? [obj any/c])
				 any]{

	Checks whether the given @scheme[obj] is a client authentication
	provider set.

}

@defproc[(make-client-auth [username (or/c string? #f)]
														[password (or/c string? #f)]
														[#:interactive interactive? any/c #f]
														[#:config-dir config-dir (or/c path-string? #f) #f]
														[#:auth-cache auth-cache? any/c #f])
					client-auth?]{

	Creates a new default client authentication provider set.

}

@deftogether[(
@defproc[(client-auth [client client?]) client-auth?]
@defproc[(set-client-auth! [client client?] [auth client-auth?]) void?]
@defform[#:id set!/client-auth #:literals (set! client-auth) (set! (client-auth client) auth)]
)]{

	Retrieves or sets the authentication provider set for a client
	context.

}

@section{Location and Identification}

@defproc[(client-path->url [path path-string?]) string?]{

	Converts a file system path inside a working copy into a Subversion
	URL inside the associated repository.

}

@defproc[(client-path->root-url [client client?] [path path-string?]) string?]{

	Maps a file system path inside a working copy or a path inside a
	repository to the root URL of the repository.

}

@defproc[(client-url-uuid [client client?] [url string?]) bytes?]{

	Retrieves the unique identifier of a repository given its URL.

}

@section{Specifying Revisions}

@defthing[_revnum ctype?]{

	An integer type representing revision numbers.

}

@defthing[_opt-revision ctype?]{

	A C type used to specify the target revisions for many operations. The
	following values can be converted into this type:

	@itemize{

		@item{
			Integers are interpreted as revision numbers.
		}

		@item{
			SRFI-19 time objects are interpreted as points in time specifying
			a revision.
		}

		@item{
			The symbol @scheme['unspecified] indicates that some default value
			for the revision number should be chosen by the Subversion library.
		}

		@item{
			The symbol @scheme['committed] indicates the revision of the most
			recent change.
		}

		@item{
			The symbol @scheme['previous] indicates the revision of the most
			recent change minus one.
		}

		@item{
			The symbol @scheme['base] indicates the current revision stored in
			@filepath{.svn/entries}.
		}

		@item{
			The symbol @scheme['working] indicates the uncommitted state of
			work in a working copy.
		}

		@item{
			The symbol @scheme['head] indicates the most recent revision in
			the repository.
		}

	}

}

@section{Managing a Checkout}

@defproc[(client-checkout [client client?]
													 [url string?]
													 [path path-string?]
													 [#:peg-revision peg-revision _opt-revision 'unspecified]
													 [#:revision revision _opt-revision 'head]
													 [#:recurse recurse? any/c #t]
													 [#:ignore-externals ignore-externals? any/c #f])
					integer?]{

	Checks out a working copy from the repository at @scheme[url] into the
	local directory at @scheme[path].

	Returns the revision number that was checked out.

}

@defproc[(client-update [client client?]
												[paths (listof path-string?)]
												 [#:revision revision _opt-revision 'head]
												 [#:recurse recurse? any/c #t]
												 [#:ignore-externals ignore-externals? any/c #f])
				 (listof integer?)]{

	Updates the working copy @scheme[paths] to a different revision from
	the repository.

	Returns a list of new revision numbers for the paths after the update.

}

@section{Listing Files under Version Control}

@defproc[(client-directory-list [client client?]
																	[path path-string?]
																	[#:peg-revision peg-revision _opt-revision 'unspecified]
																	[#:revision revision _opt-revision 'head]
																	[#:recurse recurse? any/c #f])
					(listof path?)]{

	Lists the relative paths of resources under the given repository or
	working copy @scheme[path].

}

@section{Accessing Properties}

@defproc[(client-property-list [client client?]
																 [path path-string?]
																 [#:peg-revision peg-revision _opt-revision 'unspecified]
																 [#:revision revision _opt-revision 'head]
																 [#:recurse recurse? any/c #f])
					(listof (cons/c string? (listof (cons/c symbol? bytes?))))]{

	Retrieves all properties set on the given working copy or repository
	@scheme[path] or on resources within it, if @scheme[recurse?] is
	not @scheme[#f].

	The properties are returned as a nested association list: The keys of
	the first level are repository paths, the keys of the second level are
	the property names.

}

@defproc[(client-property-ref [client client?]
																[path path-string?]
																[key symbol?]
																[#:peg-revision peg-revision _opt-revision 'unspecified]
																[#:revision revision _opt-revision 'head]
																[#:recurse recurse? any/c #f])
					(listof (cons/c string? bytes?))]{

	Retrieves all instances of the property identified by @scheme[key],
	set on the given working or repository @scheme[path] or on resources
	within it, if @scheme[recurse?] is not @scheme[#f].

	The property values are returned as an association list with
	repository paths as keys.

}

@defproc[(client-revision-property-list [client client?]
																					[url string?]
																					[#:revision revision _opt-revision 'head])
					(cons/c integer? (listof (cons/c symbol? bytes?)))]{

	Retrieves all properties set on a specific revision of the repository
	path at @scheme[url].

	The procedure returns a pair consisting of the properties' actual
	revision number and an association list with property names as keys.

}

@defproc[(client-revision-property-ref [client client?]
																				 [url string?]
																				 [key symbol?]
																				 [#:revision revision _opt-revision 'head])
					(or/c (cons/c integer? bytes?) #f)]{

	Retrieves the property identified by @scheme[key], set on a specific
	revision of the repository path at @scheme[url].

	The procedure returns a pair consisting of the property's actual
	revision number and its value or @scheme[#f] if the requested property
	is not set on the revision.

}