From 73db6587a03cf057ca258c6c95631ceb74a57cf8 Mon Sep 17 00:00:00 2001 From: Mattias Wadman Date: Sun, 26 Feb 2023 21:18:36 +0100 Subject: [PATCH] interp: Exit with error if -o name=@path fails to be read, also document --- doc/usage.md | 26 ++++++++++++++++++ pkg/interp/options.jq | 10 ++++--- pkg/interp/testdata/args.fqtest | 42 +++++++++++++++--------------- pkg/interp/testdata/options.fqtest | 8 ++++++ 4 files changed, 62 insertions(+), 24 deletions(-) diff --git a/doc/usage.md b/doc/usage.md index 830f9e2d..184cff60 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -71,6 +71,32 @@ fq -d mp4 file.mp4 fq -o force=true -d mp4 file.mp4 ``` +### CLI arguments + +Most of fq's CLI argument are borrowed from jq and works in the same way. + +#### Decode format `--decode`, `-d NAME` + +Force format to decode instead of probing. + +`NAME` is a name of a format, ex `-d mp4`, see `-h formats` for list of formats. + +#### Interactive REPL `--repl`,`-i` + +Start interactive REPL. + +Can be used with both no, one and multiple inputs, ex just `fq -i ` start a REPL with `null` input, `fq -i 123` with the number 123 as input, `fq -i . a b` with two files as input. Also works with `--slurp`. + +#### Set option `--options`,`-o KEY=VALUE|@PATH` + +`KEY` is name of option + +`VALUE` will be interpreted as a JSON value if possible otherwise a string, ex -o `name=abc` and `-o name='"abc"'` is the same. + +`@PATH` will read string from file at `PATH`. + +Specify a global option or a format option, ex: `-o decode_samples=false` would for some container decoders like `mp4` and `matroska` disable decoding of samples. + ### Display output `display` or `d` is the main function for displaying values and is also the function that will be used if no other output function is explicitly used. If its input is a decode value it will output a dump and tree structure or otherwise it will output as JSON. diff --git a/pkg/interp/options.jq b/pkg/interp/options.jq index 0de21994..5adc1d69 100644 --- a/pkg/interp/options.jq +++ b/pkg/interp/options.jq @@ -113,6 +113,7 @@ def _opt_options: def _opt_eval($rest): ( with_entries( ( select(.value | _is_string and startswith("@")) + | .key as $opt | .value |= ( . as $v | try @@ -121,7 +122,10 @@ def _opt_eval($rest): | tobytes | tostring ) - catch $v + catch + ( "-o \($opt)=@\($v[1:]): \(.)" + | halt_error(_exit_code_args_error) + ) ) ) ) @@ -413,7 +417,7 @@ def _opt_cli_opts: "show_help": { short: "-h", long: "--help", - description: "Show help for TOPIC (ex: --help, -h formats, -h mp4)", + description: "Show help for TOPIC (ex: -h formats, -h mp4)", string: "[TOPIC]", optional: true }, @@ -453,7 +457,7 @@ def _opt_cli_opts: short: "-o", long: "--option", description: "Set option (ex: -o color=true, see --help options)", - object: "KEY=VALUE", + object: "KEY=VALUE/@PATH", }, "string_input": { short: "-R", diff --git a/pkg/interp/testdata/args.fqtest b/pkg/interp/testdata/args.fqtest index 2aa6f920..8fdbf1c0 100644 --- a/pkg/interp/testdata/args.fqtest +++ b/pkg/interp/testdata/args.fqtest @@ -24,27 +24,27 @@ Example usages: fq -r 'grep_by(.protocol=="icmp").source_ip | tovalue' *.pcap fq -i ---arg NAME VALUE Set variable $NAME to string VALUE ---argdecode NAME PATH Set variable $NAME to decode of PATH ---argjson NAME JSON Set variable $NAME to JSON ---color-output,-C Force color output ---compact-output,-c Compact output ---decode,-d NAME Decode format (probe) ---from-file,-f PATH Read EXPR from file ---help,-h [TOPIC] Show help for TOPIC (ex: --help, -h formats, -h mp4) ---include-path,-L PATH Include search path ---join-output,-j No newline between outputs ---monochrome-output,-M Force monochrome output ---null-input,-n Null input (use input and inputs functions to read) ---null-output,-0 Null byte between outputs ---option,-o KEY=VALUE Set option (ex: -o color=true, see --help options) ---raw-file NAME PATH Set variable $NAME to string content of file ---raw-input,-R Read raw input strings (don't decode) ---raw-output,-r Raw string output (without quotes) ---repl,-i Interactive REPL ---slurp,-s Slurp all inputs into an array or string (-Rs) ---unicode-output,-U Force unicode output ---version,-v Show version +--arg NAME VALUE Set variable $NAME to string VALUE +--argdecode NAME PATH Set variable $NAME to decode of PATH +--argjson NAME JSON Set variable $NAME to JSON +--color-output,-C Force color output +--compact-output,-c Compact output +--decode,-d NAME Decode format (probe) +--from-file,-f PATH Read EXPR from file +--help,-h [TOPIC] Show help for TOPIC (ex: -h formats, -h mp4) +--include-path,-L PATH Include search path +--join-output,-j No newline between outputs +--monochrome-output,-M Force monochrome output +--null-input,-n Null input (use input and inputs functions to read) +--null-output,-0 Null byte between outputs +--option,-o KEY=VALUE/@PATH Set option (ex: -o color=true, see --help options) +--raw-file NAME PATH Set variable $NAME to string content of file +--raw-input,-R Read raw input strings (don't decode) +--raw-output,-r Raw string output (without quotes) +--repl,-i Interactive REPL +--slurp,-s Slurp all inputs into an array or string (-Rs) +--unicode-output,-U Force unicode output +--version,-v Show version $ fq -i null> ^D $ fq -i . test.mp3 diff --git a/pkg/interp/testdata/options.fqtest b/pkg/interp/testdata/options.fqtest index b9ae4eed..415e1688 100644 --- a/pkg/interp/testdata/options.fqtest +++ b/pkg/interp/testdata/options.fqtest @@ -1,3 +1,5 @@ +/filea: +aaa $ fq -n options { "addrbase": 16, @@ -217,3 +219,9 @@ null> _STDOUT_WIDTH=160 _STDOUT_HEIGHT=40 options | {display_bytes, line_bytes} "line_bytes": 20 } null> ^D +$ fq -n -o from_file=@filea options.from_file +"aaa\n" +$ fq -n -o from_file=@does_not_exist options.from_file +exitcode: 2 +stderr: +error: -o from_file=@does_not_exist: no such file or directory