Set

This command allows to set 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?"
      }
    ]
  }
}

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

Set Tom's height to 160.

scout set -i People.json -f json "Tom.height=160"

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

scout set "Tom.height=160" "Robert.hobbies[0]=sleeping"

Common

Invalid paths

If the path is invalid, the command will return an error with a proper message. A path can be invalid for several reasons. For instance:

A given key does not exist in a dictionary
An index is greater than an array element's count
A special element is not used properly

This command will return an error because the key "score" does not exist in Tom's dictionary.

scout set "Tom.score=250"

When that's possible, the program will display a message to offer another possible key name. For instance the command

scout set "Tom.heiht=160"

will return an error but will also inform that the key 'height' is near the 'heiht' word.

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"

Set Robert's second hobby to "talking".

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

Set Robert's last hobby to "talking loud".

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

Set command specificities

Set the key name

It's possible to set the key name in a dictionary rather the key value.

Enclose the value with sharp signs: #keyName#.
Set Tom "age" key name to "years"

scout set "Tom.age=#years#"

Set dictionaries and arrays

It’s possible to set or add a group value to a path. An array is a list of values separated by commas and enclosed by square brackets. A dictionary is a list of (key, value) parts separated by double points. Those values are separated by commas and enclosed by squared brackets.

Set Tom hobbies to a new array.

scout set "Tom.hobbies=[driving, watching movies]"

Set Robert's dictionary to a new value.

scout set "Robert={surname: Bob, score: 20}"

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 to a dictionary of arrays

scout set "Robert={monday: [1, 2], thirsday: [3, 4]}"

Empty arrays and dictionaries

It's possible to provide an empty array or dictionary when setting a value. If it might be nice to have that for the "set" features, its especially useful with the add feature to dynamically fill a dictionary or array. Set Tom's hobbies to an empty array.

scout set "Tom.hobbies=[]"

Set Robert's dictionary to an empty value.

scout set "Robert={}"

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.

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~.

Set Suzanne's third movie title to the string value "2.0"

scout set "Suzanne.movies[-1].title=/2.0/"