Use saner defaults

So that most of the time users won't need to use any switches.

--pretty-print has been inverted into jq's --compact-output,
and --auto-id has been replaced with barely, if-at-all useful
--null-as-id.
This commit is contained in:
Přemysl Eric Janouch 2020-09-05 06:00:52 +02:00
parent d57a8bd3c7
commit 984e5b4e7f
Signed by: p
GPG Key ID: A0420B94F92B9493
2 changed files with 39 additions and 32 deletions

View File

@ -27,11 +27,13 @@ processor.
Usage Usage
~~~~~ ~~~~~
Three things may appear on the internal command line, in a sequence. The first Three things may appear on the internal command line, in a sequence. The first
one must always be the name of the JSON-RPC method to call, as a bare word, one is always the name of the JSON-RPC method to call, as a bare word, separated
separated from the rest by white space. Following that, you may enter two kinds from the rest by white space. Following that, you may enter three kinds of JSON
of JSON values. If it is a string, a number, or a null value, it is taken as values. If it is an object or an array, it constitutes the method parameters.
the "id" to use for the request. If it is an object or an array, it constitutes If it is a string or a number, it is taken as the "id" to use for the request,
the method parameters. Booleans may appear in neither. which would be chosen for you automatically if left unspecified. Finally,
a null value indicates that the request should be sent as a notification,
lacking the ID completely. Booleans cannot be used for anything.
The response to the method call may be piped through external commands, the same The response to the method call may be piped through external commands, the same
way you would do it in a Unix shell. way you would do it in a Unix shell.
@ -43,9 +45,9 @@ Options
------- -------
Controlling Output Controlling Output
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
*-p*, *--pretty*:: *-c*, *--compact-output*::
Pretty-print responses, adding spaces and newlines where appropriate Do not pretty-print responses. Normally, spaces and newlines are added
to improve readability. where appropriate to improve readability.
*--color* _WHEN_:: *--color* _WHEN_::
By default, when the output of the program is a terminal, JSON responses By default, when the output of the program is a terminal, JSON responses
@ -61,11 +63,10 @@ Controlling Output
Protocol Protocol
~~~~~~~~ ~~~~~~~~
*-a*, *--auto-id*:: *-n*, *--null-as-id*::
Choose message IDs automatically, in an increasing sequence. Normally you Normally, entering a null JSON value on the command line causes
need to enter the ID on the command line manually, so as to distinguish a notification to be sent. With this option, it is sent as the "id"
notifications from other requests. Even with this option enabled, you can field of a normal request, which is discouraged by the specification.
still specify the ID, if you wish.
*-t*, *--trust-all*:: *-t*, *--trust-all*::
Trust all SSL/TLS certificates. Useful in case that the certificate is Trust all SSL/TLS certificates. Useful in case that the certificate is
@ -131,10 +132,12 @@ Examples
Running some queries against json-rpc-test-server, included in the source Running some queries against json-rpc-test-server, included in the source
distribution of this program (public services are hard to find): distribution of this program (public services are hard to find):
Pretty-printing and Manual IDs Methods Without Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
$ json-rpc-shell -p ws://localhost:1234 $ json-rpc-shell ws://localhost:1234
json-rpc> date 1 json-rpc> ping
"pong"
json-rpc> date
{ {
"year": 2020, "year": 2020,
"month": 9, "month": 9,
@ -150,7 +153,7 @@ Notifications never produce a response, not even when the method is not known
to the server: to the server:
$ json-rpc-shell ws://localhost:1234 $ json-rpc-shell ws://localhost:1234
json-rpc> notify {"events": ["conquest", "war", "famine", "death"]} json-rpc> notify {"events": ["conquest", "war", "famine", "death"]} null
[Notification] [Notification]
Piping In and Out Piping In and Out
@ -158,7 +161,7 @@ Piping In and Out
GNU Readline always repeats the prompt, which makes this a bit less useful GNU Readline always repeats the prompt, which makes this a bit less useful
for invoking from other programs: for invoking from other programs:
$ echo 'ping | jq ascii_upcase' | json-rpc-shell -a ws://localhost:1234 $ echo 'ping | jq ascii_upcase' | json-rpc-shell ws://localhost:1234
json-rpc> ping | jq ascii_upcase json-rpc> ping | jq ascii_upcase
"PONG" "PONG"

View File

@ -932,11 +932,11 @@ static struct app_context
struct config config; ///< Program configuration struct config config; ///< Program configuration
enum color_mode color_mode; ///< Colour output mode enum color_mode color_mode; ///< Colour output mode
bool pretty_print; ///< Whether to pretty print bool compact; ///< Whether to not pretty print
bool verbose; ///< Print requests bool verbose; ///< Print requests
bool trust_all; ///< Don't verify peer certificates bool trust_all; ///< Don't verify peer certificates
bool auto_id; ///< Use automatically generated ID's bool null_as_id; ///< JSON null is used as an ID
int64_t next_id; ///< Next autogenerated ID int64_t next_id; ///< Next autogenerated ID
iconv_t term_to_utf8; ///< Terminal encoding to UTF-8 iconv_t term_to_utf8; ///< Terminal encoding to UTF-8
@ -2845,7 +2845,7 @@ process_response (struct app_context *ctx, const json_t *id, struct str *buf,
if (result) if (result)
{ {
int flags = JSON_ENCODE_ANY; int flags = JSON_ENCODE_ANY;
if (ctx->pretty_print) if (!ctx->compact)
flags |= JSON_INDENT (2); flags |= JSON_INDENT (2);
char *utf8 = json_dumps (result, flags); char *utf8 = json_dumps (result, flags);
@ -3041,9 +3041,16 @@ process_input (char *user_input, void *user_data)
*target = json_incref (args[i]); *target = json_incref (args[i]);
} }
if (!id && ctx->auto_id) if (!id)
id = json_integer (ctx->next_id++); id = json_integer (ctx->next_id++);
// Use nulls to send notifications, unless a special switch is used
if (!ctx->null_as_id && json_is_null (id))
{
json_decref (id);
id = NULL;
}
make_json_rpc_call (ctx, method, id, params, pipeline); make_json_rpc_call (ctx, method, id, params, pipeline);
fail_parse: fail_parse:
@ -3341,15 +3348,12 @@ parse_program_arguments (struct app_context *ctx, int argc, char **argv,
{ 'd', "debug", NULL, 0, "run in debug mode" }, { 'd', "debug", NULL, 0, "run in debug mode" },
{ 'h', "help", NULL, 0, "display this help message and exit" }, { 'h', "help", NULL, 0, "display this help message and exit" },
{ 'V', "version", NULL, 0, "output version information and exit" }, { 'V', "version", NULL, 0, "output version information and exit" },
// TODO: consider making this the default and instead adding { 'n', "null-as-id", NULL, 0, "JSON null is used as an `id'" },
// an option to accept JSON null as an id.
{ 'a', "auto-id", NULL, 0, "automatic `id' fields" },
{ 'o', "origin", "O", 0, "set the HTTP Origin header" }, { 'o', "origin", "O", 0, "set the HTTP Origin header" },
// TODO: consider inverting this to -c/--compact-output { 'c', "compact-output", NULL, 0, "do not pretty-print responses" },
{ 'p', "pretty", NULL, 0, "pretty-print the responses" },
{ 't', "trust-all", NULL, 0, "don't care about SSL/TLS certificates" }, { 't', "trust-all", NULL, 0, "don't care about SSL/TLS certificates" },
{ 'v', "verbose", NULL, 0, "print raw requests and responses" }, { 'v', "verbose", NULL, 0, "print raw requests and responses" },
{ 'c', "color", "WHEN", OPT_LONG_ONLY, { 'C', "color", "WHEN", OPT_LONG_ONLY,
"colorize output: never, always, or auto" }, "colorize output: never, always, or auto" },
{ 'w', "write-default-cfg", "FILENAME", { 'w', "write-default-cfg", "FILENAME",
OPT_OPTIONAL_ARG | OPT_LONG_ONLY, OPT_OPTIONAL_ARG | OPT_LONG_ONLY,
@ -3375,12 +3379,12 @@ parse_program_arguments (struct app_context *ctx, int argc, char **argv,
exit (EXIT_SUCCESS); exit (EXIT_SUCCESS);
case 'o': *origin = optarg; break; case 'o': *origin = optarg; break;
case 'a': ctx->auto_id = true; break; case 'n': ctx->null_as_id = true; break;
case 'p': ctx->pretty_print = true; break; case 'c': ctx->compact = true; break;
case 't': ctx->trust_all = true; break; case 't': ctx->trust_all = true; break;
case 'v': ctx->verbose = true; break; case 'v': ctx->verbose = true; break;
case 'c': case 'C':
if (!strcasecmp (optarg, "never")) if (!strcasecmp (optarg, "never"))
ctx->color_mode = COLOR_NEVER; ctx->color_mode = COLOR_NEVER;
else if (!strcasecmp (optarg, "always")) else if (!strcasecmp (optarg, "always"))