first detected when the code is executed. Furthermore, \texttt{@} should
not be use in this code. Spatch scans the script code for the next
\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{@} occurs within e.g., 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
not have to be specified in the SmPL code, but may be present in the C code.
\item \KW{value\_format}: Integers in various formats, e.g., 1 and 0x1, are
considered to be equivalent in the matching process.
+\item \KW{optional\_declarer\_semicolon}: Some declarers (top-level terms
+ that look like function calls but serve to declare some variable) don't
+ require a semicolon. This isomorphism allows a SmPL declarer with a semicolon
+ to match such a C declarer, if no transformation is specified on the SmPL
+ semicolon.
\item \KW{comm\_assoc}: An expression of the form \NT{exp} \NT{bin\_op}
\KW{...}, where \NT{bin\_op} is commutative and associative, is
considered to match any top-level sequence of \NT{bin\_op} operators
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. A declaration metavariable matches the
+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.
\CASE{parameter list [ \NT{const} ] \NT{ids} ;}
\CASE{type \NT{ids} ;}
\CASE{statement \opt{list} \NT{ids} ;}
- \CASE{declaration \opt{list} \NT{ids} ;}
+ \CASE{declaration \NT{ids} ;}
\CASE{field \opt{list} \NT{ids} ;}
\CASE{typedef \NT{ids} ;}
\CASE{declarer name \NT{ids} ;}
\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.
+It is possible to specify some information about the definition of a fresh
+identifier. See the wiki.
+
+
\begin{grammar}
\RULE{\rt{ids}}
\CASE{\NT{COMMA\_LIST}\mth{(}\NT{pmid}\mth{)}}
alloc=kmalloc}. There should not be space around the {\tt =}. An
example is in {\tt demos/vm.cocci} and {\tt demos/vm.c}.
+
+\paragraph*{Warning:} Each metavariable declaration causes the declared
+metavariables to be immediately usable, without any inheritance
+indication. Thus the following are correct:
+
+\begin{quote}
+\begin{verbatim}
+@@
+type r.T;
+T x;
+@@
+
+[...] // some semantic patch code
+\end{verbatim}
+\end{quote}
+
+\begin{quote}
+\begin{verbatim}
+@@
+r.T x;
+type r.T;
+@@
+
+[...] // some semantic patch code
+\end{verbatim}
+\end{quote}
+
+\noindent
+But the following is not correct:
+
+\begin{quote}
+\begin{verbatim}
+@@
+type r.T;
+r.T x;
+@@
+
+[...] // some semantic patch code
+\end{verbatim}
+\end{quote}
+
+This applies to position variables, type metavariables, identifier
+metavariables that may be used in specifying a structure type, and
+metavariables used in the initialization of a fresh identifier. In the
+case of a structure type, any identifier metavariable indeed has to be
+declared as an identifier metavariable in advance. The syntax does not
+permit {\tt r.n} as the name of a structure or union type in such a
+declaration.
+
\section{Metavariables for scripts}
Metavariables for scripts can only be inherited from transformation rules.
(
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}
\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}}}}
\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}
+ \CASE{\ttlb~\opt{\NT{COMMA\_LIST}\mth{(}\NT{init\_list\_elem}\mth{)}}~\ttrb}
\RULE{\rt{init\_list\_elem}}
\CASE{\NT{dot\_expr}}
\CASE{\NT{designator} = \NT{dot\_expr}}
+ \CASE{\mth{\T{metaid}^{\ssf{Initialiser}}}}
+ \CASE{\mth{\T{metaid}^{\ssf{InitialiserList}}}}
\CASE{\NT{id} : \NT{dot\_expr}}
\RULE{\rt{designator}}
\CASE{\mth{\T{metaid}^{\ssf{Declarer}}}}
\end{grammar}
+An initializer for a structure can be ordered or unordered. It is
+considered to be unordered if there is at least one key-value pair
+initializer, e.g., \texttt{.x = e}.
+
\section{Statements}
The first rule {\em statement} describes the various forms of a statement.
\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}}}}
\CASE{"\any{[\^{}"]}"}
\end{grammar}
+\section{Comments}
+
+A \verb+//+ or \verb+/* */+ comment that is annotated with + in the
+leftmost column is considered to be added code. A \verb+//+ or
+\verb+/* */+ comment wthout such an annotation is considered to be a
+comment about the SmPL code, and thus is not matched in the C code.
+
+\section{Command-line semantic match}
+
+It is possible to specify a semantic match on the spatch command line,
+using the argument {\tt -sp}. In such a semantic match, any token
+beginning with a capital letter is assumed to be a metavariable of type
+{\tt metavariable}. In this case, the parser must be able to figure out what
+kind of metavariable it is. It is also possible to specify the type of a
+metavariable by enclosing the type in :'s, concatenated directly to the
+metavariable name.
+
+Some examples of semantic matches that can be given as an argument to {\tt
+ -sp} are as follows:
+
+\begin{itemize}
+\item \texttt{f(e)}: This only matches the expression \texttt{f(e)}.
+\item \texttt{f(E)}: This matches a call to f with any argument.
+\item \texttt{F(E)}: This gives a parse error; the semantic patch parser
+ cannot figure out what kind of metavariable \texttt{F} is.
+\item \texttt{F:identifier:(E)}: This matches any one argument function
+ call.
+\item \texttt{f:identifier:(e:struct foo *:)}: This matches any one
+ argument function call where the argument has type \texttt{struct foo
+ *}. Since the types of the metavariables are specified, it is not
+ necessary for the metavariable names to begin with a capital letter.
+\item \texttt{F:identifier:(F)}: This matches any one argument function call
+ where the argument is the name of the function itself. This example
+ shows that it is not necessary to repeat the metavariable type name.
+\item \texttt{F:identifier:(F:identifier:)}: This matches any one argument
+ function call
+ where the argument is the name of the function itself. This example
+ shows that it is possible to repeat the metavariable type name.
+\end{itemize}
+
+\texttt{When} constraints, \textit{e.g.} \texttt{when != e}, are allowed
+but the expression \texttt{e} must be represented as a single token.
+
+The generated semantic match behaves as though there were a \texttt{*} in front
+of every token.
%%% Local Variables:
%%% mode: LaTeX
HCoop / bpt / coccinelle.git / blobdiff