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

@@ -31,13 +31,13 @@ Example usages:
 --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)
+--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   Set option (ex: -o color=true, see --help options)
+--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)

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