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 an empty or non-json file is an error. Including a file that doesn't exist results in an empty array.

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 or 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.

An empty array ([]) is always returned when the include expression produces no result.

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 in paths.

The result of a glob is a list of zero, one or more matching paths. These paths are each treated in the same way as regular paths and produces the same result. Think of globs as a powerful way to specify multiple files.

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"

Type conversion

In some situations it may be useful to change the result type of an include expression to match what is expected by the consumer.

Type conversion is enabled by using an alias directive:

• @include_as_object

• @include_as_array

Type conversion is only possible when it doesn't result in data loss.

Convert from array to object ("unwrap")

When the result is an array containing only one element (object or array) the element can be unwrapped using directive: @include_as_object

If the result is anything but a single element array, the behaviour is identical to a regular inclusion.

Example

Given the following file containing an object (no other files in dir):

/path/to/dir/file.json

{
    "description": "This is the content",
    "path": "/path/to/dir/file.json"
}

The expression "@include:/path/to/dir" will result in an array containing the contents of all json-files in the specified directory even if the directory, like in this case, only contains a single file.

// A regular "@include":
{
    "result": "@include:/path/to/dir"
}

// results in an array with file content in first element (0) since we included
// a directory
{
    "result": [
        {
            "description": "This is the content",
            "path": "/path/to/dir/file.json"
        }
    ]
}

To unwrap the single element result from the array, use "@include_as_object:/path/to/dir".

// Include as object:
{
    "result": "@include_as_object:/path/to/dir"
}

// results in content being the value of result (not an array) since 
// the result array contained only one element
{
    "result": {
        "description": "This is the content",
        "path": "/path/to/dir/file.json"
    }
}

Convert from object to array ("wrap")

When the result of an include is an object it can be wrapped in an array by using directive: @include_as_array

If the result is anything but an object, the behaviour is identical to a regular inclusion.

Example

Given the following file (number of files in dir does not matter in this example):

/path/to/dir/file.json

{
    "description": "This is the content",
    "path": "/path/to/dir/file.json"
}

The expression "@include:/path/to/dir/file.json" will result in an object, since a single file is included and that file contains an object.

// A regular "@include":
{
    "result": "@include:/path/to/dir/file.json"
}

// results in value being the actual content of the file (an object or array)
{
    "result": {
        "description": "This is the content",
        "path": "/path/to/dir/file.json"
    }

}

To wrap this object in an array, use "@include_as_array:/path/to/dir/file.json".

// Include as array:
{
    "result": "@include_as_array:/path/to/dir/file.json"
}

// results in the object being being wrapped in an array
{
    "result": [
        {
            "description": "This is the content",
            "path": "/path/to/dir/file.json"
        }
    ]
}

Summary

Below are the basic includes. They may be combined to create advanced includes.

To include..	Use
a single file	"@include:/path/to/file.json"
all (json) files in a directory	"@include:/path/to/dir"
all (json) files from multiple directories	"@include:/path/to/dir,/path/to/other"
a subset of files in a single directories	"@include:/path/to/dir/file_*.json"
a subset of files in multiple directories	"@include:/path/to/*/file_*.json" "@include:/path/to/**/file_*.json" "@include:/path/to/dir/file_*.json,/path/to/other/file_*.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>