Add

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

The examples on this page will refer to this JSON file that can be found in the playground (you might want to copy/paste or to download it somewhere to keep it in sight).
Note that any of the four People files could be used.

{
  "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?"
      }
    ]
  }
}

Command-line 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.

Simple example

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

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

In the next examples, the option -i People.json -f json will be implicitly specified.
The add command can also take several paths with an associated value.

scout add "Tom.score=250" "Robert.surname=Bob"

Common

Array subscripting

It's possible to set an element in an array by specifying its index.
When the index is negative, this targets an element starting from the end of the array.
This figure gives an example with the 'ducks' array.

["Riri", "Fifi", "Loulou", "Donald", "Daisy"]
[  0   ,   1   ,    2    ,    3    ,    4   ] (Positive)
[ -5   ,  -4   ,   -3    ,   -2    ,   -1   ] (Negative)

ducks[1] targets "Fifi"
ducks[-2] targets "Donald"

Add a hobby to Robert's hobbies at the second index.

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

Add a hobby to Robert's hobbies at the last index.

scout add "Robert.hobbies[-1]=talking loud"

Add specificities

Add a new key

To add a new key to a dictionary, it has to be the last element in the path.
For instance to add a new key "surname" to Robert's disctionary.

scout add "Robert.surname=Tom"

Add at an index

To insert an element at a given index, it has to be the last element in the path. For instance to insert a new hobby to Robert's hobbies at index 1.

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

The hobbies array will then look like this.

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

It's possible to add an element at the end of an array with the count # element. Again, it will work only when it's the last element.

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

The hobbies array will then look like this.

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

Add a 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. For instance, to 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.
For instance to add a new dictionary named "weekdays" to Robert.

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

Empty arrays and 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.

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

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], thirsday: [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 Bool.
If necessary, it's possible to prevent this automatic type inferring and force one.

Command-line

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/"