#lang scribble/doc
@(require
  scribble/manual
  (for-label "../packing.rkt"))

@title[#:tag "packing"]{Generic Interface}

@local-table-of-contents[]

@defmodule[(planet "packing.rkt" ("murphy" "packed-io.plt" 1 1))]{

  This module provides the basic structure definitions, combinators
  and frontend functions for packings.
  
}

@section{Packing Structure}

@defstruct[packing ([reader (-> input-port? any/c)]
  		    [writer (-> any/c output-port? any)]
		    [contract contract?])]{

  A structure representing a packing. New packing combinators may want
  to access the elements of the structure directly, client programs
  should usually make use of the @racket[read-packed],
  @racket[unpack], @racket[write-packed] or @racket[pack] procedures.
  
}

@defproc[(with-eof-value/p [eof-value (packing-contract packing)] [packing packing?]) packing?]{

  Creates a wrapped packing that replaces the end of input with the given
  @racket[eof-value], which should obey the same contract as the values
  regularly handled by the underlying @racket[packing].

}

@defproc[(wrap/p [unwrapper (-> (packing-contract packing) wrapped-contract)]
		 [wrapper (-> wrapped-contract (packing-contract packing))]
		 [packing packing?]
		 [wrapped-contract contract? any/c]) packing?]{

  Creates a wrapped packing that applies the given @racket[unwrapper]
  and @racket[wrapper] procedures to values unpacked and packed using
  the underlying @racket[packing].

  The values produced and consumed by this packing obey the given
  @racket[wrapped-contract].

}

@section{Packed I/O}

@defproc[(read-packed [packing packing?]
		      [in input-port? (current-input-port)]) (packing-contract packing)]{

  Reads a value from the input port @racket[in] using the given
  @racket[packing]. The result is checked against the packing's
  contract.

  Returns either an unpacked value or @racket[eof] at the end of
  input.

}

@defproc[(write-packed [packing packing?] [v (packing-contract packing)]
		       [out output-port? (current-output-port)]) any]{

  Writes the value @racket[v] to the output port @racket[out] using
  the given @racket[packing]. The input value is checked against the
  packing's contract.

}

@section{Packed Byte Strings}

@defproc[(unpack [packing packing?] [b bytes?]) (packing-contract packing)]{

  Unpacks a value from the byte string @racket[b] using the given
  @racket[packing]. The result is checked against the packing's
  contract.

  Returns the unpacked value. A contract error is signalled if the end
  of the input buffer is reached before the packed value has been read
  completely.

}

@defproc[(pack [packing packing?] [v (packing-contract packing)]) bytes?]{

  Packs the value @racket[v] into a byte string using the given
  @racket[packing]. The input value is checked against the packing's
  contract.

  Returns a byte string containing the packed data.

}