Include the contents of files in another file.
| Task package: | org.schmant.task.base |
| Java package: | org.schmant.task.text |
| Category: | Text tasks |
| Since: | 0.8 |
| EntityFS-aware? | Yes* |
| Implements: | ActionTaskFactory GeneratorTaskFactory ProcessTaskFactory |
| Produces: | The interpreted target property. The exact type depends on the type used for the target. |
Description:
Include the contents of files in another file. This can for instance be used to include external examples in a documentation file.
The task replaces all file placeholders |include:path|
with the contents of the file at that path. The path is either absolute or
relative to one of the project
files roots. The path may contain variables on the form ${variable
name}, where the variable name is any valid Java variable name. The
variables are substituted with the values set in the
variables property.
Required properties
Properties
| bufferSize | top |
The size of temporary in-memory buffers used by this task.
- Setter method:
setBufferSize(int sz)
parameters:sz– The buffer size, in bytes.- Default value:
- 8192 bytes.
| escapeXmlCharacters | top |
Should XML characters in inserted files be escaped?
Escaping means that a character with a special meaning in XML, such as & is replaced with its entity reference (&).
The XML character escaping occurs before the replaces, if any, are run.
- Setter method:
setEscapeXmlCharacters(boolean b)
parameters:b– Should XML characters be escaped?- Default value:
false(XML characters are not escaped)
| ignoreMissingVariables | top |
If a project file path refers to a missing variable, should that variable be ignored? If a missing variable is ignored, the variable name is kept in the project file path. If not, the task fails.
- Setter method:
setIgnoreMissingVariables(boolean b)
parameters:b– Ignore missing variables?- Default value:
false(missing variables are not ignored)
| inputEncoding | top |
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.
| logFooter | top |
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
| logHeader | top |
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
| outputEncoding | top |
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
| overwriteStrategy | top |
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 ofparameters:truemeans that the DoOverwriteAndLogWarning strategy is used. A value of false gives the DontOverwriteAndThrowException strategy.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
| projectFilesRoots | top |
A list of directories. Each project file path found is evaluated relative to every path in this list, until the project file is found.
A directory d1 added to this list before another directory d2 has higher precedence, which means that if a path p points to a file under both d1 and d2, the file under d1 is used.
This property is required if relative paths are used for the files to include.
- Setter method:
addProjectFilesRoot(Object o)Add one or several project files root directories.parameters:- Setter method:
addProjectFilesRoots(Object o)Add one or several project files root directories.parameters:- Setter method:
clearProjectFilesRoots()Clear the list of directories.- Setter method:
setProjectFilesRoot(Object o)Add one or several project files root directories, discarding all previously added directories.parameters:- Setter method:
setProjectFilesRoots(Object o)Add one or several project files root directories, discarding all previously added directories.parameters:
| replaces | top |
A list of replaces that is run on each inserted file. The list contains pairs (TwoObjects objects) of strings, where the first string is a string representation of a Pattern to look for and the second string is the text to replace the text that the pattern matches with. The text replacement works just like the String.replaceAll method.
- Setter method:
addReplace(String pattern, String text)Add one replace.parameters:pattern– The regular expression pattern to look for.text– The text to replace pattern matches with.- Setter method:
addReplaces(Object o)Add one or several replaces.parameters:- Setter method:
clearReplaces()Clear the list of replaces.
| reportLevel | top |
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 levelparameters:l– The new report level.
| source (required) | top |
The file to process.
- Setter method:
setSource(Object o)
parameters:
| target (required) | top |
The file that the processed file should be written to.
- Setter method:
setTarget(Object o)Set the target.parameters:o– A target that can be interpreted as a writable file. If the target already exists, the overwriteStrategy property determines what will happen.
Interpreted byInterpretAsNewWritableFileStrategy.- See also:
- overwriteStrategy
| tempDirectory | top |
The temporary directory to store intermediate processing results in. By default this is the default temporary files directory for TempFileUtil. Set this to a RAM directory to speed up this task somewhat.
- Setter method:
setTempDirectory(Object d)
parameters:- Default value:
- TempFileUtil's default temporary files directory.
| traceLogging | top |
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?
| variables | top |
A mapping of variable names and their values. Variables
${variable name} in the project file paths are substituted
by their values. If a project file path refers to a missing variable, the
ignoreMissingVariables
property determines what will happen.
Variable names must be valid Java variable names.
- Setter method:
addVariable(String name, String value)Add one variable.parameters:name– The variable name.value– The variable value.- Setter method:
addVariables(Map<String, String> m)Add all variables in the map.parameters:m– The variables.- See also:
- ignoreMissingVariables
Examples
Example 1
Include contents of other files in all HTML files found
in the directory hierarchy under src
JavaScript
* 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.