src/utils/cdk/bzip2.mli

   1
   2 (* Module [Bzip2]: reading and writing to/from [bzip2] compressed files *)
   3
   4 (* This module provides functions to read and write compressed data
   5    to/from files in [bzip2] format. *)
   6
   7 (*** Reading from compressed files *)
   8
   9 type in_channel
  10         (* Abstract type representing a channel opened for reading
  11            from a compressed file. *)
  12 val open_in: string -> in_channel
  13         (* Open a compressed file for reading.  The argument is the file
  14            name. *)
  15 val open_in_chan: Pervasives.in_channel -> in_channel
  16         (* Open a compressed file for reading.  The argument is a
  17            regular file channel already opened on the compressed file. *)
  18 val input_char: in_channel -> char
  19         (* Uncompress one character from the given channel, and return it.
  20            Raise [End_of_file] if no more compressed data is available. *)
  21 val input_byte: in_channel -> int
  22         (* Same as [Bzip2.input_char], but return the 8-bit integer representing
  23            the character.
  24            Raise [End_of_file] if no more compressed data is available. *)
  25 val input: in_channel -> string -> int -> int -> int
  26         (* [input ic buf pos len] uncompresses up to [len] characters
  27            from the given channel [ic],
  28            storing them in string [buf], starting at character number [pos].
  29            It returns the actual number of characters read, between 0 and
  30            [len] (inclusive).
  31            A return value of 0 means that the end of file was reached.
  32            A return value between 0 and [len] exclusive means that
  33            not all requested [len] characters were read, either because
  34            no more characters were available at that time, or because
  35            the implementation found it convenient to do a partial read;
  36            [input] must be called again to read the remaining characters,
  37            if desired.  (See also [Bzip2.really_input] for reading
  38            exactly [len] characters.)
  39            Exception [Invalid_argument "Bzip2.input"] is raised if
  40            [pos] and [len] do not designate a valid substring of [buf]. *)
  41 val really_input: in_channel -> string -> int -> int -> unit
  42         (* [really_input ic buf pos len] uncompresses [len] characters
  43            from the given channel, storing them in
  44            string [buf], starting at character number [pos].
  45            Raise [End_of_file] if fewer than [len] characters can be read.
  46            Raise [Invalid_argument "Bzip2.input"] if
  47            [pos] and [len] do not designate a valid substring of [buf]. *)
  48 val close_in: in_channel -> unit
  49         (* Close the given input channel.  If the channel was created with
  50            [Bzip2.open_in_chan], the underlying regular file channel
  51            (of type [Pervasives.in_channel]) is also closed.
  52            Do not apply any of the functions above to a closed channel. *)
  53 val dispose: in_channel -> unit
  54         (* Same as [Bzip2.close_in], but does not close the underlying
  55            regular file channel (of type [Pervasives.in_channel]);
  56            just dispose of the resources associated with the decompression
  57            channel.  This can be useful if e.g. the underlying file channel
  58            is a network socket on which more (uncompressed) data
  59            is expected. *)
  60
  61 (*** Writing to compressed files *)
  62
  63 type out_channel
  64         (* Abstract type representing a channel opened for writing
  65            to a compressed file. *)
  66 val open_out: ?level:int -> string -> out_channel
  67         (* Open a compressed file for writing.  The argument is the file
  68            name.  The file is created if it does not exist, or
  69            truncated to zero length if it exists.
  70            The optional [level] argument (an integer between 1 and 9)
  71            indicates the compression level, with 1 being the weakest
  72            (but fastest) compression and 9 being the strongest
  73            (but slowest) compression.  The default level is 6
  74            (medium compression). *)
  75 val open_out_chan: ?level:int -> Pervasives.out_channel -> out_channel
  76         (* Open a compressed file for writing.  The argument is a
  77            regular file channel already opened on the compressed file.
  78            The optional [level] argument sets the compression level
  79            as documented for [Bzip2.open_out]. *)
  80 val output_char: out_channel -> char -> unit
  81         (* Output one character to the given compressed channel. *)
  82 val output_byte: out_channel -> int -> unit
  83         (* Same as [Bzip2.output_char], but the output character is given
  84            by its code.  The given integer is taken modulo 256. *)
  85 val output: out_channel -> string -> int -> int -> unit
  86         (* [output oc buf pos len] compresses and writes [len] characters
  87            from string [buf], starting at offset [pos], and writes the
  88            compressed data to the channel [oc].
  89            Raise [Invalid_argument "Bzip2.output"] if
  90            [pos] and [len] do not designate a valid substring of [buf]. *)
  91 val close_out: out_channel -> unit
  92         (* Close the given output channel.  If the channel was created with
  93            [Bzip2.open_out_chan], the underlying regular file channel
  94            (of type [Pervasives.out_channel]) is also closed.
  95            Do not apply any of the functions above to a closed channel. *)
  96 val flush: out_channel -> unit
  97         (* Same as [Bzip2.close_out], but do not close the underlying
  98            regular file channel (of type [Pervasives.out_channel]);
  99            just flush all pending compressed data and
 100            dispose of the resources associated with the compression
 101            channel.  This can be useful if e.g. the underlying file channel
 102            is a network socket on which more data is to be sent. *)
 103
 104 (*** Error reporting *)
 105
 106 exception Error of string
 107         (* Exception raised by the functions above to signal errors during
 108            compression or decompression, or ill-formed input files. *)