More complete handling of constant field length expressions.

[ocaml-bitstring.git] / bitmatch.mli

diff --git a/bitmatch.mli b/bitmatch.mli
index f1c7ed1..90f6acc 100644 (file)
--- a/bitmatch.mli
+++ b/bitmatch.mli
@@ -15,7 +15,7 @@
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  *
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  *

- * $Id: bitmatch.mli,v 1.16 2008-04-25 12:55:39 rjones Exp $
+ * $Id: bitmatch.mli,v 1.20 2008-05-08 21:28:28 rjones Exp $

  *)
 
 (**
  *)
 
 (**


@@ -29,7 +29,7 @@
    this module to both parse and generate binary formats, for
    example, communications protocols, disk formats and binary files.
 
    this module to both parse and generate binary formats, for
    example, communications protocols, disk formats and binary files.
 

-   {{:http://et.redhat.com/~rjones/bitmatch/}OCaml bitmatch website}
+   {{:http://code.google.com/p/bitmatch/}OCaml bitmatch website}

 
    {2 Examples}
 
 
    {2 Examples}
 


@@ -186,7 +186,7 @@ let make_message typ subtype param =
    match then the standard library [Match_failure] exception is
    thrown.
 
    match then the standard library [Match_failure] exception is
    thrown.
 

-   Patterns look a bit different from normal match patterns.  The
+   Patterns look a bit different from normal match patterns.  They

    consist of a list of bitfields separated by [;] where each bitfield
    contains a bind variable, the width (in bits) of the field, and
    other information.  Some example patterns:
    consist of a list of bitfields separated by [;] where each bitfield
    contains a bind variable, the width (in bits) of the field, and
    other information.  Some example patterns:


@@ -381,9 +381,8 @@ Bitmatch.hexdump_bitstring stdout bits ;;
    computed expression.
 
    Detection of compile-time constants is quite simplistic so only an
    computed expression.
 
    Detection of compile-time constants is quite simplistic so only an

-   immediate, simple integer is recognised as a constant and anything
-   else is considered a computed expression, even expressions such as
-   [5-2] which are obviously (to our eyes) constant.
+   simple integer literals and simple expressions (eg. [5*8]) are
+   recognized as constants.

 
    In any case the bit size of an integer is limited to the range
    \[1..64\].  This is detected as a compile-time error if that is
 
    In any case the bit size of an integer is limited to the range
    \[1..64\].  This is detected as a compile-time error if that is


@@ -533,13 +532,15 @@ type bitstring = string * int * int
     The type contains the underlying data (a string),
     the current bit offset within the string and the
     current bit length of the string (counting from the
     The type contains the underlying data (a string),
     the current bit offset within the string and the
     current bit length of the string (counting from the

-    bit offset).  Note that the offsets are bits, not bytes.
+    bit offset).  Note that the offset and length are
+    in {b bits}, not bytes.

 
     Normally you don't need to use the bitstring type
     directly, since there are functions and syntax
     extensions which hide the details.
 
     Normally you don't need to use the bitstring type
     directly, since there are functions and syntax
     extensions which hide the details.

-    See {!bitstring_of_file}, {!hexdump_bitstring},
-    {!bitstring_length}.
+
+    See also {!bitstring_of_string}, {!bitstring_of_file},
+    {!hexdump_bitstring}, {!bitstring_length}.

 *)
 
 (** {3 Exceptions} *)
 *)
 
 (** {3 Exceptions} *)


@@ -576,22 +577,46 @@ val make_bitstring : int -> char -> bitstring
 
     Note that the length is in bits, not bytes. *)
 
 
     Note that the length is in bits, not bytes. *)
 

+val bitstring_of_string : string -> bitstring
+(** [bitstring_of_string str] creates a bitstring
+    of length [String.length str * 8] (bits) containing the
+    bits in [str].
+
+    Note that the bitstring uses [str] as the underlying
+    string (see the representation of {!bitstring}) so you
+    should not change [str] after calling this. *)
+
+val bitstring_of_file : string -> bitstring
+(** [bitstring_of_file filename] loads the named file
+    into a bitstring. *)
+

 val bitstring_of_chan : in_channel -> bitstring
 (** [bitstring_of_chan chan] loads the contents of
     the input channel [chan] as a bitstring.
 
     The length of the final bitstring is determined
     by the remaining input in [chan], but will always
 val bitstring_of_chan : in_channel -> bitstring
 (** [bitstring_of_chan chan] loads the contents of
     the input channel [chan] as a bitstring.
 
     The length of the final bitstring is determined
     by the remaining input in [chan], but will always

-    be a multiple of 8 bits. *)
+    be a multiple of 8 bits.

 
 

-val bitstring_of_file : string -> bitstring
-(** [bitstring_of_file filename] loads the named file
-    into a bitstring. *)
+    See also {!bitstring_of_chan_max}. *)

 
 

-val hexdump_bitstring : out_channel -> bitstring -> unit
-(** [hexdump_bitstring chan bitstring] prints the bitstring
-    to the output channel in a format similar to the
-    Unix command [hexdump -C]. *)
+val bitstring_of_chan_max : in_channel -> int -> bitstring
+(** [bitstring_of_chan_max chan max] works like
+    {!bitstring_of_chan} but will only read up to
+    [max] bytes from the channel (or fewer if the end of input
+    occurs before that). *)
+
+val bitstring_of_file_descr : Unix.file_descr -> bitstring
+(** [bitstring_of_file_descr fd] loads the contents of
+    the file descriptor [fd] as a bitstring.
+
+    See also {!bitstring_of_chan}, {!bitstring_of_file_descr_max}. *)
+
+val bitstring_of_file_descr_max : Unix.file_descr -> int -> bitstring
+(** [bitstring_of_file_descr_max fd max] works like
+    {!bitstring_of_file_descr} but will only read up to
+    [max] bytes from the channel (or fewer if the end of input
+    occurs before that). *)

 
 val bitstring_length : bitstring -> int
 (** [bitstring_length bitstring] returns the length of
 
 val bitstring_length : bitstring -> int
 (** [bitstring_length bitstring] returns the length of


@@ -606,6 +631,13 @@ val string_of_bitstring : bitstring -> string
     bitstring isn't aligned then this involves a lot of bit twiddling
     and is particularly inefficient. *)
 
     bitstring isn't aligned then this involves a lot of bit twiddling
     and is particularly inefficient. *)
 

+(** {3 Printing bitstrings} *)
+
+val hexdump_bitstring : out_channel -> bitstring -> unit
+(** [hexdump_bitstring chan bitstring] prints the bitstring
+    to the output channel in a format similar to the
+    Unix command [hexdump -C]. *)
+

 (** {3 Bitstring buffer} *)
 
 module Buffer : sig
 (** {3 Bitstring buffer} *)
 
 module Buffer : sig


@@ -652,10 +684,16 @@ val extract_int32_le_unsigned : string -> int -> int -> int -> int32 * int * int
 
 val extract_int64_be_unsigned : string -> int -> int -> int -> int64 * int * int
 
 
 val extract_int64_be_unsigned : string -> int -> int -> int -> int64 * int * int
 

-val construct_bit : Buffer.t -> bool -> int -> unit
+val extract_int64_le_unsigned : string -> int -> int -> int -> int64 * int * int
+
+val construct_bit : Buffer.t -> bool -> int -> exn -> unit

 
 val construct_char_unsigned : Buffer.t -> int -> int -> exn -> unit
 
 val construct_int_be_unsigned : Buffer.t -> int -> int -> exn -> unit
 
 
 val construct_char_unsigned : Buffer.t -> int -> int -> exn -> unit
 
 val construct_int_be_unsigned : Buffer.t -> int -> int -> exn -> unit
 

+val construct_int32_be_unsigned : Buffer.t -> int32 -> int -> exn -> unit
+

 val construct_int64_be_unsigned : Buffer.t -> int64 -> int -> exn -> unit
 val construct_int64_be_unsigned : Buffer.t -> int64 -> int -> exn -> unit

+
+val construct_string : Buffer.t -> string -> unit