% our implementation using the Menhir parser generator \cite{menhir}.
This document presents the grammar of the SmPL language used by the
-\href{http://www.emn.fr/x-info/coccinelle}{Coccinelle tool}. For the most
+\href{http://coccinelle.lip6.fr/}{Coccinelle tool}. For the most
part, the grammar is written using standard notation. In some rules,
however, the left-hand side is in all uppercase letters. These are
macros, which take one or more grammar rule right-hand-sides as
\RULE{\rt{include\_cocci}}
\CASE{using \NT{string}}
\CASE{using \NT{pathToIsoFile}}
+ \CASE{virtual \T{id} \ANY{, \T{id}}}
\RULE{\rt{changeset}}
\CASE{\NT{metavariables} \NT{transformation}}
\texttt{@} and considers that to be the beginning of the next rule, even if
\texttt{@} occurs within e.g., a string or a comment.
+\texttt{virtual} keyword is used to declare virtual rules. Virtual
+rules may be subsequently used as a dependency for the rules in the
+SmPL file. Whether a virtual rule is defined or not is controlled by
+the \texttt{-D} option on the command line.
+
% Between the metavariables and the transformation rule, there can be a
% specification of constraints on the names of the old and new files,
% analogous to the filename specifications in the standard patch syntax.
\RULE{\rt{rulename}}
\CASE{\T{id} \OPT{extends \T{id}} \OPT{depends on \NT{dep}} \opt{\NT{iso}}
\opt{\NT{disable-iso}} \opt{\NT{exists}} \opt{expression}}
- \CASE{script:\T{language} \OPT{depends on \NT{dep}}}
-
- \RULE{\rt{script\_init\_final}}
- \CASE{initialize:\T{language}}
- \CASE{finalize:\T{language}}
\RULE{\rt{dep}}
\CASE{\NT{pnrule}}
isomorphisms defined in standard.iso or whatever isomorphism file has been
included. There are, however, some other isomorphisms that are built into
the implementation of Coccinelle and that can be disabled as well. Their
-names are given below. In each case, the text descibes the standard
+names are given below. In each case, the text describes the standard
behavior. Using \NT{disable-iso} with the given name disables this behavior.
\begin{itemize}
The possible types of metavariable declarations are defined by the grammar
rule below. Metavariables should occur at least once in the transformation
-immediately following their declaration. Fresh metavariables must only be
-used in {\tt +} code. These properties are not expressed in the grammar,
-but are checked by a subsequent analysis. The metavariables are designated
-according to the kind of terms they can match, such as a statement, an
-identifier, or an expression. An expression metavariable can be further
-constrained by its type.
+immediately following their declaration. Fresh identifier metavariables
+must only be used in {\tt +} code. These properties are not expressed in
+the grammar, but are checked by a subsequent analysis. The metavariables
+are designated according to the kind of terms they can match, such as a
+statement, an identifier, or an expression. An expression metavariable can
+be further constrained by its type. A declaration metavariable matches the
+declaration of one or more variables, all sharing the same type
+specification ({\em e.g.}, {\tt int a,b,c=3;}). A field metavariable does
+the same, but for structure fields.
\begin{grammar}
\RULE{\rt{metadecl}}
+ \CASE{metavariable \NT{ids} ;}
\CASE{fresh identifier \NT{ids} ;}
\CASE{identifier \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_regexp}\mth{)} ;}
- \CASE{identifier \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq}\mth{)} ;}
+ \CASE{identifier \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_virt\_or\_not\_eq}\mth{)} ;}
\CASE{parameter \opt{list} \NT{ids} ;}
\CASE{parameter list [ \NT{id} ] \NT{ids} ;}
+ \CASE{parameter list [ \NT{const} ] \NT{ids} ;}
\CASE{type \NT{ids} ;}
\CASE{statement \opt{list} \NT{ids} ;}
+ \CASE{declaration \NT{ids} ;}
+ \CASE{field \opt{list} \NT{ids} ;}
\CASE{typedef \NT{ids} ;}
\CASE{declarer name \NT{ids} ;}
% \CASE{\opt{local} function \NT{pmid\_with\_not\_eq\_list} ;}
\CASE{\opt{local} idexpression \some{*} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq}\mth{)} ;}
\CASE{expression list \NT{ids} ;}
\CASE{expression \some{*} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq}\mth{)} ;}
+ \CASE{expression enum \any{*} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq}\mth{)} ;}
+ \CASE{expression struct \any{*} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq}\mth{)} ;}
+ \CASE{expression union \any{*} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq}\mth{)} ;}
\CASE{expression \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_ceq}\mth{)} ;}
- \CASE{expression list [ ident ] \NT{ids} ;}
+ \CASE{expression list [ \NT{id} ] \NT{ids} ;}
+ \CASE{expression list [ \NT{const} ] \NT{ids} ;}
\CASE{\NT{ctype} [ ] \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq}\mth{)} ;}
\CASE{\NT{ctype} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_ceq}\mth{)} ;}
\CASE{\ttlb \NT{ctypes}\ttrb~\any{*} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_ceq}\mth{)} ;}
\CASE{position \opt{any} \NT{COMMA\_LIST}\mth{(}\NT{pmid\_with\_not\_eq\_mid}\mth{)} ;}
\end{grammar}
+A metavariable declaration local idexpression v means that v is restricted
+to be a local variable. If it should just be a variable, but not
+necessarily a local one, then drop local. A more complex description of a
+location, such as a->b is considered to be an expression, not an
+ideexpression.
+
+Constant is for constants, such as 27. But it also considers an identifier
+that is all capital letters (possibly containing numbers) as a constant as
+well, because the names gives to macros in Linux usually have this form.
+
+An identifier is the name of a structure field, a macro, a function, or a
+variable. Is is the name of something rather than an expression that has a
+value. But an identifier can be used in the position of an expression as
+well, where it represents a variable.
+
+It is possible to specify that an expression list or a parameter list
+metavariable should match a specific number of expressions or parameters.
+
\begin{grammar}
\RULE{\rt{ids}}
\CASE{\NT{COMMA\_LIST}\mth{(}\NT{pmid}\mth{)}}
\RULE{\rt{pmid\_with\_regexp}}
\CASE{\NT{pmid} \~{}= \NT{regexp}}
+ \CASE{\NT{pmid} !\~{}= \NT{regexp}}
\RULE{\rt{pmid\_with\_not\_eq}}
- \CASE{\NT{pmid} \OPT{!= \T{id}}}
- \CASE{\NT{pmid} \OPT{!= \ttlb~\NT{COMMA\_LIST}\mth{(}\T{id}\mth{)} \ttrb}}
+ \CASE{\NT{pmid} \OPT{!= \NT{id\_or\_meta}}}
+ \CASE{\NT{pmid}
+ \OPT{!= \ttlb~\NT{COMMA\_LIST}\mth{(}\NT{id\_or\_meta}\mth{)} \ttrb}}
+
+ \RULE{\rt{pmid\_with\_virt\_or\_not\_eq}}
+ \CASE{virtual.\T{id}}
+ \CASE{\NT{pmid\_with\_not\_eq}}
\RULE{\rt{pmid\_with\_not\_ceq}}
\CASE{\NT{pmid} \OPT{!= \NT{id\_or\_cst}}}
\CASE{\T{id}}
\CASE{\T{integer}}
+ \RULE{\rt{id\_or\_meta}}
+ \CASE{\T{id}}
+ \CASE{\T{rulename\_id}.\T{id}}
+
\RULE{\rt{pmid\_with\_not\_eq\_mid}}
\CASE{\NT{pmid} \OPT{!= \NT{mid}}}
\CASE{\NT{pmid} \OPT{!= \ttlb~\NT{COMMA\_LIST}\mth{(}\NT{mid}\mth{)} \ttrb}}
For example, \mth{\msf{metaid}^{\ssf{Type}}} refers to a metavariable
that was declared using \texttt{type} and stands for any type.
+{\tt metavariable} declares a metavariable for which the parser tried to
+figure out the metavariable type based on the usage context. Such a
+metavariable must be used consistently. These metavariables cannot be used
+in all contexts; specifically, they cannot be used in context that would
+make the parsing ambiguous. Some examples are the leftmost term of an
+expression, such as the left-hand side of an assignment, or the type in a
+variable declaration. These restrictions may seems somewhat arbitrary from
+the user's point of view. Thus, it is better to use metavariables with
+metavariable types. If Coccinelle is given the argument {\tt
+ -parse\_cocci}, it will print information about the type that is inferred
+for each metavariable.
+
The \NT{ctype} and \NT{ctypes} nonterminals are used by both the grammar of
metavariable declarations and the grammar of transformations, and are
defined on page~\pageref{types}.
+An identifier metavariable with {\tt virtual} as its ``rule name'' is given
+a value on the command line. For example, if a semantic patch contains a
+rule that declares an identifier metavariable with the name {\tt
+ virtual.alloc}, then the command line could contain {\tt -D
+ alloc=kmalloc}. There should not be space around the {\tt =}. An
+example is in {\tt demos/vm.cocci} and {\tt demos/vm.c}.
+
\section{Metavariables for scripts}
Metavariables for scripts can only be inherited from transformation rules.
\begin{grammar}
\RULE{\rt{script\_metavariables}}
- \CASE{@ script:\NT{language} \OPT{depends on \NT{dep}} @
+ \CASE{@ script:\NT{language} \OPT{\NT{rulename}} \OPT{depends on \NT{dep}} @
\any{\NT{script\_metadecl}} @@}
- \CASE{@ initialize:\NT{language} @}
- \CASE{@ finalize:\NT{language} @}
+ \CASE{@ initialize:\NT{language} \OPT{depends on \NT{dep}} @}
+ \CASE{@ finalize:\NT{language} \OPT{depends on \NT{dep}} @}
- \RULE{\rt{language}} \CASE{python}
+ \RULE{\rt{language}} \CASE{python} \CASE{ocaml}
- \RULE{\rt{script\_metadecl}} \CASE{\T{id} <{}< \T{rulename\_id}.\T{id} ;}
+ \RULE{\rt{script\_metadecl}}
+ \CASE{\T{id} <{}< \T{rulename\_id}.\T{id} ;}
+ \CASE{\T{id} ;}
\end{grammar}
-Currently, the only scripting language that is supported is Python. The
+Currently, the only scripting languages that are supported are Python and
+OCaml, indicated using {\tt python} and {\tt ocaml}, respectively. The
set of available scripting languages may be extended at some point.
Script rules declared with \KW{initialize} are run before the treatment of
variables initialized by the other script rules, allowing information to be
transmitted from the matching process to the finalize rule.
+A script metavariable that does not specify an origin, using \texttt{<<},
+is newly declared by the script. This metavariable should be assigned to a
+string and can be inherited by subsequent rules as an identifier. In
+Python, the assignment of such a metavariable $x$ should refer to the
+metavariable as {\tt coccinelle.\(x\)}. Examples are in the files
+\texttt{demos/pythontococci.cocci} and \texttt{demos/camltococci.cocci}.
+
+In an ocaml script, the following extended form of \textit{script\_metadecl}
+may be used:
+
+\begin{grammar}
+ \RULE{\rt{script\_metadecl}}
+ \CASE{(\T{id},\T{id}) <{}< \T{rulename\_id}.\T{id} ;}
+ \CASE{\T{id} <{}< \T{rulename\_id}.\T{id} ;}
+ \CASE{\T{id} ;}
+\end{grammar}
+
+\noindent
+In a declaration of the form \texttt{(\T{id},\T{id}) <{}<
+ \T{rulename\_id}.\T{id} ;}, the left component of \texttt{(\T{id},\T{id})}
+receives a string representation of the value of the inherited metavariable
+while the right component receives its abstract syntax tree. The file
+\texttt{parsing\_c/ast\_c.ml} in the Coccinelle implementation gives some
+information about the structure of the abstract syntax tree. Either the
+left or right component may be replaced by \verb+_+, indicating that the
+string representation or abstract syntax trees representation is not
+wanted, respectively.
+
+The abstract syntax tree of a metavariable declared using {\tt
+ metavariable} is not available.
+
\section{Transformation}
The transformation specification essentially has the form of C code,
Each element of a disjunction must be a proper term like an
expression, a statement, an identifier or a declaration. Thus, the
-rule on the left below is not a syntaxically correct SmPL rule. One may
+rule on the left below is not a syntactically correct SmPL rule. One may
use the rule on the right instead.
\begin{center}
(
writeb(...,
|
- readb(
+ readb(...,
)
@--(T)
b)
\end{tabular}
\end{center}
+Some kinds of terms can only appear in + code. These include comments,
+ifdefs, and attributes (\texttt{\_\_attribute\_\_((...))}).
+
\section{Types}
\label{types}
\CASE{\opt{\NT{ctype\_qualif}} long long}
\CASE{double}
\CASE{float}
+ \CASE{size\_t} \CASE{ssize\_t} \CASE{ptrdiff\_t}
+ \CASE{enum \NT{id} \{ \NT{PARAMSEQ}\mth{(}\NT{dot\_expr}, \NT{exp\_whencode}\mth{)} \OPT{,} \}}
\CASE{\OPT{struct\OR union} \T{id} \OPT{\{ \any{\NT{struct\_decl\_list}} \}}}
\RULE{\rt{ctype\_qualif}}
\CASE{\opt{\NT{const\_vol}} \T{id} \NT{d\_ident};}
\RULE{\rt{d\_ident}}
- \CASE{\NT{id} \any{[\opt{\NT{expr}}]}}
+ \CASE{\T{id} \any{[\opt{\NT{expr}}]}}
\RULE{\rt{fn\_ctype}}
\CASE{\NT{generic\_ctype} \any{*}}
\RULE{\rt{funid}}
\CASE{\T{id}}
\CASE{\mth{\T{metaid}^{\ssf{Id}}}}
+ \CASE{\NT{OR}\mth{(}\NT{stmt}\mth{)}}
% \CASE{\mth{\T{metaid}^{\ssf{Func}}}}
% \CASE{\mth{\T{metaid}^{\ssf{LocalFunc}}}}
\CASE{\NT{COMMA\_LIST}\mth{(}\NT{gram\_p} \OR \ldots \opt{\NT{when\_p}}\mth{)}}
\end{grammar}
+To match a function it is not necessary to provide all of the annotations
+that appear before the function name. For example, the following semantic
+patch:
+
+\begin{lstlisting}[language=Cocci]
+@@
+@@
+
+foo() { ... }
+\end{lstlisting}
+
+\noindent
+matches a function declared as follows:
+
+\begin{lstlisting}[language=C]
+static int foo() { return 12; }
+\end{lstlisting}
+
+\noindent
+This behavior can be turned off by disabling the \KW{optional\_storage}
+isomorphism. If one adds code before a function declaration, then the
+effect depends on the kind of code that is added. If the added code is a
+function definition or CPP code, then the new code is placed before
+all information associated with the function definition, including any
+comments preceeding the function definition. On the other hand, if the new
+code is associated with the function, such as the addition of the keyword
+{\tt static}, the new code is placed exactly where it appears with respect
+to the rest of the function definition in the semantic patch. For example,
+
+\begin{lstlisting}[language=Cocci]
+@@
+@@
+
++ static
+foo() { ... }
+\end{lstlisting}
+
+\noindent
+causes static to be placed just before the function name. The following
+causes it to be placed just before the type
+
+\begin{lstlisting}[language=Cocci]
+@@
+type T;
+@@
+
++ static
+T foo() { ... }
+\end{lstlisting}
+
+\noindent
+It may be necessary to consider several cases to ensure that the added ode
+is placed in the right position. For example, one may need one pattern
+that considers that the function is declared {\tt inline} and another that
+considers that it is not.
+
%\newpage
\section{Declarations}
\RULE{\rt{initialize}}
\CASE{\NT{dot\_expr}}
+ \CASE{\mth{\T{metaid}^{\ssf{Initialiser}}}}
\CASE{\ttlb~\opt{\NT{COMMA\_LIST}\mth{(}\NT{dot\_expr}\mth{)}}~\ttrb}
+ \RULE{\rt{init\_list\_elem}}
+ \CASE{\NT{dot\_expr}}
+ \CASE{\NT{designator} = \NT{dot\_expr}}
+ \CASE{\NT{id} : \NT{dot\_expr}}
+
+ \RULE{\rt{designator}}
+ \CASE{. \NT{id}}
+ \CASE{[ \NT{dot\_expr} ]}
+ \CASE{[ \NT{dot\_expr} ... \NT{dot\_expr} ]}
+
\RULE{\rt{decl\_ident}}
\CASE{\T{DeclarerId}}
\CASE{\mth{\T{metaid}^{\ssf{Declarer}}}}
\end{grammar}
-\section{Constant, Identifiers and Types for Transformations}
+\section{Constants, Identifiers and Types for Transformations}
\begin{grammar}
\RULE{\rt{const}}
\CASE{"\any{[\^{}"]}"}
\RULE{\rt{id}}
- \CASE{\T{id} \OR \mth{\T{metaid}^{\ssf{Id}}}}
+ \CASE{\T{id} \OR \mth{\T{metaid}^{\ssf{Id}}}
+ \OR {\NT{OR}\mth{(}\NT{stmt}\mth{)}}}
\RULE{\rt{typedef\_ident}}
\CASE{\T{id} \OR \mth{\T{metaid}^{\ssf{Type}}}}
%%% Local Variables:
%%% mode: LaTeX
%%% TeX-master: "main_grammar"
-%%% coding: latin-9
+%%% coding: utf-8
%%% TeX-PDF-mode: t
%%% ispell-local-dictionary: "american"
%%% End:
HCoop / bpt / coccinelle.git / blobdiff