writeToml

Signature

function writeToml(string calldata json, string calldata path) external;
 
function writeToml(string calldata json, string calldata path, string calldata valueKey) external;

Description

Writes a serialized JSON object to a TOML file after conversion.

The argument json must be a JSON object in stringified form. For example:

{ "boolean": true, "number": 342, "object": { "title": "finally json serialization" } }

This is usually built through serializeJson.

The argument path is the path of the TOML file to write to.

If no valueKey is provided, then the TOML object will be written to a new file. If the file already exists, it will be overwritten.

If a valueKey is provided, then the file must already exist and be a valid TOML file. The object in that file will be updated by replacing the value at the JSON path valueKey with the JSON object json after TOML conversion.

This is useful for replacing some values in a TOML file without having to first parse and then reserialize it. Note that if the specified key, or any of the intermediate ones in the JSON path, don't exist, they will be created.

Remember: The file path path needs to be in the allowed paths. Read more in File cheatcodes.

JSON Paths

The valueKey parameter uses JSONPath syntax to specify where in the JSON structure to place or update the value. Foundry uses the jsonpath_lib library internally to parse these paths.

Let's consider the following JSON object:

{
  "boolean": true,
  "number": 342,
  "obj1": {
    "aNumber": 123,
    "obj2": {
      "aNumber": 123,
      "obj3": {
        "veryDeep": 13371337
      }
    }
  }
}

Important: JSON paths must be properly formatted to work correctly:

• Root object assumption: The root object is always assumed, so you should start paths with a dot (.) or dollar sign ($)
• Dot notation: Use .boolean, .number, .obj1 to access root-level properties
• Nested access: Use .obj1.aNumber or .obj1.obj2.aNumber to go deeper into the structure
• Descendant search: Use ..keyName to search for a key anywhere in a subtree, like .obj1..veryDeep or just ..veryDeep

Common mistake: Using bare key names like "key.foo" will be silently converted to "$key.foo" by the JSONPath parser, which will fail because it looks for a root property named key.foo. Instead, use ".key.foo" or "$.key.foo".

Valid path examples:

• .boolean - accesses the boolean property at root level
• $.boolean - equivalent to above using explicit root notation
• .obj1.aNumber - accesses nested property
• .obj1..veryDeep - finds veryDeep anywhere within obj1
• ..veryDeep - finds veryDeep anywhere in the document

See the examples to see this in action.

Examples

A simple example

string memory jsonObj = '{ "boolean": true, "number": 342, "myObject": { "title": "finally json serialization" } }';
vm.writeToml(jsonObj, "./output/example.toml");
 
// replaces the value of `myObject` with a new object
string memory newJsonObj = '{ "aNumber": 123, "aString": "asd" }';
vm.writeToml(newJsonObj, "./output/example.toml", ".myObject");
 
// replaces the value of `aString` in the new object
vm.writeToml("my new string", "./output/example.toml", ".myObject.aString");
 
// Here's example.toml:
//
// boolean = true
// number = 342
 
// [myObject]
// aNumber = 123
// aString = "my new string"

A more complex example

string memory jsonObj = '{ "boolean": true, "number": 342, "obj1": { "foo": "bar" } }';
vm.writeToml(jsonObj, "./output/example2.toml");
 
string memory jsonObj2 = '{ "aNumber": 123, "obj2": {} }';
vm.writeToml(jsonObj2, "./output/example2.toml", ".obj1");
 
string memory jsonObj3 = '{ "aNumber": 123, "obj3": { "veryDeep": 3 } }';
vm.writeToml(jsonObj3, "./output/example2.toml", ".obj1.obj2");
 
// Here's example2.toml so far:
//
// boolean = true
// number = 342
//
// [obj1]
// aNumber = 123
//
// [obj1.obj2]
// aNumber = 123
//
// [obj1.obj2.obj3]
// veryDeep = 3
 
// Note that the JSON object is just the value 13371337 in this case.
vm.writeToml("13371337", "./output/example2.toml", "..veryDeep");
 
// Here's the final example2.toml:
//
// boolean = true
// number = 342
//
// [obj1]
// aNumber = 123
//
// [obj1.obj2]
// aNumber = 123
//
// [obj1.obj2.obj3]
// veryDeep = 13371337

SEE ALSO

• serializeJson