Add deck file echo --selector=... command

[rspurgeon]

Various commands in the deck file subcategory use JSON Path selectors to apply transformations to declarative files in a pipeline. This issue raises a proposal to add a command that will return a value from a selector on STDOUT. This command can be useful in a few scenarios:

1. Provide a command that can be used at development time to test the behavior of a given selector
2. Provide a command that can be used in pipelines to query a file for a value using the same syntax as the rest of the pipeline. This could be useful to populate an env var or feed into a --value parameter in a subsequent command.

Suggested syntax:

deck file echo --selector "$..key" --format yaml|json -n

print or echo verbs could be chosen.

-n will append a new line to the returned value, otherwise no newline character is added

The command should fail (return non-zero exit code) if the selector returns no value so that users can easily determine empty values vs "missed selectors" as well as break pipelines if queries fail.

[Tieske]

how about deck file select "$..key1" "$..key2"

• -s, --state string file to read from, default "-" (stdin)
• -o, --output-file string to specify an output file, default "-" (stdout)
• --format string output format to specify json/yaml
• --allow-empty to not fail on an empty selection (output becomes an empty array)

what's the use of the -n? yaml is always multi-line, so does it matter to have one more or less?

[rspurgeon]

what's the use of the -n?

I missed that the output options should include text only (non-structured values) for selecting down to a single value to pass into subsequent commands or variables. Maybe that can be automatic based on the selector results. It's similar to bash echo which provides a new line by default but often needs to be suppressed. We can match the behavior of echo if we want.

I'm indifferent on the select verb. If we allow multiple selectors we'll need to design outputting multiple values in a helpful way. I'm not sure it's necessary to support multiple personally.

[Tieske]

That makes sense.

A selector always returns an array. So individual values to be returned needs some extra flags to specify then.

if a selector returns:

[
  "hello"
]

How would the command know to output hello over ["hello"] ?

Adding a flag --single or --first to return the first entry, then what would the behaviour be if there is more than 1 entry in the selector result?

[rspurgeon]

A selector always returns an array.

Thank you, I had forgotten this was the behavior even for the scalar return values. Considering the options...