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

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

@local-table-of-contents[]

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

  This module provides some utilities to work with native data
  structures used by the Subversion API. Most of the definitions in
  this module are only of interest to someone hacking on the source
  of this binding.

}

@defform[(unsafe-subr!)]{

  Some bindings in this module are deemed unsafe and have to be
  imported using the this declaration before they can be used.

}

@section[#:tag "subr-errors"]{Error Handling}

@defstruct[(exn:fail:svn exn:fail)
	   ([status exact-integer?]
	    [child (or/c exn:fail:svn? #f)]
	    [location (or/c srcloc? #f)])]{

  Exception type raised by failing Subversion procedures. The
  @scheme[status] fields contains a status code classifying the
  error, the @scheme[child] fields may point to another error that
  caused this one and the location field may contain information
  designating the source code position where the error originated.

}

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

   C pointer type returned by most native Subversion procedures.
   Describes an error, if applicable.

}

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

  Checks whether the given @scheme[obj] is a Subversion error pointer.

}

@defproc[(check-error [source any/c] [error (or/c error? #f)])
	 any]{

  Checks the given @scheme[error] return value from a native Subversion
  procedure. If the error pointer describes an error, the procedure
  raises an exception of type @scheme[exn:fail:svn] with the given
  @scheme[source] information prepended to the error message.

  Destroys the given error object, if necessary.

  This procedure is unsafe.

}

@section{Strings}

@deftogether[(
@defthing[_svn-string ctype?]
@defthing[_svn-string-pointer ctype?]
@defthing[_svn-string-pointer/null ctype?]
)]{

  C structure type representing a binary string for Subversion.

}

@defproc[(svn-string? [obj any/c])
	 any]{

  Checks whether the given @scheme[obj] is a C pointer to a binary
  Subversion string.

}

@defproc[(bytes->svn-string [bytes (or/c bytes? #f)])
	 (or/c svn-string? #f)]{

  Converts the given byte string @scheme[bytes] into a binary
  Subversion string.

  This procedure is unsafe.

}

@defproc[(svn-string->bytes [str (or/c svn-string? #f)])
	 (or/c bytes? #f)]{

  Converts the given binary Subversion string @scheme[str] into a
  Scheme byte string.

  This procedure is unsafe.

}

@deftogether[(
@defthing[_svn-stringbuf ctype?]
@defthing[_svn-stringbuf-pointer ctype?]
@defthing[_svn-stringbuf-pointer/null ctype?]
)]{

  C structure type representing a binary string buffer for Subversion.

}

@defproc[(svn-stringbuf? [obj any/c])
	 any]{

  Checks whether the given @scheme[obj] is a C pointer to a binary
  Subversion string buffer.

}

@defproc[(bytes->svn-stringbuf [bytes (or/c bytes? #f)])
	 (or/c svn-stringbuf? #f)]{

  Converts the given byte string @scheme[bytes] into a binary
  Subversion string buffer.

  This procedure is unsafe.

}

@defproc[(svn-stringbuf->bytes [str (or/c svn-stringbuf? #f)])
	 (or/c bytes? #f)]{

  Converts the given binary Subversion string buffer @scheme[str] into a
  Scheme byte string.

  This procedure is unsafe.

}

@section{Streams}

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

  C pointer type representing generic Subversion streams.

}

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

  Checks whether the given @scheme[obj] is a generic Subversion
  stream.

}

@defproc[(stream->input-port [name any/c] [stream stream?])
	 input-port?]{

  Converts the given Subversion @scheme[stream] into a Scheme input
  port tagged with @scheme[name].

}

@defproc[(stream->output-port [name any/c] [stream stream?])
	 output-port?]{

  Converts the given Subversion @scheme[stream] into a Scheme output
  port tagged with @scheme[name].

}

@section{UUID Generation}

@defproc[(genuuid)
	 bytes?]{

  Generates a UUID and returns its hexadecimal representation as a
  binary string.

}