Merge pull request #15 from mbarbin/commandlang

Assorted changes - prepare 0.0.5
mbarbin · Aug 22, 2024 · a85a9ff · a85a9ff
2 parents 5780a8b + e0fff77
commit a85a9ff
Show file tree

Hide file tree

Showing 270 changed files with 1,294 additions and 769 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,3 +1,11 @@
+## 0.0.5 (2024-08-19)
+
+### Changed
+
+- Renamed `vcs_param` to `vcs_arg` to match commandlang conventions.
+- Switch commands to new library `commandlang` with `cmdliner` backend.
+- Upgrade `provider` to `0.0.8`.
+
 ## 0.0.4 (2024-08-05)
 
 Release a version compatible with the latest renames in the provider library.

diff --git a/COPYING.HEADER b/COPYING.HEADER
@@ -1,4 +1,4 @@
-Vcs - a Versatile OCaml Library for Git Interaction
+Vcs - a Versatile OCaml Library for Git Operations
 Copyright (C) 2024 Mathieu Barbin <[email protected]>
 
 This file is part of Vcs.

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <h1 align="center">
-  <p align="center">A Versatile OCaml Library for Git Interaction</p>
+  <p align="center">A Versatile OCaml Library for Git Operations</p>
   <img
     src="./doc/static/img/ocaml-vcs.png?raw=true"
     width='216'

diff --git a/bin/dune b/bin/dune
@@ -3,6 +3,6 @@
  (public_name ocaml-vcs)
  (package vcs-command)
  (flags :standard -w +a-4-40-41-42-44-45-48-66 -warn-error +a)
- (libraries command-unix-for-opam vcs-command)
+ (libraries commandlang-err commandlang-to-cmdliner vcs-command)
  (instrumentation
   (backend bisect_ppx)))
diff --git a/bin/main.ml b/bin/main.ml
@@ -1,5 +1,5 @@
 (*******************************************************************************)
-(*  Vcs - a Versatile OCaml Library for Git Interaction                        *)
+(*  Vcs - a Versatile OCaml Library for Git Operations                         *)
 (*  Copyright (C) 2024 Mathieu Barbin <[email protected]>               *)
 (*                                                                             *)
 (*  This file is part of Vcs.                                                  *)
@@ -19,4 +19,15 @@
 (*  <http://www.gnu.org/licenses/> and <https://spdx.org>, respectively.       *)
 (*******************************************************************************)
 
-let () = Command_unix_for_opam.run Vcs_command.main
+let () =
+  Commandlang_to_cmdliner.run
+    Vcs_command.main
+    ~name:"ocaml-vcs"
+    ~version:"%%VERSION%%"
+    ~exn_handler:(function
+    | Vcs.E e ->
+      Some
+        (Commandlang_err.Err.make
+           [ Commandlang_err.Err.pp_of_sexp (Vcs.Err.sexp_of_t e) ])
+    | _ -> None [@coverage off])
+;;
diff --git a/doc/blog/authors.yml b/doc/blog/authors.yml
@@ -1,5 +1,5 @@
 mbarbin:
   name: Mathieu Barbin
-  title: Maintainer of ocaml-vcs
+  title: Author & Maintainer of ocaml-vcs
   url: https://github.com/mbarbin
   image_url: https://github.com/mbarbin.png
diff --git a/doc/docs/design/introduction.md b/doc/docs/design/introduction.md
@@ -6,7 +6,7 @@ The concurrency runtime must be compatible with programs written in a direct sty
 
 ## How It Works
 
-`Vcs` is an interface composed of [Traits](./traits.md), each providing different functionalities associated with Git interaction. The dynamic dispatch implementation of Vcs is powered by the [provider](https://github.com/mbarbin/provider) library.
+`Vcs` is an interface composed of [Traits](./traits.md), each providing different functionalities associated with Git operations. The dynamic dispatch implementation of Vcs is powered by the [provider](https://github.com/mbarbin/provider) library.
 
 ## Architecture
 

diff --git a/doc/docs/design/traits.md b/doc/docs/design/traits.md
@@ -1,33 +1,17 @@
 # The Power of Traits in `Vcs`
 
-The `Vcs` library leverages the `provider`-based parametric model to offer a
-flexible and adaptable interface for Git interaction. This model, also used in
-the `Eio` library (`Eio.Resource`), allows us to define small scopes of
-functionality, or `Traits`, within the `Vcs` library.
+The `Vcs` library leverages the `provider`-based parametric model to offer a flexible and adaptable interface for Git operations. This model, also used in the `Eio` library (`Eio.Resource`), allows us to define small scopes of functionality, or `Traits`, within the `Vcs` library.
 
 ## Experience with `providers`
 
-Our use of the [provider](https://github.com/mbarbin/provider) based parametric
-library in `Vcs` serves as a practical, real-world case study of this pattern.
+Our use of the [provider](https://github.com/mbarbin/provider) based parametric library in `Vcs` serves as a practical, real-world case study of this pattern.
 
-We aim to bring this pattern to the attention of the community, fostering a
-general understanding that can be applied to other projects using the same
-pattern. In essence, understanding the parametrized model of `Vcs` equates to
-understanding `Eio.Resource`, and vice versa.
+We aim to bring this pattern to the attention of the community, fostering a general understanding that can be applied to other projects using the same pattern. In essence, understanding the parametrized model of `Vcs` equates to understanding `Eio.Resource`, and vice versa.
 
 ## Granularity of the Interface via Trait Granularity
 
-The `Trait` design of `provider` allows us to define specific and isolated
-sub-functionalities within the `Vcs` library. This granularity enables different
-providers to choose which `Trait` they wish to implement, offering a level of
-flexibility not possible with a monolithic functor.
+The `Trait` design of `provider` allows us to define specific and isolated sub-functionalities within the `Vcs` library. This granularity enables different providers to choose which `Trait` they wish to implement, offering a level of flexibility not possible with a monolithic functor.
 
-With `Traits`, you can select a provider with the specific set of traits you
-need, without changing any other code. As explained
-[here](https://mbarbin.github.io/provider/provider/Provider/Interface/index.html#type-t),
-provider interfaces come with some notion of phantom types, offering additional
-compiler assistance.
+With `Traits`, you can select a provider with the specific set of traits you need, without changing any other code. As explained [here](https://mbarbin.github.io/provider/provider/Provider/Interface/index.html#type-t), provider interfaces come with some notion of phantom types, offering additional compiler assistance.
 
-In summary, the use of `Traits` in `Vcs` provides a flexible, adaptable, and
-granular interface for Git interaction, promoting a broader understanding and
-application of the `provider`-based parametric model.
+In summary, the use of `Traits` in `Vcs` provides a flexible, adaptable, and granular interface for Git operations, promoting a broader understanding and application of the `provider`-based parametric model.
diff --git a/doc/docs/tests/exploratory_tests.md b/doc/docs/tests/exploratory_tests.md
@@ -9,57 +9,99 @@ Whether you're testing new features, diagnosing problems, or seeking to understa
 Below is a quick overview of the commands available in `ocaml-vcs`:
 
 ```bash
-$ ocaml-vcs help -expand-dots -flags -recursive
-call a command from the vcs interface
-
-  ocaml-vcs SUBCOMMAND
-
-This is an executable to test the Version Control System (vcs) library.
-
-We expect a 1:1 mapping between the function exposed in the [Vcs.S] and the
-sub commands exposed here, plus additional functionality in [more-tests].
-
-=== subcommands and flags ===
-
-  add                        . add a file to the index
-  commit                     . commit a file
-  commit --message MSG, -m   . commit message
-  commit [--quiet], -q       . suppress output on success
-  current-branch             . current branch
-  current-revision           . revision of HEAD
-  git                        . run the git cli
-  git [--]                   . pass the remaining args to git
-  init                       . initialize a new repository
-  init [--quiet], -q         . suppress output on success
-  load-file                  . print a file from the filesystem (aka cat)
-  log                        . show the log of current repo
-  ls-files                   . list file
-  ls-files [--below PATH]    . only below path
-  more-tests                 . more tests combining vcs functions
-  more-tests branch-revision . revision of a branch
-  more-tests gca             . print greatest common ancestors of revisions
-  name-status                . show a summary of the diff between 2 revs
-  num-status                 . show a summary of the number of lines of diff
-                               between 2 revs
-  refs                       . show the refs of current repo
-  rename-current-branch      . move/rename a branch to a new name
-  save-file                  . save stdin to a file from the filesystem (aka
-                               tee)
-  set-user-config            . set the user config
-  set-user-config --user.email EMAIL
-                             . user email
-  set-user-config --user.name USER
-                             . user name
-  show-file-at-rev           . show the contents of file at a given revision
-  show-file-at-rev --rev REV, -r
-                             . revision
-  tree                       . compute tree of current repo
-  version                    . print version information
-  version [-build-info]      . print build info for this build
-  version [-version]         . print the version of this build
-  help                       . explain a given subcommand (perhaps recursively)
-  help [-expand-dots]        . expand subcommands in recursive help
-  help [-flags]              . show flags as well in recursive help
-  help [-recursive]          . show subcommands of subcommands, etc.
+$ ocaml-vcs --help=plain
+NAME
+       ocaml-vcs - call a command from the vcs interface
+
+SYNOPSIS
+       ocaml-vcs COMMAND …
+
+
+
+       This is an executable to test the Version Control System (vcs)
+       library.
+
+
+
+       We expect a 1:1 mapping between the function exposed in the [Vcs.S]
+       and the sub commands exposed here, plus additional functionality in
+       [more-tests].
+
+
+
+COMMANDS
+       add [OPTION]… file
+           add a file to the index
+
+       commit [--message=MSG] [--quiet] [OPTION]…
+           commit a file
+
+       current-branch [OPTION]…
+           current branch
+
+       current-revision [OPTION]…
+           revision of HEAD
+
+       git [OPTION]… [ARG]…
+           run the git cli
+
+       init [--quiet] [OPTION]… file
+           initialize a new repository
+
+       load-file [OPTION]… file
+           print a file from the filesystem (aka cat)
+
+       log [OPTION]…
+           show the log of current repo
+
+       ls-files [--below=PATH] [OPTION]…
+           list file
+
+       more-tests COMMAND …
+           more tests combining vcs functions
+
+       name-status [OPTION]… rev rev
+           show a summary of the diff between 2 revs
+
+       num-status [OPTION]… rev rev
+           show a summary of the number of lines of diff between 2 revs
+
+       refs [OPTION]…
+           show the refs of current repo
+
+       rename-current-branch [OPTION]… branch
+           move/rename a branch to a new name
+
+       save-file [OPTION]… file
+           save stdin to a file from the filesystem (aka tee)
+
+       set-user-config [--user.email=EMAIL] [--user.name=USER] [OPTION]…
+           set the user config
+
+       show-file-at-rev [--rev=REV] [OPTION]… file
+           show the contents of file at a given revision
+
+       tree [OPTION]…
+           compute tree of current repo
+
+COMMON OPTIONS
+       --help[=FMT] (default=auto)
+           Show this help in format FMT. The value FMT must be one of auto,
+           pager, groff or plain. With auto, the format is pager or plain
+           whenever the TERM env var is dumb or undefined.
+
+       --version
+           Show version information.
+
+EXIT STATUS
+       ocaml-vcs exits with:
+
+       0   on success.
+
+       123 on indiscriminate errors reported on standard error.
+
+       124 on command line parsing errors.
+
+       125 on unexpected internal errors (bugs).
 
 ```
diff --git a/doc/docusaurus.config.ts b/doc/docusaurus.config.ts
@@ -4,7 +4,7 @@ import type * as Preset from '@docusaurus/preset-classic';
 
 const config: Config = {
   title: 'ocaml-vcs',
-  tagline: 'A Versatile OCaml Library for Git Interaction',
+  tagline: 'A Versatile OCaml Library for Git Operations',
   favicon: 'img/favicon.ico',
 
   // Set the production url of your site here

diff --git a/doc/src/pages/index.md b/doc/src/pages/index.md
@@ -1,5 +1,5 @@
 <h1 align="center">
-  <p align="center">A Versatile OCaml Library for Git Interaction</p>
+  <p align="center">A Versatile OCaml Library for Git Operations</p>
   <img
     src="./img/ocaml-vcs.png?raw=true"
     width='288'