Debian Codegraph @

vendor/opam/src/core/opamConsole.mli

raw
1 (**************************************************************************)
2 (* *)
3 (* Copyright 2012-2019 OCamlPro *)
4 (* Copyright 2012 INRIA *)
5 (* *)
6 (* All rights reserved. This file is distributed under the terms of the *)
7 (* GNU Lesser General Public License version 2.1, with the special *)
8 (* exception on linking described in the file LICENSE. *)
9 (* *)
10 (**************************************************************************)
11
12 (** Console output, ANSI color, logging and user querying *)
13
14 (** Global configuration parameters (read from OpamGlobalConfig, and the
15 environment when necessary) *)
16
17 val debug: unit -> bool
18 val verbose: unit -> bool
19 val color: unit -> bool
20 val utf8: unit -> bool
21 val utf8_extended: unit -> bool
22 val disp_status_line: unit -> bool
23
24 (** General text formatting *)
25
26 (** Settable attributes for ANSI terminal output. Nesting is generally not
27 handled. *)
28 type text_style =
29 [ `black
30 | `blue
31 | `bold
32 | `crossed
33 | `cyan
34 | `green
35 | `magenta
36 | `red
37 | `underline
38 | `white
39 | `yellow ]
40
41 (** Helper coloring functions. Returns the string unchanged if color is
42 disabled *)
43 val colorise : text_style -> string -> string
44 val colorise' : text_style list -> string -> string
45 val acolor : text_style -> unit -> string -> string
46 val acolor_w : int -> text_style -> Format.formatter -> string -> unit
47
48 module Symbols : sig
49 val rightwards_arrow : Uchar.t
50 val box_drawings_light_down_and_right : Uchar.t
51 val box_drawings_light_horizontal : Uchar.t
52 val box_drawings_light_vertical : Uchar.t
53 val box_drawings_light_up_and_right : Uchar.t
54 val box_drawings_light_right : Uchar.t
55 val circled_division_slash : Uchar.t
56 val asterisk_operator : Uchar.t
57 val north_east_arrow : Uchar.t
58 val south_east_arrow : Uchar.t
59 val clockwise_open_circle_arrow : Uchar.t
60 val greek_small_letter_lambda : Uchar.t
61 val latin_capital_letter_o_with_stroke : Uchar.t
62 val six_pointed_black_star : Uchar.t
63 val upwards_arrow : Uchar.t
64 val downwards_arrow : Uchar.t
65 val up_down_arrow : Uchar.t
66 val downwards_double_arrow : Uchar.t
67 val downwards_black_arrow : Uchar.t
68 val black_down_pointing_triangle : Uchar.t
69 end
70
71 val utf8_symbol:
72 Uchar.t -> ?alternates:Uchar.t list -> string -> string
73
74 (** Logging *)
75
76 (** Timers, only active when debug is on. Returns the time between the
77 application to each argument, in seconds *)
78 val timer : unit -> unit -> float
79
80 (** [log section ~level fmt args]. Used for debug messages, default
81 level is 1 *)
82 val log : string -> ?level:int -> ('a, Format.formatter, unit) format -> 'a
83
84 (** Helper to pass stringifiers to log (use [log "%a" (slog to_string) x]
85 rather than [log "%s" (to_string x)] to avoid costly unneeded
86 stringifications *)
87 val slog : ('a -> string) -> Format.formatter -> 'a -> unit
88
89 val error : ('a, unit, string, unit) format4 -> 'a
90 val warning : ('a, unit, string, unit) format4 -> 'a
91 val note : ('a, unit, string, unit) format4 -> 'a
92
93 (** Message without prefix, reformat or newline, to stderr (useful to continue
94 error messages without repeating "[ERROR]") *)
95 val errmsg : ('a, unit, string, unit) format4 -> 'a
96
97 val error_and_exit :
98 OpamStd.Sys.exit_reason -> ('a, unit, string, 'b) format4 -> 'a
99 val msg : ('a, unit, string, unit) format4 -> 'a
100 val formatted_msg : ?indent:int -> ('a, unit, string, unit) format4 -> 'a
101 val header_msg : ('a, unit, string, unit) format4 -> 'a
102 val header_error :
103 ('a, unit, string, ('b, unit, string, unit) format4 -> 'b) format4 -> 'a
104
105 (** Erase the current line on stdout (doesn't flush stdout) *)
106 val carriage_delete: unit -> unit
107
108 (** Display a dynamic status line to stdout, that will be erased on next call.
109 The message should not be wider than screen nor contain newlines. Use
110 {!clear_status} when the status line should be erased. *)
111 val status_line : ('a, unit, string, unit) format4 -> 'a
112
113 (** Erase the status line and restore the cursor to the start of the line *)
114 val clear_status : unit -> unit
115
116 (** Show a prompt and wait for the user to press anything. *)
117 val pause: ('a, unit, string, unit) format4 -> 'a
118
119 (** Ask the user to press Y/y/N/n to continue (returns a boolean).
120 Defaults to true (yes) if unspecified.
121 If [require_unsafe_yes] is true, it automatically answer yes to the
122 question if automatic answering is set to [`unsafe_yes] ; otherwise it will
123 prompt and wait user input if it is set [`all_yes] (interactive). Its
124 default is false. *)
125 val confirm:
126 ?require_unsafe_yes:bool -> ?default:bool ->
127 ('a, unit, string, bool) format4 -> 'a
128
129 (** Prompts the user with multiple numbered choices [(answer, message)].
130
131 [unsafe_yes], [yes] are the options to choose if the corresponding global
132 options are set.
133 [no] is the option to choose otherwise, when non interactive, on [escape].
134 [default] is the option to choose on an active empty input ("\n").
135 Max 9 options. *)
136 val menu:
137 ?default:'a -> ?unsafe_yes:'a -> ?yes:'a -> no:'a ->
138 options:('a * string) list ->
139 ('b, unit, string, 'a) format4 -> 'b
140
141 (** Read some input from the user (returns a string option) *)
142 val read: ('a, unit, string, string option) format4 -> 'a
143
144 (** Prints a table; generally called on tables passed through [align_table].
145 The default [cut] is to wrap on stdout, stderr, keep as-is otherwise.
146 [`Wrap sep] prepends [sep] on wrapped lines *)
147 val print_table:
148 ?cut:[`Wrap of string | `Truncate | `None] -> out_channel -> sep:string ->
149 string list list -> unit
150
151 (** Tree printing *)
152 module Tree : sig
153 type 'elt t
154
155 val value: 'elt t -> 'elt
156 val children: 'elt t -> 'elt t list
157
158 (** Creates a tree node. *)
159 val create: ?children:'a t list -> 'a -> 'a t
160
161 (** The symbols to be used in the tree printer. *)
162 type symbols = {
163 vert: string; (** | *)
164 hor: string; (** - *)
165 tee: string; (** |- *)
166 hook: string; (** '- *)
167 }
168
169 (** Returns UTF8 or ASCII tree symbols depending on [utf8 ()]. *)
170 val get_default_symbols: unit -> symbols
171
172 (** Prints the given tree as a Unicode/ASCII art.
173 @param printer may return a multi-line string, but should not return an
174 empty string. *)
175 val print: ?symbols:symbols -> printer:('a -> string) -> 'a t -> unit
176 end