From 8a2741f5be8c0d17311be78bea3bfe3ee9b8fc6a Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Thu, 24 Oct 2024 12:40:04 +0200 Subject: [PATCH 1/3] Update dependencies bounds --- cmdlang-cmdliner-runner.opam | 4 ++-- cmdlang-tests.opam | 4 ++-- cmdlang-to-climate.opam | 4 ++-- cmdlang-to-cmdliner.opam | 4 ++-- cmdlang.opam | 2 +- dune-project | 26 +++++++++++++++++--------- 6 files changed, 26 insertions(+), 18 deletions(-) diff --git a/cmdlang-cmdliner-runner.opam b/cmdlang-cmdliner-runner.opam index 6fdc192..9a126b2 100644 --- a/cmdlang-cmdliner-runner.opam +++ b/cmdlang-cmdliner-runner.opam @@ -9,10 +9,10 @@ doc: "https://mbarbin.github.io/cmdlang/" bug-reports: "https://github.com/mbarbin/cmdlang/issues" depends: [ "dune" {>= "3.16"} - "ocaml" {>= "5.2"} + "ocaml" {>= "4.14"} "cmdlang" {= version} "cmdlang-to-cmdliner" {= version} - "cmdliner" {= "1.3.0"} + "cmdliner" {>= "1.3.0" & < "1.4"} "err" {= version} "odoc" {with-doc} ] diff --git a/cmdlang-tests.opam b/cmdlang-tests.opam index 4506c6b..5ebe3a8 100644 --- a/cmdlang-tests.opam +++ b/cmdlang-tests.opam @@ -13,13 +13,13 @@ depends: [ "ocamlformat" {with-dev-setup & = "0.26.2"} "base" {>= "v0.17" & < "v0.18"} "bisect_ppx" {with-dev-setup & >= "2.8.3"} - "climate" {>= "0.1.0~preview-0.1"} + "climate" {>= "0.1.0~" & < "0.2"} "cmdlang" {= version} "cmdlang-cmdliner-runner" {= version} "cmdlang-to-base" {= version} "cmdlang-to-climate" {= version} "cmdlang-to-cmdliner" {= version} - "cmdliner" {= "1.3.0"} + "cmdliner" {>= "1.3.0"} "core" {>= "v0.17" & < "v0.18"} "core_unix" {>= "v0.17" & < "v0.18"} "err" {= version} diff --git a/cmdlang-to-climate.opam b/cmdlang-to-climate.opam index 923c1a4..2c6cc8f 100644 --- a/cmdlang-to-climate.opam +++ b/cmdlang-to-climate.opam @@ -9,8 +9,8 @@ doc: "https://mbarbin.github.io/cmdlang/" bug-reports: "https://github.com/mbarbin/cmdlang/issues" depends: [ "dune" {>= "3.16"} - "ocaml" {>= "5.2"} - "climate" {>= "0.1.0~preview-0.1"} + "ocaml" {>= "4.14"} + "climate" {>= "0.1.0~" & < "0.2"} "cmdlang" {= version} "odoc" {with-doc} ] diff --git a/cmdlang-to-cmdliner.opam b/cmdlang-to-cmdliner.opam index fb47937..8b2f09a 100644 --- a/cmdlang-to-cmdliner.opam +++ b/cmdlang-to-cmdliner.opam @@ -9,9 +9,9 @@ doc: "https://mbarbin.github.io/cmdlang/" bug-reports: "https://github.com/mbarbin/cmdlang/issues" depends: [ "dune" {>= "3.16"} - "ocaml" {>= "5.2"} + "ocaml" {>= "4.14"} "cmdlang" {= version} - "cmdliner" {= "1.3.0"} + "cmdliner" {>= "1.3.0" & < "1.4"} "odoc" {with-doc} ] build: [ diff --git a/cmdlang.opam b/cmdlang.opam index bd4ca2b..da950b1 100644 --- a/cmdlang.opam +++ b/cmdlang.opam @@ -9,7 +9,7 @@ doc: "https://mbarbin.github.io/cmdlang/" bug-reports: "https://github.com/mbarbin/cmdlang/issues" depends: [ "dune" {>= "3.16"} - "ocaml" {>= "5.2"} + "ocaml" {>= "4.14"} "odoc" {with-doc} ] build: [ diff --git a/dune-project b/dune-project index ee5e399..f6e5dfd 100644 --- a/dune-project +++ b/dune-project @@ -22,7 +22,7 @@ (synopsis "Declarative Command-line Parsing for OCaml") (depends (ocaml - (>= 5.2)))) + (>= 4.14)))) (package (name err) @@ -121,20 +121,24 @@ (synopsis "Convert cmdlang Parsers to cmdliner") (depends (ocaml - (>= 5.2)) + (>= 4.14)) (cmdlang (= :version)) (cmdliner - (= 1.3.0)))) + (and + (>= 1.3.0) + (< 1.4))))) (package (name cmdlang-to-climate) (synopsis "Convert cmdlang Parsers to climate") (depends (ocaml - (>= 5.2)) + (>= 4.14)) (climate - (>= 0.1.0~preview-0.1)) + (and + (>= 0.1.0~) + (< 0.2))) (cmdlang (= :version)))) @@ -143,13 +147,15 @@ (synopsis "A cmdlang runner using cmdliner and err") (depends (ocaml - (>= 5.2)) + (>= 4.14)) (cmdlang (= :version)) (cmdlang-to-cmdliner (= :version)) (cmdliner - (= 1.3.0)) + (and + (>= 1.3.0) + (< 1.4))) (err (= :version)))) @@ -172,7 +178,9 @@ :with-dev-setup (>= 2.8.3))) (climate - (>= 0.1.0~preview-0.1)) + (and + (>= 0.1.0~) + (< 0.2))) (cmdlang (= :version)) (cmdlang-cmdliner-runner @@ -184,7 +192,7 @@ (cmdlang-to-cmdliner (= :version)) (cmdliner - (= 1.3.0)) + (>= 1.3.0)) (core (and (>= v0.17) From 907c8c8fff946dccaa26f7247801e355d747bca6 Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Thu, 24 Oct 2024 13:47:14 +0200 Subject: [PATCH 2/3] Improve documentation --- lib/cmdlang/src/command.mli | 87 +++++++++++++++++-- lib/cmdlang_ast/src/ast.mli | 17 ++++ .../src/cmdlang_cmdliner_runner.mli | 12 ++- lib/cmdlang_to_base/src/translate.mli | 12 +++ lib/cmdlang_to_climate/src/translate.mli | 8 ++ lib/cmdlang_to_cmdliner/src/translate.mli | 2 + 6 files changed, 129 insertions(+), 9 deletions(-) diff --git a/lib/cmdlang/src/command.mli b/lib/cmdlang/src/command.mli index 33ea87e..81f7ec3 100644 --- a/lib/cmdlang/src/command.mli +++ b/lib/cmdlang/src/command.mli @@ -1,12 +1,66 @@ -(** Declarative Command-line Parsing for OCaml. *) +(** Declarative Command-line Parsing for OCaml. + + Cmdlang is a library for creating command-line parsers in OCaml. Implemented + as an OCaml EDSL, its declarative specification language lives at the + intersection of other well-established similar libraries. + + Cmdlang exposes a single module named [Command], which contains the entire + API to declare command line parsers. + + Assuming [Cmdlang.Command] to be available in your scope as [Command], the + following is a minimalist command that does nothing: + + {[ + let cmd : unit Command.t = + Command.make + ~summary:"A command that does nothing" + (let open Command.Std in + let+ () = Arg.return () in + ()) + ;; + ]} + + To get started with this API refers to this + {{:https://mbarbin.github.io/cmdlang/docs/tutorials/getting-started/} tutorial} + from cmdlang's documentation. *) (** {1 Utils} *) module Nonempty_list : sig + (** A type to represent lists that are statically known to be non-empty. *) + + (** The way this constructor is defined allows one to use the regular list + literal syntax in a context where a non-empty list is expected. For + example, the function {!val:Arg.flag} expects a first argument of type + [string Nonempty_list.t] and may be used that way: + + {[ + Arg.flag [ "verbose" ] ~doc:"enable more output" + ]} + + The point being that the following would be a type error: + + {[ + Arg.flag [] ~doc:"enable more output" + ]} *) type 'a t = 'a Cmdlang_ast.Ast.Nonempty_list.t = ( :: ) : 'a * 'a list -> 'a t end +(** {1 Interfaces} + + These interfaces are convenient to use with the {!module:Param} module, so + you can apply its helpers to custom modules. For example, if your module + [My_enum] implements the {!Enumerated_stringable} interface, then you can + build a parser for it with: + + {[ + Param.enumerated (module My_enum) + ]} *) + module type Enumerated_stringable = sig + (** An interface for types that have a finite number of inhabitants that all + have a canonical string representation. *) + type t val all : t list @@ -28,11 +82,11 @@ end module type Validated_string = sig (** An interface for types that can be parsed from strings, with the possibility - of parsing failures. This is useful for types that require validation - during conversion from string representations. + of parsing failures. - The names [v] and [to_string] were chosen to match the conventions used by - some existing libraries, such as [Fpath]. *) + This is useful for types that require validation during conversion from + string representations. The names [v] and [to_string] were chosen to match + the conventions used by some existing libraries, such as [Fpath]. *) type t @@ -162,7 +216,17 @@ end (** {1 Let operators} - For use with the [( let+ )] style. *) + For use with the [( let+ )] style: + + {[ + let cmd : unit Command.t = + Command.make + ~summary:"A command that does nothing" + (let open Command.Std in + let+ () = Arg.return () in + ()) + ;; + ]} *) module Std : sig include Applicative_syntax with type 'a t := 'a Arg.t @@ -173,7 +237,16 @@ end (** {1 Ppx_let} - For use with the [( let%map_open.Command )] style. *) + For use with the [( let%map_open.Command )] style: + + {[ + let cmd : unit Command.t = + Command.make + ~summary:"A command that does nothing" + (let%map_open.Command () = Arg.return () in + ()) + ;; + ]} *) module Let_syntax : sig (** Substituted below. *) diff --git a/lib/cmdlang_ast/src/ast.mli b/lib/cmdlang_ast/src/ast.mli index a054e38..3345e56 100644 --- a/lib/cmdlang_ast/src/ast.mli +++ b/lib/cmdlang_ast/src/ast.mli @@ -1,3 +1,20 @@ +(** The internal representation for the EDSL used by the cmdlang library. + + Cmdlang doesn't include an execution engine. Instead, Cmdlang parsers are + automatically translated to `cmdliner`, `core.command`, or `climate` + commands for execution. + + When you use the cmdlang library to define a command-line interface, you are + effectively building a value of type [Cmdlang_ast.Ast.Command.t]. It is then + converted internally to the targeted backend. + + This module is not meant to be used directly by users of the library. + Rather, users use the [Cmdlang.Command] interface which provides a + high-level API meant to be ergonomic and user-friendly. + + [Cmdlang_ast] is exposed to allow extending the library with new backends or + to write analysis tools, etc. *) + type 'a parse := string -> ('a, [ `Msg of string ]) result type 'a print := Format.formatter -> 'a -> unit diff --git a/lib/cmdlang_cmdliner_runner/src/cmdlang_cmdliner_runner.mli b/lib/cmdlang_cmdliner_runner/src/cmdlang_cmdliner_runner.mli index a755508..f311527 100644 --- a/lib/cmdlang_cmdliner_runner/src/cmdlang_cmdliner_runner.mli +++ b/lib/cmdlang_cmdliner_runner/src/cmdlang_cmdliner_runner.mli @@ -1,5 +1,13 @@ -(** This is the standard way that is designed with cmdlang, assuming you are - using [Err] etc. *) +(** An opinionated runner for cmdlang parsers using cmdliner as a backend. + + This module provides a default runner that wraps [cmdlang-to-cmdliner] and + runs the command under a [Err.protect] block. + + This furnishes a standard way to run cmdlang commands, assuming you are + using [Err]. + + It is opinionated and adds a few dependencies to your project, such as + [Logs] and [Fmt]. *) val run : ?exn_handler:(exn -> Err.t option) -> unit Cmdlang.Command.t diff --git a/lib/cmdlang_to_base/src/translate.mli b/lib/cmdlang_to_base/src/translate.mli index 27cf5ff..fcbef5a 100644 --- a/lib/cmdlang_to_base/src/translate.mli +++ b/lib/cmdlang_to_base/src/translate.mli @@ -1,3 +1,15 @@ +(** Translate cmdlang parsers to core.command. *) + +(** {1 Configuration} + + The translation implemented in this module allows some configuration + regarding the resulting command that you want to build. The goal of this + configuration is to furnish assistance for complex multi-stages migrations from + a backend to another. + + It is currently experimental, not well tested or documented, and expected to + change in the future. *) + module Config : sig type t diff --git a/lib/cmdlang_to_climate/src/translate.mli b/lib/cmdlang_to_climate/src/translate.mli index 1bd9902..e2fd3c5 100644 --- a/lib/cmdlang_to_climate/src/translate.mli +++ b/lib/cmdlang_to_climate/src/translate.mli @@ -1,3 +1,11 @@ +(** Translate cmdlang parsers to climate. + + The translation to climate is experimental, not well tested or documented, + and doesn't support all features of climate. In particular there's currently + no support to target the auto-completion features offered by climate. This + is an area left for future work. More info + {{:https://mbarbin.github.io/cmdlang/docs/explanation/future_plans/} here}. *) + (** {1 Param} *) val param : 'a Cmdlang.Command.Param.t -> 'a Climate.Arg_parser.conv diff --git a/lib/cmdlang_to_cmdliner/src/translate.mli b/lib/cmdlang_to_cmdliner/src/translate.mli index f52337e..0bf2714 100644 --- a/lib/cmdlang_to_cmdliner/src/translate.mli +++ b/lib/cmdlang_to_cmdliner/src/translate.mli @@ -1,3 +1,5 @@ +(** Translate cmdlang parsers to cmdliner. *) + (** {1 Param} *) val param : 'a Cmdlang.Command.Param.t -> 'a Cmdliner.Arg.conv From bb1569965c35abcea62a3392ec7831b843a47bbd Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Thu, 24 Oct 2024 11:21:31 +0200 Subject: [PATCH 3/3] Prepare changelog for release --- CHANGES.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 902f1b4..d0eaf9f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,14 +1,11 @@ -## 0.0.6 (unreleased) - -### Added +## 0.0.6 (2024-10-24) ### Changed -### Deprecated - -### Fixed - -### Removed +- Prepare documentation for initial release. +- Upgrade to `climate.0.1.0`. +- Make opam files pass opam-repository linting rules. +- Upgrade Docusaurus. ## 0.0.5 (2024-09-17)