org.codehaus.plexus.interpolation

## Class RegexBasedInterpolator

- java.lang.Object
- - org.codehaus.plexus.interpolation.RegexBasedInterpolator

All Implemented Interfaces:
  Interpolator

    public class RegexBasedInterpolator
    extends java.lang.Object
    implements Interpolator

Expansion of the original RegexBasedInterpolator, found in plexus-utils, this interpolator provides options for setting custom prefix/suffix regex parts, and includes a `RecursionInterceptor` parameter in its interpolate(..) call, to allow the detection of cyclical expression references.

Version:
  $Id$

### Field Summary

Fields
`static java.lang.String` `DEFAULT_REGEXP`

### Constructor Summary

Constructors
Constructor and Description
`RegexBasedInterpolator()` Setup a basic interpolator.
`RegexBasedInterpolator(boolean reusePatterns)`
`RegexBasedInterpolator(java.util.List valueSources)` Setup a basic interpolator with the specified list of value sources.
`RegexBasedInterpolator(java.lang.String startRegex, java.lang.String endRegex)` Setup an interpolator with no value sources, and the specified regex pattern prefix and suffix in place of the default one.
`RegexBasedInterpolator(java.lang.String startRegex, java.lang.String endRegex, java.util.List valueSources)` Setup an interpolator with the specified value sources, and the specified regex pattern prefix and suffix in place of the default one.

### Method Summary

Methods
`void` `addPostProcessor(InterpolationPostProcessor postProcessor)` Add a new post-processor to handle final processing after recursively-interpolated value is determined.
`void` `addValueSource(ValueSource valueSource)` Add a new `ValueSource` to the stack used to resolve expressions in this interpolator instance.
`void` `clearAnswers()`
`void` `clearFeedback()` Clear the feedback messages from previous interpolate(..) calls.
`java.util.List` `getFeedback()` Return any feedback messages and errors that were generated - but suppressed - during the interpolation process.
`java.lang.String` `interpolate(java.lang.String input)` See `interpolate(String, String, RecursionInterceptor)`.
`java.lang.String` `interpolate(java.lang.String input, RecursionInterceptor recursionInterceptor)` See `interpolate(String, String, RecursionInterceptor)`.
`java.lang.String` `interpolate(java.lang.String input, java.lang.String thisPrefixPattern)` See `interpolate(String, String, RecursionInterceptor)`.
`java.lang.String` `interpolate(java.lang.String input, java.lang.String thisPrefixPattern, RecursionInterceptor recursionInterceptor)` Attempt to resolve all expressions in the given input string, using the given pattern to first trim an optional prefix from each expression.
`boolean` `isCacheAnswers()`
`boolean` `isReusePatterns()`
`void` `removePostProcessor(InterpolationPostProcessor postProcessor)` Remove the given post-processor.
`void` `removeValuesSource(ValueSource valueSource)` Remove the specified `ValueSource` from the stack used to resolve expressions in this interpolator instance.
`void` `setCacheAnswers(boolean cacheAnswers)`
`void` `setReusePatterns(boolean reusePatterns)`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### DEFAULT_REGEXP

    public static final java.lang.String DEFAULT_REGEXP

See Also:
  Constant Field Values

### Constructor Detail

#### RegexBasedInterpolator

    public RegexBasedInterpolator()

Setup a basic interpolator.
NOTE: You will have to call `addValueSource(ValueSource)` at least once if you use this constructor!

#### RegexBasedInterpolator

    public RegexBasedInterpolator(boolean reusePatterns)

Parameters:
  `reusePatterns` - already compiled patterns will be reused

#### RegexBasedInterpolator

    public RegexBasedInterpolator(java.lang.String startRegex,
                          java.lang.String endRegex)

Setup an interpolator with no value sources, and the specified regex pattern prefix and suffix in place of the default one.
NOTE: You will have to call `addValueSource(ValueSource)` at least once if you use this constructor!

Parameters:
  `startRegex` - start of the regular expression to use
  `endRegex` - end of the regular expression to use

#### RegexBasedInterpolator

    public RegexBasedInterpolator(java.util.List valueSources)

Setup a basic interpolator with the specified list of value sources.

Parameters:
  `valueSources` - The list of value sources to use

#### RegexBasedInterpolator

    public RegexBasedInterpolator(java.lang.String startRegex,
                          java.lang.String endRegex,
                          java.util.List valueSources)

Setup an interpolator with the specified value sources, and the specified regex pattern prefix and suffix in place of the default one.

Parameters:
  `startRegex` - start of the regular expression to use
  `endRegex` - end of the regular expression to use
  `valueSources` - The list of value sources to use

### Method Detail

#### addValueSource

    public void addValueSource(ValueSource valueSource)

Add a new `ValueSource` to the stack used to resolve expressions in this interpolator instance.

Specified by:
  `addValueSource` in interface `Interpolator`

#### removeValuesSource

    public void removeValuesSource(ValueSource valueSource)

Remove the specified `ValueSource` from the stack used to resolve expressions in this interpolator instance.

Specified by:
  `removeValuesSource` in interface `Interpolator`

#### addPostProcessor

    public void addPostProcessor(InterpolationPostProcessor postProcessor)

Add a new post-processor to handle final processing after recursively-interpolated value is determined.

Specified by:
  `addPostProcessor` in interface `Interpolator`

#### removePostProcessor

    public void removePostProcessor(InterpolationPostProcessor postProcessor)

Remove the given post-processor.

Specified by:
  `removePostProcessor` in interface `Interpolator`

#### interpolate

    public java.lang.String interpolate(java.lang.String input,
                               java.lang.String thisPrefixPattern,
                               RecursionInterceptor recursionInterceptor)
                                 throws InterpolationException

Attempt to resolve all expressions in the given input string, using the given pattern to first trim an optional prefix from each expression. The supplied recursion interceptor will provide protection from expression cycles, ensuring that the input can be resolved or an exception is thrown.

Specified by:
  `interpolate` in interface `Interpolator`
Parameters:
  `input` - The input string to interpolate
  `thisPrefixPattern` - An optional pattern that should be trimmed from the start of any expressions found in the input.
  `recursionInterceptor` - Used to protect the interpolation process from expression cycles, and throw an exception if one is detected.
Throws:
  `InterpolationException`

#### getFeedback

    public java.util.List getFeedback()

Return any feedback messages and errors that were generated - but suppressed - during the interpolation process. Since unresolvable expressions will be left in the source string as-is, this feedback is optional, and will only be useful for debugging interpolation problems.

Specified by:
  `getFeedback` in interface `Interpolator`
Returns:
  a `List` that may be interspersed with `String` and `Throwable` instances.

#### clearFeedback

    public void clearFeedback()

Clear the feedback messages from previous interpolate(..) calls.

Specified by:
  `clearFeedback` in interface `Interpolator`

#### interpolate

    public java.lang.String interpolate(java.lang.String input,
                               java.lang.String thisPrefixPattern)
                                 throws InterpolationException

See `interpolate(String, String, RecursionInterceptor)`.
This method triggers the use of a `SimpleRecursionInterceptor` instance for protection against expression cycles.

Specified by:
  `interpolate` in interface `Interpolator`
Parameters:
  `input` - The input string to interpolate
  `thisPrefixPattern` - An optional pattern that should be trimmed from the start of any expressions found in the input.
Throws:
  `InterpolationException`

#### interpolate

    public java.lang.String interpolate(java.lang.String input)
                                 throws InterpolationException

See `interpolate(String, String, RecursionInterceptor)`.
This method triggers the use of a `SimpleRecursionInterceptor` instance for protection against expression cycles. It also leaves empty the expression prefix which would otherwise be trimmed from expressions. The result is that any detected expression will be resolved as-is.

Specified by:
  `interpolate` in interface `Interpolator`
Parameters:
  `input` - The input string to interpolate
Throws:
  `InterpolationException`

#### interpolate

    public java.lang.String interpolate(java.lang.String input,
                               RecursionInterceptor recursionInterceptor)
                                 throws InterpolationException

See `interpolate(String, String, RecursionInterceptor)`.
This method leaves empty the expression prefix which would otherwise be trimmed from expressions. The result is that any detected expression will be resolved as-is.

Specified by:
  `interpolate` in interface `Interpolator`
Parameters:
  `input` - The input string to interpolate
  `recursionInterceptor` - Used to protect the interpolation process from expression cycles, and throw an exception if one is detected.
Throws:
  `InterpolationException`

#### isReusePatterns

    public boolean isReusePatterns()

#### setReusePatterns

    public void setReusePatterns(boolean reusePatterns)

#### isCacheAnswers

    public boolean isCacheAnswers()

Specified by:
  `isCacheAnswers` in interface `Interpolator`

#### setCacheAnswers

    public void setCacheAnswers(boolean cacheAnswers)

Specified by:
  `setCacheAnswers` in interface `Interpolator`

#### clearAnswers

    public void clearAnswers()

Specified by:
  `clearAnswers` in interface `Interpolator`