Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: Add man page #698

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

doc: Add man page #698

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions doc/fq.1.jq
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 ([email protected])"
)
14 changes: 8 additions & 6 deletions pkg/interp/help.jq
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down
9 changes: 5 additions & 4 deletions pkg/interp/init.jq
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"
)
Expand Down
128 changes: 66 additions & 62 deletions pkg/interp/options.jq
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@ include "binary";

def _opt_build_default_fixed:
( stdout_tty as $stdout
| {
addrbase: 16,
| { addrbase: 16,
arg: [],
argdecode: [],
argjson: [],
Expand All @@ -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",
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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)
)
)
Expand All @@ -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",
Expand Down