Merge pull request #1 from skolemlabs/initial

.gitignore

@@ -0,0 +1,30 @@
+*.annot
+*.cmo
+*.cma
+*.cmi
+*.a
+*.o
+*.cmx
+*.cmxs
+*.cmxa
+
+# ocamlbuild working directory
+_build/
+
+# ocamlbuild targets
+*.byte
+*.native
+
+# oasis generated files
+setup.data
+setup.log
+
+# Merlin configuring file for Vim and Emacs
+.merlin
+
+# Dune generated files
+*.install
+
+# Local OPAM switch
+_opam/
+

.ocamlformat

@@ -0,0 +1 @@
+profile = default

CHANGES

@@ -0,0 +1,3 @@
+1.0.0
+========
+- #1: initial implementation

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Skolem Technologies US Corp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,44 @@
+# diff
+An OCaml library for generating diffs of product types.
+
+## Example
+```ocaml
+type t = { foo : int; bar : string; }
+[@@deriving diff]
+
+let spec = Diff.many [
+  Diff.leaf ~field:Foo ~equal:Int.equal;
+  Diff.leaf ~field:Bar ~equal:String.equal;
+]
+
+let () =
+  let t0 = { foo = 1; bar = "Skolem" } in
+  let t1 = { foo = 1; bar = "OCaml" } in
+  let diff = Diff.compute t0 t1 spec in
+  let t0' = Diff.apply_all t0 diff in
+  assert (t0' = t1)
+```
+
+## Usage
+
+The main use case of this library is to version records without having to keep a copy of each version around.
+
+The library includes a ppx for generating field accessors from records. To use the ppx with dune, add it to the `preprocessing` field of your stanza:
+```dune
+(library
+ (name mylib)
+ ...
+ (preprocessing (pps diff.ppx)))
+```
+
+In order to actually compute diffs, you need to write a spec for how your record should be traversed. There are functions provided to help you do so:
+
+- `leaf ~field ~equal` represents a "terminal" node in the spec tree, i.e. the diffing algorithm should simply compare the field values and add it to the diff list if they are different.
+- `child ~field ~spec` represents an "intermediate" node in the spec tree, i.e. the diffing algorithm should recursively compute the diff of a "child" record.
+- `opt_child ~field ~spec` reprents an *optional* intermediate node in the spec tree, i.e. a child record that is optional in the parent.
+- `many specs`: flattens many specs into a single one.
+
+For more usage examples, check out `example/example.ml` and `tests/*_test.ml`.
+
+## License
+This project is licensed under the MIT License.

diff.opam

@@ -0,0 +1,32 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+version: "1.0.0"
+synopsis: "A library for generating diffs from product types"
+maintainer: ["Zach Baylin <[email protected]>"]
+authors: ["Zach Baylin <[email protected]>"]
+license: "MIT"
+homepage: "https://github.com/skolemlabs/diff"
+bug-reports: "https://github.com/skolemlabs/diff/issues"
+depends: [
+  "dune" {>= "3.10"}
+  "ppxlib" {>= "0.25.0"}
+  "ocamlformat" {with-dev-setup}
+  "ppx_deriving" {with-test}
+  "tezt" {with-test & >= "3.1.1" & < "4.0.0"}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/skolemlabs/diff.git"

dune-project

@@ -0,0 +1,21 @@
+(lang dune 3.10)
+
+(name diff)
+
+
+(generate_opam_files true)
+
+(version 1.0.0)
+(source (github skolemlabs/diff))
+(license MIT)
+(authors "Zach Baylin <[email protected]>")
+(maintainers "Zach Baylin <[email protected]>")
+
+(package
+ (name diff)
+ (synopsis "A library for generating diffs from product types")
+ (depends
+  (ppxlib (>= 0.25.0))
+  (ocamlformat :with-dev-setup)
+  (ppx_deriving :with-test)
+  (tezt (and :with-test (and (>= 3.1.1) (< 4.0.0))))))

example/dune

@@ -0,0 +1,4 @@
+(executable
+ (name example)
+ (preprocess
+  (pps ppx_diff)))

example/example.ml

@@ -0,0 +1,61 @@
+type foo = { x : int; y : string } [@@deriving diff]
+type bar = { z : float; foo : foo } [@@deriving diff]
+type recursive = { v : int; r : recursive option } [@@deriving diff]
+
+let bar () =
+  let bar = { foo = { x = 42; y = "Skolem" }; z = 1. } in
+  let f = Diff.Field.Infix.(Bar_foo --| Foo_x) in
+  let x' = 10 in
+  let () = Format.printf "Setting %a: %d\n%!" Diff.Field.pp f x' in
+  let bar' = Diff.Field.set bar f x' in
+  let x = Diff.Field.get bar' f in
+  Format.printf "Getting %a: %d\n%!" Diff.Field.pp f x
+
+let recursive () =
+  let recursive = { v = 1; r = Some { v = 2; r = None } } in
+  let f = Diff.Field.Infix.(Recursive_r --| ?*Recursive_r --| ?+Recursive_v) in
+  let v' = Some 3 in
+  let () =
+    Format.printf "Setting %a: %a\n%!" Diff.Field.pp f
+      (Format.pp_print_option Format.pp_print_int)
+      v'
+  in
+  let recursive' = Diff.Field.set recursive f v' in
+  let v = Diff.Field.get recursive' f in
+  Format.printf "Getting %a: %a\n%!" Diff.Field.pp f
+    (Format.pp_print_option Format.pp_print_int)
+    v
+
+let foo_spec =
+  Diff.(
+    many
+      [
+        leaf ~field:Foo_x ~equal:Int.equal;
+        leaf ~field:Foo_y ~equal:String.equal;
+      ])
+
+let bar_spec =
+  Diff.(
+    many
+      [
+        leaf ~field:Bar_z ~equal:Float.equal;
+        child ~field:Bar_foo ~spec:foo_spec;
+      ])
+
+let bar_diff () =
+  let bar0, bar1 =
+    ( { z = 2.; foo = { x = 0xdeadbeef; y = "Skolem" } },
+      { z = 5.; foo = { x = 0x1337; y = "Skolem" } } )
+  in
+  let diff = Diff.compute bar0 bar1 bar_spec in
+  Format.printf "Computed diff:\n";
+  List.iter
+    (fun (Diff.Diff { field; _ }) -> Format.printf "\t%a\n" Diff.Field.pp field)
+    diff;
+  let bar0' = List.fold_left Diff.apply bar0 diff in
+  Format.printf "bar0' = bar1? %b\n%!" (bar0' = bar1)
+
+let () =
+  bar ();
+  recursive ();
+  bar_diff ()