Merge pull request #82 from avsm/1.9.0

release 1.9.0

CHANGES

@@ -1,3 +1,8 @@
+1.9.0 (2016-02-19):
+* Add support for a ppx-based extension that uses the extension point
+  support in OCaml 4.02 and higher to generate Cstruct and Cenum
+  function definitions.  The new syntax is documented in the README file.
+
 1.8.0 (2016-01-05):
 * Add support for `-safe-string` in OCaml 4.02 upwards.
   The main change is to rename `blit_to_string` to `blit_to_bytes` and

README.md

@@ -2,7 +2,177 @@ Cstruct is a library and syntax extension to make it easier to access C-like
 structures directly from OCaml.  It supports both reading and writing to these
 structures, and they are accessed via the `Bigarray` module.
 
-An example pcap description is:
+There are two supported syntax extensions: the
+[ppx](http://whitequark.org/blog/2014/04/16/a-guide-to-extension-points-in-ocaml/)
+extension point supported from OCaml 4.02.0 onwards, and the older
+[camlp4](http://caml.inria.fr/pub/docs/manual-camlp4/manual002.html) extension.
+
+## PPX
+
+The PPX processor is used by passing the OCaml source code through the
+`ppx_cstruct` binary. An example pcap description is:
+
+```
+[%%cstruct
+type pcap_header = {
+  magic_number: uint32_t;   (* magic number *)
+  version_major: uint16_t;  (* major version number *)
+  version_minor: uint16_t;  (* minor version number *)
+  thiszone: uint32_t;       (* GMT to local correction *)
+  sigfigs: uint32_t;        (* accuracy of timestamps *)
+  snaplen: uint32_t;        (* max length of captured packets, in octets *)
+  network: uint32_t;        (* data link type *)
+} [@@little_endian]]
+
+[%%cstruct
+type pcap_packet = {
+  ts_sec: uint32_t;         (* timestamp seconds *)
+  ts_usec: uint32_t;        (* timestamp microseconds *)
+  incl_len: uint32_t;       (* number of octets of packet saved in file *)
+  orig_len: uint32_t;       (* actual length of packet *)
+} [@@little_endian]]
+
+[%%cstruct
+type ethernet = {
+  dst: uint8_t [@len 6];
+  src: uint8_t [@len 6];
+  ethertype: uint16_t;
+} [@@big_endian]]
+
+[%%cstruct
+type ipv4 = {
+  hlen_version: uint8_t;
+  tos: uint8_t;
+  len: uint16_t;
+  id: uint16_t;
+  off: uint16_t;
+  ttl: uint8_t;
+  proto: uint8_t;
+  csum: uint16_t;
+  src: uint8_t [@len 4];
+  dst: uint8_t [@len 4];
+} [@@big_endian]]
+```
+
+This auto-generates generates functions of the form below in the `ml` file:
+
+```
+let sizeof_pcap_packet = 16
+let get_pcap_packet_ts_sec v = Cstruct.LE.get_uint32 v 0
+let set_pcap_packet_ts_sec v x = Cstruct.LE.set_uint32 v 0 x
+let get_pcap_packet_ts_usec v = Cstruct.LE.get_uint32 v 4
+let set_pcap_packet_ts_usec v x = Cstruct.LE.set_uint32 v 4 x
+let get_pcap_packet_incl_len v = Cstruct.LE.get_uint32 v 8
+let set_pcap_packet_incl_len v x = Cstruct.LE.set_uint32 v 8 x
+let get_pcap_packet_orig_len v = Cstruct.LE.get_uint32 v 12
+let set_pcap_packet_orig_len v x = Cstruct.LE.set_uint32 v 12 x
+
+let sizeof_ethernet = 14
+let get_ethernet_dst src = Cstruct.sub src 0 6
+let copy_ethernet_dst src = Cstruct.copy src 0 6
+let set_ethernet_dst src srcoff dst =
+  Cstruct.blit_from_string src srcoff dst 0 6
+let blit_ethernet_dst src srcoff dst = Cstruct.blit src srcoff dst 0 6
+let get_ethernet_src src = Cstruct.sub src 6 6
+let copy_ethernet_src src = Cstruct.copy src 6 6
+let set_ethernet_src src srcoff dst =
+  Cstruct.blit_from_string src srcoff dst 6 6
+let blit_ethernet_src src srcoff dst = Cstruct.blit src srcoff dst 6 6
+let get_ethernet_ethertype v = Cstruct.BE.get_uint16 v 12
+let set_ethernet_ethertype v x = Cstruct.BE.set_uint16 v 12 x
+```
+
+The `mli` file will have signatures of this form:
+
+```
+val sizeof_pcap_packet : int
+val get_pcap_packet_ts_sec : Cstruct.t -> Cstruct.uint32
+val set_pcap_packet_ts_sec : Cstruct.t -> Cstruct.uint32 -> unit
+val get_pcap_packet_ts_usec : Cstruct.t -> Cstruct.uint32
+val set_pcap_packet_ts_usec : Cstruct.t -> Cstruct.uint32 -> unit
+val get_pcap_packet_incl_len : Cstruct.t -> Cstruct.uint32
+val set_pcap_packet_incl_len : Cstruct.t -> Cstruct.uint32 -> unit
+val get_pcap_packet_orig_len : Cstruct.t -> Cstruct.uint32
+val set_pcap_packet_orig_len : Cstruct.t -> Cstruct.uint32 -> unit
+val hexdump_pcap_packet_to_buffer : Buffer.t -> pcap_packet -> unit
+val hexdump_pcap_packet : Cstruct.t -> unit
+
+val sizeof_ethernet : int
+val get_ethernet_dst : Cstruct.t -> Cstruct.t
+val copy_ethernet_dst : Cstruct.t -> string
+val set_ethernet_dst : string -> int -> Cstruct.t -> unit
+val blit_ethernet_dst : Cstruct.t -> int -> Cstruct.t -> unit
+val get_ethernet_src : Cstruct.t -> Cstruct.t
+val copy_ethernet_src : Cstruct.t -> string
+val set_ethernet_src : string -> int -> Cstruct.t -> unit
+val blit_ethernet_src : Cstruct.t -> int -> Cstruct.t -> unit
+val get_ethernet_ethertype : Cstruct.t -> Cstruct.uint16
+val set_ethernet_ethertype : Cstruct.t -> Cstruct.uint16 -> unit
+val hexdump_ethernet_to_buffer : Buffer.t -> Cstruct.t -> unit
+val hexdump_ethernet : Cstruct.t -> unit
+```
+
+The `hexdump` functions above are convenient pretty-printing functions
+to help you debug, and aren't intended to be high performance.
+
+You can also declare C-like enums:
+
+```
+[%%cenum
+type foo32 =
+  | ONE32
+  | TWO32 [@id 0xfffffffel]
+  | THREE32
+  [@@uint32_t]
+]
+
+[%%cenum
+type bar16 =
+  | ONE [@id 1]
+  | TWO
+  | FOUR [@id 4]
+  | FIVE
+  [@@uint16_t]
+]
+```
+
+This generates signatures of the form:
+
+```
+type foo32 = | ONE32 | TWO32 | THREE32
+val int_to_foo32 : int32 -> foo32 option
+val foo32_to_int : foo32 -> int32
+val foo32_to_string : foo32 -> string
+val string_to_foo32 : string -> foo32 option
+type bar16 = | ONE | TWO | FOUR | FIVE
+val int_to_bar16 : int -> bar16 option
+val bar16_to_int : bar16 -> int
+val bar16_to_string : bar16 -> string
+val string_to_bar16 : string -> bar16 option
+```
+
+You can also add a `(sexp)` decorator to output s-expression convertors
+for use with the `sexplib` library.
+
+```
+[%%cenum
+type foo64 =
+  | ONE64
+  | TWO64
+  | THREE64
+  [@@uint64_t] [@@sexp]
+]
+```
+
+And `sexp_of_foo64` and `foo64_of_sexp` functions will also be available.
+The representation of the Sexp is the string representation of the enum.
+
+Please see the `ppx_test/` directory for more in-depth examples.
+
+## Camlp4
+
+The Camlp4 subpackage is activated by using the `cstruct.syntax` ocamlfind
+package.  An example pcap description is:
 
 ```
 cstruct pcap_header {
@@ -139,17 +309,16 @@ You can also add a `(sexp)` decorator to output s-expression convertors
 for use with the `sexplib` library.
 
 ```
-cenum foo32 {
-  ONE32;
-  TWO32 = 0xfffffffel;
-  THREE32
-} as uint32_t(sexp)
+cenum foo64 {
+  ONE64;
+  TWO64;
+  THREE64
+} as uint64_t(sexp)
 ```
 
 And `sexp_of_foo64` and `foo64_of_sexp` functions will also be available.
 The representation of the Sexp is the string representation of the enum.
 
-
 Please see the `lib_test/` directory for more in-depth examples.
 
 [![Build Status](https://travis-ci.org/mirage/ocaml-cstruct.png)](https://travis-ci.org/mirage/ocaml-cstruct)

_oasis

@@ -1,9 +1,9 @@
 OASISFormat: 0.4
 Name:        cstruct
-Version:     1.8.0
+Version:     1.9.0
 Synopsis:    Manipulate external buffers as C-like structs
 Authors:     Anil Madhavapeddy, Richard Mortier, Thomas Gazagnaire,
-             Pierre Chambart, David Kaloper, Jeremy Yallop
+             Pierre Chambart, David Kaloper, Jeremy Yallop, Hannes Mehnert
 License:     ISC
 Plugins:     META (0.4), DevFiles (0.4)
 BuildTools:  ocamlbuild

lib/META

@@ -1,6 +1,6 @@
 # OASIS_START
-# DO NOT EDIT (digest: b53f8084a9572ea1d8ecfadd7abd7e30)
-version = "1.8.0"
+# DO NOT EDIT (digest: 71456649c67b9fc0992b1c035c9112de)
+version = "1.9.0"
 description = "Manipulate external buffers as C-like structs"
 requires = "bytes bigarray ocplib-endian ocplib-endian.bigstring sexplib"
 archive(byte) = "cstruct.cma"
@@ -9,7 +9,7 @@ archive(native) = "cstruct.cmxa"
 archive(native, plugin) = "cstruct.cmxs"
 exists_if = "cstruct.cma"
 package "unix" (
- version = "1.8.0"
+ version = "1.9.0"
  description = "Manipulate external buffers as C-like structs"
  requires = "cstruct unix"
  archive(byte) = "unix_cstruct.cma"
@@ -20,7 +20,7 @@ package "unix" (
 )
 
 package "syntax" (
- version = "1.8.0"
+ version = "1.9.0"
  description = "Syntax extension for Cstruct"
  requires = "camlp4"
  archive(syntax, preprocessor) = "cstruct-syntax.cma"
@@ -31,7 +31,7 @@ package "syntax" (
 )
 
 package "lwt" (
- version = "1.8.0"
+ version = "1.9.0"
  description = "Manipulate external buffers as C-like structs"
  requires = "cstruct lwt.unix"
  archive(byte) = "lwt_cstruct.cma"
@@ -42,7 +42,7 @@ package "lwt" (
 )
 
 package "async" (
- version = "1.8.0"
+ version = "1.9.0"
  description = "Manipulate external buffers as C-like structs"
  requires = "cstruct async threads"
  archive(byte) = "async_cstruct.cma"

ppx/ppx_cstruct.ml

@@ -252,7 +252,7 @@ let output_hexdump _loc s =
                 [%expr Printf.bprintf _buf "0x%Lx\n" ([%e Ast.evar (getter_name s f)] v)]
               |Buffer (_,_) ->
                 [%expr Printf.bprintf _buf "<buffer %s>"
-                         [%e Ast.str (field_to_string f)]
+                         [%e Ast.str (field_to_string f)];
                          Cstruct.hexdump_to_buffer _buf ([%e Ast.evar (getter_name s f)] v)]
           ]]
       ) (Ast.unit ()) s.fields
@@ -320,7 +320,7 @@ let output_enum _loc name fields width ~sexp =
   let printers = List.map (fun ({txt = f},_) ->
       {pc_lhs = Ast.pconstr f []; pc_guard = None; pc_rhs = Ast.str f}) fields in
   let parsers = List.map (fun ({txt = f},_) ->
-      {pc_lhs = Ast.pstr f; pc_guard = None; pc_rhs = Ast.constr f []}) fields in
+      {pc_lhs = Ast.pstr f; pc_guard = None; pc_rhs = Ast.constr "Some" [Ast.constr f []]}) fields in
   let getter {txt = x} = sprintf "int_to_%s" x in
   let setter {txt = x} = sprintf "%s_to_int" x in
   let printer {txt = x} = sprintf "%s_to_string" x in
@@ -407,14 +407,20 @@ let constr_enum = function
   | {pcd_loc = loc} ->
     loc_err loc "invalid cenum variant"
 
-let constr_field {pld_name = fname; pld_type = fty; pld_loc = loc} =
-  let sz = match fty.ptyp_attributes with
+let constr_field {pld_name = fname; pld_type = fty; pld_loc = loc; pld_attributes = att} =
+  let get = function
     | [{txt = "len"}, PStr
          [{pstr_desc = Pstr_eval ({pexp_desc = Pexp_constant (Const_int sz)}, _)}]] ->
       Some sz
     | _ ->
       None
   in
+  let sz = match get fty.ptyp_attributes, get att with
+  | Some sz, None
+  | None, Some sz -> Some sz
+  | Some _, Some _ -> loc_err loc "multiple field length attribute"
+  | None, None -> None
+  in
   let fty = match fty.ptyp_desc with
     | Ptyp_constr ({txt = Lident fty}, []) -> fty
     | _ ->