Merge pull request #62 from rottened23/master

First take at an example of how to use the library

README.adoc

@@ -548,10 +548,13 @@ about speed.
 
 I Need to See an Example
 ------------------------
-I should really put together some trivial example code.  But in the meantime,
-the https://github.com/pelzlpj/capnp-ocaml/tree/master/src/tests[tests]
-and https://github.com/pelzlpj/capnp-ocaml/tree/master/src/benchmark[benchmark]
-subdirectories may be helpful to look at.
+There are some simple examples in the https://github.com/capnproto/capnp-ocaml/tree/master/src/examples[examples] directory.
+
+The https://github.com/capnproto/capnp-ocaml/tree/master/src/tests[tests]
+and https://github.com/capnproto/capnp-ocaml/tree/master/src/benchmark[benchmark]
+subdirectories may also be helpful to look at.
+
+The https://github.com/mirage/capnp-rpc/blob/master/README.md[RPC tutorial] also contains many examples.
 
 
 Installation

src/examples/1/dune

@@ -0,0 +1,13 @@
+(executable
+  (name example1)
+  (libraries capnp)
+  ; We want to disable warnings 53 to 55 (see: http://caml.inria.fr/pub/docs/manual-ocaml/toplevel.html)
+  ; We disable warning 55 as this relates to inlining certain functions. For inlining please see the README.md 
+  ; and the benchmarks for examples.
+  (flags :standard -w -53-55))
+
+; This rule tells dune how to generate foo.ml and foo.mli by compiling foo.capnp against the CAP'N PROTO compiler
+; PLEASE NOTE that capnpc must exist on your computer for this to work (https://capnproto.org/install.html)
+(rule 
+  (targets foo.ml foo.mli)
+  (action (run capnp compile -o %{bin:capnpc-ocaml} %{dep:foo.capnp})))

src/examples/1/example1.ml

@@ -0,0 +1,30 @@
+(* Instantiate a module for the Foo type *)
+module Foo = Foo.Make(Capnp.BytesMessage)
+
+
+(* This is a very simple example where we create a message - encode it then decode it *)
+
+let encode n =
+  let open Foo in
+  (* Constructing the message. First we instantiate and initialize the Foo builder giving us a handle on a read/write object. *)
+  let rw = Builder.Foo.init_root () in
+  (* Using the readwrite handle we set [num] to the provided value *)
+  Builder.Foo.num_set rw n;
+  let message = Builder.Foo.to_message rw in
+  (* Then encode it into a message constructing a string with the contents *)
+  Capnp.Codecs.serialize ~compression:`None message
+
+let decode_exn s =
+  let open Foo in
+  (* Get a stream of the bytes to deserialize *)
+  let stream = Capnp.Codecs.FramedStream.of_string ~compression:`None s in
+  (* Attempt to get the next frame from the stream in the form of a Message *)
+  let res = Capnp.Codecs.FramedStream.get_next_frame stream in 
+  match res with
+  | Result.Ok message -> Reader.Foo.of_message message
+  | Result.Error _ -> failwith "Could not extract frame"
+
+let () = 
+  let open Foo in
+  let f = encode 3l in
+  Printf.printf "Read: %ld\n" (Reader.Foo.num_get (decode_exn f))

src/examples/1/foo.capnp

@@ -0,0 +1,7 @@
+@0xa6cd9abc91c34775;
+
+# compilation specified in dune file
+
+struct Foo {
+    num @0 :Int32;
+}

src/examples/2/dune

@@ -0,0 +1,8 @@
+(executable
+  (name example2)
+  (libraries capnp)
+  (flags :standard -w -53-55))
+
+(rule
+  (targets shape.ml shape.mli)
+  (action (run capnp compile -o %{bin:capnpc-ocaml} %{dep:shape.capnp})))

src/examples/2/example2.ml

@@ -0,0 +1,53 @@
+module Shape = Shape.Make(Capnp.BytesMessage)
+
+let rect_str =
+  let open Shape in
+  let rw = Builder.Shape.init_root() in
+  Builder.Shape.colour_set rw Builder.Shape.Colour.Blue;
+  let rect = Builder.Shape.rectangle_init rw in 
+  Builder.Shape.Rectangle.width_set rect 10.0;
+  Builder.Shape.Rectangle.height_set rect 15.0;
+  let message = Builder.Shape.to_message rw in 
+  Capnp.Codecs.serialize ~compression:`None message
+
+let circle_str =
+  let open Shape in
+  let rw = Builder.Shape.init_root() in
+  Builder.Shape.colour_set rw Builder.Shape.Colour.Green;
+  let circle = Builder.Shape.circle_init rw in 
+  Builder.Shape.Circle.radius_set circle 3.0;
+  let message = Builder.Shape.to_message rw in 
+  Capnp.Codecs.serialize ~compression:`None message
+
+
+let colour_to_string c =
+  let open Shape.Reader.Shape.Colour in
+  match c with
+  | Red -> "Red"
+  | Green -> "Green"
+  | Blue -> "Blue"
+  | _ -> failwith "Colour not handled"
+
+let decode_exn shape_str = 
+  let open Shape in
+  let stream = Capnp.Codecs.FramedStream.of_string ~compression:`None shape_str in 
+  let res = Capnp.Codecs.FramedStream.get_next_frame stream in 
+  let shape = match res with 
+    | Result.Ok message -> Reader.Shape.of_message message 
+    | Result.Error _ -> failwith "Could not read string"
+  in
+  match Reader.Shape.get shape with 
+  | Reader.Shape.Circle c -> 
+    Printf.printf "%s circle with a radius of %f\n"
+      (colour_to_string (Reader.Shape.colour_get shape))
+      (Reader.Shape.Circle.radius_get c)
+  | Reader.Shape.Rectangle r -> 
+    Printf.printf "%s rectangle with a width of %f and a height of %f\n"
+      (colour_to_string (Reader.Shape.colour_get shape))
+      (Reader.Shape.Rectangle.width_get r)
+      (Reader.Shape.Rectangle.height_get r)
+  | Reader.Shape.Undefined _ -> failwith "Could not read type"
+
+let () =
+  decode_exn rect_str;
+  decode_exn circle_str

src/examples/2/shape.capnp

@@ -0,0 +1,25 @@
+@0xf5d779179e64a219;
+
+# A more complex type from https://capnproto.org/language.html
+
+# compile this with: capnpc -o ocaml shape.capnp
+
+struct Shape {
+  colour @0 :Colour;
+
+  enum Colour {
+    red @0;
+    green @1;
+    blue @2;
+  }
+
+  union {
+    circle :group {
+      radius @1 :Float64;
+    }
+    rectangle :group {
+      width @2 :Float64;
+      height @3 :Float64;
+    }
+  }
+}