package core

  1. Overview
  2. Docs
package core
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Source file command_shape_intf.ml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
(** A [Command_shape] allows limited introspection of a [Command], including subcommands,
    arguments, and doc strings. Think of it as machine-readable help. *)

open! Import
open! Std_internal

module type Command_shape = sig
  module Anons : sig
    module Grammar : sig
      type t =
        | Zero
        | One of string
        | Many of t
        | Maybe of t
        | Concat of t list
        | Ad_hoc of string
      [@@deriving bin_shape, compare, sexp_of]

      include Invariant.S with type t := t

      val usage : t -> string
    end

    type t =
      | Usage of string
      (** When exec'ing an older binary whose help sexp doesn't expose the grammar. *)
      | Grammar of Grammar.t
    [@@deriving bin_shape, compare, sexp_of]
  end

  module Num_occurrences : sig
    type t =
      { at_least_once : bool
      ; at_most_once : bool
      }
    [@@deriving compare, enumerate, fields, sexp_of]

    val to_help_string : t -> flag_name:string -> string
  end

  module Flag_info : sig
    type t =
      { name : string (** See [flag_name] below. *)
      ; doc : string
      ; aliases : string list
      }
    [@@deriving compare, fields, sexp_of]

    (** [flag_name] infers the string which one would pass on the command line. It is not
        the same as the raw [name] field, which additionally encodes [num_occurrences] and
        [requires_arg] (sort of). *)
    val flag_name : t -> string Or_error.t

    val num_occurrences : t -> Num_occurrences.t Or_error.t

    (** [requires_arg] gives undefined behavior on [escape] flags. This is a limitation of
        the underlying shape representation. *)
    val requires_arg : t -> bool Or_error.t

    include
      Binable.S with type t := t
      [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Flag_info]."]

    val t_of_sexp : Sexp.t -> t
    [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Flag_info]."]
  end

  module Flag_help_display : sig
    type t = Flag_info.t list

    val sort : t -> t
    val to_string : t -> string
  end

  module Base_info : sig
    type t =
      { summary : string
      ; readme : string option
      ; anons : Anons.t
      ; flags : Flag_info.t list
      }
    [@@deriving compare, fields, sexp_of]

    (** [find_flag t prefix] looks up the flag, if any, to which [prefix] refers.

        It raises if [prefix] does not begin with [-] as all flags should.

        [find_flag] does not consider [aliases_excluded_from_help], and it assumes that
        all flags can be passed by prefix. These are limitations in the underlying shape
        representation. *)
    val find_flag : t -> string -> Flag_info.t Or_error.t

    val get_usage : t -> string

    include
      Binable.S with type t := t
      [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Base_info]."]

    val t_of_sexp : Sexp.t -> t
    [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Base_info]."]
  end

  module Group_info : sig
    type 'a t =
      { summary : string
      ; readme : string option
      ; subcommands : (string, 'a) List.Assoc.t Lazy.t
      }
    [@@deriving compare, fields, sexp_of]

    val find_subcommand : 'a t -> string -> 'a Or_error.t
    val map : 'a t -> f:('a -> 'b) -> 'b t

    include
      Binable.S1 with type 'a t := 'a t
      [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Group_info]."]

    val t_of_sexp : (Sexp.t -> 'a) -> Sexp.t -> 'a t
    [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Group_info]."]
  end

  module Exec_info : sig
    type t =
      { summary : string
      ; readme : string option
      ; working_dir : string
      ; path_to_exe : string
      ; child_subcommand : string list
      }
    [@@deriving compare, fields, sexp_of]

    include
      Binable.S with type t := t
      [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Exec_info]."]

    val t_of_sexp : Sexp.t -> t
    [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Exec_info]."]
  end

  (** Fully forced shapes are comparable and serializable. *)
  module Fully_forced : sig
    type t =
      | Basic of Base_info.t
      | Group of t Group_info.t
      | Exec of Exec_info.t * t
    [@@deriving compare, sexp_of]

    val expanded_subcommands : t -> string list list

    include
      Binable.S with type t := t
      [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Fully_forced]."]

    val t_of_sexp : Sexp.t -> t
    [@@deprecated "[since 2020-04] Use [Command.Stable.Shape.Fully_forced]."]
  end

  type t =
    | Basic of Base_info.t
    | Group of t Group_info.t
    | Exec of Exec_info.t * (unit -> t)
    | Lazy of t Lazy.t

  val fully_forced : t -> Fully_forced.t
  val get_summary : t -> string

  module Sexpable : sig
    type t =
      | Base of Base_info.t
      | Group of t Group_info.t
      | Exec of Exec_info.t
      | Lazy of t Lazy.t
    [@@deriving sexp_of]

    val extraction_var : string
    val supported_versions : Set.M(Int).t

    module Versioned : sig
      type t [@@deriving sexp]
    end

    val of_versioned : Versioned.t -> t
    val to_versioned : t -> version_to_use:int -> Versioned.t
  end

  val help_text : [ `Use_Command_unix ]
  [@@deprecated "[since 2021-03] Use [Command_unix]"]

  module Stable : sig
    module Anons : sig
      module Grammar : sig
        module V1 : Stable_without_comparator with type t = Anons.Grammar.t
      end

      module V2 : Stable_without_comparator with type t = Anons.t
    end

    module Flag_info : sig
      module V1 : Stable_without_comparator with type t = Flag_info.t
    end

    module Base_info : sig
      module V2 : Stable_without_comparator with type t = Base_info.t
    end

    module Group_info : sig
      module V2 : Stable1 with type 'a t = 'a Group_info.t
    end

    module Exec_info : sig
      module V3 : Stable_without_comparator with type t = Exec_info.t
    end

    module Fully_forced : sig
      module V1 : Stable_without_comparator with type t = Fully_forced.t
    end
  end

  module Private : sig
    module Key_type : sig
      type t =
        | Subcommand
        | Flag

      val to_string : t -> string
    end

    val abs_path : dir:string -> string -> string
    val help_screen_compare : string -> string -> int

    val lookup_expand
      :  (string * ('a * [ `Full_match_required | `Prefix ])) list
      -> string
      -> Key_type.t
      -> (string * 'a, string) result

    val word_wrap : string -> int -> string list
  end
end