Initialize Err library for error handling

mbarbin · Aug 22, 2024 · 4b81a35 · 4b81a35
1 parent fc92903
commit 4b81a35
Show file tree

Hide file tree

Showing 34 changed files with 1,552 additions and 44 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,4 +1,10 @@
-## 0.0.1~preview-0.1 (2024-08-19)
+## 0.0.1 (2024-08-22)
+
+### Added
+
+- Added library `Err` establishing a standard for error handling in commandlang CLIs.
+
+## 0.0.1_preview-0.1 (2024-08-19)
 
 ### Added
 

diff --git a/README.md b/README.md
@@ -85,4 +85,5 @@ We initiated the library as part of another project where we are migrating some
 
 - We are grateful for the years of accumulated work and experience that have resulted in high-quality CLI libraries like `cmdliner` and `core.command`.
 - `climate`'s early programming interface was a great source of inspiration. We are very thankful for their work on auto-completion and excited to see where the `climate` project goes next.
+- We would like to thank the Dune developers for the user-facing error handling of Dune (`Stdune.User_message`), on which we based the error handling scheme used in commandlang (`Err`). By adopting a similar approach, we aim to provide a consistent and unified user experience for OCaml users across different tools and libraries.
 - We are inspired by the [diataxis](https://diataxis.fr/) approach to technical documentation, which we use to structure our documentation.
diff --git a/commandlang-err.opam b/commandlang-err.opam
@@ -0,0 +1,34 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "Error Handling Standard for Commandlang CLIs"
+maintainer: ["Mathieu Barbin"]
+authors: ["Mathieu Barbin"]
+license: "MIT"
+homepage: "https://github.com/mbarbin/commandlang"
+doc: "https://mbarbin.github.io/commandlang/"
+bug-reports: "https://github.com/mbarbin/commandlang/issues"
+depends: [
+  "dune" {>= "3.16"}
+  "ocaml" {>= "5.2"}
+  "bisect_ppx" {dev & >= "2.8.3"}
+  "commandlang" {= version}
+  "ppx_js_style" {dev & >= "v0.17" & < "v0.18"}
+  "sexplib0" {>= "v0.17" & < "v0.18"}
+  "stdune" {>= "3.16"}
+  "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/mbarbin/commandlang.git"
diff --git a/commandlang-test.opam b/commandlang-test.opam
@@ -18,6 +18,7 @@ depends: [
   "core" {>= "v0.17" & < "v0.18"}
   "core_unix" {>= "v0.17" & < "v0.18"}
   "expect_test_helpers_core" {>= "v0.17" & < "v0.18"}
+  "loc" {>= "0.0.2"}
   "mdx" {>= "2.4"}
   "ppx_compare" {>= "v0.17" & < "v0.18"}
   "ppx_enumerate" {>= "v0.17" & < "v0.18"}
@@ -31,6 +32,7 @@ depends: [
   "ppxlib" {>= "0.33"}
   "sherlodoc" {with-doc & >= "0.2"}
   "stdio" {>= "v0.17" & < "v0.18"}
+  "stdune" {>= "3.16"}
   "odoc" {with-doc}
 ]
 build: [

diff --git a/commandlang-to-base.opam b/commandlang-to-base.opam
@@ -11,6 +11,8 @@ depends: [
   "dune" {>= "3.16"}
   "ocaml" {>= "5.2"}
   "base" {>= "v0.17" & < "v0.18"}
+  "bisect_ppx" {dev & >= "2.8.3"}
+  "commandlang" {= version}
   "core" {>= "v0.17" & < "v0.18"}
   "ppx_compare" {>= "v0.17" & < "v0.18"}
   "ppx_enumerate" {>= "v0.17" & < "v0.18"}

diff --git a/commandlang-to-climate.opam b/commandlang-to-climate.opam
@@ -10,8 +10,10 @@ bug-reports: "https://github.com/mbarbin/commandlang/issues"
 depends: [
   "dune" {>= "3.16"}
   "ocaml" {>= "5.2"}
+  "bisect_ppx" {dev & >= "2.8.3"}
   "climate" {= "0.0.1~preview-0.1"}
   "commandlang" {= version}
+  "ppx_js_style" {dev & >= "v0.17" & < "v0.18"}
   "odoc" {with-doc}
 ]
 build: [

diff --git a/commandlang-to-cmdliner.opam b/commandlang-to-cmdliner.opam
@@ -10,8 +10,10 @@ bug-reports: "https://github.com/mbarbin/commandlang/issues"
 depends: [
   "dune" {>= "3.16"}
   "ocaml" {>= "5.2"}
+  "bisect_ppx" {dev & >= "2.8.3"}
   "cmdliner" {= "1.3.0"}
   "commandlang" {= version}
+  "ppx_js_style" {dev & >= "v0.17" & < "v0.18"}
   "odoc" {with-doc}
 ]
 build: [

diff --git a/commandlang.opam b/commandlang.opam
@@ -10,6 +10,8 @@ bug-reports: "https://github.com/mbarbin/commandlang/issues"
 depends: [
   "dune" {>= "3.16"}
   "ocaml" {>= "5.2"}
+  "bisect_ppx" {dev & >= "2.8.3"}
+  "ppx_js_style" {dev & >= "v0.17" & < "v0.18"}
   "odoc" {with-doc}
 ]
 build: [

diff --git a/doc/docs/tutorials/getting-started/README.md b/doc/docs/tutorials/getting-started/README.md
@@ -53,7 +53,7 @@ First, create a `lib/` directory and a `lib/dune` file for our library, listing
 
 Next, create an empty command-line skeleton that we will complete incrementally.
 
-<!-- $MDX file=getting_started.ml,part=void -->
+<!-- $MDX skip -->
 ```ocaml
 let cmd =
   Command.make
@@ -81,20 +81,18 @@ As you'll learn, `commandlang` doesn't come with its own command runner. Instead
 ```lisp
 (executable
  (name main)
- (libraries commandlang_to_cmdliner cmdliner getting_started))
+ (libraries commandlang_to_cmdliner getting_started))
 ```
 
 An invocation of `cmdliner` for a `commandlang` command may look like this:
 
 <!-- $MDX file=main.ml -->
 ```ocaml
 let () =
-  Cmdliner.Cmd.eval
-    (Commandlang_to_cmdliner.Translate.command
-       Getting_started.cmd
-       ~name:"my-calculator"
-       ~version:"%%VERSION%%")
-  |> Stdlib.exit
+  Commandlang_to_cmdliner.run
+    Getting_started.cmd
+    ~name:"my-calculator"
+    ~version:"%%VERSION%%"
 ;;
 ```
 
@@ -138,7 +136,7 @@ Next, we'll start exposing the functionality via the command-line interface.
 
 Let's revisit our empty skeleton:
 
-<!-- $MDX file=getting_started.ml,part=void,skip -->
+<!-- $MDX skip -->
 ```ocaml
 let cmd =
   Command.make

diff --git a/doc/docs/tutorials/getting-started/bin/dune b/doc/docs/tutorials/getting-started/bin/dune
@@ -1,6 +1,6 @@
 (executable
  (name main)
  (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
- (libraries cmdliner commandlang_to_cmdliner getting_started)
+ (libraries commandlang_to_cmdliner getting_started)
  (instrumentation
   (backend bisect_ppx)))
diff --git a/doc/docs/tutorials/getting-started/bin/main.ml b/doc/docs/tutorials/getting-started/bin/main.ml
@@ -1,8 +1,6 @@
 let () =
-  Cmdliner.Cmd.eval
-    (Commandlang_to_cmdliner.Translate.command
-       Getting_started.cmd
-       ~name:"my-calculator"
-       ~version:"%%VERSION%%")
-  |> Stdlib.exit
+  Commandlang_to_cmdliner.run
+    Getting_started.cmd
+    ~name:"my-calculator"
+    ~version:"%%VERSION%%"
 ;;
diff --git a/doc/docs/tutorials/getting-started/lib/getting_started.ml b/doc/docs/tutorials/getting-started/lib/getting_started.ml
@@ -19,18 +19,6 @@ module Operator = struct
 end
 (* $MDX part-end *)
 
-(* $MDX part-begin=void *)
-let cmd =
-  Command.make
-    ~summary:"A simple calculator"
-    (let open Command.Std in
-     let+ () = Arg.return () in
-     ())
-;;
-
-(* $MDX part-end *)
-let _ = cmd
-
 (* $MDX part-begin=final *)
 let cmd =
   Command.make

diff --git a/dune-project b/dune-project
@@ -22,7 +22,40 @@
  (synopsis "Declarative Command-line Parsing for OCaml")
  (depends
   (ocaml
-   (>= 5.2))))
+   (>= 5.2))
+  (bisect_ppx
+   (and
+    :dev
+    (>= 2.8.3)))
+  (ppx_js_style
+   (and
+    :dev
+    (>= v0.17)
+    (< v0.18)))))
+
+(package
+ (name commandlang-err)
+ (synopsis "Error Handling Standard for Commandlang CLIs")
+ (depends
+  (ocaml
+   (>= 5.2))
+  (bisect_ppx
+   (and
+    :dev
+    (>= 2.8.3)))
+  (commandlang
+   (= :version))
+  (ppx_js_style
+   (and
+    :dev
+    (>= v0.17)
+    (< v0.18)))
+  (sexplib0
+   (and
+    (>= v0.17)
+    (< v0.18)))
+  (stdune
+   (>= 3.16))))
 
 (package
  (name commandlang-to-base)
@@ -34,6 +67,12 @@
    (and
     (>= v0.17)
     (< v0.18)))
+  (bisect_ppx
+   (and
+    :dev
+    (>= 2.8.3)))
+  (commandlang
+   (= :version))
   (core
    (and
     (>= v0.17)
@@ -86,21 +125,39 @@
  (depends
   (ocaml
    (>= 5.2))
+  (bisect_ppx
+   (and
+    :dev
+    (>= 2.8.3)))
   (cmdliner
    (= 1.3.0))
   (commandlang
-   (= :version))))
+   (= :version))
+  (ppx_js_style
+   (and
+    :dev
+    (>= v0.17)
+    (< v0.18)))))
 
 (package
  (name commandlang-to-climate)
  (synopsis "Convert commandlang Parsers to climate")
  (depends
   (ocaml
    (>= 5.2))
+  (bisect_ppx
+   (and
+    :dev
+    (>= 2.8.3)))
   (climate
    (= 0.0.1~preview-0.1))
   (commandlang
-   (= :version))))
+   (= :version))
+  (ppx_js_style
+   (and
+    :dev
+    (>= v0.17)
+    (< v0.18)))))
 
 (package
  (name commandlang-test)
@@ -134,6 +191,8 @@
    (and
     (>= v0.17)
     (< v0.18)))
+  (loc
+   (>= 0.0.2))
   (mdx
    (>= 2.4))
   (ppx_compare
@@ -182,4 +241,6 @@
   (stdio
    (and
     (>= v0.17)
-    (< v0.18)))))
+    (< v0.18)))
+  (stdune
+   (>= 3.16))))
diff --git a/lib/commandlang/src/command.mli b/lib/commandlang/src/command.mli
@@ -1,3 +1,5 @@
+(** Declarative Command-line Parsing for OCaml. *)
+
 (** {1 Utils} *)
 
 module Nonempty_list : sig

diff --git a/lib/commandlang/test/test__command.ml b/lib/commandlang/test/test__command.ml
@@ -2,7 +2,7 @@ let%expect_test "Param.enum" =
   let open Command.Std in
   require_does_raise [%here] (fun () ->
     let+ _ = Arg.named [ "a" ] (Param.assoc []) ~doc:"empty enum" in
-    ());
+    (() [@coverage off]));
   [%expect {| (Invalid_argument Command.Arg.enum) |}];
   ()
 ;;
diff --git a/lib/commandlang_err/src/dune b/lib/commandlang_err/src/dune
@@ -0,0 +1,19 @@
+(library
+ (name commandlang_err)
+ (public_name commandlang-err)
+ (flags
+  :standard
+  -w
+  +a-4-40-41-42-44-45-48-66
+  -warn-error
+  +a
+  -open
+  Commandlang
+  -open
+  Sexplib0)
+ (libraries commandlang sexplib0 stdune)
+ (instrumentation
+  (backend bisect_ppx))
+ (lint
+  (pps ppx_js_style -allow-let-operators -check-doc-comments))
+ (preprocess no_preprocessing))