* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
- * version 2 of the License, or (at your option) any later version.
+ * version 2 of the License, or (at your option) any later version,
+ * with the OCaml linking exception described in COPYING.LIB.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
str strlen
v}
+ or:
+
+{v
+(* Load a persistent pattern from a file. *)
+open bitmatch "pascal.bmpp"
+
+let is_pascal_string bits =
+ bitmatch bits with
+ | \{ :pascal_string } ->
+ printf "matches a Pascal string %s, len %d bytes\n"
+ str strlen
+v}
+
{3 Important notes}
There are some important things you should know about
link to camlp4. Since camlp4 in OCaml >= 3.10 is rather large, we
have placed this code into this separate submodule, so that
programs which just use bitmatch don't need to pull in the whole of
- camlp4. This restriction does not apply to generated code which
- only uses persistent patterns. If the distinction isn't clear,
- use [ocamlobjinfo] to look at the dependencies of your [*.cmo]
- files.
+ camlp4. This restriction does not apply to code which only uses
+ persistent patterns but does not generate them. If the distinction
+ isn't clear, use [ocamlobjinfo] to look at the dependencies of your
+ [*.cmo] files.
Persistent patterns can be generated in several ways, but they
can only be {i used} by the [pa_bitmatch] syntax extension.
[bitmatch bits with { :name } -> ...]
- You can use named patterns within named patterns.
+ You can nest named patterns within named patterns to any depth.
Currently the use of named patterns is somewhat limited.
The restrictions are:
the file that your tool reads for input. By convention,
locations are bound to name [_loc]:
-{v
+ {v
let _loc = Loc.move_line 42 (Loc.mk "input.xml")
-v}
+ v}
Create a pattern field representing a length field which is 8 bits wide,
bound to the identifier [len]:
-{v
+ {v
let len_field = create_pattern_field _loc
let len_field = set_length_int len_field 8
let len_field = set_lident_patt len_field "len"
-v}
+ v}
Create a pattern field representing a string of [len*8] bits.
Note that the use of [<:expr< >>] quotation requires
(see {{:http://brion.inria.fr/gallium/index.php/Reflective_OCaml}this
page on Reflective OCaml}).
-{v
+ {v
let str_field = create_pattern_field _loc
let str_field = set_length str_field <:expr< len*8 >>
let str_field = set_lident_patt str_field "str"
let str_field = set_type_string str_field
-v}
+ v}
Join the two fields together and name it:
-{v
- let named_pattern = "pascal_string", Pattern [len_field; str_field]
-v}
+ {v
+ let pattern = [len_field; str_field]
+ let named_pattern = "pascal_string", Pattern pattern
+ v}
Save it to a file:
-{v
+ {v
let chan = open_out "output.bmpp" in
named_to_channel chan named_pattern;
close_out chan
-v}
+ v}
You can now use this pattern in another program like this:
-{v
+ {v
open bitmatch "output.bmpp" ;;
let parse_pascal_string bits =
- bitmatch bits with
- | \{ :pascal_string } -> str, len
- | \{ _ } -> invalid_arg "not a Pascal string"
-v}
+ bitmatch bits with
+ | \{ :pascal_string } -> str, len
+ | \{ _ } -> invalid_arg "not a Pascal string"
+ v}
You can write more than one named pattern to the output file, and
they will all be loaded at the same time by [open bitmatch ".."]
val string_of_pattern : pattern -> string
val string_of_constructor : constructor -> string
-val string_of_field : 'a field -> string
+val string_of_pattern_field : patt field -> string
+val string_of_constructor_field : expr field -> string
(** Convert patterns, constructors or individual fields
into printable strings for debugging purposes.
The pattern is unbound, the type is set to [int], bit length to [32],
endianness to [BigEndian], signedness to unsigned ([false]),
- and source code location to the [_loc] parameter.
+ source code location to the [_loc] parameter, and no offset expression.
To create a complete field you need to call the [set_*]
functions. For example, to create [{ len : 8 : int }]
(** Sets the source code location of a field. This is used when
pa_bitmatch displays error messages. *)
+val set_offset_int : 'a field -> int -> 'a field
+(** Set the offset expression for a field to the given number.
+
+ The effect is that the field [{ _ : 8 : offset(160) }] could
+ be created by calling [set_offset_int field 160]. *)
+
+val set_offset : 'a field -> expr -> 'a field
+(** Set the offset expression for a field to the given expression.
+
+ The effect is that the field [{ _ : 8 : offset(160) }] could
+ be created by calling [set_offset_int field <:expr< 160 >>]. *)
+
+val set_no_offset : 'a field -> 'a field
+(** Remove the offset expression from a field. The field will
+ follow the previous field, or if it is the first field will
+ be at offset zero. *)
+
+val set_check : 'a field -> expr -> 'a field
+(** Set the check expression for a field to the given expression. *)
+
+val set_no_check : 'a field -> 'a field
+(** Remove the check expression from a field. *)
+
+val set_bind : 'a field -> expr -> 'a field
+(** Set the bind-expression for a field to the given expression. *)
+
+val set_no_bind : 'a field -> 'a field
+(** Remove the bind-expression from a field. *)
+
+val set_save_offset_to : 'a field -> patt -> 'a field
+(** Set the save_offset_to pattern for a field to the given pattern. *)
+
+val set_save_offset_to_lident : 'a field -> string -> 'a field
+(** Set the save_offset_to pattern for a field to identifier. *)
+
+val set_no_save_offset_to : 'a field -> 'a field
+(** Remove the save_offset_to from a field. *)
+
(** {3 Create constructor fields}
These fields are used in constructors ([BITSTRING]). *)
val get_location : 'a field -> loc_t
(** Get the source code location of a field. *)
+
+val get_offset : 'a field -> expr option
+(** Get the offset expression of a field, or [None] if there is none. *)
+
+val get_check : 'a field -> expr option
+(** Get the check expression of a field, or [None] if there is none. *)
+
+val get_bind : 'a field -> expr option
+(** Get the bind expression of a field, or [None] if there is none. *)
+
+val get_save_offset_to : 'a field -> patt option
+(** Get the save_offset_to pattern of a field, or [None] if there is none. *)
git.annexia.org / ocaml-bitstring.git / blobdiff