diff --git a/cmdliner/Cmdliner/Cmd/index.html b/cmdliner/Cmdliner/Cmd/index.html index f8630b67..b5abf74e 100644 --- a/cmdliner/Cmdliner/Cmd/index.html +++ b/cmdliner/Cmdliner/Cmd/index.html @@ -42,14 +42,22 @@ ?argv:string array -> ?term_err:Exit.code -> (Exit.code, string) result t -> - Exit.code

eval_result' cmd is:

See eval_value for other arguments.

Low level evaluation

This interface gives more information on command evaluation results and lets you choose how to map evaluation results to exit codes.

type 'a eval_ok = [
  1. | `Ok of 'a
    (*

    The term of the command evaluated to this value.

    *)
  2. | `Version
    (*

    The version of the main cmd was requested.

    *)
  3. | `Help
    (*

    Help was requested.

    *)
]

The type for successful evaluation results.

type eval_error = [
  1. | `Parse
    (*

    A parse error occurred.

    *)
  2. | `Term
    (*

    A term evaluation error occurred.

    *)
  3. | `Exn
    (*

    An uncaught exception occurred.

    *)
]

The type for erroring evaluation results.

val eval_value : + Exit.code

eval_result' cmd is:

See eval_value for other arguments.

Low level evaluation

This interface gives more information on command evaluation results and lets you choose how to map evaluation results to exit codes.

type 'a eval_ok = [
  1. | `Ok of 'a
    (*

    The term of the command evaluated to this value.

    *)
  2. | `Version
    (*

    The version of the main cmd was requested.

    *)
  3. | `Help
    (*

    Help was requested.

    *)
]

The type for successful evaluation results.

type eval_error = [
  1. | `Parse
    (*

    A parse error occurred.

    *)
  2. | `Term
    (*

    A term evaluation error occurred.

    *)
  3. | `Exn
    (*

    An uncaught exception occurred.

    *)
]

The type for erroring evaluation results.

type 'a eval_exit = [
  1. | `Ok of 'a
    (*

    The term of the command evaluated to this value.

    *)
  2. | `Exit of Exit.code
    (*

    The evaluation wants to exit with this code.

    *)
]
val eval_value : ?help:Stdlib.Format.formatter -> ?err:Stdlib.Format.formatter -> ?catch:bool -> ?env:(string -> string option) -> ?argv:string array -> 'a t -> - ('a eval_ok, eval_error) result

eval ~help ~err ~catch ~env ~argv cmd is the evaluation result of cmd with:

val eval_peek_opts : + ('a eval_ok, eval_error) result

eval ~help ~err ~catch ~env ~argv cmd is the evaluation result of cmd with:

val eval_value' : + ?help:Stdlib.Format.formatter -> + ?err:Stdlib.Format.formatter -> + ?catch:bool -> + ?env:(string -> string option) -> + ?argv:string array -> + ?term_err:int -> + 'a t -> + 'a eval_exit

eval_value' is like eval_value, but if the command term does not evaluate, returns an exit code like the evaluation function do (which can be Exit.ok in case help or version was requested).

val eval_peek_opts : ?version_opt:bool -> ?env:(string -> string option) -> ?argv:string array -> diff --git a/cmdliner/Cmdliner/Term/Syntax/index.html b/cmdliner/Cmdliner/Term/Syntax/index.html new file mode 100644 index 00000000..bbc19aa0 --- /dev/null +++ b/cmdliner/Cmdliner/Term/Syntax/index.html @@ -0,0 +1,2 @@ + +Syntax (cmdliner.Cmdliner.Term.Syntax)

Module Term.Syntax

let operators.

val let+ : 'a t -> ('a -> 'b) -> 'b t

( let+ ) is map.

val and+ : 'a t -> 'b t -> ('a * 'b) t

( and* ) is product.

diff --git a/cmdliner/Cmdliner/Term/index.html b/cmdliner/Cmdliner/Term/index.html index a68d5a09..271fc7bf 100644 --- a/cmdliner/Cmdliner/Term/index.html +++ b/cmdliner/Cmdliner/Term/index.html @@ -1,5 +1,5 @@ -Term (cmdliner.Cmdliner.Term)

Module Cmdliner.Term

Terms.

A term is evaluated by a program to produce a result, which can be turned into an exit status. A term made of terms referring to command line arguments implicitly defines a command line syntax.

Terms

type +'a t

The type for terms evaluating to values of type 'a.

val const : 'a -> 'a t

const v is a term that evaluates to v.

val ($) : ('a -> 'b) t -> 'a t -> 'b t

f $ v is a term that evaluates to the result of applying the evaluation of v to the one of f.

val app : ('a -> 'b) t -> 'a t -> 'b t

app is ($).

Interacting with Cmdliner's evaluation

val term_result : ?usage:bool -> ('a, [ `Msg of string ]) result t -> 'a t

term_result ~usage t evaluates to

  • `Ok v if t evaluates to Ok v
  • `Error `Term with the error message e and usage shown according to usage (defaults to false), if t evaluates to Error (`Msg e).

See also term_result'.

val term_result' : ?usage:bool -> ('a, string) result t -> 'a t

term_result' is like term_result but with a string error case.

val cli_parse_result : ('a, [ `Msg of string ]) result t -> 'a t

cli_parse_result t is a term that evaluates to:

  • `Ok v if t evaluates to Ok v.
  • `Error `Parse with the error message e if t evaluates to Error (`Msg e).

See also cli_parse_result'.

val cli_parse_result' : ('a, string) result t -> 'a t

cli_parse_result' is like cli_parse_result but with a string error case.

val main_name : string t

main_name is a term that evaluates to the main command name; that is the name of the tool.

val choice_names : string list t

choice_names is a term that evaluates to the names of the commands that are children of the main command.

val with_used_args : 'a t -> ('a * string list) t

with_used_args t is a term that evaluates to t tupled with the arguments from the command line that where used to evaluate t.

type 'a ret = [
  1. | `Help of Manpage.format * string option
  2. | `Error of bool * string
  3. | `Ok of 'a
]

The type for command return values. See ret.

val ret : 'a ret t -> 'a t

ret v is a term whose evaluation depends on the case to which v evaluates. With :

  • `Ok v, it evaluates to v.
  • `Error (usage, e), the evaluation fails and Cmdliner prints the error e and the term's usage if usage is true.
  • `Help (format, name), the evaluation fails and Cmdliner prints a manpage in format format. If name is None this is the the main command's manpage. If name is Some c this is the man page of the sub command c of the main command.

Note. While not deprecated you are encouraged not use this API.

Deprecated Term evaluation interface

This interface is deprecated in favor of Cmdliner.Cmd. Follow the compiler deprecation warning hints to transition.

Term information

Term information defines the name and man page of a term. For simple evaluation this is the name of the program and its man page. For multiple term evaluation, this is the name of a command and its man page.

type exit_info

The type for exit status information.

  • deprecated Use Cmd.Exit.info instead.
val exit_info : ?docs:string -> ?doc:string -> ?max:int -> int -> exit_info

exit_info ~docs ~doc min ~max describe the range of exit statuses from min to max (defaults to min). doc is the man page information for the statuses, defaults to "undocumented". docs is the title of the man page section in which the statuses will be listed, it defaults to Manpage.s_exit_status.

In doc the documentation markup language can be used with following variables:

  • $(status), the value of min.
  • $(status_max), the value of max.
  • The variables mentioned in info
  • deprecated Use Cmd.Exit.info instead.
val default_exits : exit_info list

default_exits is information for exit status exit_status_success added to default_error_exits.

  • deprecated Use Cmd.Exit.defaults or Cmd.info's defaults ~exits value instead.
val default_error_exits : exit_info list

default_error_exits is information for exit statuses exit_status_cli_error and exit_status_internal_error.

  • deprecated List.filter the Cmd.Exit.defaults value instead.
type env_info

The type for environment variable information.

  • deprecated Use Cmd.Env.info instead.
val env_info : ?docs:string -> ?doc:string -> string -> env_info

env_info ~docs ~doc var describes an environment variable var. doc is the man page information of the environment variable, defaults to "undocumented". docs is the title of the man page section in which the environment variable will be listed, it defaults to Cmdliner.Manpage.s_environment.

In doc the documentation markup language can be used with following variables:

  • $(env), the value of var.
  • The variables mentioned in info
  • deprecated Use Cmd.Env.info instead.
type info

The type for term information.

  • deprecated Use Cmd.info instead.
val info : +Term (cmdliner.Cmdliner.Term)

Module Cmdliner.Term

Terms.

A term is evaluated by a program to produce a result, which can be turned into an exit status. A term made of terms referring to command line arguments implicitly defines a command line syntax.

Terms

type +'a t

The type for terms evaluating to values of type 'a.

val const : 'a -> 'a t

const v is a term that evaluates to v.

val ($) : ('a -> 'b) t -> 'a t -> 'b t

f $ v is a term that evaluates to the result of applying the evaluation of v to the one of f.

val app : ('a -> 'b) t -> 'a t -> 'b t

app is ($).

val map : ('a -> 'b) -> 'a t -> 'b t

map f t is app (const f) t.

val product : 'a t -> 'b t -> ('a * 'b) t

product t0 t1 is app (app (map (fun x y -> (x, y)) t0) t1)

module Syntax : sig ... end

let operators.

Interacting with Cmdliner's evaluation

val term_result : ?usage:bool -> ('a, [ `Msg of string ]) result t -> 'a t

term_result ~usage t evaluates to

  • `Ok v if t evaluates to Ok v
  • `Error `Term with the error message e and usage shown according to usage (defaults to false), if t evaluates to Error (`Msg e).

See also term_result'.

val term_result' : ?usage:bool -> ('a, string) result t -> 'a t

term_result' is like term_result but with a string error case.

val cli_parse_result : ('a, [ `Msg of string ]) result t -> 'a t

cli_parse_result t is a term that evaluates to:

  • `Ok v if t evaluates to Ok v.
  • `Error `Parse with the error message e if t evaluates to Error (`Msg e).

See also cli_parse_result'.

val cli_parse_result' : ('a, string) result t -> 'a t

cli_parse_result' is like cli_parse_result but with a string error case.

val main_name : string t

main_name is a term that evaluates to the main command name; that is the name of the tool.

val choice_names : string list t

choice_names is a term that evaluates to the names of the commands that are children of the main command.

val with_used_args : 'a t -> ('a * string list) t

with_used_args t is a term that evaluates to t tupled with the arguments from the command line that where used to evaluate t.

type 'a ret = [
  1. | `Help of Manpage.format * string option
  2. | `Error of bool * string
  3. | `Ok of 'a
]

The type for command return values. See ret.

val ret : 'a ret t -> 'a t

ret v is a term whose evaluation depends on the case to which v evaluates. With :

  • `Ok v, it evaluates to v.
  • `Error (usage, e), the evaluation fails and Cmdliner prints the error e and the term's usage if usage is true.
  • `Help (format, name), the evaluation fails and Cmdliner prints a manpage in format format. If name is None this is the the main command's manpage. If name is Some c this is the man page of the sub command c of the main command.

Note. While not deprecated you are encouraged not use this API.

Deprecated Term evaluation interface

This interface is deprecated in favor of Cmdliner.Cmd. Follow the compiler deprecation warning hints to transition.

Term information

Term information defines the name and man page of a term. For simple evaluation this is the name of the program and its man page. For multiple term evaluation, this is the name of a command and its man page.

type exit_info

The type for exit status information.

  • deprecated Use Cmd.Exit.info instead.
val exit_info : ?docs:string -> ?doc:string -> ?max:int -> int -> exit_info

exit_info ~docs ~doc min ~max describe the range of exit statuses from min to max (defaults to min). doc is the man page information for the statuses, defaults to "undocumented". docs is the title of the man page section in which the statuses will be listed, it defaults to Manpage.s_exit_status.

In doc the documentation markup language can be used with following variables:

  • $(status), the value of min.
  • $(status_max), the value of max.
  • The variables mentioned in info
  • deprecated Use Cmd.Exit.info instead.
val default_exits : exit_info list

default_exits is information for exit status exit_status_success added to default_error_exits.

  • deprecated Use Cmd.Exit.defaults or Cmd.info's defaults ~exits value instead.
val default_error_exits : exit_info list

default_error_exits is information for exit statuses exit_status_cli_error and exit_status_internal_error.

  • deprecated List.filter the Cmd.Exit.defaults value instead.
type env_info

The type for environment variable information.

  • deprecated Use Cmd.Env.info instead.
val env_info : ?docs:string -> ?doc:string -> string -> env_info

env_info ~docs ~doc var describes an environment variable var. doc is the man page information of the environment variable, defaults to "undocumented". docs is the title of the man page section in which the environment variable will be listed, it defaults to Cmdliner.Manpage.s_environment.

In doc the documentation markup language can be used with following variables:

  • $(env), the value of var.
  • The variables mentioned in info
  • deprecated Use Cmd.Env.info instead.
type info

The type for term information.

  • deprecated Use Cmd.info instead.
val info : ?man_xrefs:Manpage.xref list -> ?man:Manpage.block list -> ?envs:env_info list -> diff --git a/cmdliner/_doc-dir/CHANGES.md b/cmdliner/_doc-dir/CHANGES.md index 67d7f8e7..36968f93 100755 --- a/cmdliner/_doc-dir/CHANGES.md +++ b/cmdliner/_doc-dir/CHANGES.md @@ -1,3 +1,17 @@ +v1.3.0 2024-05-23 La Forclaz (VS) +--------------------------------- + +- Add let operators in `Cmdliner.Term.Syntax` (#173). Thanks to Benoit + Montagu for suggesting, Gabriel Scherer for reminding us of language + punning obscurities and Sebastien Mondet for strengthening the case + to add them. +- Pager. Support full path command lookups on Windows. + (#185). Thanks to @kit-ty-kate for the report. +- In manpage specifications use `$(iname)` in the default + introduction of the `ENVIRONMENT` section. Follow up to + #168. +- Add `Cmd.eval_value'` a variation on `Cmd.eval_value`. + v1.2.0 2023-04-10 La Forclaz (VS) --------------------------------- diff --git a/cmdliner/_doc-dir/README.md b/cmdliner/_doc-dir/README.md index 6e5ff4c1..c7d0a804 100755 --- a/cmdliner/_doc-dir/README.md +++ b/cmdliner/_doc-dir/README.md @@ -1,6 +1,6 @@ Cmdliner — Declarative definition of command line interfaces for OCaml ------------------------------------------------------------------------------- -v1.2.0 +v1.3.0 Cmdliner allows the declarative definition of command line interfaces for OCaml. diff --git a/cmdliner/_doc-dir/odoc-pages/examples.mld b/cmdliner/_doc-dir/odoc-pages/examples.mld index 8ac88212..a437b9ce 100755 --- a/cmdliner/_doc-dir/odoc-pages/examples.mld +++ b/cmdliner/_doc-dir/odoc-pages/examples.mld @@ -79,7 +79,7 @@ let cmd = `S Manpage.s_bugs; `P "Report bugs to ."; `S Manpage.s_see_also; `P "$(b,rmdir)(1), $(b,unlink)(2)" ] in - let info = Cmd.info "rm" ~version:"v1.2.0" ~doc ~man in + let info = Cmd.info "rm" ~version:"v1.3.0" ~doc ~man in Cmd.v info Term.(const rm $ prompt $ recursive $ files) let main () = exit (Cmd.eval cmd) @@ -149,7 +149,7 @@ let cmd = [ `S Manpage.s_bugs; `P "Email them to ."; ] in - let info = Cmd.info "cp" ~version:"v1.2.0" ~doc ~man ~man_xrefs in + let info = Cmd.info "cp" ~version:"v1.3.0" ~doc ~man ~man_xrefs in Cmd.v info Term.(ret (const cp $ verbose $ recurse $ force $ srcs $ dest)) @@ -258,7 +258,7 @@ let cmd = `S Manpage.s_see_also; `P "$(b,cat)(1), $(b,head)(1)" ] in - let info = Cmd.info "tail" ~version:"v1.2.0" ~doc ~man in + let info = Cmd.info "tail" ~version:"v1.3.0" ~doc ~man in Cmd.v info Term.(const tail $ lines $ follow $ verb $ pid $ files) @@ -435,7 +435,7 @@ let help_cmd = let main_cmd = let doc = "a revision control system" in let man = help_secs in - let info = Cmd.info "darcs" ~version:"v1.2.0" ~doc ~sdocs ~man in + let info = Cmd.info "darcs" ~version:"v1.3.0" ~doc ~sdocs ~man in let default = Term.(ret (const (fun _ -> `Help (`Pager, None)) $ copts_t)) in Cmd.group info ~default [initialize_cmd; record_cmd; help_cmd] diff --git a/cmdliner/_doc-dir/odoc-pages/index.mld b/cmdliner/_doc-dir/odoc-pages/index.mld index 962dd49f..db93924d 100755 --- a/cmdliner/_doc-dir/odoc-pages/index.mld +++ b/cmdliner/_doc-dir/odoc-pages/index.mld @@ -1,4 +1,4 @@ -{0 Cmdliner {%html: v1.2.0%}} +{0 Cmdliner {%html: v1.3.0%}} [Cmdliner] provides a simple and compositional mechanism to convert command line arguments to OCaml values and pass them to diff --git a/cmdliner/examples.html b/cmdliner/examples.html index a5900cde..ce6bf176 100644 --- a/cmdliner/examples.html +++ b/cmdliner/examples.html @@ -52,7 +52,7 @@ let cmd = `S Manpage.s_bugs; `P "Report bugs to <bugs@example.org>."; `S Manpage.s_see_also; `P "$(b,rmdir)(1), $(b,unlink)(2)" ] in - let info = Cmd.info "rm" ~version:"v1.2.0" ~doc ~man in + let info = Cmd.info "rm" ~version:"v1.3.0" ~doc ~man in Cmd.v info Term.(const rm $ prompt $ recursive $ files) let main () = exit (Cmd.eval cmd) @@ -101,7 +101,7 @@ let cmd = [ `S Manpage.s_bugs; `P "Email them to <bugs@example.org>."; ] in - let info = Cmd.info "cp" ~version:"v1.2.0" ~doc ~man ~man_xrefs in + let info = Cmd.info "cp" ~version:"v1.3.0" ~doc ~man ~man_xrefs in Cmd.v info Term.(ret (const cp $ verbose $ recurse $ force $ srcs $ dest)) @@ -183,7 +183,7 @@ let cmd = `S Manpage.s_see_also; `P "$(b,cat)(1), $(b,head)(1)" ] in - let info = Cmd.info "tail" ~version:"v1.2.0" ~doc ~man in + let info = Cmd.info "tail" ~version:"v1.3.0" ~doc ~man in Cmd.v info Term.(const tail $ lines $ follow $ verb $ pid $ files) @@ -330,7 +330,7 @@ let help_cmd = let main_cmd = let doc = "a revision control system" in let man = help_secs in - let info = Cmd.info "darcs" ~version:"v1.2.0" ~doc ~sdocs ~man in + let info = Cmd.info "darcs" ~version:"v1.3.0" ~doc ~sdocs ~man in let default = Term.(ret (const (fun _ -> `Help (`Pager, None)) $ copts_t)) in Cmd.group info ~default [initialize_cmd; record_cmd; help_cmd] diff --git a/ppx_yojson_conv_lib/_doc-dir/LICENSE.md b/ppx_yojson_conv_lib/_doc-dir/LICENSE.md index f45a250e..55cdc790 100644 --- a/ppx_yojson_conv_lib/_doc-dir/LICENSE.md +++ b/ppx_yojson_conv_lib/_doc-dir/LICENSE.md @@ -1,6 +1,6 @@ The MIT License -Copyright (c) 2019--2023 Jane Street Group, LLC +Copyright (c) 2019--2024 Jane Street Group, LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal