wader/fq
1
1
Fork 0
mirror of https://github.com/wader/fq.git synced 2024-08-16 23:40:43 +03:00
Code Issues Projects Releases Wiki Activity

doc: Add man page

Browse Source 
To test:
go run . -nrf doc/fq.1.jq > fq.1 && man ./fq.1
This commit is contained in:
Mattias Wadman 2023-05-10 16:52:07 +02:00
parent 7e2a10c0ef
commit 12128e716e
4 changed files with 147 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
doc/fq.1.jq Normal file
View File

@ -0,0 +1,68 @@
( ".TH fq 1"
, ".SH NAME"
, _help("fq"; "fq_banner")
, ".SH SYNOPSIS"
, _help("fq"; "fq_usage")
, ""
, _help(""; "fq_example_usage")
, ".SH DESCRIPTION"
, _help(""; "fq_summary")
, ""
, "fq is inspired by the well known jq tool and language and allows you to work with binary formats the same way you would using jq. In addition it can present data like a hex viewer, transform, slice and concatenate binary data. It also supports nested formats and has an interactive REPL with auto-completion."
, ".SH OPTIONS"
, ( _opt_cli_args
| to_entries[] as $a
| $a.value
| ".TP"
, ( "\(.long)\(.short | if . then ",\(.)" else "" end)"
+ ( .string // .array // .object // .pairs
| if . then " \(.)"
else ""
end
)
)
, .description
, ( select($a.key == "option")
| ( _opt_options
| to_entries[] as $o
| select($o.value.help != null)
| ".TP"
, " -o \($o.key)=<\($o.value.type)>"
, " \($o.value.help)"
)
)
)
, ".SH ENVIRONMENT"
, ( _opt_environment
| to_entries[] as $e
| ".TP"
, $e.key
, $e.value
)
, ".SH SUPPORTED FORMATS"
, "By default fq will try to probe input format. If this does not work"
, "a format can by specified by using -d <NAME>."
, "To see more details like options and example about a format use -h <NAME>."
, ""
, ".EX"
, "$ fq -d msgpack d file # decode as msgpack"
, "$ fq -h msgpack # see msgpack help"
, "$ fq -h formats # list formats"
, ".EE"
, ""
, ".EX"
, _help(""; "formats")
, ".EE"
, ".SH SEE ALSO"
, "jq(1)"
, "dd(1)"
, ".SH AUTHOR"
, "Mattias Wadman (mattias.wadman@gmail.com)"
)

14
pkg/interp/help.jq
View File

@ -76,11 +76,12 @@ def _help_format_enrich($arg0; $f; $include_basic):
end end
); );
def _help($arg0; $topic): def _help($arg0; $topic):
( $topic ( $topic
| if . == "usage" then | if . == "fq_usage" then
"Usage: \($arg0) [OPTIONS] [--] [EXPR] [FILE...]" "Usage: \($arg0) [OPTIONS] [--] [EXPR] [FILE...]"
elif . == "example_usage" then elif . == "fq_example_usage" then
( "Example usages:" ( "Example usages:"
, " fq . file" , " fq . file"
, " fq d file" , " fq d file"
@ -92,13 +93,14 @@ def _help($arg0; $topic):
, " fq 'grep(\"^main$\") | parent' /bin/ls" , " fq 'grep(\"^main$\") | parent' /bin/ls"
, " fq -i" , " fq -i"
) )
elif . == "banner" then elif . == "fq_banner" then
( "fq - jq for binary formats" "fq - jq for binary formats"
, "Tool, language and decoders for working with binary data." elif . == "fq_summary" then
( "Tool, language and decoders for working with binary data."
, "For more information see https://github.com/wader/fq" , "For more information see https://github.com/wader/fq"
) )
elif . == "args" then elif . == "args" then
args_help_text(_opt_cli_opts) args_help_text(_opt_cli_args)
elif . == "options" then elif . == "options" then
( [ ( options ( [ ( options
| _opt_cli_arg_from_options | _opt_cli_arg_from_options

9
pkg/interp/init.jq
View File

@ -172,7 +172,7 @@ def _main:
( . as {$version, $os, $arch, $args, args: [$arg0]} ( . as {$version, $os, $arch, $args, args: [$arg0]}
# make sure we don't unintentionally use . to make things clearer # make sure we don't unintentionally use . to make things clearer
| null | null
| ( try _args_parse($args[1:]; _opt_cli_opts) | ( try _args_parse($args[1:]; _opt_cli_args)
catch halt_error(_exit_code_args_error) catch halt_error(_exit_code_args_error)
) as {parsed: $parsed_args, $rest} ) as {parsed: $parsed_args, $rest}
# combine default fixed opt, parsed args and -o key=value opts # combine default fixed opt, parsed args and -o key=value opts
@ -189,11 +189,12 @@ def _main:
( # if show_help is a string -h <topic> was used ( # if show_help is a string -h <topic> was used
if ($opts.show_help | type) == "boolean" then if ($opts.show_help | type) == "boolean" then
( # "" to print separators ( # "" to print separators
( "banner" ( "fq_banner"
, "fq_summary"
, "" , ""
, "usage" , "fq_usage"
, "" , ""
, "example_usage" , "fq_example_usage"
, "" , ""
, "args" , "args"
) )

128
pkg/interp/options.jq
View File

@ -4,8 +4,7 @@ include "binary";
def _opt_build_default_fixed: def _opt_build_default_fixed:
( stdout_tty as $stdout ( stdout_tty as $stdout
| { | { addrbase: 16,
addrbase: 16,
arg: [], arg: [],
argdecode: [], argdecode: [],
argjson: [], argjson: [],
@ -24,23 +23,23 @@ def _opt_build_default_fixed:
} }
], ],
color: ($stdout.is_terminal and (env.NO_COLOR | . == null or . == "")), color: ($stdout.is_terminal and (env.NO_COLOR | . == null or . == "")),
colors: { colors:
null: "brightblack", { null: "brightblack",
false: "yellow", false: "yellow",
true: "yellow", true: "yellow",
number: "cyan", number: "cyan",
string: "green", string: "green",
objectkey: "brightblue", objectkey: "brightblue",
array: "white", array: "white",
object: "white", object: "white",
index: "white", index: "white",
value: "white", value: "white",
error: "brightred", error: "brightred",
dumpheader: "yellow+underline", dumpheader: "yellow+underline",
dumpaddr: "yellow", dumpaddr: "yellow",
prompt_repl_level: "brightblack", prompt_repl_level: "brightblack",
prompt_value: "white" prompt_value: "white"
}, },
compact: false, compact: false,
completion_timeout: (env.COMPLETION_TIMEOUT | if . != null then tonumber else 1 end), completion_timeout: (env.COMPLETION_TIMEOUT | if . != null then tonumber else 1 end),
decode_group: "probe", decode_group: "probe",
@ -72,46 +71,51 @@ def _opt_build_default_fixed:
); );
def _opt_options: def _opt_options:
{ # null help means the option has an --arg or is internal in some way
addrbase: "number", { addrbase: {type: "number", help: "Number base for addresses"},
arg: "array_string_pair", arg: {type: "array_string_pair", help: null},
argdecode: "array_string_pair", argdecode: {type: "array_string_pair", help: null},
argjson: "array_string_pair", argjson: {type: "array_string_pair", help: null},
array_truncate: "number", array_truncate: {type: "number", help: "Number of elements to truncate arrays by default"},
bits_format: "string", bits_format: {type: "string", help: "How binaries should be represented as JSON"},
byte_colors: "csv_ranges_array", byte_colors: {type: "csv_ranges_array", help: "How byte values should be colorized"},
color: "boolean", color: {type: "boolean", help: "Use color output"},
colors: "csv_kv_obj", colors: {type: "csv_kv_obj", help: "How types and interface should be colorized"},
compact: "boolean", compact: {type: "boolean", help: "Use compact JSON output (no new lines)"},
completion_timeout: "number", completion_timeout: {type: "number", help: null},
decode_group: "string", decode_group: {type: "string", help: null},
decode_progress: "boolean", decode_progress: {type: "boolean", help: null},
depth: "number", depth: {type: "number", help: "Max display tree depth"},
display_bytes: "number", display_bytes: {type: "number", help: "Number of bytes to display per field"},
expr: "string", expr: {type: "string", help: null},
expr_given: "boolean", expr_given: {type: "boolean", help: null},
expr_eval_path: "string", expr_eval_path: {type: "string", help: null},
expr_file: "string", expr_file: {type: "string", help: null},
filenames: "array_string", filenames: {type: "array_string", help: null},
force: "boolean", force: {type: "boolean", help: "Force decode"},
include_path: "string", include_path: {type: "string", help: null},
join_string: "string", join_string: {type: "string", help: null},
line_bytes: "number", line_bytes: {type: "number", help: "Number of bytes to display per line"},
null_input: "boolean", null_input: {type: "boolean", help: null},
raw_file: "array_string_pair", raw_file: {type: "array_string_pair", help: null},
raw_output: "boolean", raw_output: {type: "boolean", help: null},
raw_string: "boolean", raw_string: {type: "boolean", help: null},
repl: "boolean", repl: {type: "boolean", help: null},
show_formats: "boolean", show_formats: {type: "boolean", help: null},
show_help: "boolean", show_help: {type: "boolean", help: null},
sizebase: "number", sizebase: {type: "number", help: "Number base for sizes"},
skip_gaps: "boolean", skip_gaps: {type: "boolean", help: "Skip gaps when represented as JSON"},
slurp: "boolean", slurp: {type: "boolean", help: null},
string_input: "boolean", string_input: {type: "boolean", help: null},
unicode: "boolean", unicode: {type: "boolean", help: null},
value_output: "boolean", value_output: {type: "boolean", help: null},
verbose: "boolean", verbose: {type: "boolean", help: null},
width: "number", width: {type: "number", help: null},
};
def _opt_environment:
{ "NO_COLOR": "Don't use color output"
, "CLIUNICODE": "Use unicode output"
}; };
def _opt_eval($rest): def _opt_eval($rest):
@ -364,7 +368,7 @@ def _opt_cli_arg_to_options:
( _opt_options as $opts ( _opt_options as $opts
| with_entries( | with_entries(
( .key as $k ( .key as $k
| .value |= _opt_to($opts[$k] // "fuzzy") | .value |= _opt_to($opts[$k].type // "fuzzy")
| select(.value != null) | select(.value != null)
) )
) )
@ -374,13 +378,13 @@ def _opt_cli_arg_from_options:
( _opt_options as $opts ( _opt_options as $opts
| with_entries( | with_entries(
( .key as $k ( .key as $k
| .value |= _opt_from($opts[$k] // "string") | .value |= _opt_from($opts[$k].type // "string")
| select(.value != null) | select(.value != null)
) )
) )
); );
def _opt_cli_opts: def _opt_cli_args:
{ {
"arg": { "arg": {
long: "--arg", long: "--arg",