coccinelle release 0.2.5

[bpt/coccinelle.git] / docs / manual / cocci_syntax.tex

diff --git a/docs/manual/cocci_syntax.tex b/docs/manual/cocci_syntax.tex
index 3099c37..1f55dfc 100644 (file)
--- a/docs/manual/cocci_syntax.tex
+++ b/docs/manual/cocci_syntax.tex
@@ -134,18 +134,19 @@ behavior.  Using \NT{disable-iso} with the given name disables this behavior.
 
 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.
 
 \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\_virt\_or\_not\_eq}\mth{)} ;}
@@ -154,7 +155,7 @@ 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} ;}
@@ -185,6 +186,21 @@ the same, but for structure fields.
   \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.
 
@@ -237,6 +253,18 @@ indicates the {\it metakind} used in the declaration of the variable.
 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}.
@@ -309,6 +337,9 @@ 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,
@@ -508,7 +539,7 @@ T b;
 (
  writeb(...,
 |
- readb(
+ readb(...,
 )
 @--(T)
  b)
@@ -533,6 +564,9 @@ write
   \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}
 
@@ -626,6 +660,7 @@ $^\dag$ The optional \texttt{when} construct ends at the end of the line.
   \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}}}}
 
@@ -901,7 +936,7 @@ in a concise way.
 
 \end{grammar}
 
-\section{Constant, Identifiers and Types for Transformations}
+\section{Constants, Identifiers and Types for Transformations}
 
 \begin{grammar}
   \RULE{\rt{const}}
@@ -913,7 +948,8 @@ in a concise way.
   \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}}}}