cat ';' FILEPATH

Summary

The cat macro reads the contents of a file, directory, or URL and returns it as a string. It’s similar to the Unix cat command, allowing you to embed file contents directly in your configuration.

Syntax

${cat;<path-or-url>}

Parameters

• path-or-url - Path to a file or directory (relative to project), or a URL

Behavior

• For files: Returns the entire file contents as a string, with backslashes escaped
• For directories: Returns a list of filenames in the directory
• For URLs: Downloads and returns the content (assumes UTF-8 encoding)
• File paths are resolved relative to the project directory
• Returns null if the path doesn’t exist and isn’t a valid URL

Examples

Read a text file:

license.text=${cat;LICENSE.txt}

Read a property file:

build.info=${cat;build.properties}

List directory contents:

resource.files=${cat;resources}

Fetch content from a URL:

remote.config=${cat;https://example.com/config.txt}

Embed a template:

header=${cat;templates/header.txt}

Use Cases

• Embedding license text in bundle manifests
• Reading version information from external files
• Loading configuration templates
• Fetching remote configuration or data
• Including file contents in property values
• Listing files in a directory for processing

Notes

• Backslashes in file content are automatically escaped (useful for Windows paths)
• For large files, consider using file references instead of embedding
• URL fetching requires network access and may fail in restricted environments
• Directory listing returns a simple list of filenames
• UTF-8 encoding is assumed for both files and URLs

See test cases in MacroTestsForDocsExamples.java