Debian Codegraph @

tools/spgen/source/disj_generator.mli

raw
1 (*
2 * This file is part of Coccinelle, licensed under the terms of the GPL v2.
3 * See copyright.txt in the Coccinelle source code for more information.
4 * The Coccinelle source code can be obtained at http://coccinelle.lip6.fr
5 *)
6
7 (* Handles disjunctions.
8
9 * Disjunctions need special rule generation hence the separate module:
10 * - The positions have to be the same over each disjunction case. Therefore
11 * there can at most be generated one position per disjunction case. Also,
12 * it has to be the exact same position for all cases.
13 *
14 * - Disjunctions can be used for pattern matching in Coccinelle rules, where
15 * only some cases are matched/patched. However, this may create false
16 * positives when generating a context rule from a patch rule. Therefore two
17 * rules have to be generated (aka the ugly part).
18 * This is the case when there is:
19 * - something interesting outside the disjunction
20 * - something uninteresting inside the disjunction
21 * - something interesting inside the disjunction
22 *
23 * - Disregard the above rule in cases where there is no risk of false
24 * positives - e.g. if the disjunction is the only thing in the rule.
25 * Determined by at_top flag.
26 *
27 * ----------------------------------------------------------------------------
28 * Example of rule splitting:
29 *
30 * @disj@ expression n; identifier x; @@
31 *
32 * - x = call(x);
33 * (
34 * some_function(0);
35 * |
36 * - some_function(n);
37 * + some_function(x);
38 * )
39 *
40 * The following would NOT work:
41 *
42 * @disj@ expression n; identifier x; position p1,p2; @@
43 *
44 * * x@p1 = call(x);
45 * (
46 * some_function(0);
47 * |
48 * * some_function@p2(n);
49 * )
50 *
51 * because that would match even when some_function is called on 0 (due to the
52 * first star) which we don't want. Instead we want two rules:
53 *
54 * @disj1@ expression n; identifier x; position p1,p2; @@
55 *
56 * x@p1 = call(x);
57 * (
58 * some_function(0);
59 * |
60 * some_function@p2(n);
61 * )
62 *
63 * @disj2@ expression n; identifier x; position disj1.p1, disj1.p2 @@
64 *
65 * * x@p1 = call(x);
66 * * some_function@p2(n);
67 *
68 * which would match if and only if n is not 0 (in this particular example).
69 *)
70
71 (* ------------------------------------------------------------------------- *)
72 (* DISJ GENERATION FUNCTIONS *)
73
74 (* These types are just aliases for functions that take some AST0 component and
75 * a snapshot, handle the component with regards to the input snapshot and
76 * return the resulting snapshot.
77 *)
78
79 type statement_dots_fn =
80 Ast0_cocci.statement Ast0_cocci.dots -> Snapshot.t -> Snapshot.t
81
82 type string_fn = string Ast0_cocci.mcode -> Snapshot.t -> Snapshot.t
83
84 type statement_fn = Ast0_cocci.statement -> Snapshot.t -> Snapshot.t
85
86 type expression_fn = Ast0_cocci.expression -> Snapshot.t -> Snapshot.t
87
88 type ident_fn = Ast0_cocci.ident -> Snapshot.t -> Snapshot.t
89
90 type declaration_fn = Ast0_cocci.declaration -> Snapshot.t -> Snapshot.t
91
92 type field_fn = Ast0_cocci.field -> Snapshot.t -> Snapshot.t
93
94 (* These functions take a disjunction component (stmt, expr, ident, decl) and a
95 * snapshot + some other things, and perform the disjunction rule generation.
96 * Fails if the disjunction component is NOT a disjunction.
97 *
98 * All functions take:
99 * - strfn: a function to handle string_mcodes.
100 * - some Ast0 component, ie. the thing that contains the disjunction.
101 * - some function to handle the Ast0 component.
102 * - at_top: a flag that indicates whether it is safe to just generate one
103 * rule, even though the disjunction uses pattern matching.
104 *
105 * Return:
106 * - an updated snapshot with the inserted disjunction, possibly an extra
107 * disjunction rule if needed.
108 *)
109
110 val generate_statement :
111 stmtdotsfn:statement_dots_fn ->
112 strfn:string_fn ->
113 stmtfn:statement_fn ->
114 stmt:Ast0_cocci.statement ->
115 at_top:bool ->
116 Snapshot.t ->
117 Snapshot.t
118
119 val generate_expression :
120 strfn:string_fn ->
121 exprfn:expression_fn ->
122 expr:Ast0_cocci.expression ->
123 at_top:bool ->
124 Snapshot.t ->
125 Snapshot.t
126
127 val generate_ident :
128 strfn:string_fn ->
129 identfn:ident_fn ->
130 ident:Ast0_cocci.ident ->
131 at_top:bool ->
132 Snapshot.t ->
133 Snapshot.t
134
135 val generate_declaration :
136 strfn:string_fn ->
137 declfn:declaration_fn ->
138 decl:Ast0_cocci.declaration ->
139 at_top:bool ->
140 Snapshot.t ->
141 Snapshot.t
142
143 val generate_field :
144 strfn:string_fn ->
145 fieldfn:field_fn ->
146 field:Ast0_cocci.field ->
147 at_top:bool ->
148 Snapshot.t ->
149 Snapshot.t