jackpot30 / help / jackpot30-help.tex

\documentclass{article}
\usepackage{verbdef}
\usepackage{hyperref}

\verbdef\simplevariable=$[0-9A-Za-z_]+=
\verbdef\statementvariable=$[0-9A-Za-z_]+;=
\verbdef\multipletreevariable=$[0-9A-Za-z_]+$=
\verbdef\multiplestatementvariable=$[0-9A-Za-z_]+$;=
\verbdef\wholepattern=$$_=
\verbdef\reserved=$$[0-9A-Za-z_]+=

\begin{document}

\section{Rules Language}

\subsection{Basic Structure}

The rules file consists of any number of transformation rules.
The rule is defined as follows:
\begin{verbatim}
    <pattern>
=> <fix-pattern>
=> <fix-pattern>
;;
\end{verbatim}

Each occurrence of \verb=<pattern>= in the source code can be rewritten to one
of the \verb=<fix-pattern>=s. For example, the following transformation rule:
\begin{verbatim}
   $1 == null
=> null == $1
;;
\end{verbatim}

will rewrite the following code:
\begin{verbatim}
if (a == null) {
   System.err.println("a is null");
}
\end{verbatim}
to:
\begin{verbatim}
if (null == a) {
    System.err.println("a is null");
}
\end{verbatim}

Note: \verb=$1$= is a variable, explained \hyperref{below}{in Section~}{variables}{}.

Note: batch refactoring will typically use only the first applicable fix patterns
of each applicable rule.

\subsection{Patterns}

The pattern is a Java expression, statement or several statements.
All references to classes in the pattern need to be resolvable, i.e. either fully
qualified names need to be used, or the custom import section must be used
(see \hyperref{Custom Imports}{Section~}{custom-import}{}).

TODO: equivalence - static elements are checked only against themselves, blocks with
one statement considered equivalent to single statement.

Note: variable declaration is a Java statement.

\subsection{Variables}

Variables start with the dollar sign \verb=$=). In the pattern, first occurrences
of a variable is bound to the actual sub-tree that appears in the code. Second and
following occurrences of the variable the actual sub-tree is verified against the subtree
bound to the variable. The pattern occurs in the text only if the actual sub-tree
matches the sub-tree bound to the variable. In the fix pattern, all occurrences of
the variables are replaced with the tree(s) bound to the respective variables.

The forms of the variables are:
\begin{description}
\item[\simplevariable]{any expression}
\item[\statementvariable]{any statement}
\item[\multipletreevariable]{any number of sub-trees (except statements - see next definition)}
\item[\multiplestatementvariable]{any number of statements}
\item[\wholepattern]{for patterns undefined, for fixes and conditions automatically bound to the current matched region}
\item[\reserved]{reserved -- do not use}
\end{description}

\subsection{Conditions}

Both the search and fix patterns may specify additional conditions. These conditions
are specified after \verb=::=. Currently, the conditions have the following
limitations:

\begin{verbatim}
   $1.isDirectory() :: $1 instanceof java.io.File
=> !$1.isFile()
;;
\end{verbatim}

will rewrite the following code:
\begin{verbatim}
java.io.File testFile = new java.io.File("/tmp");
if (testFile.isDirectory()) {
    System.err.println("/tmp is a directory");
}
\end{verbatim}
to:
\begin{verbatim}
java.io.File testFile = new java.io.File("/tmp");
if (!testFile.isFile()) {
    System.err.println("/tmp is a directory");
}
\end{verbatim}

\subsection{Display Names and Localization}

\subsection{Custom Conditions}

\subsection{Custom Import}

\subsection{Options}

\end{document}
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.