mirror of
https://github.com/wader/fq.git
synced 2024-07-14 15:20:31 +03:00
doc: Add man page
To test: go run . -nrf doc/fq.1.jq > fq.1 && man ./fq.1
This commit is contained in:
Mattias Wadman
parent
7e2a10c0ef
commit
12128e716e
68
doc/fq.1.jq
Normal file
68
doc/fq.1.jq
Normal 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)"
|
||||
)
|
||||
@ -76,11 +76,12 @@ def _help_format_enrich($arg0; $f; $include_basic):
|
||||
end
|
||||
);
|
||||
|
||||
|
||||
def _help($arg0; $topic):
|
||||
( $topic
|
||||
| if . == "usage" then
|
||||
| if . == "fq_usage" then
|
||||
"Usage: \($arg0) [OPTIONS] [--] [EXPR] [FILE...]"
|
||||
elif . == "example_usage" then
|
||||
elif . == "fq_example_usage" then
|
||||
( "Example usages:"
|
||||
, " fq . file"
|
||||
, " fq d file"
|
||||
@ -92,13 +93,14 @@ def _help($arg0; $topic):
|
||||
, " fq 'grep(\"^main$\") | parent' /bin/ls"
|
||||
, " fq -i"
|
||||
)
|
||||
elif . == "banner" then
|
||||
( "fq - jq for binary formats"
|
||||
, "Tool, language and decoders for working with binary data."
|
||||
elif . == "fq_banner" then
|
||||
"fq - jq for binary formats"
|
||||
elif . == "fq_summary" then
|
||||
( "Tool, language and decoders for working with binary data."
|
||||
, "For more information see https://github.com/wader/fq"
|
||||
)
|
||||
elif . == "args" then
|
||||
args_help_text(_opt_cli_opts)
|
||||
args_help_text(_opt_cli_args)
|
||||
elif . == "options" then
|
||||
( [ ( options
|
||||
| _opt_cli_arg_from_options
|
||||
|
||||
@ -172,7 +172,7 @@ def _main:
|
||||
( . as {$version, $os, $arch, $args, args: [$arg0]}
|
||||
# make sure we don't unintentionally use . to make things clearer
|
||||
| null
|
||||
| ( try _args_parse($args[1:]; _opt_cli_opts)
|
||||
| ( try _args_parse($args[1:]; _opt_cli_args)
|
||||
catch halt_error(_exit_code_args_error)
|
||||
) as {parsed: $parsed_args, $rest}
|
||||
# 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 ($opts.show_help | type) == "boolean" then
|
||||
( # "" to print separators
|
||||
( "banner"
|
||||
( "fq_banner"
|
||||
, "fq_summary"
|
||||
, ""
|
||||
, "usage"
|
||||
, "fq_usage"
|
||||
, ""
|
||||
, "example_usage"
|
||||
, "fq_example_usage"
|
||||
, ""
|
||||
, "args"
|
||||
)
|
||||
|
||||
@ -4,8 +4,7 @@ include "binary";
|
||||
|
||||
def _opt_build_default_fixed:
|
||||
( stdout_tty as $stdout
|
||||
| {
|
||||
addrbase: 16,
|
||||
| { addrbase: 16,
|
||||
arg: [],
|
||||
argdecode: [],
|
||||
argjson: [],
|
||||
@ -24,23 +23,23 @@ def _opt_build_default_fixed:
|
||||
}
|
||||
],
|
||||
color: ($stdout.is_terminal and (env.NO_COLOR | . == null or . == "")),
|
||||
colors: {
|
||||
null: "brightblack",
|
||||
false: "yellow",
|
||||
true: "yellow",
|
||||
number: "cyan",
|
||||
string: "green",
|
||||
objectkey: "brightblue",
|
||||
array: "white",
|
||||
object: "white",
|
||||
index: "white",
|
||||
value: "white",
|
||||
error: "brightred",
|
||||
dumpheader: "yellow+underline",
|
||||
dumpaddr: "yellow",
|
||||
prompt_repl_level: "brightblack",
|
||||
prompt_value: "white"
|
||||
},
|
||||
colors:
|
||||
{ null: "brightblack",
|
||||
false: "yellow",
|
||||
true: "yellow",
|
||||
number: "cyan",
|
||||
string: "green",
|
||||
objectkey: "brightblue",
|
||||
array: "white",
|
||||
object: "white",
|
||||
index: "white",
|
||||
value: "white",
|
||||
error: "brightred",
|
||||
dumpheader: "yellow+underline",
|
||||
dumpaddr: "yellow",
|
||||
prompt_repl_level: "brightblack",
|
||||
prompt_value: "white"
|
||||
},
|
||||
compact: false,
|
||||
completion_timeout: (env.COMPLETION_TIMEOUT | if . != null then tonumber else 1 end),
|
||||
decode_group: "probe",
|
||||
@ -72,46 +71,51 @@ def _opt_build_default_fixed:
|
||||
);
|
||||
|
||||
def _opt_options:
|
||||
{
|
||||
addrbase: "number",
|
||||
arg: "array_string_pair",
|
||||
argdecode: "array_string_pair",
|
||||
argjson: "array_string_pair",
|
||||
array_truncate: "number",
|
||||
bits_format: "string",
|
||||
byte_colors: "csv_ranges_array",
|
||||
color: "boolean",
|
||||
colors: "csv_kv_obj",
|
||||
compact: "boolean",
|
||||
completion_timeout: "number",
|
||||
decode_group: "string",
|
||||
decode_progress: "boolean",
|
||||
depth: "number",
|
||||
display_bytes: "number",
|
||||
expr: "string",
|
||||
expr_given: "boolean",
|
||||
expr_eval_path: "string",
|
||||
expr_file: "string",
|
||||
filenames: "array_string",
|
||||
force: "boolean",
|
||||
include_path: "string",
|
||||
join_string: "string",
|
||||
line_bytes: "number",
|
||||
null_input: "boolean",
|
||||
raw_file: "array_string_pair",
|
||||
raw_output: "boolean",
|
||||
raw_string: "boolean",
|
||||
repl: "boolean",
|
||||
show_formats: "boolean",
|
||||
show_help: "boolean",
|
||||
sizebase: "number",
|
||||
skip_gaps: "boolean",
|
||||
slurp: "boolean",
|
||||
string_input: "boolean",
|
||||
unicode: "boolean",
|
||||
value_output: "boolean",
|
||||
verbose: "boolean",
|
||||
width: "number",
|
||||
# null help means the option has an --arg or is internal in some way
|
||||
{ addrbase: {type: "number", help: "Number base for addresses"},
|
||||
arg: {type: "array_string_pair", help: null},
|
||||
argdecode: {type: "array_string_pair", help: null},
|
||||
argjson: {type: "array_string_pair", help: null},
|
||||
array_truncate: {type: "number", help: "Number of elements to truncate arrays by default"},
|
||||
bits_format: {type: "string", help: "How binaries should be represented as JSON"},
|
||||
byte_colors: {type: "csv_ranges_array", help: "How byte values should be colorized"},
|
||||
color: {type: "boolean", help: "Use color output"},
|
||||
colors: {type: "csv_kv_obj", help: "How types and interface should be colorized"},
|
||||
compact: {type: "boolean", help: "Use compact JSON output (no new lines)"},
|
||||
completion_timeout: {type: "number", help: null},
|
||||
decode_group: {type: "string", help: null},
|
||||
decode_progress: {type: "boolean", help: null},
|
||||
depth: {type: "number", help: "Max display tree depth"},
|
||||
display_bytes: {type: "number", help: "Number of bytes to display per field"},
|
||||
expr: {type: "string", help: null},
|
||||
expr_given: {type: "boolean", help: null},
|
||||
expr_eval_path: {type: "string", help: null},
|
||||
expr_file: {type: "string", help: null},
|
||||
filenames: {type: "array_string", help: null},
|
||||
force: {type: "boolean", help: "Force decode"},
|
||||
include_path: {type: "string", help: null},
|
||||
join_string: {type: "string", help: null},
|
||||
line_bytes: {type: "number", help: "Number of bytes to display per line"},
|
||||
null_input: {type: "boolean", help: null},
|
||||
raw_file: {type: "array_string_pair", help: null},
|
||||
raw_output: {type: "boolean", help: null},
|
||||
raw_string: {type: "boolean", help: null},
|
||||
repl: {type: "boolean", help: null},
|
||||
show_formats: {type: "boolean", help: null},
|
||||
show_help: {type: "boolean", help: null},
|
||||
sizebase: {type: "number", help: "Number base for sizes"},
|
||||
skip_gaps: {type: "boolean", help: "Skip gaps when represented as JSON"},
|
||||
slurp: {type: "boolean", help: null},
|
||||
string_input: {type: "boolean", help: null},
|
||||
unicode: {type: "boolean", help: null},
|
||||
value_output: {type: "boolean", help: null},
|
||||
verbose: {type: "boolean", help: null},
|
||||
width: {type: "number", help: null},
|
||||
};
|
||||
|
||||
def _opt_environment:
|
||||
{ "NO_COLOR": "Don't use color output"
|
||||
, "CLIUNICODE": "Use unicode output"
|
||||
};
|
||||
|
||||
def _opt_eval($rest):
|
||||
@ -364,7 +368,7 @@ def _opt_cli_arg_to_options:
|
||||
( _opt_options as $opts
|
||||
| with_entries(
|
||||
( .key as $k
|
||||
| .value |= _opt_to($opts[$k] // "fuzzy")
|
||||
| .value |= _opt_to($opts[$k].type // "fuzzy")
|
||||
| select(.value != null)
|
||||
)
|
||||
)
|
||||
@ -374,13 +378,13 @@ def _opt_cli_arg_from_options:
|
||||
( _opt_options as $opts
|
||||
| with_entries(
|
||||
( .key as $k
|
||||
| .value |= _opt_from($opts[$k] // "string")
|
||||
| .value |= _opt_from($opts[$k].type // "string")
|
||||
| select(.value != null)
|
||||
)
|
||||
)
|
||||
);
|
||||
|
||||
def _opt_cli_opts:
|
||||
def _opt_cli_args:
|
||||
{
|
||||
"arg": {
|
||||
long: "--arg",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user