Read

This command outputs a single value (e.g. a string) or a group value (e.g. a dictionary) for 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?"
      }
    ]
  }
}

Basics

Read Tom's height.

Use the option -i|--input to specify a file as input. Otherwise Scout can read the input stream.

scout read -i People.json -f json "Tom.height"

Important

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

Get a Group Value

❖ Read Tom's dictionary.

scout read "Tom"

Output

{
  "age" : 68,
  "hobbies" : [
    "cooking",
    "guitar"
  ],
  "height" : 175
}

Count

It's possible to get a dictionary or an array count with the count [#] symbol.

❖ Get Robert hobbies count.

scout read "Robert.hobbies[#]"

❖ Get people count.

scout read "[#]"

Keys Symbol

List the keys of a dictionary with the keys list {#} symbol.

❖ Get the keys of the Suzanne's dictionary.

scout read "Suzanne{#}"

Output

[
  "job",
  "movies"
]

Array Slicing

It's possible to target a slice of an array from a lower bound to an upper bound. The upper bound is included. When a array is sliced, it's possible to continue the path with a next element that elements in the slice have in common.

A slice is specified with square brackets and a double point ':' between the bounds: '[lower:upper]'. No lower means 0 like [:10] and no upper means the last index like [10:]. Use a negative index to target the last nth elements like [-4:] to target the last 4 elements or [-4: -2] to target from the last fourth to the last second element.

❖ Get Robert's first two hobbies.

scout read "Robert.hobbies[:1]"

Output

[
  "video games",
  "party"
]

❖ Get Suzanne's movies titles.

scout read "Suzanne.movies[:].title"

Output

[
  "Tomorrow is so far",
  "Yesterday will never go",
  "What about today?"
]

Keys Filtering

It's possible to target specific keys in a dictionary with a regular expression. When a dictionary is filtered, it's possible to continue the path with a next element that elements in the slice have in common. If the provided regular expression is invalid, an error will be thrown/returned.

This element is enclosed by sharp '#' signs. For instance #.*device.*# to target all the keys in a dictionary containing the word device.

❖ Get Tom keys that start with 'h'.

scout read "Tom.#h.*#"

Output

{
  "hobbies" : [
    "cooking",
    "guitar"
  ],
  "height" : 175
}

❖ Get Tom and Robert first hobby.

scout read "#Tom|Robert#.hobbies[0]"

Output

{
  "Robert_hobbies_index(0)" : "video games",
  "Tom_hobbies_index(0)" : "cooking"
}

Mixing

It's possible to mix the array slicing and dictionary filtering features.

❖ Get Tom and Robert first two hobbies.

Output

{
  "Tom" : [
    "cooking",
    "guitar"
  ],
  "Robert" : [
    "video games",
    "party"
  ]
}

Zsh Arrays

Scout allows to read a Zsh array directly from an array or dictionary. To get a 1-dimension array from the data, the option —export|-e can be used with the array option and by enclosing the result with brackets.

hobbies=("${(@f)$(scout read -i People.json -f json "Robert.hobbies" -e array)}")
echo $hobbies[1] # video games

The same goes for dictionaries to associative arrays with the dictionary option.

declare -A movie=("${(@f)$(scout read -i People.json -f json "Suzanne.movies[0]" -e dictionary)}")
echo $movie[title] # Tomorrow is so far

XML Attributes

When working with XML and the read features, Scout will allow to read an attribute with a key element from 4.0.0.

For instance with the following XML.

<Tom score="20">
    <height>175</height>
    <age>68</age>
</Tom>

It’s possible to read the score value.

❖ The following will output 20.

scout read -I Tom.xml -f xml "Tom.score"

❖ When the following will output 68.

scout read -I Tom.xml -f xml "Tom.[1]"