====
json
====

Parse variables from a JSON file or from a variable (for example, ``RESULT_STDOUT``) that contains a valid JSON string.
If the "local_path" option is used, the JSON is read directly from the specified file. The "cmd" option is optional. If "local_path" is defined, the "cmd" option will be ignored.
If no "local_path" is set, the JSON is read from the "cmd" option. The variables are recursively parsed from the JSON input and saved in the variable store.
The variables are recursively parsed from the json input and are saved as single variables in the variable store.
Variable names are generated by concatenating keys at each level using an underscore (_) as a separator.
If the lowest-level value is a list of primitives (e.g., strings, integers), the list is preserved as-is without further flattening.

Example
-------

Given the following JSON input:

.. code-block:: json

    {
      "first_list": [1, 2, 3],
      "user": {
        "name": "John Doe",
        "age": 30,
        "address": {
          "street": "123 Main St",
          "city": "New York",
          "postal_codes": [10001, 10002]
        },
        "friends": [
          {
            "name": "Jane Smith",
            "age": 28,
            "address": {
              "street": "456 Oak Rd",
              "city": "Los Angeles",
              "postal_codes": [90001, 90002]
            }
          },
          {
            "name": "Emily Davis",
            "age": 35,
            "address": {
              "street": "789 Pine Ln",
              "city": "Chicago",
              "postal_codes": [60007, 60008]
            }
          }
        ]
      }
    }

The variables would be saved in the variable store as follows:

.. code-block:: yaml

    first_list: [1, 2, 3]
    user_name: "John Doe"
    user_age: 30
    user_address_street: "123 Main St"
    user_address_city: "New York"
    user_address_postal_codes: [10001, 10002, 10003]
    user_friends_0_name: "Jane Smith"
    user_friends_0_age: 28
    user_friends_0_address_street: "456 Oak Rd"
    user_friends_0_address_city: "Los Angeles"
    user_friends_0_address_postal_codes: [90001, 90002]
    user_friends_1_name: "Emily Davis"
    user_friends_1_age: 35
    user_friends_1_address_street: "789 Pine Ln"
    user_friends_1_address_city: "Chicago"
    user_friends_1_address_postal_codes: [60007, 60008]

Configuration
-------------

.. confval:: local_path

   The JSON input to parse from. Valid input is a path to a JSON file. If "local_path" is set, the "cmd" option will be ignored.

   :type: str
   :required: False

.. confval:: cmd

   The JSON input to parse from. Valid input is a variable name from the variable store (without the leading ``$``) that contains a valid JSON string.

   :type: str
   :required: False

   Either ``local_path`` OR ``cmd`` is required.

.. confval:: varstore

   If set to ``True``, logs the variable store before and after adding variables using the JSON command.

   :type: bool
   :required: False

Examples
--------

.. code-block:: yaml

    commands:
      - type: json
        local_path: "/path/to/samplefile.json"
        varstore: True
      - type: shell
        cmd: |
          cat <<EOF
          {
            "name": "Whiskers",
            "favorite_toys": ["ball", "feather", "laser pointer"]
          }
          EOF
      - type: json
        cmd: RESULT_STDOUT
        use_var: True