📄️ Lossless Semantic Trees (LST)
LST comparison
📄️ Java LST examples
When building recipes, it's important to understand how OpenRewrite Lossless Semantic Trees (LSTs) correspond to code. You couldn't, for example, properly rename a variable with a recipe unless you knew that J.Identifier is the class used to represent a variable.
📄️ YAML LST examples
When building recipes that read or modify YAML files, it's important to understand how the YAML Lossless Semantic Tree (LST) is constructed.
📄️ TreeVisitingPrinter
When you first begin to look into Lossless Semantic Trees (LSTs), it can be difficult to understand what code corresponds to what LST. You could use a debugger to step through the tree, but that can take a lot of time and it's easy to get lost in irrelevant elements.
📄️ How LSTs are handled locally
When you run a recipe locally, the first thing that happens is that the Lossless Semantic Tree (LST) is produced. The LST is stored in memory and used throughout the recipe execution. At the end of the recipe run, this LST is discarded. Even though the LST is destroyed, your code may have been updated locally depending on whether or not the recipe found stuff to change.
📄️ Recipes
A recipe represents a group of search and refactoring operations that can be applied to a Lossless Semantic Tree. A recipe can represent a single, stand-alone operation or it can be linked together with other recipes to accomplish a larger goal such as a framework migration.
📄️ Visitors
In OpenRewrite recipes, a visitor is where the core logic lives. It determines what elements should be updated and when.
📄️ Styles
A style is a programmatic way of defining what your code visually looks like. Do you use tabs or spaces? How many spaces is a tab composed of? When do you make a new line vs. not? These are all questions that are answered by a style.
📄️ Environment
OpenRewrite's Environment abstraction provides discovery, activation, and configuration facilities for Recipes and Styles. It can be helpful to look at the common runtime contexts in which OpenRewrite operates to better understand how the environment is established:
📄️ Markers
Markers annotate LST elements with metadata. Visitors can read or attach any type implementing the Marker interface to any LST element's Markers. Markers can be used to identify search results or to communicate between Recipes during OpenRewrite execution. When an LST is printed back to source code most markers, being metadata, have no textual representation within the source. The exception is SearchResult Markers which are printed as comments that indicate the result of a search. OpenRewrite attaches framework provided markers to LSTs.
📄️ JavaTemplate
More advanced refactoring recipes often require the construction of complex Lossless Semantic Tree (LST) elements. Manually constructing complex LST elements can be tedious and unfamiliar to developers accustomed to authoring code as text. OpenRewrite addresses this need with JavaTemplate, which parses textual code snippets into LST elements ready for use in a visitor.
📄️ Quarks
A Quark in OpenRewrite serves as a representation of a file that cannot be parsed, either due to its large size or because it is a type we don't have a parser for (such as images or HTML files). Instead of disregarding such files, we capture their path and relevant metadata (but not the contents of these files). This allows you to move or delete these files in recipes.