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
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
(**************************************************************************)
(* *)
(* This file is part of Frama-C. *)
(* *)
(* Copyright (C) 2007-2010 *)
(* CEA (Commissariat l'nergie atomique et aux nergies *)
(* alternatives) *)
(* *)
(* you can redistribute it and/or modify it under the terms of the GNU *)
(* Lesser General Public License as published by the Free Software *)
(* Foundation, version 2.1. *)
(* *)
(* It is distributed in the hope that it will be useful, *)
(* but WITHOUT ANY WARRANTY; without even the implied warranty of *)
(* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *)
(* GNU Lesser General Public License for more details. *)
(* *)
(* See the GNU Lesser General Public License version 2.1 *)
(* for more details (enclosed in the file licenses/LGPLv2.1). *)
(* *)
(**************************************************************************)
(* -------------------------------------------------------------------------- *)
(** Logging Services for Frama-C Kernel and Plugins.
@since Beryllium-20090601-beta1 *)
(* -------------------------------------------------------------------------- *)
open Format
type kind = Result | Feedback | Debug | Warning | Error | Failure
(** @since Beryllium-20090601-beta1 *)
type source = { src_file : string ; src_line : int }
(** @since Beryllium-20090601-beta1 *)
type event = {
evt_kind : kind ;
evt_plugin : string ;
evt_source : source option ;
evt_message : string ;
}
(** @since Beryllium-20090601-beta1 *)
type 'a pretty_printer =
?current:bool -> ?source:source ->
?emitwith:(event -> unit) -> ?echo:bool -> ?once:bool ->
?append:(Format.formatter -> unit) ->
('a,formatter,unit) format -> 'a
(** @since Beryllium-20090601-beta1 *)
type ('a,'b) pretty_aborter =
?current:bool -> ?source:source -> ?echo:bool ->
?append:(Format.formatter -> unit) ->
('a,formatter,unit,'b) format4 -> 'a
(** @since Beryllium-20090601-beta1 *)
(* -------------------------------------------------------------------------- *)
(** {2 Exception Registry}
@plugin development guide
@since Beryllium-20090601-beta1 *)
(* -------------------------------------------------------------------------- *)
exception AbortError of string (** Plug-in name *)
(** User error that prevents a plugin to terminate.
@since Beryllium-20090601-beta1 *)
exception AbortFatal of string (** Plug-in name *)
(** Internal error that prevents a plugin to terminate.
@since Beryllium-20090601-beta1 *)
exception FeatureRequest of string * string
(** Raise by [not_yet_implemented].
You may catch [FeatureRequest(p,r)] to support degenerated behavior.
The responsible plugin is 'p' and the feature request is 'r'. *)
(* -------------------------------------------------------------------------- *)
(** {2 Plugin Interface}
@plugin development guide
@since Beryllium-20090601-beta1 *)
(* -------------------------------------------------------------------------- *)
(** @since Beryllium-20090601-beta1 *)
module type Messages = sig
val verbose_atleast : int -> bool
(** @since Beryllium-20090601-beta1 *)
val debug_atleast : int -> bool
(** @since Beryllium-20090601-beta1 *)
val result : ?level:int -> 'a pretty_printer
(** Results of analysis. Default level is 1.
@since Beryllium-20090601-beta1 *)
val feedback : ?level:int -> 'a pretty_printer
(** Progress and feedback. Level is tested against the verbose.
@since Beryllium-20090601-beta1 *)
val debug : ?level:int -> 'a pretty_printer
(** Debugging information dedicated to Plugin developpers.
Default level is 1.
@since Beryllium-20090601-beta1 *)
val warning : 'a pretty_printer
(** Hypothesis and restrictions.
@since Beryllium-20090601-beta1 *)
val error : 'a pretty_printer
(** user error: syntax/typing error, bad expected input, etc.
@since Beryllium-20090601-beta1 *)
val abort : ('a,'b) pretty_aborter
(** user error stopping the plugin.
@raise AbortError with the channel name.
@since Beryllium-20090601-beta1 *)
val failure : 'a pretty_printer
(** internal error of the plug-in. *)
val fatal : ('a,'b) pretty_aborter
(** internal error of the plug-in.
@raise AbortFatal with the channel name.
@since Beryllium-20090601-beta1 *)
val verify : bool -> ('a,bool) pretty_aborter
(** If the first argument is [true], return [true] and do nothing else,
otherwise, send the message on the {i fatal} channel and return
[false].
The intended usage is: [assert (verify e "Bla...") ;].
@since Beryllium-20090601-beta1 *)
val not_yet_implemented : ('a,formatter,unit,'b) format4 -> 'a
(** raises [FeatureRequest] but {i do not} send any message.
If the exception is not catched, Frama-C displays a feature-request
message to the user.
@since Beryllium-20090901 *)
val deprecated: string -> now:string -> ('a -> 'b) -> ('a -> 'b)
(** [deprecated s ~now f] indicates that the use of [f] of name [s] is now
deprecated. It should be replaced by [now].
@return the given function itself
@since Lithium-20081201 in Extlib
@since Beryllium-20090902 *)
val with_result : (event -> 'b) -> ('a,'b) pretty_aborter
(** @since Beryllium-20090601-beta1 *)
val with_warning : (event -> 'b) -> ('a,'b) pretty_aborter
(** @since Beryllium-20090601-beta1 *)
val with_error : (event -> 'b) -> ('a,'b) pretty_aborter
(** @since Beryllium-20090601-beta1 *)
val with_failure : (event -> 'b) -> ('a,'b) pretty_aborter
(** @since Beryllium-20090601-beta1 *)
val log : ?kind:kind -> ?verbose:int -> ?debug:int -> 'a pretty_printer
(** Generic log routine. The default kind is [Result]. Use cases (with
[n,m > 0]):
- [log ~verbose:n]: emit the message only when verbosity level is
at least [n].
- [log ~debug:n]: emit the message only when debugging level is
at least [n].
- [log ~verbose:n ~debug:m]: any debugging or verbosity level is
sufficient.
@since Beryllium-20090901 *)
val with_log : (event -> 'b) -> ?kind:kind -> ('a,'b) pretty_aborter
(** @since Beryllium-20090901 *)
val register : kind -> (event -> unit) -> unit
(** Local registry for listeners. *)
val register_tag_handlers : (string -> string) * (string -> string) -> unit
end
(** Each plugin has its own channel to output messages.
This functor should not be directly applied by plug-in developer.
They should apply {!Plugin.Register} instead.
@since Beryllium-20090601-beta1 *)
module Register
(P : sig
val channel : string
val label : string
val verbose_atleast : int -> bool
val debug_atleast : int -> bool
end)
: Messages
(* -------------------------------------------------------------------------- *)
(** {2 Echo and Notification} *)
(* -------------------------------------------------------------------------- *)
val set_echo : ?plugin:string -> ?kind:kind list -> bool -> unit
(** Turns echo on or off. Applies to all channel unless specified,
and all kind of messages unless specified.
@since Beryllium-20090601-beta1 *)
val add_listener : ?plugin:string -> ?kind:kind list -> (event -> unit) -> unit
(** Register a hook that is called each time an event is
emitted. Applies to all channel unless specified,
and all kind of messages unless specified.
@since Beryllium-20090601-beta1 *)
val echo : event -> unit
(** Display an event of the terminal, unless echo has been turned off.
@since Beryllium-20090601-beta1 *)
val notify : event -> unit
(** Send an event over the associated listeners.
@since Beryllium-20090601-beta1 *)
val reset_once_flag : unit -> unit
(** Reset the [once] flag of pretty-printers. Messages already printed
will be printed again.
@since Boron-20100401 *)
(* -------------------------------------------------------------------------- *)
(** {2 Channel interface}
This is the {i low-level} interface to logging services.
Not to be used by casual users.
*)
(* -------------------------------------------------------------------------- *)
type channel
(** @since Beryllium-20090601-beta1 *)
val new_channel : string -> channel
(** @since Beryllium-20090901 *)
type prefix =
| Label of string
| Prefix of string
| Indent of int
val log_channel : channel ->
?kind:kind -> ?prefix:prefix -> 'a pretty_printer
(** logging function to user-created channel.
@since Beryllium-20090901 *)
val with_log_channel : channel -> (event -> 'b) ->
?kind:kind -> ?prefix:prefix -> ('a,'b) pretty_aborter
(** logging function to user-created channel.
@since Beryllium-20090901 *)
val kernel_channel_name: string
(** the reserved channel name used by the Frama-C kernel.
@since Beryllium-20090601-beta1 *)
val kernel_label_name: string
(** the reserved label name used by the Frama-C kernel.
@since Beryllium-20090601-beta1 *)
val set_current_source : (unit -> source) -> unit
(** @since Beryllium-20090601-beta1 *)
(* -------------------------------------------------------------------------- *)
(** {2 Terminal interface}
This is the {i low-level} interface to logging services.
Not to be used by casual users. *)
(* -------------------------------------------------------------------------- *)
val null : formatter
(** Prints nothing.
@since Beryllium-20090901 *)
val nullprintf : ('a,formatter,unit) format -> 'a
(** Discards the message and returns unit.
@since Beryllium-20090901 *)
val with_null : (unit -> 'b) -> ('a,formatter,unit,'b) format4 -> 'a
(** Discards the message and call the continuation.
@since Beryllium-20090901 *)
val set_output : (string -> int -> int -> unit) -> (unit -> unit) -> unit
(** This function has the same parameters as Format.make_formatter.
@since Beryllium-20090901 *)
val print_on_output : ('a,Format.formatter,unit) format -> 'a
(** Direct printing on output.
Message echo is delayed until the output is finished.
Then, the output is flushed and all pending message are echoed.
Notification of listeners is not delayed, however.
Can not be recursively invoked.
@since Beryllium-20090901 *)
val print_delayed : ('a,Format.formatter,unit) format -> 'a
(** Direct printing on output. Same as [print_on_output], except
that message echo is not delayed until text material is actually
written. This gives an chance for formatters to emit messages
before actual pretty printing.
Can not be recursively invoked.
@since Beryllium-20090901 *)
|
