Make a release, create NEWS

Streamline the manual page a bit
I have consulted `man 7 man-pages` but overall it's a huge mess.
2020-09-05 20:42:02 +02:00 · 2020-09-05 06:34:00 +02:00 · 2020-09-05 06:07:45 +02:00 · 2020-09-05 04:36:43 +02:00
4 changed files with 70 additions and 65 deletions
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -13,8 +13,8 @@ if ("${CMAKE_C_COMPILER_ID}" MATCHES "GNU" OR CMAKE_COMPILER_IS_GNUCC)
 endif ("${CMAKE_C_COMPILER_ID}" MATCHES "GNU" OR CMAKE_COMPILER_IS_GNUCC)

 # Version
-set (project_VERSION_MAJOR "0")
-set (project_VERSION_MINOR "1")
+set (project_VERSION_MAJOR "1")
+set (project_VERSION_MINOR "0")
 set (project_VERSION_PATCH "0")

 set (project_VERSION "${project_VERSION_MAJOR}")
--- a/4
+++ b/4
@@ -0,0 +1,4 @@
+1.0.0 (2020-09-05)
+
+ * Initial release
+
--- a/json-rpc-shell.adoc
+++ b/json-rpc-shell.adoc
@@ -1,8 +1,8 @@
 json-rpc-shell(1)
 =================
 :doctype: manpage
-:man manual: json-rpc-shell Manual
-:man source: json-rpc-shell {release-version}
+:manmanual: json-rpc-shell Manual
+:mansource: json-rpc-shell {release-version}

 Name
 ----
@@ -15,7 +15,7 @@ Synopsis
 Description
 -----------
 The _ENDPOINT_ must be either an HTTP or a WebSocket URL, with or without TLS
-(i.e. one of the _http://_, _https://_, _ws://_, _wss://_ schemas).
+(i.e. one of the _+++http+++://_, _+++https+++://_, _ws://_, _wss://_ schemas).

 *json-rpc-shell* will use it to send any JSON-RPC 2.0 requests you enter on its
 command line. The server's response will be parsed and validated, stripping it
@@ -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.
@@ -41,13 +43,13 @@ this action as they might conflict with method names.

 Options
 -------
-Controlling Output
+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_::
+*--color*=_WHEN_::
 	By default, when the output of the program is a terminal, JSON responses
 	are syntax-highlighted.  This corresponds to the _auto_ setting.  You may
 	also set this to _always_ or _never_.  In either case, color is never
@@ -61,21 +63,20 @@ 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
 	self-signed, or when the CA isn't in your CA store.  Beware that this option
 	is about as good as using plain unencrypted HTTP.

-*-o*, *--origin* _ORIGIN_::
+*-o* _ORIGIN_, *--origin*=_ORIGIN_::
 	Set the HTTP Origin header to _ORIGIN_.  Some servers may need this.

-Program Information
+Program information
 ~~~~~~~~~~~~~~~~~~~
 *-h*, *--help*::
 	Display a help message and exit.
@@ -83,7 +84,7 @@ Program Information
 *-V*, *--version*::
 	Output version information and exit.

-*--write-default-cfg*::
+*--write-default-cfg*[**=**__PATH__]::
 	Write a default configuration file, show its path and exit.

 Files
@@ -114,7 +115,7 @@ WebSockets
 The JSON-RPC 2.0 specification doesn't say almost anything about underlying
 transports. As far as the author is aware, he is the only person combining it
 with WebSockets.  The way it's implemented here is that every request is sent as
-a single text message.  If it has an "id" field, i.e. it's not just
+a single text message.  If it has an "id" field, i.e., it's not just
 a notification, the client waits for a message from the server in response.
 Should any message arrive unexpectedly, you will receive a warning.

@@ -131,49 +132,45 @@ 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
-{
-  "year": 2020,
-  "month": 9,
-  "day": 5,
-  "hours": 2,
-  "minutes": 23,
-  "seconds": 51
-}
-```
+Methods without parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+ $ json-rpc-shell ws://localhost:1234
+ json-rpc> ping
+ "pong"
+ json-rpc> date
+ {
+   "year": 2020,
+   "month": 9,
+   "day": 5,
+   "hours": 2,
+   "minutes": 23,
+   "seconds": 51
+ }

-Notification With a Parameter
+Notification with a parameter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 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"]}
-[Notification]
-```
+ $ json-rpc-shell ws://localhost:1234
+ json-rpc> notify {"events": ["conquest", "war", "famine", "death"]} null
+ [Notification]

-Piping In and Out
+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
-json-rpc> ping | jq ascii_upcase
-"PONG"
-```
+ $ echo 'ping | jq ascii_upcase' | json-rpc-shell ws://localhost:1234
+ json-rpc> ping | jq ascii_upcase
+ "PONG"

-Reporting Bugs
+Reporting bugs
 --------------
 Use https://git.janouch.name/p/json-rpc-shell to report bugs, request features,
 or submit pull requests.

-See Also
+See also
 --------
 *jq*(1), *readline*(3) or *editline*(7)

--- 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"))
Author	SHA1	Message	Date
Přemysl Eric Janouch	710f5f197f	Make a release, create NEWS	2020-09-05 20:42:02 +02:00
Přemysl Eric Janouch	ba68585d14	Streamline the manual page a bit I have consulted `man 7 man-pages` but overall it's a huge mess.	2020-09-05 06:34:00 +02:00
Přemysl Eric Janouch	984e5b4e7f	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.	2020-09-05 06:07:45 +02:00
Přemysl Eric Janouch	d57a8bd3c7	Improve AsciiDoc compatibility I need two renderers to work: hswg/libasciidoc and asciidoctor in man page mode (and ideally in HTML as well). That should be covered now. The triple-plus thing was the first thing that showed good results, after trying backslashes, single-plus quoting and [] after ://. The change of the source code block kind could be considered as unification. I'm combining tabs with spaces within one document though, and I should get rid of the tabs in the rest of it then...	2020-09-05 04:36:43 +02:00