Store and transform

This feature is officially available in Carbone v5. However, you can activate it in v4 by inserting {o.preReleaseFeatureIn=4022011} into your template.
For more details, refer to the Files and features documentation.

Store values -> :set(absolutePath)

The :set(absolutePath) formatter allows you to store values in data. absolutePath specifies the destination where the value will be stored.

• It is good practice to store new variables in the complement object ({c.}) instead of the data object ({d.}). This helps maintain a cleaner and more organized data structure.
• The execution order of multiple Carbone tags using the :set formatter is guaranteed within the same section of a document (e.g., body, header, footer, or text box).
  As a result, you can create new variables that depend on previously created ones. When one :set expression is used to create another, the new expression must be defined after or below the existing one.
• The :set formatter overwrites existing values in the data.

A Carbone tag using :set does not print anything in the generated report. The tag is removed when executed. A loop with iterators [i] cannot be used in combination with :set.

Example: store the sum in c.mySum

Example with order of execution:

Modify JSON -> :set(.relativePath)

Add or modify attributes in your data using a JSON relative path.

In this example, the Carbone tags {d.cars[].qty:append(' tyres'):set(.newInfo)} adds the attribute "newInfo" to all objects in the "cars" array.

• d.cars[]: Loops over all cars.
• .qty: Prints the qty value.
• append(' tyres'): Appends the string " tyres" to qty.
• :set(.newInfo): Stores the result in the new attribute newInfo in each object of cars

Transform JSON -> :set(absolutePath[])

Generate a completely new JSON structure with :set formatter.

Here is an overview of the syntax:

{ d.sourceArray[arrayFilter] :set( c.destinationArray[searchExpression] )}

• d.sourceArray : The existing array
• [arrayFilter] : Optional array filters. The i iterator is not allowed with the :set formatter. Leave empty [] to traverse all data.
• :set: The formatter
• c.destinationArray : The newly created array in c.
• [searchExpression] : An optional condition used to find and merge items with existing ones in the newly created array. It works like an inner join expression in SQL. An empty searchExpression is accepted only for the last created array in the :set() expression. In this case, all items are aggregated without searching for existing ones. Only the equality = operator is allowed in the searchExpression, and exactly one expression is permitted within []. This searchExpression works only on newly created arrays by Carbone, not on existing arrays in the original JSON data passed when calling Carbone.

Learn the basics with simple examples:

• Clone arrays
• Selective array cloning
• Merge arrays

Advanced usage with search/join expressions:

• Distinct merge
• Group data in nested arrays

Cloning arrays

{ d.myArray[] :set( c.new[] )}

• d.myArray[] : Loops over the existing array and retrieves its content
• :set(c.new[]): Injects the content into a new array located at {c.new}.

Array of objects example:

Array of string example:

Selective array cloning

In this example, only the country attribute is injected into the new array.

As you can see, Carbone creates an array of string or an array of objects according to destination c.newArr1[] or c.newArr2[].country.

Merge arrays

Distinct Merge

Carbone accepts a search expression enclosed in square brackets to determine how to add new items.

If an item in the new array matches the condition, the new item is merged with the existing one

{ d.myArray[] :set( c.new[ country = .country] )}

• d.myArray[] : Loops over the existing array and return its content
• :set(c.new[ country = .country ]): Injects the content into a new array
  • c.new is the newly created array in c.
  • [country=.country] is a search expression used to find existing items that match the criteria
  • country is a relative path to the new object inside c.new. Equivalent to c.new[].country
  • .country is a relative path in the currently visited array. Equivalent to d.myArray[].country

Automatic creation of non-existing attributes

If the left operand of the condition does not exist, Carbone automatically creates it (c.new[].id).

Group data in nested arrays

Carbone accepts a search expression enclosed in square brackets to determine how to add new items.

If an item in the new array matches the condition, the new item is merged with the existing one

{ d.myArray[] :set( c.countries[ id = .country].cities[] )}

• d.myArray[] : Loops over the existing array and return its content
• :set(c.countries[ id = .country ]: Injects the content into the new array c.countries[]
  • c.countries is the newly created array in c.
  • [id=.country] is a search expression used to find existing items that match the criteria
  • id is a relative path to the new object inside c.countries. Equivalent to c.countries[].id
  • .country is a relative path within the currently visited array. Equivalent to d.myArray[].country
• .cities[]): For each country, injects items into the new nested array cities[]

Other examples

Here, only city is injected into the :set. Carbone creates an array of strings.

Join two arrays -> :set(absolutePath[])

Here is a basic example to join two separate arrays: