Bump version, update NEWS

Sadly, the 3.5 deprecation warning doesn't go away after this.

.clang-format

@@ -0,0 +1,33 @@
+# clang-format is fairly limited, and these rules are approximate:
+#  - array initializers can get terribly mangled with clang-format 12.0,
+#  - sometimes it still aligns with space characters,
+#  - EV_DEFAULT_ and EV_A_ are always taken as identifiers,
+#  - struct name NL { NL ... NL } NL name; is unachievable.
+BasedOnStyle: GNU
+ColumnLimit: 80
+IndentWidth: 4
+TabWidth: 4
+UseTab: ForContinuationAndIndentation
+BreakBeforeBraces: Allman
+SpaceAfterCStyleCast: true
+AlignAfterOpenBracket: DontAlign
+AlignOperands: DontAlign
+AlignConsecutiveMacros: Consecutive
+AllowAllArgumentsOnNextLine: false
+AllowAllParametersOfDeclarationOnNextLine: false
+IndentGotoLabels: false
+
+# IncludeCategories has some potential, but it may also break the build.
+# Note that the documentation says the value should be "Never".
+SortIncludes: false
+
+# This is a compromise, it generally works out aesthetically better.
+BinPackArguments: false
+
+# Unfortunately, this can't be told to align to column 40 or so.
+SpacesBeforeTrailingComments: 2
+
+# liberty-specific macro body wrappers.
+MacroBlockBegin: "BLOCK_START"
+MacroBlockEnd: "BLOCK_END"
+ForEachMacros: ["LIST_FOR_EACH"]

.gitignore

@@ -7,3 +7,5 @@
 /json-rpc-shell.files
 /json-rpc-shell.creator*
 /json-rpc-shell.includes
+/json-rpc-shell.cflags
+/json-rpc-shell.cxxflags

CMakeLists.txt

@@ -1,5 +1,5 @@
-project (json-rpc-shell C)
-cmake_minimum_required (VERSION 2.8.5)
+cmake_minimum_required (VERSION 3.0...3.27)
+project (json-rpc-shell VERSION 1.2.0 LANGUAGES C)
 
 # Options
 option (WANT_READLINE "Use GNU Readline for the UI (better)" ON)
@@ -10,54 +10,73 @@ if ("${CMAKE_C_COMPILER_ID}" MATCHES "GNU" OR CMAKE_COMPILER_IS_GNUCC)
 	# -Wunused-function is pretty annoying here, as everything is static
 	set (CMAKE_C_FLAGS
 		"${CMAKE_C_FLAGS} -std=c99 -Wall -Wextra -Wno-unused-function")
-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_PATCH "0")
-
-set (project_VERSION "${project_VERSION_MAJOR}")
-set (project_VERSION "${project_VERSION}.${project_VERSION_MINOR}")
-set (project_VERSION "${project_VERSION}.${project_VERSION_PATCH}")
+endif ()
 
 # For custom modules
-set (CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+set (CMAKE_MODULE_PATH
+	"${PROJECT_SOURCE_DIR}/cmake;${PROJECT_SOURCE_DIR}/liberty/cmake")
 
 # Dependencies
 find_package (Curses)
+find_package (Ncursesw)
 find_package (PkgConfig REQUIRED)
-pkg_check_modules (dependencies REQUIRED libcurl jansson)
 # Note that cURL can link to a different version of libssl than we do,
 # in which case the results are undefined
-pkg_check_modules (libssl REQUIRED libssl libcrypto)
+pkg_check_modules (dependencies REQUIRED libcurl jansson libssl libcrypto)
 find_package (LibEV REQUIRED)
-pkg_check_modules (ncursesw ncursesw)
 
-set (project_libraries ${dependencies_LIBRARIES}
-	${libssl_LIBRARIES} ${LIBEV_LIBRARIES})
-include_directories (${dependencies_INCLUDE_DIRS}
-	${libssl_INCLUDE_DIRS} ${LIBEV_INCLUDE_DIRS})
+set (project_libraries ${dependencies_LIBRARIES} ${LibEV_LIBRARIES})
+include_directories (${dependencies_INCLUDE_DIRS} ${LibEV_INCLUDE_DIRS})
+link_directories (${dependencies_LIBRARY_DIRS})
 
-if (ncursesw_FOUND)
-	list (APPEND project_libraries ${ncursesw_LIBRARIES})
-	include_directories (${ncursesw_INCLUDE_DIRS})
+if ("${CMAKE_SYSTEM_NAME}" MATCHES "BSD")
+	# Need this for SIGWINCH in FreeBSD and OpenBSD respectively;
+	# our POSIX version macros make it undefined
+	add_definitions (-D__BSD_VISIBLE=1 -D_BSD_SOURCE=1)
+elseif (APPLE)
+	add_definitions (-D_DARWIN_C_SOURCE)
+endif ()
+
+# -liconv may or may not be a part of libc
+find_library (iconv_LIBRARIES iconv)
+if (iconv_LIBRARIES)
+	list (APPEND project_libraries ${iconv_LIBRARIES})
+endif ()
+
+include (CheckCSourceRuns)
+set (CMAKE_REQUIRED_LIBRARIES ${project_libraries})
+get_property (CMAKE_REQUIRED_INCLUDES
+	DIRECTORY "${PROJECT_SOURCE_DIR}" PROPERTY INCLUDE_DIRECTORIES)
+CHECK_C_SOURCE_RUNS ("#include <iconv.h>
+	int main () { return iconv_open (\"UTF-8//TRANSLIT\", \"ISO-8859-1\")
+		== (iconv_t) -1; }" ICONV_ACCEPTS_TRANSLIT)
+
+if (Ncursesw_FOUND)
+	list (APPEND project_libraries ${Ncursesw_LIBRARIES})
+	include_directories (${Ncursesw_INCLUDE_DIRS})
+	link_directories (${Ncursesw_LIBRARY_DIRS})
 elseif (CURSES_FOUND)
 	list (APPEND project_libraries ${CURSES_LIBRARY})
 	include_directories (${CURSES_INCLUDE_DIR})
-else (CURSES_FOUND)
+else ()
 	message (SEND_ERROR "Curses not found")
-endif (ncursesw_FOUND)
+endif ()
 
 if ((WANT_READLINE AND WANT_LIBEDIT) OR (NOT WANT_READLINE AND NOT WANT_LIBEDIT))
 	message (SEND_ERROR "You have to choose either GNU Readline or libedit")
 elseif (WANT_READLINE)
-	list (APPEND project_libraries readline)
+	# OpenBSD's default readline is too old
+	if ("${CMAKE_SYSTEM_NAME}" MATCHES "OpenBSD")
+		include_directories (${OPENBSD_LOCALBASE}/include/ereadline)
+		list (APPEND project_libraries ereadline)
+	else ()
+		list (APPEND project_libraries readline)
+	endif ()
 elseif (WANT_LIBEDIT)
 	pkg_check_modules (libedit REQUIRED libedit)
 	list (APPEND project_libraries ${libedit_LIBRARIES})
 	include_directories (${libedit_INCLUDE_DIRS})
-endif ((WANT_READLINE AND WANT_LIBEDIT) OR (NOT WANT_READLINE AND NOT WANT_LIBEDIT))
+endif ()
 
 # Generate a configuration file
 set (HAVE_READLINE "${WANT_READLINE}")
@@ -70,27 +89,59 @@ include_directories (${PROJECT_BINARY_DIR})
 add_executable (${PROJECT_NAME} ${PROJECT_NAME}.c http-parser/http_parser.c)
 target_link_libraries (${PROJECT_NAME} ${project_libraries})
 
+# Development tools
+find_package (LibMagic)
+if (LIBMAGIC_FOUND)
+	include_directories (${LIBMAGIC_INCLUDE_DIRS})
+	add_executable (json-rpc-test-server
+		json-rpc-test-server.c http-parser/http_parser.c)
+	target_link_libraries (json-rpc-test-server
+		${project_libraries} ${LIBMAGIC_LIBRARIES})
+endif ()
+
 # The files to be installed
 include (GNUInstallDirs)
 install (TARGETS ${PROJECT_NAME} DESTINATION ${CMAKE_INSTALL_BINDIR})
 install (PROGRAMS json-format.pl DESTINATION ${CMAKE_INSTALL_BINDIR})
 install (FILES LICENSE DESTINATION ${CMAKE_INSTALL_DOCDIR})
 
-# Generate documentation from program help
-find_program (HELP2MAN_EXECUTABLE help2man)
-if (NOT HELP2MAN_EXECUTABLE)
-	message (FATAL_ERROR "help2man not found")
-endif (NOT HELP2MAN_EXECUTABLE)
+# Generate documentation from text markup
+find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor)
+find_program (A2X_EXECUTABLE a2x)
+if (NOT ASCIIDOCTOR_EXECUTABLE AND NOT A2X_EXECUTABLE)
+	message (WARNING "Neither asciidoctor nor a2x were found, "
+		"falling back to a substandard manual page generator")
+endif ()
 
 foreach (page ${PROJECT_NAME})
 	set (page_output "${PROJECT_BINARY_DIR}/${page}.1")
 	list (APPEND project_MAN_PAGES "${page_output}")
-	add_custom_command (OUTPUT ${page_output}
-		COMMAND ${HELP2MAN_EXECUTABLE} -N
-			"${PROJECT_BINARY_DIR}/${page}" -o ${page_output}
-		DEPENDS ${page}
-		COMMENT "Generating man page for ${page}" VERBATIM)
-endforeach (page)
+	if (ASCIIDOCTOR_EXECUTABLE)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage
+				-a release-version=${PROJECT_VERSION}
+				-o "${page_output}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	elseif (A2X_EXECUTABLE)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND ${A2X_EXECUTABLE} --doctype manpage --format manpage
+				-a release-version=${PROJECT_VERSION}
+				-D "${PROJECT_BINARY_DIR}"
+				"${PROJECT_SOURCE_DIR}/${page}.adoc"
+			DEPENDS ${page}.adoc
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	else ()
+		set (ASCIIMAN ${PROJECT_SOURCE_DIR}/liberty/tools/asciiman.awk)
+		add_custom_command (OUTPUT ${page_output}
+			COMMAND env LC_ALL=C asciidoc-release-version=${PROJECT_VERSION}
+				awk -f ${ASCIIMAN} "${PROJECT_SOURCE_DIR}/${page}.adoc"
+				> ${page_output}
+			DEPENDS ${page}.adoc ${ASCIIMAN}
+			COMMENT "Generating man page for ${page}" VERBATIM)
+	endif ()
+endforeach ()
 
 add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES})
 
@@ -98,22 +149,19 @@ foreach (page ${project_MAN_PAGES})
 	string (REGEX MATCH "\\.([0-9])$" manpage_suffix "${page}")
 	install (FILES "${page}"
 		DESTINATION "${CMAKE_INSTALL_MANDIR}/man${CMAKE_MATCH_1}")
-endforeach (page)
+endforeach ()
 
 # CPack
-set (CPACK_PACKAGE_DESCRIPTION_SUMMARY "Shell for running JSON-RPC 2.0 queries")
-set (CPACK_PACKAGE_VENDOR "Premysl Janouch")
-set (CPACK_PACKAGE_CONTACT "Přemysl Janouch <p@janouch.name>")
+set (CPACK_PACKAGE_DESCRIPTION_SUMMARY "A shell for JSON-RPC 2.0")
+set (CPACK_PACKAGE_VENDOR "Premysl Eric Janouch")
+set (CPACK_PACKAGE_CONTACT "Přemysl Eric Janouch <p@janouch.name>")
 set (CPACK_RESOURCE_FILE_LICENSE "${PROJECT_SOURCE_DIR}/LICENSE")
-set (CPACK_PACKAGE_VERSION_MAJOR ${project_VERSION_MAJOR})
-set (CPACK_PACKAGE_VERSION_MINOR ${project_VERSION_MINOR})
-set (CPACK_PACKAGE_VERSION_PATCH ${project_VERSION_PATCH})
 set (CPACK_GENERATOR "TGZ;ZIP")
 set (CPACK_PACKAGE_FILE_NAME
-	"${PROJECT_NAME}-${project_VERSION}-${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_PROCESSOR}")
-set (CPACK_PACKAGE_INSTALL_DIRECTORY "${PROJECT_NAME}-${project_VERSION}")
+	"${PROJECT_NAME}-${PROJECT_VERSION}-${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_PROCESSOR}")
+set (CPACK_PACKAGE_INSTALL_DIRECTORY "${PROJECT_NAME}-${PROJECT_VERSION}")
 set (CPACK_SOURCE_GENERATOR "TGZ;ZIP")
 set (CPACK_SOURCE_IGNORE_FILES "/\\\\.git;/build;/CMakeLists.txt.user")
-set (CPACK_SOURCE_PACKAGE_FILE_NAME "${PROJECT_NAME}-${project_VERSION}")
+set (CPACK_SOURCE_PACKAGE_FILE_NAME "${PROJECT_NAME}-${PROJECT_VERSION}")
 
 include (CPack)

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014 - 2016, Přemysl Janouch <p@janouch.name>
+Copyright (c) 2014 - 2022, Přemysl Eric Janouch <p@janouch.name>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.

NEWS

@@ -0,0 +1,34 @@
+1.2.0 (2024-12-24)
+
+ * Add a backend for co-processes, such as language servers
+
+ * Support reading OpenRPC documents from a file
+
+ * Respect the NO_COLOR environment variable
+
+ * Miscellaneous libedit (editline) fixes
+
+ * Miscellaneous portability improvements
+
+ * json-rpc-test-server: implement OpenRPC discovery
+
+ * json-rpc-test-server: only serve regular files
+
+ * json-rpc-test-server: miscellaneous WebSocket fixes
+
+
+1.1.0 (2020-10-13)
+
+ * Add method name tab completion using OpenRPC information
+
+ * Bind M-Enter to insert a newline into the command line
+
+ * json-rpc-test-server: fix a memory leak and request URI parsing
+
+ * Miscellaneous bug fixes
+
+
+1.0.0 (2020-09-05)
+
+ * Initial release
+

README.adoc

@@ -2,50 +2,44 @@ json-rpc-shell
 ==============
 :compact-option:
 
-'json-rpc-shell' is a simple shell for running JSON-RPC 2.0 queries.
+'json-rpc-shell' is a shell for running JSON-RPC 2.0 queries.
 
-This software has been created as a replacement for the following shell, which
-is written in Java: http://software.dzhuvinov.com/json-rpc-2.0-shell.html
+This software was originally created as a replacement for
+http://software.dzhuvinov.com/json-rpc-2.0-shell.html[a different shell] made by
+Vladimir Dzhuvinov, in order to avoid Java, but has evolved since.
 
 Features
 --------
-In addition to most of the features provided by Vladimir Dzhuvinov's shell
-you get the following niceties:
+In addition to most of the features provided by its predecessor, you will get
+the following niceties:
 
  - configurable JSON syntax highlight, which with prettyprinting turned on
    helps you make sense of the results significantly
  - ability to pipe output through a shell command, so that you can view the
    results in your favourite editor or redirect them to a file
  - ability to edit the input line in your favourite editor as well with Alt+E
+ - WebSocket (RFC 6455) can also be used as a transport rather than HTTP
+ - even Language Server Protocol servers may be launched as a slave command
+ - support for method name tab completion using OpenRPC discovery or file input
 
-Supported transports
---------------------
- - HTTP
- - HTTPS
- - WebSocket
- - WebSocket over TLS
-
-WebSockets
-~~~~~~~~~~
-The JSON-RPC 2.0 spec doesn't say almost anything about underlying transports.
-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 notification, the
-client waits for a message from the server in response.
-
-There's no support so far for any protocol extensions, nor for specifying
-the higher-level protocol (the "Sec-Ws-Protocol" HTTP field).
+Documentation
+-------------
+See the link:json-rpc-shell.adoc[man page] for information about usage.
+The rest of this README will concern itself with externalities.
 
 Packages
 --------
-Regular releases are sporadic.  git master should be stable enough.  You can get
-a package with the latest development version from Archlinux's AUR.
+Regular releases are sporadic.  git master should be stable enough.
+You can get a package with the latest development version using Arch Linux's
+https://aur.archlinux.org/packages/json-rpc-shell-git[AUR],
+or as a https://git.janouch.name/p/nixexprs[Nix derivation].
 
-Building and Usage
-------------------
-Build dependencies: CMake, pkg-config, help2man,
-                    liberty (included), http-parser (included) +
-Runtime dependencies: libev, Jansson, cURL, openssl,
-                      readline or libedit >= 2013-07-12,
+Building
+--------
+Build dependencies: CMake, pkg-config, liberty (included),
+ http-parser (included), asciidoctor or asciidoc (recommended but optional) +
+Runtime dependencies:
+ libev, Jansson, cURL, openssl, readline or libedit >= 2013-07-12
 
  $ git clone --recursive https://git.janouch.name/p/json-rpc-shell.git
  $ mkdir json-rpc-shell/build
@@ -62,10 +56,12 @@ Or you can try telling CMake to make a package for you.  For Debian it is:
  $ cpack -G DEB
  # dpkg -i json-rpc-shell-*.deb
 
-Note that for versions of CMake before 2.8.9, you need to prefix `cpack` with
-`fakeroot` or file ownership will end up wrong.
-
-Run the program with `--help` to obtain usage information.
+Test server
+-----------
+If you install development packages for libmagic, an included test server will
+be built but not installed which provides a trivial JSON-RPC 2.0 service with
+FastCGI, SCGI, WebSocket and LSP-like co-process interfaces.  It responds to
+`ping` and `date`, supports OpenRPC discovery and it can serve static files.
 
 Contributing and Support
 ------------------------

cmake/FindLibEV.cmake

@@ -5,14 +5,16 @@
 
 # Some distributions do add it, though
 find_package (PkgConfig REQUIRED)
-pkg_check_modules (LIBEV QUIET libev)
+pkg_check_modules (LibEV QUIET libev)
 
-if (NOT LIBEV_FOUND)
-	find_path (LIBEV_INCLUDE_DIRS ev.h)
-	find_library (LIBEV_LIBRARIES NAMES ev)
+set (required_vars LibEV_LIBRARIES)
+if (NOT LibEV_FOUND)
+	find_path (LibEV_INCLUDE_DIRS ev.h)
+	find_library (LibEV_LIBRARIES NAMES ev)
+	list (APPEND required_vars LibEV_INCLUDE_DIRS)
+endif ()
 
-	if (LIBEV_INCLUDE_DIRS AND LIBEV_LIBRARIES)
-		set (LIBEV_FOUND TRUE)
-	endif (LIBEV_INCLUDE_DIRS AND LIBEV_LIBRARIES)
-endif (NOT LIBEV_FOUND)
+include (FindPackageHandleStandardArgs)
+FIND_PACKAGE_HANDLE_STANDARD_ARGS (LibEV DEFAULT_MSG ${required_vars})
 
+mark_as_advanced (LibEV_LIBRARIES LibEV_INCLUDE_DIRS)

cmake/FindLibMagic.cmake

@@ -0,0 +1,10 @@
+# Public Domain
+
+find_library (LIBMAGIC_LIBRARIES magic)
+find_path (LIBMAGIC_INCLUDE_DIRS magic.h)
+
+include (FindPackageHandleStandardArgs)
+find_package_handle_standard_args (LibMagic DEFAULT_MSG
+	LIBMAGIC_LIBRARIES LIBMAGIC_INCLUDE_DIRS)
+
+mark_as_advanced (LIBMAGIC_LIBRARIES LIBMAGIC_INCLUDE_DIRS)

config.h.in

@@ -2,10 +2,12 @@
 #define CONFIG_H
 
 #define PROGRAM_NAME "${PROJECT_NAME}"
-#define PROGRAM_VERSION "${project_VERSION}"
+#define PROGRAM_VERSION "${PROJECT_VERSION}"
 
 #cmakedefine HAVE_READLINE
 #cmakedefine HAVE_EDITLINE
 
+#cmakedefine01 ICONV_ACCEPTS_TRANSLIT
+
 #endif  // ! CONFIG_H
 

json-rpc-shell.adoc

@@ -0,0 +1,196 @@
+json-rpc-shell(1)
+=================
+:doctype: manpage
+:manmanual: json-rpc-shell Manual
+:mansource: json-rpc-shell {release-version}
+
+Name
+----
+json-rpc-shell - a shell for JSON-RPC 2.0
+
+Synopsis
+--------
+*json-rpc-shell* [_OPTION_]... { _ENDPOINT_ | _COMMAND_ [_ARG_]... }
+
+Description
+-----------
+:colon: :
+The _ENDPOINT_ must be either an HTTP or a WebSocket URL, with or without TLS
+(i.e. one of the _http{colon}//_, _https{colon}//_, _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
+of the protocol's noisy envelope.  At your option, it can then also be
+pretty-printed, rendered with adjustable syntax highlighting, or even piped
+through another program such as the *less*(1) pager or the *jq*(1) JSON
+processor.
+
+Usage
+~~~~~
+Three things may appear on the internal command line, in a sequence.  The first
+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.
+
+Exit the program by pressing C-c or C-d.  No special keywords are reserved for
+this action as they might conflict with method names.
+
+Options
+-------
+Controlling output
+~~~~~~~~~~~~~~~~~~
+*-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
+	are syntax-highlighted.  This corresponds to the _auto_ setting.  You may
+	also set this to _always_ or _never_.  In either case, color is never
+	applied when piping to another program.
+
+*-v*, *--verbose*::
+	Print raw requests and responses, including the JSON-RPC 2.0 envelope.
+
+*-d*, *--debug*::
+	Print even more information to help debug various issues.
+
+Protocol
+~~~~~~~~
+*-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*=_ORIGIN_::
+	Set the HTTP Origin header to _ORIGIN_.  Some servers may need this.
+
+*-O*[__PATH__], *--openrpc*[**=**__PATH__]::
+	Call "rpc.discover" upon start-up in order to pull in OpenRPC data for
+	tab completion of method names.  If a path is given, it is read from a file.
+
+*-e*, *--execute*::
+	Rather than an _ENDPOINT_, accept a command line to execute and communicate
+	with using the JSON-RPC 2.0 protocol variation used in the Language Server
+	Protocol.
+
+Program information
+~~~~~~~~~~~~~~~~~~~
+*-h*, *--help*::
+	Display a help message and exit.
+
+*-V*, *--version*::
+	Output version information and exit.
+
+*--write-default-cfg*[**=**__PATH__]::
+	Write a default configuration file, show its path and exit.
+
+Environment
+-----------
+*VISUAL*, *EDITOR*::
+	The editor program to be launched by the M-e key binding.
+	If neither variable is set, it defaults to *vi*(1).
+
+Files
+-----
+*json-rpc-shell* follows the XDG Base Directory Specification.
+
+_~/.config/json-rpc-shell/json-rpc-shell.conf_::
+	The configuration file, in which you can configure color output and
+	CA certificate paths.  Use the *--write-default-cfg* option to create
+	a new one for editing.
+
+_~/.local/share/json-rpc-shell/history_::
+	All your past method invocations are stored here upon exit and loaded back
+	on start-up.
+
+Notes
+-----
+Editing
+~~~~~~~
+While single-line editing on the command line may be satisfactory for simple
+requests, it is often convenient or even necessary to run a full text editor
+in order to construct complex objects or arrays, and may even be used to import
+data from elsewhere.  You can launch an editor for the current request using
+the M-e key combination.  Both *readline*(3) and *editline*(7) also support
+multiline editing natively, press either M-Enter or C-v C-j in order to insert
+newlines.
+
+WebSocket
+~~~~~~~~~
+The JSON-RPC 2.0 specification doesn't say almost anything about underlying
+transports.  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 notification, the client waits for a message from the server in response.
+Should any message arrive unexpectedly, you will receive a warning.
+
+There is no support so far for any protocol extensions, nor for specifying
+the higher-level protocol (the "Sec-Ws-Protocol" HTTP field).
+
+Bugs
+----
+The editline (libedit) frontend may exhibit some unexpected behaviour.
+
+Examples
+--------
+Running some queries against json-rpc-test-server, included in the source
+distribution of this program (public services are hard to find):
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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"]} null
+ [Notification]
+
+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 ws://localhost:1234
+ json-rpc> ping | jq ascii_upcase
+ "PONG"
+
+Reporting bugs
+--------------
+Use https://git.janouch.name/p/json-rpc-shell to report bugs, request features,
+or submit pull requests.
+
+See also
+--------
+*jq*(1), *readline*(3) or *editline*(7)
+
+Specifications
+~~~~~~~~~~~~~~
+https://www.jsonrpc.org/specification +
+https://www.json.org