Merge pull request #597 from wader/opt-file-value-error

interp: Exit with error if -o name=@path fails to be read, also document

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.

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

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

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