TextReplaceTF

Insert, modify or replace text in a file.

Description:

This task takes a list of replaces and runs them on the contents of the source file. The result is saved in the target file. Each replace sees the results from previously run replaces.

A replace is a regular expression matching the text to replace paired with the text to replace it with. See replaces.

By using capturing groups, replacers can use the text to be replaced in the text that it replaces it with. This can, for instance, be used for inserting rather than replacing text. See example 4 and example 5.

Required properties

• replaces
• source
• target

Properties

The size of internal buffers used when replacing text.

Setter method:

setBufferSize(int i)
parameters:

i – The buffer size, in bytes.

Default value:

8192 bytes

If the source text for one replace is not found, is that an error?

Setter method:

setErrorIfReplaceNotFound(boolean b)
parameters:

b – An error?

Default value:

false

The character encoding of the input file. Use this if the input file has a non-standard encoding, i.e. an encoding different from the Java virtual machine's (platform dependent) default charset.

Setter method:

setInputEncoding(Charset c)
parameters:

c – The input charset.

Setter method:

setInputEncoding(String s)
parameters:

s – The name of a character encoding.

Default value:

The platform's default encoding.

The message that is logged to info level after the task has been successfully run.

Setter method:

setLogFooter(String s)
parameters:

s – The footer message.

Default value:

Empty (no footer message is logged.)

See also:

logHeader

The message that is logged to info level before the task is run.

Setter method:

setLogHeader(String s)
parameters:

s – The header message.

Default value:

A task class specific message.

See also:

logFooter

Limit the number of times that a replace may be used. If this is set to a negative number, which is the default, each replace is used for all of the text segments that it matches in the processed document.

Setter method:

setMaxNoOfReplacesPerReplace(int n)
parameters:

n – Max number of replaces.

Default value:

-1 (Unlimited number of replaces for each replacer.)

The character encoding of the output file. Use this if the output file should have a non-standard encoding, i.e. an encoding different from the Java virtual machine's (platform dependent) default charset.

Setter method:

setOutputEncoding(Charset c)
parameters:

c – The output charset.

Setter method:

setOutputEncoding(String s)
parameters:

s – The name of a character encoding.

Default value:

The platform's default encoding.

See also:

target

The overwrite strategy decides how the task will react if there already is an entity (file or directory) in a location where it wants to create a new entity.

If the strategy is to not overwrite existing entities, the task will fail when it cannot create the entities that it wants to create.

Non-empty directories are never overwritten, regardless of the chosen strategy.

Setter method:

setOverwrite(boolean b)

Setting this to a value of true means that the DoOverwriteAndLogWarning strategy is used. A value of false gives the DontOverwriteAndThrowException strategy.

parameters:

b – Should an existing entity be overwritten?

Setter method:

setOverwriteStrategy(OverwriteStrategy strat)

Set the overwrite strategy.

parameters:

strat – The overwrite strategy.

Default value:

DontOverwriteAndThrowException

See also:

target

A list of text replaces. Replaces are pairs of objects.

The first object is one of the following:

• A Pattern.
• A java.lang.CharSequence (a String, for instance) containing something that can be parsed using Pattern.compile(java.lang.String). In other words, the text is interpreted as a regular expression also when it is given as a CharSequence argument. To match exact strings, quote them using Pattern:s quoting constructs \Q and \E. For instance, "\\Qfoo.bar\\E" matches the exact string "foo.bar".

The second object is one of the following:

• A String. Matched text will be replaced with the contents of the string. This string can contain references to capturing groups in the matched text. Capture group n is referenced by the placeholder \\n See Pattern documentation and examples 4 and 5.
• A ReplacementTextStrategy. Matched text will be replaced with the text that is returned from the strategy.
• A FutureEntity that evaluates to any of the above.
• A closure with one or two arguments. When the closure is evaluated it should return the replacement text in a string. The closure can have one or two arguments. The first, mandatory, argument is a string containing the text to replace. The second, optional, argument is the Matcher that matched the text to replace. The closure may not update the matcher's state in any way. See example 2 and example 3 below.

There are several different ReplacementTextStrategy implementations available:

• StringTextStrategy – replace matched text with a constant string.
• CapturingGroupAwareStringTextStrategy – replace matched text with a string. The placeholder \\n in the string is replaced with the text matched by the capturing group n in the Pattern that matched the text to replace. This is the strategy that is used when just giving the replace a string argument (instead of a ReplacementTextStrategy). See example 4 and example 5 below.
• PropertyValueTextStrategy – uses the text returned by one capturing group in the Pattern that matched the text to replace as a property key and replaces the text with that property's value. See example 6.

The replaces are applied in the order that they are added to this property. When run, a replacer sees the results from previous replacers.

If the task has more than one replacer, files created by intermediate replacing steps are put in the target file system's temporary files directory. See FileSystem.

Setter method:

addReplace(String pattern, Object o)

Add one replace.

parameters:

pattern – A String containing a valid Pattern pattern. The pattern is compiled without setting any Pattern flags.

o – The replace.

Setter method:

addReplace(Pattern p, Object o)

Add one replace.

parameters:

p – The pattern.

o – The replace.
Interpreted by TextReplaceTask.createReplaces(org.entityfs.ReadableFile).

Setter method:

addReplace(TwoObjects<?, ?> p)

Add one replace.

parameters:

p – The replace.

Setter method:

addReplaces(Object o)

Add one or several replaces.

parameters:

o – One replace or an array or collection of replaces (TwoObjects<?, ?> objects).
Interpreted by TextReplaceTask.createReplaces(org.entityfs.ReadableFile).

Setter method:

clearReplaces()

Clear the list of replaces.

This property is used to change the Report level for all task created by this task factory. The report level is changed for the thread running the task when the it is run, and is restored to its previous level when the it is done.

Setter method:

setReportLevel(Level l)

Set the report level

parameters:

l – The new report level.

The source file to read text from.

Setter method:

setSource(Object o)
parameters:

o – The source file.
Interpreted by InterpretAsReadOnlyFileStrategy.

See also:

inputEncoding

The target file to write text to.

Setter method:

setTarget(Object o)
parameters:

o – The target file.
Interpreted by InterpretAsNewWritableFileStrategy.

See also:

outputEncoding

A temporary files directory where intermediate replace results are put if there are more than one replace for this task.

Setter method:

setTempDirectory(Object o)
parameters:

o – The temporary files directory.
Interpreted by |si:ai_directory;InterpretAsDirectoryStrategy|.

Default value:

The target file system's default temporary files directory.

If trace logging is enabled for a task, it reports its configuration before it is run.

Trace logging may also be enabled globally for all tasks by calling TraceMode.setTraceMode(boolean).

Setter method:

setTraceLogging(boolean b)

Enable or disable trace logging.

parameters:

b – Enable trace logging?

Examples

Example 1

Replace all occurrences of the string !!!VERSION!!! with the string 1.0 in all text files in the directory hierarchy under the directory d.

Example 2

Replace all occurrences of strings matching the regular expression pattern dat(a)+ in the text file txt with the same string enclosed in <code> tags using a closure to generate the replacement text.

Example 3

Replace all occurrences of strings matching the regular expression pattern #insert:.*?# (for instance #insert:d2/f.txt# matches) in the file f with the contents of the file that the "tag" references. The "tag" files are stored in or under the directory d. The result is put in the file fp.

Example 4

In the file report.html, add the text " - confirmed!" to all occurrences of "wild hypothesis no n", where n is a digit. Use capturing group zero to repeat the whole matched text.

Example 5

"Auto-comment" each start tag in the file info.html. Use capturing group zero to repeat the whole matched text and capturing group one to repeat the name of the tag.

Example 6

Replace the ###city### and ###country### placeholders with values supplied in an EntityFS Properties object.

* An EntityFS-aware task is implemented using EntityFS. This means that it uses the filter settings of DirectoryView:s and also that it often can work with other file system implementations than File-based, such as the RAM file system.