From 30cc4a4bb02eb72fb987c5b76fa68f50a89157e9 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 19:44:55 +0200 Subject: [PATCH 1/2] Rename the site documents ahead of converting them A pure rename, so that git records it and `git log --follow` and `git blame` still reach the history of each page after the conversion that follows. The content is still APT at this point and the site does not build between the two commits. --- src/site/{apt/index.apt => markdown/index.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/site/{apt/index.apt => markdown/index.md} (100%) diff --git a/src/site/apt/index.apt b/src/site/markdown/index.md similarity index 100% rename from src/site/apt/index.apt rename to src/site/markdown/index.md From 83e08a08400d841a98ec174ff57f5c9c2ff7b4a5 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 19:44:55 +0200 Subject: [PATCH 2/2] Port the index page from APT to Markdown Converted with doxia-converter and then cleaned up by hand: - <<>> becomes backticks, <> becomes **bold**, {{{url}text}} becomes [text](url) - the ASF license header becomes a single block HTML comment - the page needs no Velocity, so it is a plain .md and the title, which was ${project.name}, is now spelled out Verified by building the site before and after: the rendered page is unchanged apart from / becoming / and quotes in prose picking up the Markdown module's typographic substitution. --- src/site/markdown/index.md | 96 ++++++++++++++------------------------ 1 file changed, 35 insertions(+), 61 deletions(-) diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index f17172e..1f9fd42 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -1,75 +1,48 @@ - ----- - Plexus Interpolator - ----- - John Casey - Hervé Boutemy - ----- - 2012-10-31 - ----- - -Introduction - - Plexus interpolator is the outgrowth of multiple iterations of development focused on providing a more modular, - flexible interpolation framework for the expression language style commonly seen in Maven, Plexus, and other related projects. - - It has its foundation in the <<>> package within - {{{/plexus-utils/}<<>>}}, but has been separated in order to allow these two libraries to vary independently - of one another. - -Features - - * Stackable Expression-Resolution Strategies - - Expression-resolution strategies can be 'stacked' to provide an order of operations, containing multiple approaches that could - potentially resolve a given expression. - - These strategies are called {{{./apidocs/org/codehaus/plexus/interpolation/ValueSource.html}<<>>s}}, - and each implements a very simple piece of resolution logic. +# Introduction + +Plexus interpolator is the outgrowth of multiple iterations of development focused on providing a more modular, flexible interpolation framework for the expression language style commonly seen in Maven, Plexus, and other related projects. + +It has its foundation in the `org.codehaus.plexus.utils.interpolation` package within [`plexus-utils`](/plexus-utils/), but has been separated in order to allow these two libraries to vary independently of one another. + +# Features + +- Stackable Expression-Resolution Strategies + + Expression-resolution strategies can be 'stacked' to provide an order of operations, containing multiple approaches that could potentially resolve a given expression. + + These strategies are called [`ValueSource`s](./apidocs/org/codehaus/plexus/interpolation/ValueSource.html), and each implements a very simple piece of resolution logic. It's also possible to define your own, domain-specific value source. - - * Flexible Expression-Cycle Detection - Expression cycles are detected using various strategies, ranging from simplistic consultation of a stack of explicit in-process - expressions, to tracking of in-process expressions that takes multiple synonym expression variants into account. +- Flexible Expression-Cycle Detection - It's even possible to define your own - {{{./apidocs/org/codehaus/plexus/interpolation/RecursionInterceptor.html}<<>>}} to implement - an alternative strategy. + Expression cycles are detected using various strategies, ranging from simplistic consultation of a stack of explicit in-process expressions, to tracking of in-process expressions that takes multiple synonym expression variants into account. - * Configurable Regular Expression-Based Default Interpolator + It's even possible to define your own [`RecursionInterceptor`](./apidocs/org/codehaus/plexus/interpolation/RecursionInterceptor.html) to implement an alternative strategy. - The default interpolator implementation uses regular expressions to search for interpolation candidate expressions within - an input string. +- Configurable Regular Expression-Based Default Interpolator - This interpolator can use a custom prefix/suffix pair that will effectively redefine the regular expression used to extract - candidate expressions. - - * Built-In Synonym Support for Expressions + The default interpolator implementation uses regular expressions to search for interpolation candidate expressions within an input string. - Any <<>> implementation can be wrapped to allow multiple synonym expressions using different expression prefixes. - - * Resolution Feedback + This interpolator can use a custom prefix/suffix pair that will effectively redefine the regular expression used to extract candidate expressions. - <<>> implementations have the option of implementing <<>>, which provides the ability to - give feedback to the calling code about what failed during expression resolution. For instance, the <<>> - traverses the object graph below a given root object; if an object in that graph doesn't contain a property corresponding to - the expression-part currently being navigated, the value source can store a feedback message to that effect. - Once interpolation of the larger input string has completed, the calling code can use the <<>> method - to retrieve this feedback message (among others). - -Getting Started +- Built-In Synonym Support for Expressions - The simplest way to explain how to use the plexus-interpolation API is with a few examples. + Any `ValueSource` implementation can be wrapped to allow multiple synonym expressions using different expression prefixes. - First, let's look at a simplified version of the interpolation configuration used in Maven. - Remember that Maven uses several source for interpolation of its POM files: the POM itself, system properties, - user-defined properties, and environment variables from the shell that spawned the current Java process. - Also, Maven allows POM references to be defined as $\{pom.groupId}, $\{project.groupId}, or even the discouraged $\{groupId}. +- Resolution Feedback - The following is a simplified version of the plexus-interpolation configuration Maven might use to resolve POM expressions: - -+---+ + `ValueSource` implementations have the option of implementing `FeedbackEnabledValueSource`, which provides the ability to give feedback to the calling code about what failed during expression resolution. For instance, the `ObjectBasedValueSource` traverses the object graph below a given root object; if an object in that graph doesn't contain a property corresponding to the expression-part currently being navigated, the value source can store a feedback message to that effect. Once interpolation of the larger input string has completed, the calling code can use the `Interpolator.getFeedback()` method to retrieve this feedback message (among others). + +# Getting Started + +The simplest way to explain how to use the plexus-interpolation API is with a few examples. + +First, let's look at a simplified version of the interpolation configuration used in Maven. Remember that Maven uses several source for interpolation of its POM files: the POM itself, system properties, user-defined properties, and environment variables from the shell that spawned the current Java process. Also, Maven allows POM references to be defined as ${pom.groupId}, ${project.groupId}, or even the discouraged ${groupId}. + +The following is a simplified version of the plexus-interpolation configuration Maven might use to resolve POM expressions: + +```unknown // serialize current POM object graph into a string called serializedPOM. RegexBasedInterpolator interpolator = new RegexBasedInterpolator(); @@ -97,4 +70,5 @@ RecursionInterceptor recursionInterceptor = new PrefixAwareRecursionInterceptor( serializedPOM = interpolator.interpolate( serializedPOM, recursionInterceptor ); // parse POM back into an object graph, and pass it back. -+---+ \ No newline at end of file +``` +