Syntax and actions

Syntax

The syntax of the jsonPlug method is:

moduleVariable.jsonPlug(result, {
    action: parameterValue,
    jsPathConditionFlag: parameterValue,
    jsPath: parameterValue,
    jsPathAction: parameterValue,
    recursive: parameterValue,
    values: parameterValue [,
    skipNameValidation: parameterValue
    addIndexToRecords: parameterValue]
});

Note

The parts in square brackets are optional.

parameterValue is one of the possible values of the corresponding parameters described below:

• moduleVariable is the variable corresponding to the module and set with require().
• result is the object containing the analysis results.

• action is the action to perform on the results object. The available values for this parameter are:

  • delete
  • delete template
  • delete record
  • add field
  • add fields
  • add template
  • add record
  • add property
  • add key
  • clone
  • clone new
  • clone new multiple
  • clone value
  • clone instances
  • add category
  • modify
  • modify regex
  • apply math

  Note

  The following actions can be used interchangeably, producing the same output:

  • delete template and delete record.
  • add field and add fields.
  • add template and add record.
  • add property and add key.

• jsPathConditionFlag is either a boolean or a string. In the first case, it can be:

  • true: the action specified by the action parameter is performed only if the value of jspath selects one or more nodes.
  • false: the action specified by the action parameter is performed only if the value of jspath does not select any nodes.

  In the second case, it can be a string and it is a condition relating to the number of nodes—the count—selected by jspath. The action is applied if the condition is verified (see below). The string has this format:

  count operator integer

  where:

  • operator can be:
    • >
    • <
    • <=
    • >=
    • =
    • ==
  • integer is a non-negative integer number.

  Or, it can be this string:

  multiple

  where multiple allows the action performance thanks to boolean values specified in jsPath (see the example in modify).

  jsPathConditionFlag is a condition relating to the number of nodes—the count—selected by jspath. The action is applied if the condition is verified.

  For example, if jsPathConditionFlag is:

  count > 3
  

  it means that jsPath must identify at least three nodes for the action to be applied.

• jsPath is either a single JSONPath expression or an array of JSONPath expressions that, in combination with jsPathAction (except for the case when also jsPathAction is a full JSONPath expression), determines the nodes to which the action must be applied. The elements of the jsPath parameters are evaluated in couples:

  • A boolean that is a flag necessary for the application of the action. If true, the action is performed to the nodes selected by the JSONPath expression.
  • A JSONPath expression indicating the nodes where the action must be performed.

  Info

  Several useful resources are available on the Web to get more information about JSONPath syntax and to test JSONPath expressions.

• jsPathAction is either a single JSONPath expression or an array of JSONPath expressions (for the array case, see the second example in clone) that, alone or in combination with jsPath, determines where the action must be applied. Its value can be:

  • #this# or .: the action is applied to the nodes selected by jspath.
  • ^: the action is applied to the parent nodes of the nodes selected by jspath.
  • ^ relativepath: the action is applied to the sibling nodes of the nodes selected by jspath that matches relativepath.
  • . relativepath: the action is applied to a child node selected by jspath that matches relativepath.

  • a JSONPath expression: the action is applied to the nodes selected by jsPathAction if jspathConditionFlag is satisfied. In case of an array, the elements of the expression are:

    • A boolean that is a flag necessary for the application of the action. If true, the action is performed to the nodes selected by the JSONPath expression.
    • A JSONPath expression indicating the nodes where the action must be performed.

• recursive is a boolean indicating if the action has to be applied to the first or to all of the nodes selected by jsPath and/or jsPathAction.

• values is an array containing the specification of the action. The meaning of the array items and their order vary according to the action.

• skipNameValidation (optional) doesn't apply the template and field validation if set to true. This optional flag is used for:

  • modify
  • modify regex
  • add field and add fields
  • add template and add record
  • clone
  • clone new
  • clone new multiple
  • clone value
  • clone instances

• addIndexToRecords (optional) if set to true, an index property will be temporarily added to each extracted record during the jsonpath validation phase. This property will contain the position of each record within the extraction array and will be automatically deleted after the jsonpath evaluation is applied.

Note

For modify, values can also be a string.

Alternatively, you can use this syntax:

moduleVariable.jsonPlug(result, action, jsPathConditionFlag, jsPath, jsPathAction, recursive, values, skipNameValidation, addIndexToRecords)

Note

• The parameters in the second syntax must be declared in this exact order.
• Both syntaxes can be used interchangeably.

Actions

The following pages will describe the possible values of the action parameter. The value of the values parameter is interpreted based upon the value of action.

Note

All actions changing the categorization results will automatically re-calculate the frequency score of each category.

The example codes will be written according to the first syntax explained above.