From 984e5b4e7fc4e433008b32883ec6447e5c49bc29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C5=99emysl=20Eric=20Janouch?= Date: Sat, 5 Sep 2020 06:00:52 +0200 Subject: [PATCH] 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. --- json-rpc-shell.adoc | 41 ++++++++++++++++++++++------------------- json-rpc-shell.c | 30 +++++++++++++++++------------- 2 files changed, 39 insertions(+), 32 deletions(-) diff --git a/json-rpc-shell.adoc b/json-rpc-shell.adoc index c7dab10..952ff8c 100644 --- a/json-rpc-shell.adoc +++ b/json-rpc-shell.adoc @@ -27,11 +27,13 @@ processor. Usage ~~~~~ 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, -separated from the rest by white space. Following that, you may enter two kinds -of JSON values. If it is a string, a number, or a null value, it is taken as -the "id" to use for the request. If it is an object or an array, it constitutes -the method parameters. Booleans may appear in neither. +one is always the name of the JSON-RPC method to call, as a bare word, separated +from the rest by white space. Following that, you may enter three kinds of JSON +values. If it is an object or an array, it constitutes the method parameters. +If it is a string or a number, it is taken as the "id" to use for the request, +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 way you would do it in a Unix shell. @@ -43,9 +45,9 @@ Options ------- Controlling Output ~~~~~~~~~~~~~~~~~~ -*-p*, *--pretty*:: - Pretty-print responses, adding spaces and newlines where appropriate - to improve readability. +*-c*, *--compact-output*:: + Do not pretty-print responses. Normally, spaces and newlines are added + where appropriate to improve readability. *--color* _WHEN_:: By default, when the output of the program is a terminal, JSON responses @@ -61,11 +63,10 @@ Controlling Output Protocol ~~~~~~~~ -*-a*, *--auto-id*:: - Choose message IDs automatically, in an increasing sequence. Normally you - need to enter the ID on the command line manually, so as to distinguish - notifications from other requests. Even with this option enabled, you can - still specify the ID, if you wish. +*-n*, *--null-as-id*:: + Normally, entering a null JSON value on the command line causes + a notification to be sent. With this option, it is sent as the "id" + field of a normal request, which is discouraged by the specification. *-t*, *--trust-all*:: 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 distribution of this program (public services are hard to find): -Pretty-printing and Manual IDs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $ json-rpc-shell -p ws://localhost:1234 - json-rpc> date 1 +Methods Without Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~ + $ json-rpc-shell ws://localhost:1234 + json-rpc> ping + "pong" + json-rpc> date { "year": 2020, "month": 9, @@ -150,7 +153,7 @@ Notifications never produce a response, not even when the method is not known to the server: $ json-rpc-shell ws://localhost:1234 - json-rpc> notify {"events": ["conquest", "war", "famine", "death"]} + json-rpc> notify {"events": ["conquest", "war", "famine", "death"]} null [Notification] 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 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 "PONG" diff --git a/json-rpc-shell.c b/json-rpc-shell.c index 10105cd..94baaf9 100644 --- a/json-rpc-shell.c +++ b/json-rpc-shell.c @@ -932,11 +932,11 @@ static struct app_context struct config config; ///< Program configuration 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 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 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) { int flags = JSON_ENCODE_ANY; - if (ctx->pretty_print) + if (!ctx->compact) flags |= JSON_INDENT (2); char *utf8 = json_dumps (result, flags); @@ -3041,9 +3041,16 @@ process_input (char *user_input, void *user_data) *target = json_incref (args[i]); } - if (!id && ctx->auto_id) + if (!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); 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" }, { 'h', "help", NULL, 0, "display this help message and exit" }, { 'V', "version", NULL, 0, "output version information and exit" }, - // TODO: consider making this the default and instead adding - // an option to accept JSON null as an id. - { 'a', "auto-id", NULL, 0, "automatic `id' fields" }, + { 'n', "null-as-id", NULL, 0, "JSON null is used as an `id'" }, { 'o', "origin", "O", 0, "set the HTTP Origin header" }, - // TODO: consider inverting this to -c/--compact-output - { 'p', "pretty", NULL, 0, "pretty-print the responses" }, + { 'c', "compact-output", NULL, 0, "do not pretty-print responses" }, { 't', "trust-all", NULL, 0, "don't care about SSL/TLS certificates" }, { '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" }, { 'w', "write-default-cfg", "FILENAME", OPT_OPTIONAL_ARG | OPT_LONG_ONLY, @@ -3375,12 +3379,12 @@ parse_program_arguments (struct app_context *ctx, int argc, char **argv, exit (EXIT_SUCCESS); case 'o': *origin = optarg; break; - case 'a': ctx->auto_id = true; break; - case 'p': ctx->pretty_print = true; break; + case 'n': ctx->null_as_id = true; break; + case 'c': ctx->compact = true; break; case 't': ctx->trust_all = true; break; case 'v': ctx->verbose = true; break; - case 'c': + case 'C': if (!strcasecmp (optarg, "never")) ctx->color_mode = COLOR_NEVER; else if (!strcasecmp (optarg, "always"))