File inclusion

Configuration LEGO

Introduction

Configuration supports inclusion of files to enable a modular structure.

An inclusion expression has the following format:

"@include:/path/to/includable/file/or/dir"

After inclusion the property value containing the inclusion will be replaced with the content of the include file(s).

Only files of type JSON are supported and file must contain a JSON object ("{...}") or array ("[...]").

Syntax

An inclusion expressen MUST:

• be a string ("...")

• start with @include:

• end with one or more comma separated paths or globs specifying the files or directories to include

• NOT contain expansions

Both files and directories can be included.

If include is a file:

1. Load content of file

2. Parse content as JSON

3. Replace property value with included JSON (object or array)

Including a non-existing, empty or non-json file is an error.

If include is a directory:

1. Create a JSON array ("result")

2. For each file in directory matching pattern "*.json" or "*.jsonc"

   1. Load content of file

   2. Parse content as JSON

   3. Add JSON (object or array) to result array

3. Replace property value with result array

Including a non-existing directory is an error. Including an empty directory (or a directory that doesn't contain any .json files) results in an empty result array.

If more than one path is supplied the above process will be repeated for each path. When including multiple path the result is always an array.

Paths

Paths can be absolute or relative. Relative paths are resolved against the directory of the including file.

// Absolute path
"property": "@include:/absolute/path/to/included/file.json"

// Relative path, same directory
"property": "@include:file.json"
"property": "@include:./file.json"

// Relative path, sub directory
"property": "@include:includes/dir/file.json"
"property": "@include:./includes/dir/file.json"

// Relative path, sibling directory
"property": "@include:../other/dir/file.json"

// Multiple dirs
"property": "@include:path/to/dir/,path/to/other/"

Directory paths can be specified with or without trailing path separator ("/").

Globs

Glob patterns ("globs") are supported.

Globs are simplified forms of regular expressions used to match file paths and names based on certain patterns. Here's a description of the most common glob-pattern syntax elements:

Asterisk (*):

Matches any number of any characters, including none. Example: *.txt matches all files with a .txt extension (notes.txt, report.txt).

Question Mark (?):

Matches exactly one character. Example: file?.txt matches file1.txt, file2.txt, but not file10.txt.

Brackets ([]):

Matches any one of the enclosed characters. Example: file[123].txt matches file1.txt, file2.txt, or file3.txt.

Hyphen (within brackets):

Specifies a range of characters. Example: file[a-c].txt matches filea.txt, fileb.txt, or filec.txt, but not filez.txt

Braces ({}):

Matches any of the comma-separated patterns. Example: file{1,2,3}.txt matches file1.txt, file2.txt, or file3.txt, but not file4.txt.

Double Asterisk (**):

Matches directories recursively. Example: **/*.txt matches all .txt files in the current directory and all subdirectories.

// Simple glob inluding all json-files in a dir
// This is the same as including 'path/to/include/'
"property": "@include:path/to/include/*.json"

// Include all json-files having a name starting with 'test'
"property": "@include:path/to/include/test*.json"

// Include all json-files located in a dir named 'test'
"property": "@include:**/test/*.json"

Troubleshooting

Included file/dir not found:

Include not found: <path/to/file>

Included file does not contain valid JSON:

Invalid include content type (<type>): <path/to/file>

Included file is empty:

Empty include: <path/to/file>