System Setting Expansion Namespaces

CommandBox : CLI, Package Manager, REPL & More

Search…

The default namespace when using the ${foo} system setting expansion syntax is box environment variable, Java system properties, and OS environment variables.  
It is also possible to leverage built-in namespaces to allow expansions that reference:
server.json properties
box.json properties
arbitrary JSON file properties
Config settings (like the config show command)
Server info properties (like the server info property=name command)
Other properties in the same JSON file
server.json properties
If the current working directory of the shell contains a server.json file, you can reference any property in it with the serverjson. namespace.:
1
${serverjson.name}
2
${serverjson.app.cfengine}
3
${serverjson.web.http.port}
4
${serverjson.trayEnable:defaultValue}
Copied!
if you have a server json file with a non-default name such as server-custom.json then you can access it with the serverjson. namespace.:
1
${serverjson.[email protected]-custom.json}
2
${serverjson.app.[email protected]-custom.json}
3
${serverjson.web.http.[email protected]-custom.json}
4
${serverjson.[email protected]-custom.json:defaultValue}
Copied!
box.json properties
If the current working directory of the shell contains a box.json file, you can reference any property in it with the boxjson. namespace.:
1
${boxjson.name}
2
${boxjson.slug}
3
${boxjson.testbox.runner}
4
${boxjson.description:defaultValue}
Copied!
Arbitrary JSON file properties
You can can reference properties from any JSON file with either a relative path (to the current working directory) or an absolute path with the json. namespace..
1
${json.myProperty.[email protected].json}
2
${json.myProperty.[email protected]/path/to/myFile.json:defaultValue}
Copied!
Config settings
You can expand any valid config setting with the configsetting. namespace.  So getting the same value you get when you run the command
1
config show endpoints.forgebox.apitoken
Copied!
can be expanded like this:
1
${configsetting.endpoints.forgebox.apitoken}
2
${configsetting.endpoints.forgebox.apitoken:defaultValue}
Copied!
Server info properties
You can expand any valid server info property with the serverinfo. namespace.  So getting the same value you get when you run the command
1
server info property=serverHomeDirectory
Copied!
can be expanded like this:
1
${serverinfo.serverHomeDirectory}
2
${serverinfo.serverHomeDirectory:defaultValue}
Copied!
By default, the expansion looks at the default server in the current working directory.  To grab a server property by server name, use this syntax:
1
${serverinfo.[email protected]}
2
${serverinfo.[email protected]:defaultValue}
Copied!
Other properties in the same JSON file
You can self-reference other properties in the same JSON file using the @ namespace.  So given the following JSON file:
1
{
2
    "appFileGlobs" : "models/**/*.cfc,tests/specs/**/*.cfc",
3
    "scripts":{
4
        "format":"cfformat run ${@appFileGlobs} --overwrite",
5
        "format:check":"cfformat check ${@appFileGlobs} --verbose"
6
    }
7
}
Copied!
The expansion of ${@appFileGlobs} self-references the appFileGlobs property inside the same file, allowing for easy re-use of that value.
Custom namespaces
Modules can register an onSystemSettingExpansion interceptor to contribute custom system setting namespace expansions. The interceptor gets the following data in interceptData
setting - The name of the setting to be expanded (with ${} and :defaultValue removed)
defaultValue - The default value, or empty string if none specified
resolved - A boolean that should be set true if the interceptor was able to resolve the setting
context - A struct of the original JSON being expanded or the parameters from the command line where the expansion was used.
A hypothetical example would be:
1
function onSystemSettingExpansion( struct interceptData ) {	
2
  // ${luceeInfo.property}
3
  if( interceptData.setting.lcase().startsWith( 'luceeinfo.' ) ) {
4
		
5
    var settingName = interceptData.setting.replaceNoCase( 'luceeInfo.', '', 'one' );
6
				
7
    interceptData.setting = server.lucee[ settingName ] ?: interceptData.defaultValue;
8
		
9
    // Stop processing expansions on this setting
10
    interceptData.resolved=true;
11
    return true;
12
  }	
13
}
Copied!
And then we would use our hypothetical namespace to reference any Lucee information like so
1
echo ${luceeinfo.version}
Copied!
It's important if you implement your own onSystemSettingExpansion interceptor that you check the incoming setting to see if it applies to you.  If you process the system setting, you must place the final expanded value back in the interceptData.setting struct key, set interceptData.resolved to true and return true from the interception method so the chain stops processing. 