transient-cons-option: New suffix class for non-cmdline options

The existing `transient-option' class is suitable for options passed to
commands.  A suffix that uses that class may represent an argument such
as "--option".  In the list returned by `transient-args', that argument
and its value, "value", is represented as one element "--option=value".

For "options" that are not passed to a command that is not appropriate.
A caller that wants to extract the value of such an option would have
to parse that string.  `transient-arg-value' can help with that, but it
always returns a string (or nil).

The new `transient-cons-option' class provides a more direct way to deal
with "non-command-line options", by representing the key value pair
using a cons-cell (ARGUMENT . VALUE), not just internally, but in
particular when handing it of to a caller.  VALUE can have any printable
type and ARGUMENT can have any printable type, expect string.

We cannot use the term "key" because that is already used to the key
binding for the command.  Also avoid using "property" because that
implies a property list, while the value returned by `transient-args'
is an alist when all infixes use the `transient-cons-options' class.
Sticking to "argument" also has the advantage, that we don't have to
implement or generalize a dozen methods.

2 files changed, 39 insertions, 0 deletions

diff --git a/docs/transient.org b/docs/transient.org
index ed92eea..58b0593 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -2083,6 +2083,25 @@ object should not affect later invocations.
   it is somewhat likely that future improvements won't be fully
   backward compatible.
 
+- The ~transient-cons-option~ class is intended for situations where
+  ~transient-args~ should return an alist, instead of a list of strings
+  (arguments).  Such suffixes can be specified in prefix definitions
+  like so:
+
+  #+begin_src emacs-lisp
+    (:cons OPTION :key KEY [KEYWORD VALUE]...)
+  #+end_src
+
+  OPTION may be something other than a string, likely a keyword or
+  some other symbol, it is used as the ~car~ of the cons-cell.  When
+  using such an inline definition ~:key~ has to be specified.  In most
+  cases ~:reader~ should also be specified.  When defining such a suffix
+  separately, the "alist key" has to be specified using the ~:variable~
+  keyword argument.
+
+  This class is still experimental it is somewhat likely that future
+  improvements won't be fully backward compatible.
+
 - The ~transient-describe-target~ class is used by the command
   ~transient-describe~.
 
diff --git a/docs/transient.texi b/docs/transient.texi
index 4576cc6..0f1a837 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -2333,6 +2333,26 @@ it is somewhat likely that future improvements won't be fully
 backward compatible.
 
 @item
+The @code{transient-cons-option} class is intended for situations where
+@code{transient-args} should return an alist, instead of a list of strings
+(arguments).  Such suffixes can be specified in prefix definitions
+like so:
+
+@lisp
+(:cons OPTION :key KEY [KEYWORD VALUE]...)
+@end lisp
+
+OPTION may be something other than a string, likely a keyword or
+some other symbol, it is used as the @code{car} of the cons-cell.  When
+using such an inline definition @code{:key} has to be specified.  In most
+cases @code{:reader} should also be specified.  When defining such a suffix
+separately, the "alist key" has to be specified using the @code{:variable}
+keyword argument.
+
+This class is still experimental it is somewhat likely that future
+improvements won't be fully backward compatible.
+
+@item
 The @code{transient-describe-target} class is used by the command
 @code{transient-describe}.