commands: add menu

Add a new :menu command that can be used to spawn a shell command in an
interactive dialog and execute aerc commands for each of the lines
printed on its standard output like xargs(1) would do in a shell.

The shell command can be configured in aerc.conf under
[general].default-menu-cmd and overridden via the :menu -c <cmd> option.

There are two flags to provide input text to the shell command which can
be useful in combination with other aerc commands:

	-a: All account names, one per line:
		'<account>' LF

	-d: All current account directory names, one per line:
		'<directory>' LF

	-ad: All directories of all accounts, one per line:
		'<account>' '<directory>' LF

Here are some examples:

	:menu -adc fzf :cf -a
	:menu -c 'fzf --multi' :attach
	:menu -dc 'fzf --multi' :cp

And also for key bindings:

	<C-p> = :menu -adc fzf :cf -a<Enter>

Changelog-added: New `:menu` command to invoke other aerc commands
 based on a shell command output.
Signed-off-by: Robin Jarry <robin@jarry.cc>
Tested-by: Bence Ferdinandy <bence@ferdinandy.com>
Tested-by: Johannes Thyssen Tishman <johannes@thyssentishman.com>

2 files changed, 61 insertions, 0 deletions

diff --git a/doc/aerc-config.5.scd b/doc/aerc-config.5.scd
index a616160f..5acb9427 100644
--- a/doc/aerc-config.5.scd
+++ b/doc/aerc-config.5.scd
@@ -79,6 +79,17 @@ These options are configured in the *[general]* section of _aerc.conf_.
 
 	Default: _false_
 
+*default-menu-cmd* = _<cmd>_
+	Default shell command to use for *:menu*. This will be executed with
+	_sh -c_ and will run in an popover dialog.
+
+	Any occurrence of _%f_ will be replaced by a temporary file path where
+	the command is expected to write output lines to be consumed by *:menu*.
+	Otherwise, the lines will be read from the command's standard output.
+
+	Example:
+		*default-menu-cmd* = _fzf_
+
 # UI OPTIONS
 
 These options are configured in the *[ui]* section of _aerc.conf_.
diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index 63ce6345..ee5b27c5 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -170,6 +170,56 @@ These commands work in any context.
 	passed as one argument to the command, unless it is empty, in which case no
 	extra argument is added.
 
+*:menu* [*-c* _"<shell-cmd>"_] [*-e*] [*-b*] [*-a*] [*-d*] _<aerc-cmd ...>_
+	Opens a popover dialog running _sh -c "<shell-cmd>"_ (if not specified
+	*[general].default-menu-cmd* will be used). When the command exits, all
+	lines printed on its standard output will be appended to _<aerc-cmd ...>_
+	and executed as a standard aerc command like *xargs*(1) would do when
+	used in a shell. A colon (*:*) prefix is supported for _<aerc-cmd ...>_
+	but is not required.
+
+	*-c* _"<shell-cmd>"_
+		Override *[general].default-menu-cmd*. See *aerc-config*(5) for
+		more details.
+
+	*-e*: Stop executing commands on the first error.
+
+	*-b*: Do *NOT* spawn the popover dialog. Start the commands in the
+	background (*NOT* in a virtual terminal). Use this if _<shell-cmd>_ is
+	a graphical application that does not need a terminal.
+
+	_<shell-cmd>_ may be fed with input text using the following flags:
+		*-a*: All account names, one per line. E.g.:
+
+			'<account>' LF
+
+		*-d*: All current account directory names, one per line. E.g.:
+
+			'<directory>' LF
+
+		*-ad*: All directories of all accounts, one per line. E.g.:
+
+			'<account>' '<directory>' LF
+
+		Quotes may be added by aerc when either tokens contain special
+		characters. The quotes should be preserved for _<aerc-cmd ...>_.
+
+	Examples:
+
+	```
+	:menu -adc fzf :cf -a
+	:menu -c 'fzf --multi' :attach
+	:menu -dc 'fzf --multi' :cp
+	:menu -bc 'dmenu -l 20' :cf
+	:menu -c 'ranger --choosefiles=%f' :attach
+	```
+
+	This may also be used in key bindings (see *aerc-binds*(5)):
+
+	```
+	<C-p> = :menu -adc fzf :cf -a<Enter>
+	```
+
 *:choose* *-o* _<key>_ _<text>_ _<command>_ [*-o* _<key>_ _<text>_ _<command>_]...
 	Prompts the user to choose from various options.