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

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

@local-table-of-contents[]

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

  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 @scheme[read-packed],
  @scheme[unpack], @scheme[write-packed] or @scheme[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
  @scheme[eof-value], which should obey the same contract as the values
  regularly handled by the underlying @scheme[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 @scheme[unwrapper]
  and @scheme[wrapper] procedures to values unpacked and packed using
  the underlying @scheme[packing].

  The values produced and consumed by this packing obey the given
  @scheme[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 @scheme[in] using the given
  @scheme[packing]. The result is checked against the packing's
  contract.

  Returns either an unpacked value or @scheme[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 @scheme[v] to the output port @scheme[out] using
  the given @scheme[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 @scheme[b] using the given
  @scheme[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 @scheme[v] into a byte string using the given
  @scheme[packing]. The input value is checked against the packing's
  contract.

  Returns a byte string containing the packed data.

}