-(** Bitmatch library. *)
+(** Bitstring library. *)
(* Copyright (C) 2008 Red Hat Inc., Richard W.M. Jones
*
* This library is free software; you can redistribute it and/or
{2 Introduction}
- Bitmatch adds Erlang-style bitstrings and matching over bitstrings
+ Bitstring adds Erlang-style bitstrings and matching over bitstrings
as a syntax extension and library for OCaml. You can use
this module to both parse and generate binary formats, for
example, communications protocols, disk formats and binary files.
- {{:http://code.google.com/p/bitmatch/}OCaml bitmatch website}
+ {{:http://code.google.com/p/bitstring/}OCaml bitstring website}
+
+ This library used to be called "bitmatch".
{2 Examples}
printf " checksum: %d\n" checksum;
printf " source: %lx dest: %lx\n" source dest;
printf " header options + padding:\n";
- Bitmatch.hexdump_bitstring stdout options;
+ Bitstring.hexdump_bitstring stdout options;
printf " packet payload:\n";
- Bitmatch.hexdump_bitstring stdout payload
+ Bitstring.hexdump_bitstring stdout payload
| { version : 4 } ->
eprintf "unknown IP version %d\n" version;
| { _ } as pkt ->
eprintf "data is smaller than one nibble:\n";
- Bitmatch.hexdump_bitstring stderr pkt;
+ Bitstring.hexdump_bitstring stderr pkt;
exit 1
]}
{{:http://lxr.linux.no/linux/include/linux/ext3_fs.h}Linux EXT3 filesystem superblocks}:
{[
-let bits = Bitmatch.bitstring_of_file "tests/ext3_sb"
+let bits = Bitstring.bitstring_of_file "tests/ext3_sb"
let () =
bitmatch bits with
{[
| { n : 4;
rest : -1 : bitstring }
- when Bitmatch.bitstring_length rest = 0 -> ...
+ when Bitstring.bitstring_length rest = 0 -> ...
(* Only matches exactly 4 bits. *)
]}
the integer 1, and the following 12 bits containing the integer 10,
arranged in network byte order. *)
-Bitmatch.hexdump_bitstring stdout bits ;;
+Bitstring.hexdump_bitstring stdout bits ;;
(* Prints:
{2 Named patterns and persistent patterns}
- Please see {!Bitmatch_persistent} for documentation on this subject.
+ Please see {!Bitstring_persistent} for documentation on this subject.
{2 Compiling}
Using the compiler directly you can do:
{v
- ocamlc -I +bitmatch \
- -pp "camlp4of bitmatch.cma bitmatch_persistent.cma \
- `ocamlc -where`/bitmatch/pa_bitmatch.cmo" \
- unix.cma bitmatch.cma test.ml -o test
+ ocamlc -I +bitstring \
+ -pp "camlp4of bitstring.cma bitstring_persistent.cma \
+ `ocamlc -where`/bitstring/pa_bitstring.cmo" \
+ unix.cma bitstring.cma test.ml -o test
v}
Simpler method using findlib:
{v
ocamlfind ocamlc \
- -package bitmatch,bitmatch.syntax -syntax bitmatch.syntax \
+ -package bitstring,bitstring.syntax -syntax bitstring.syntax \
-linkpkg test.ml -o test
v}
However the above does not necessarily apply to strings used in
matching, since they may cause the library to use the
- {!Bitmatch.string_of_bitstring} function, which allocates a string.
+ {!Bitstring.string_of_bitstring} function, which allocates a string.
So you should take care if you use the [string] type particularly
with a computed length that is derived from external input.
Note that the when-clause is evaluated {i last}, so if you are
relying on the when-clause to filter cases then your code may do a
lot of extra and unncessary pattern-matching work on fields which
- may never be needed just to evaluate the when-clause. You can
- usually rearrange the code to do only the first part of the match,
- followed by the when-clause, followed by a second inner bitmatch.
+ may never be needed just to evaluate the when-clause. Either
+ rearrange the code to do only the first part of the match,
+ followed by the when-clause, followed by a second inner bitmatch,
+ or use a [check()] qualifier within fields.
{3 Safety}
(** {3 Miscellaneous} *)
val package : string
-(** The package name, always ["ocaml-bitmatch"] *)
+(** The package name, always ["ocaml-bitstring"] *)
val version : string
(** The package version as a string. *)
val debug : bool ref
(** Set this variable to true to enable extended debugging.
This only works if debugging was also enabled in the
- [pa_bitmatch.ml] file at compile time, otherwise it
+ [pa_bitstring.ml] file at compile time, otherwise it
does nothing. *)
(**/**)
val construct_int_be_unsigned : Buffer.t -> int -> int -> exn -> unit
+val construct_int_le_unsigned : Buffer.t -> int -> int -> exn -> unit
+
val construct_int_ne_unsigned : Buffer.t -> int -> int -> exn -> unit
val construct_int_ee_unsigned : endian -> Buffer.t -> int -> int -> exn -> unit
val construct_int32_be_unsigned : Buffer.t -> int32 -> int -> exn -> unit
+val construct_int32_le_unsigned : Buffer.t -> int32 -> int -> exn -> unit
+
val construct_int32_ne_unsigned : Buffer.t -> int32 -> int -> exn -> unit
val construct_int32_ee_unsigned : endian -> Buffer.t -> int32 -> int -> exn -> unit
val construct_int64_be_unsigned : Buffer.t -> int64 -> int -> exn -> unit
+val construct_int64_le_unsigned : Buffer.t -> int64 -> int -> exn -> unit
+
val construct_int64_ne_unsigned : Buffer.t -> int64 -> int -> exn -> unit
val construct_int64_ee_unsigned : endian -> Buffer.t -> int64 -> int -> exn -> unit