gistfile1.ml

(*---------------------------------------------------------------------------
   Copyright (c) 2014 Daniel C. Bünzli. All rights reserved.
   Distributed under the BSD3 license, see license at the end of the file.
   %%NAME%% release %%VERSION%%
  ---------------------------------------------------------------------------*)

(** Non-blocking streaming deflate, gzip and zlib codec.

    [Deflatem] is a non-blocking streaming codec to
    {{!section:decode}decode} and {{!section:encode}encode} the
    deflate, gzip and zlib data formats. It can process data streams
    withoug blocking on IO.
    
    Consult {{!examples}examples} of use.

    {e Release %%VERSION%% - %%MAINTAINER%% }
    {3 References}
    {ul 
    {- P. Deutsch. 
     {e {{:http://tools.ietf.org/html/rfc1951}DEFLATE Compressed Data Format 
     Specification 1.3}}, 1996.}
    {- P. Deutsch, J-L. Gailly. 
     {e {{:http://tools.ietf.org/html/rfc1950}ZLIB Compressed Data Format 
     Specification version 3.3}}, 1996}
    {- P. Deutsch. 
     {e {{:http://tools.ietf.org/html/rfc1952}GZIP file format specification 
     version 4.3}}, 1996}} *)

(** {1:decode Decode} *)

type error = [ `Crc ]

val pp_error : Format.formatter -> [< error ] -> unit 
(** [pp_error e] prints an unspecified representation of [e] on [ppf]. *) 

type encoding = [ `Deflate | `Gzip | `Zlib ] 
(** The type for data stream encodings. *) 

type src = [ `Channel of Pervasives.in_channel | `Manual | `Bytes of Bytes.t ]
(** The type for input sources. With a `Manual source the client must provide
    input with {!Manual.src}. *) 

type decoder 
(** The type for decoders. *) 

val decoder : [< encoding] -> [< src] -> decoder 
(** [decoder encoding src] is a decoder that inputs from [src]. 
    [encoding] specifies the data format to decode. *)

val decode : decoder -> [> `Await | `End | `Bytes of Bytes.t | `Error of error ]
(** [decode d] is: 
    {ul 
    {- [`Await] if [d] has a [`Manual] source and awaits for more input. 
       The client must use {!Manual.src} to provide it.}
    {- [`Bytes b] if bytes were decoded. {b Warning} [b] will be overwritten
       by further calls to {!decode}.}
    {- [`End] if the end of input was reached.}
    {- [`Error e] if a decoding error occured. If the client is interested
       in a best-effort decoding it can still continue to decode after an 
       error (see {!errorrecovery}) although the resulting sequence of bytes
       is undefined.}}

    {b Note.} Repeated invocation always eventually returns [`End], even 
    in case of errors. *)
       
val decoder_src : decoder -> src
(** [decoder_src d] is [d]'s input source. *) 

val decoder_encoding : decoder -> [> encoding ]
(** [decoder_encoding d] is [d]'s decoded encoding. *) 

(** {1:encode Encode} *) 

type dst = [ `Buffer of Buffer.t | `Channel of Pervasives.out_channel 
           | `Manual ]
(** The type for output destinations. With a [`Manual] destination the client
    must provide output storage with {!Manual.dst}. *)

type encoder
(** The type for encoders. *) 

val encoder : encoding -> dst -> encoder 
(** [encoder enc dst] is an encoder that outputs to [dst] using encoding 
    [enc]. *) 

val encode : encoder -> [`Await | `End | `Bytes of Bytes.t ] -> 
  [ `Ok | `Partial ]
(** [encode e v] is: 
    {ul 
    {- [`Partial] iff [e] has a [`Manual] destination and needs more output 
       storage. The client must use {!Manual.dst} to provide a new buffer 
       and then call {!encode} with [`Await] until [`Ok] is returned.}
    {- [`Ok] when the encoder is ready to encode new [`Bytes] or [`End].}}
   
    For [`Manual] destinations, encoding [`End] always returns [`Partial], 
    the client should as usual use {!Manual.dst} and continue with [`Await]
    until [`Ok] is returned at which point {!Manual.dst_rem}[e] is guaranteed
    to be the size of the last provided buffer (i.e. nothing was written).
 
    @raise Invalid_argument if [`Bytes] or [`End] is encoded after a 
    [`Partial] encode. *)


val encoder_dst : encoder -> dst 
(** [encoder_dst e] is [e]'s output destination. *) 

val encoder_encoding : encoder -> dst 
(** [encoder_encoding e] is [e]'s encoding. *) 

(** {1:manual Manual sources and destinations} *) 

(** Manual input sources and output destinations. 

    {b Warning.} Use only with [`Manual] decoders and encoders. *) 
module Manual : sig 
  val src : decoder -> Bytes.t -> int -> int -> unit
  (** [src d b j l] provides [d] with [l] bytes to read, starting at [j]
      in [b]. This byte range is read by calls to {!decode} until [`Await]
      is returned. *)

  val dst : encoder -> Bytes.t -> int -> int -> unit 
  (** [dst e b j l] provides [e] with [l] bytes to read, starting at [j]
      in [b]. This byte reange is written by calls to {!encode} until 
      [`Partial] is returned. Use {!dst_rem} to know the remaining number 
      of non-written free bytes in [b]. *) 

  val dst_rem : encoder -> int 
  (** [dst_rem e] is the remaining number of non-written, free bytes in 
      the last buffer provided with {!Manual.dst}. *)
end

(** {1:errorrecovery Error recovery} *) 

(** {1:examples Examples}  *)

(*---------------------------------------------------------------------------
   Copyright (c) 2014 Daniel C. Bünzli.
   All rights reserved.

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:
     
   1. Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

   2. Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.

   3. Neither the name of Daniel C. Bünzli nor the names of
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  ---------------------------------------------------------------------------*)