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
~~~~~
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"

View File

@ -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"))