CommandBox

PropertyFile is a library designed to load, modify, and store Java property files directly from CFML using a fluent API. It encapsulates the behavior of a Java properties file within a single CFC, allowing you to manage properties without writing Java code.

getInstance( 'propertyFile' )
    .load( myPath )
    .set( 'myProp', 'myValue' )
    .store();

Most methods in the PropertyFile object that do not return an explicit value return this, enabling a fluent interface for chaining operations like loading, setting, and storing in a single statement.

getInstance( 'propertyFile' )
	.load( myPath )
	.set( 'myProp', 'myValue' )
	.set( 'myOtherProp', 'myOtherValue' )
	.store();

On Lucee 5, the library uses an alternate formatter that deserializes JSON to ordered structs, providing a significant performance boost while preserving key order and data types.

Adobe ColdFusion does not preserve key order and (prior to ACF 2018) may inaccurately serialize data types. If you are using ColdFusion and want the performance boost of the Lucee 5 formatter—and you are willing to accept the loss of key order or potential data type inaccuracies—you can inject the specific formatter using the @JSONPrettyPrint alias.

component {
  // Inject the Lucee 5 formatter specifically
  property name='JSONPrettyPrint' inject="CFMLPrinter@JSONPrettyPrint";

  function writeJSON( required JSON, required path ) {
    fileWrite( path, JSONPrettyPrint.formatJSON( JSON ) );
  }
}

JMESPath supports several special characters to control how expressions and values are evaluated:

• @ (Current Node): Refers to the current number, string, array, or object being evaluated.
• & (Expression): Used to denote a function or a keyname (e.g., &to_number() or &keyname). This is required when passing functions as arguments to other functions.
• ! (NOT): Negates an expression.
• && (AND): Logical AND expression.
• || (OR): Logical OR expression.
• `{'ab':true}` (Literal Expressions): Used to define literals, which are converted to JSON.
• 'foo' (Raw String Literals): Single quotes are used for raw strings that should not be evaluated.

To add the JMESPath implementation to your Commandbox environment, use the box install command.

$ box install jmespath

JSONPrettyPrint is a threadsafe singleton and is designed to be injected using WireBox.

component {
  property name='JSONPrettyPrint' inject;

  function writeJSON( required JSON, required path ) {
    fileWrite( path, JSONPrettyPrint.formatJSON( JSON ) );
  }
}

You can pass file paths or raw JSON strings as the data argument to JMESPath.search.

// Using a file path via expandPath
JMESPath.search(expression, expandPath('/path/to/data.json'));

// Using file content directly
fileContent = fileRead(expandPath('./path/to/data.json'), 'utf-8');
JMESPath.search(expression, fileContent);

To initialize the utility with an existing file, create an instance using getInstance( 'propertyFile' ) and call the load() method with the absolute path to the file.

var propertyFile = getInstance( 'propertyFile' ).load( expandPath( 'myFile.properties' ) );

Install the JSONPrettyPrint module via the CommandBox CLI to enable pretty-printing of JSON objects with human-readable indentation and line breaks.

CommandBox> install JSONPrettyPrint