Add

This command allows to add a single value in the data at a given path.

The examples on this page will refer to the JSON file "People.json" that can be found in the playground.

Tip

Any of the four People files could be used.

People.json

{
  "Tom" : {
    "age" : 68,
    "hobbies" : [
      "cooking",
      "guitar"
    ],
    "height" : 175
  },
  "Robert" : {
    "age" : 23,
    "hobbies" : [
      "video games",
      "party",
      "tennis"
    ],
    "running_records" : [
      [
        10,
        12, 9,
        10
      ],
      [ 9,
        12,
        11
      ]
    ],
    "height" : 181
  },
  "Suzanne" : {
    "job" : "actress",
    "movies" : [
      {
        "title" : "Tomorrow is so far",
        "awards" : "Best speech for a silent movie"
      },
      {
        "title" : "Yesterday will never go",
        "awards" : "Best title"
      },
      {
        "title" : "What about today?"
      }
    ]
  }
}

Input and Output

The option -i|--input option can be used to specify a file as input. Otherwise Scout can read the input stream. The option -o|--output option can be used to specify a file where the modified data should be written. Otherwise Scout will output it in the terminal. The option -m|--modify option can be used to specify a file as input and as output.

Basics

❖ Add the key "score" with the value 250 to Tom's dictionary.

scout add -i People.json -f json "Tom.score=250"

Important

In the next examples, the option -i People.json -f json will be implicitly specified.

Add New Key

To add a new key to a dictionary, it has to be the last element in the path.

❖ Add a new key "surname" to Robert's dictionary.

scout add "Robert.surname=Bob"

Add at Index

To insert an element at a given index, it has to be the last element in the path.

❖ Insert a new hobby to Robert's hobbies at index 1.

scout add "Robert.hobbies[1]=surfing"

Updated hobbies array

"hobbies" : [
  "video games",
  "surfing",
  "party",
  "tennis"
]

Add New Array or Dictionary

It's also possible to add a dictionary or an array. An array is specified as a list of values separated by commas and enclosed by square brackets.

❖ Add a new "colors" array to Tom's dictionary.

scout set -i People.json -f json "Tom.colors=[Blue, White, Yellow]"

Similarly, a dictionary is a list of (key, value) parts separated by double points and enclosed by curl brackets.

❖ Add a new dictionary named "weekdays" to Robert.

scout add -i People.json -f json "Robert.weekdays={monday: 5, thursday: 3}"

Empty Arrays or Dictionaries

Sometimes, it might me useful to add an empty array or dictionary to fill it dynamically after. To do so, the enclosing brackets can be used.

❖ Empty array

scout set -i People.json -f json "Tom.colors=[]"

❖ Empty dictionary

scout add -i People.json -f json "Robert.weekdays={}"

Then, it's possible to write a for loop for instance to parse an array and add the values to the array/dictionary.

file="path/to/file"
colors=(Red White Blue)

scout add -m $file -f $format "Tom.colors=[]"

for color in $colors; do
    scout add -m $file -f $format "Tom.colors[#]=$color"
done

Nested Values

It’s possible to nest values in each other. Although it’s not recommenced to nest too much, this can be useful when the value is built programmatically.

❖ Set Robert weekdays to a dictionary of arrays.

scout set -i People.json -f json \
"Robert.weekdays={monday: [1, 2], thursday: [3, 4]}"

Forcing a Type

The library tries to infer the type of a value to set it. For instance "12.3" will be taken as a Double and "true" as a Boolean. If necessary, it's possible to prevent this automatic type inferring and force one.

• String: enclose the value with slash signs to force the value as a string: /valueAsString/.
• Real/Double: enclose the value with tilde signs to force the value as a real: ~valueToReal~.

❖ Add to Suzanne's last movie an award with string value "2.0".

scout add "Suzanne.movies[-1].awards=/2.0/"