module Annotations: sig
.. end
Annotations in the AST.
The AST should be computed before calling functions of this module.
Change in Oxygen-20120901: fully rewritten.
Consult the Plugin Development Guide for additional details.
Getting annotations
Code annotations
val code_annot : ?emitter:Emitter.t ->
?filter:(Cil_types.code_annotation -> bool) ->
Cil_types.stmt -> Cil_types.code_annotation list
Get all the code annotations attached to the given statement.
If emitter
(resp. filter
) is specified, return only the annotations that
has been generated by this emitter
(resp. that satisfies the given
predicate).
val code_annot_emitter : ?filter:(Emitter.t -> Cil_types.code_annotation -> bool) ->
Cil_types.stmt -> (Cil_types.code_annotation * Emitter.t) list
Same as
Annotations.code_annot
, but also returns the emitter who emitted the
annotation.
Since Fluorine-20130401
Function Contracts
exception No_funspec of Emitter.t
val funspec : ?emitter:Emitter.t ->
?populate:bool -> Cil_types.kernel_function -> Cil_types.funspec
Get the contract associated to the given function.
If emitter
is specified, return only the annotations that
has been generated by this emitter
. If populate
is set to false
(default is true
), then the default contract of function declaration is
generated.
val behaviors : ?emitter:Emitter.t ->
?populate:bool ->
Cil_types.kernel_function ->
(Cil_types.identified_predicate, Cil_types.identified_term)
Cil_types.behavior list
Get the behaviors clause of the contract associated to the given function.
Meaning of
emitter
and
populate
is similar to
Annotations.funspec
.
val decreases : ?emitter:Emitter.t ->
?populate:bool ->
Cil_types.kernel_function -> Cil_types.term Cil_types.variant option
If any, get the decrease clause of the contract associated to the given
function. Meaning of
emitter
and
populate
is similar to
Annotations.funspec
.
val terminates : ?emitter:Emitter.t ->
?populate:bool ->
Cil_types.kernel_function -> Cil_types.identified_predicate option
If any, get the terminates clause of the contract associated to the given
function. Meaning of
emitter
and
populate
is similar to
Annotations.funspec
.
val complete : ?emitter:Emitter.t ->
?populate:bool -> Cil_types.kernel_function -> string list list
Get the complete behaviors clause of the contract associated to the given
function. Meaning of
emitter
and
populate
is similar to
Annotations.funspec
.
val disjoint : ?emitter:Emitter.t ->
?populate:bool -> Cil_types.kernel_function -> string list list
If any, get the disjoint behavior clause of the contract associated to the
given function. Meaning of
emitter
and
populate
is similar to
Annotations.funspec
.
Global Annotations
val model_fields : ?emitter:Emitter.t -> Cil_types.typ -> Cil_types.model_info list
returns the model fields attached to a given type (either directly or
because the type is a typedef of something that has model fields.
Since Fluorine-20130401
Iterating over annotations
val iter_code_annot : (Emitter.t -> Cil_types.code_annotation -> unit) -> Cil_types.stmt -> unit
Iter on each code annotation attached to the given statement.
val fold_code_annot : (Emitter.t -> Cil_types.code_annotation -> 'a -> 'a) ->
Cil_types.stmt -> 'a -> 'a
Fold on each code annotation attached to the given statement.
val iter_all_code_annot : (Cil_types.stmt -> Emitter.t -> Cil_types.code_annotation -> unit) -> unit
Iter on each code annotation of the program.
val fold_all_code_annot : (Cil_types.stmt -> Emitter.t -> Cil_types.code_annotation -> 'a -> 'a) ->
'a -> 'a
Fold on each code annotation of the program.
val iter_global : (Emitter.t -> Cil_types.global_annotation -> unit) -> unit
Iter on each global annotation of the program.
val fold_global : (Emitter.t -> Cil_types.global_annotation -> 'a -> 'a) -> 'a -> 'a
Fold on each global annotation of the program.
val iter_requires : (Emitter.t -> Cil_types.identified_predicate -> unit) ->
Cil_types.kernel_function -> string -> unit
Iter on the requires of the corresponding behavior.
Since Fluorine-20130401
val fold_requires : (Emitter.t -> Cil_types.identified_predicate -> 'a -> 'a) ->
Cil_types.kernel_function -> string -> 'a -> 'a
Fold on the requires of the corresponding behavior.
val iter_assumes : (Emitter.t -> Cil_types.identified_predicate -> unit) ->
Cil_types.kernel_function -> string -> unit
Iter on the assumes of the corresponding behavior.
Since Fluorine-20130401
val fold_assumes : (Emitter.t -> Cil_types.identified_predicate -> 'a -> 'a) ->
Cil_types.kernel_function -> string -> 'a -> 'a
Fold on the assumes of the corresponding behavior.
val iter_ensures : (Emitter.t ->
Cil_types.termination_kind * Cil_types.identified_predicate -> unit) ->
Cil_types.kernel_function -> string -> unit
Iter on the ensures of the corresponding behavior.
Since Fluorine-20130401
val fold_ensures : (Emitter.t ->
Cil_types.termination_kind * Cil_types.identified_predicate -> 'a -> 'a) ->
Cil_types.kernel_function -> string -> 'a -> 'a
Fold on the ensures of the corresponding behavior.
val iter_assigns : (Emitter.t -> Cil_types.identified_term Cil_types.assigns -> unit) ->
Cil_types.kernel_function -> string -> unit
Iter on the assigns of the corresponding behavior.
Since Fluorine-20130401
val fold_assigns : (Emitter.t -> Cil_types.identified_term Cil_types.assigns -> 'a -> 'a) ->
Cil_types.kernel_function -> string -> 'a -> 'a
Fold on the assigns of the corresponding behavior.
val iter_allocates : (Emitter.t -> Cil_types.identified_term Cil_types.allocation -> unit) ->
Cil_types.kernel_function -> string -> unit
Iter on the allocates of the corresponding behavior.
Since Fluorine-20130401
val fold_allocates : (Emitter.t -> Cil_types.identified_term Cil_types.allocation -> 'a -> 'a) ->
Cil_types.kernel_function -> string -> 'a -> 'a
Fold on the allocates of the corresponding behavior.
val iter_behaviors : (Emitter.t ->
(Cil_types.identified_predicate, Cil_types.identified_term)
Cil_types.behavior -> unit) ->
Cil_types.kernel_function -> unit
Iter on the behaviors of the given kernel function.
Since Fluorine-20130401
val fold_behaviors : (Emitter.t ->
(Cil_types.identified_predicate, Cil_types.identified_term)
Cil_types.behavior -> 'a -> 'a) ->
Cil_types.kernel_function -> 'a -> 'a
Fold on the behaviors of the given kernel function.
val iter_complete : (Emitter.t -> string list -> unit) -> Cil_types.kernel_function -> unit
Iter on the complete clauses of the given kernel function.
Since Fluorine-20130401
val fold_complete : (Emitter.t -> string list -> 'a -> 'a) ->
Cil_types.kernel_function -> 'a -> 'a
Fold on the complete clauses of the given kernel function.
val iter_disjoint : (Emitter.t -> string list -> unit) -> Cil_types.kernel_function -> unit
Iter on the disjoint clauses of the given kernel function.
Since Fluorine-20130401
val fold_disjoint : (Emitter.t -> string list -> 'a -> 'a) ->
Cil_types.kernel_function -> 'a -> 'a
Fold on the disjoint clauses of the given kernel function.
val iter_terminates : (Emitter.t -> Cil_types.identified_predicate -> unit) ->
Cil_types.kernel_function -> unit
apply f to the terminates predicate if any.
Since Fluorine-20130401
val fold_terminates : (Emitter.t -> Cil_types.identified_predicate -> 'a -> 'a) ->
Cil_types.kernel_function -> 'a -> 'a
apply f to the terminates predicate if any.
val iter_decreases : (Emitter.t -> Cil_types.term Cil_types.variant -> unit) ->
Cil_types.kernel_function -> unit
apply f to the decreases term if any.
Since Fluorine-20130401
val fold_decreases : (Emitter.t -> Cil_types.term Cil_types.variant -> 'a -> 'a) ->
Cil_types.kernel_function -> 'a -> 'a
apply f to the decreases term if any.
Adding annotations
val add_code_annot : Emitter.t ->
?kf:Cil_types.kernel_function ->
Cil_types.stmt -> Cil_types.code_annotation -> unit
Add a new code annotation attached to the given statement. If kf
is
provided, the function runs faster.
val add_assert : Emitter.t ->
?kf:Cil_types.kernel_function ->
Cil_types.stmt -> Cil_types.predicate Cil_types.named -> unit
Add an assertion attached to the given statement. If
kf
is
provided, the function runs faster.
Consult the Plugin Development Guide for additional details.
val add_global : Emitter.t -> Cil_types.global_annotation -> unit
Add a new global annotation into the program.
val add_behaviors : ?register_children:bool ->
Emitter.t ->
Cil_types.kernel_function ->
(Cil_types.identified_predicate, Cil_types.identified_term)
Cil_types.behavior list -> unit
Add new behaviors into the contract of the given function.
if register_children
is true
(the default), inner clauses of the
behavior will also be registered by the function.
val add_decreases : Emitter.t ->
Cil_types.kernel_function -> Cil_types.term Cil_types.variant -> unit
Add a decrease clause into the contract of the given function.
No decrease clause must previously be attached to this function.
val add_terminates : Emitter.t ->
Cil_types.kernel_function -> Cil_types.identified_predicate -> unit
Add a terminates clause into the contract of the given function.
No terminates clause must previously be attached to this function.
val add_complete : Emitter.t -> Cil_types.kernel_function -> string list -> unit
Add a new complete behaviors clause into the contract of the given
function.
val add_disjoint : Emitter.t -> Cil_types.kernel_function -> string list -> unit
Add a new disjoint behaviors clause into the contract of the given
function.
val add_requires : Emitter.t ->
Cil_types.kernel_function ->
string -> Cil_types.identified_predicate list -> unit
Add new requires clauses into the given behavior (provided by its name) of
the given function.
val add_assumes : Emitter.t ->
Cil_types.kernel_function ->
string -> Cil_types.identified_predicate list -> unit
Add new assumes clauses into the given behavior (provided by its name) of
the given function.
val add_ensures : Emitter.t ->
Cil_types.kernel_function ->
string ->
(Cil_types.termination_kind * Cil_types.identified_predicate) list -> unit
Add new ensures clauses into the given behavior (provided by its name) of
the given function.
val add_assigns : keep_empty:bool ->
Emitter.t ->
Cil_types.kernel_function ->
string -> Cil_types.identified_term Cil_types.assigns -> unit
Add new assigns into the given behavior (provided by its name) of the given
function. If keep_empty
is true
and the assigns clause were empty, then
the assigns clause remains empty. (That corresponds to the ACSL semantics of
an assigns clause: if no assigns is specified, that is equivalent to assigns
everything.)
val add_allocates : Emitter.t ->
Cil_types.kernel_function ->
string -> Cil_types.identified_term Cil_types.allocation -> unit
Add new allocates into the given behavior (provided by its name) of the
given function.
Removing annotations
val remove_code_annot : Emitter.t ->
?kf:Cil_types.kernel_function ->
Cil_types.stmt -> Cil_types.code_annotation -> unit
Remove a code annotation attached to a statement. The provided emitter must
be the one that emits this annotation. Do nothing if the annotation does not
exist, or if the emitter is not ok.
val remove_global : Emitter.t -> Cil_types.global_annotation -> unit
Remove a global annotation. The provided emitter must be the one that emits
this annotation. Do nothing if the annotation does not exist, or if the
emitter is not ok.
val remove_behavior : Emitter.t ->
Cil_types.kernel_function ->
(Cil_types.identified_predicate, Cil_types.identified_term)
Cil_types.behavior -> unit
Remove a behavior attached to a function. The provided emitter must be the
one that emits this annotation. Do nothing if the annotation does not exist,
or if the emitter is not ok.
val remove_behavior_components : Emitter.t -> Cil_types.kernel_function -> Cil_types.funbehavior -> unit
remove all the component of a behavior, but keeps the name (so as to
avoid issues with disjoint/complete clauses.
val remove_decreases : Emitter.t -> Cil_types.kernel_function -> unit
Remove the decreases clause attached to a function. The provided emitter
must be the one that emits this annotation. Do nothing if the annotation
does not exist, or if the emitter is not ok.
val remove_terminates : Emitter.t -> Cil_types.kernel_function -> unit
Remove the terminates clause attached to a function. The provided emitter
must be the one that emits this annotation. Do nothing if the annotation
does not exist, or if the emitter is not ok.
val remove_complete : Emitter.t -> Cil_types.kernel_function -> string list -> unit
Remove a complete behaviors clause attached to a function. The provided
emitter must be the one that emits this annotation. Do nothing if the
annotation does not exist, or if the emitter is not ok.
val remove_disjoint : Emitter.t -> Cil_types.kernel_function -> string list -> unit
Remove a disjoint behaviors clause attached to a function. The provided
emitter must be the one that emits this annotation. Do nothing if the
annotation does not exist, or if the emitter is not ok.
val remove_requires : Emitter.t ->
Cil_types.kernel_function -> Cil_types.identified_predicate -> unit
Remove a requires clause from the spec of the given function. Do nothing
if the predicate does not exist or
was not emitted by the given emitter.
val remove_assumes : Emitter.t ->
Cil_types.kernel_function -> Cil_types.identified_predicate -> unit
Remove an assumes clause from the spec of the given function. Do nothing
if the predicate does not exist or was not emitted
by the given emitter.
val remove_ensures : Emitter.t ->
Cil_types.kernel_function ->
Cil_types.termination_kind * Cil_types.identified_predicate -> unit
Remove a post-condition from the spec of the given function. Do nothing
if the post-cond does not exist or was not emitted
by the given emitter.
val remove_allocates : Emitter.t ->
Cil_types.kernel_function ->
Cil_types.identified_term Cil_types.allocation -> unit
Remove the corresponding allocation clause. Do nothing if the clause
does not exist or was not emitted by the given emitter.
val remove_assigns : Emitter.t ->
Cil_types.kernel_function ->
Cil_types.identified_term Cil_types.assigns -> unit
Remove the corresponding assigns clause. Do nothing if the clause
does not exist or was not emitted by the given emitter.
Other useful functions
val has_code_annot : ?emitter:Emitter.t -> Cil_types.stmt -> bool
Returns true
iff there is some annotation attached to the given statement
(and generated by the given emitter, if any).
val emitter_of_global : Cil_types.global_annotation -> Emitter.t
Raises Not_found
if the global annotation is not registered.
Returns the emitter which generates a global annotation.
val logic_info_of_global : string -> Cil_types.logic_info list
Raises Not_found
if no global annotation declare such a variable
Returns the purely logic var of the given name
val behavior_names_of_stmt_in_kf : Cil_types.kernel_function -> string list
Returns all the behavior names included in any statement contract of the
given function.
val code_annot_of_kf : Cil_types.kernel_function ->
(Cil_types.stmt * Cil_types.code_annotation) list
Returns all the annotations attached to a statement of the given
function.
val fresh_behavior_name : Cil_types.kernel_function -> string -> string
Returns a valid behavior name for the given function and based on the given
name.
States
val code_annot_state : State.t
The state which stores all the code annotations of the program.
val funspec_state : State.t
The state which stores all the function contracts of the program.
val global_state : State.t
The state which stores all the global annotations of the program.