binds: parse annotations from keybind config

Parse inline comments in binds.conf as annotations to the corresponding
keybinds. Note that a space is required before the comment symbol, so
the comment delimiter is " # ".

Example:

	p = :postpone<Enter> # I'll work on it later

where "I'll work on it later" is the annotation.

When a comment symbol ("#") is needed in the value part of the keybind,
it should be escaped ("\#"). Comment symbols can be used without
restriction in the annotation itself.

Signed-off-by: Koni Marti <koni.marti@gmail.com>
Tested-by: Bence Ferdinandy <bence@ferdinandy.com>
Reviewed-by: Bence Ferdinandy <bence@ferdinandy.com>
Acked-by: Robin Jarry <robin@jarry.cc>

3 files changed, 24 insertions, 6 deletions

diff --git a/config/binds.go b/config/binds.go
index b65aa1ab..9647388d 100644
--- a/config/binds.go
+++ b/config/binds.go
@@ -49,6 +49,8 @@ type KeyStroke struct {
 type Binding struct {
 	Output []KeyStroke
 	Input  []KeyStroke
+
+	Annotation string
 }
 
 type KeyBindings struct {
@@ -84,7 +86,7 @@ func defaultBindsConfig() *BindingConfig {
 	wizard := NewKeyBindings()
 	wizard.ExKey = KeyStroke{Key: tcell.KeyCtrlE}
 	wizard.Globals = false
-	quit, _ := ParseBinding("<C-q>", ":quit<Enter>")
+	quit, _ := ParseBinding("<C-q>", ":quit<Enter>", "Quit aerc")
 	wizard.Add(quit)
 	return &BindingConfig{
 		Global:                 NewKeyBindings(),
@@ -105,6 +107,10 @@ func parseBindsFromFile(root string, filename string) error {
 	log.Debugf("Parsing key bindings configuration from %s", filename)
 	binds, err := ini.LoadSources(ini.LoadOptions{
 		KeyValueDelimiters: "=",
+		// IgnoreInlineComment is set to true which tells ini's parser
+		// to treat comments (#) on the same line as part of the value;
+		// hence we need cut the comment off ourselves later
+		IgnoreInlineComment: true,
 	}, filename)
 	if err != nil {
 		return err
@@ -167,6 +173,9 @@ func parseBinds(root string, filename string) error {
 func LoadBindingSection(sec *ini.Section) (*KeyBindings, error) {
 	bindings := NewKeyBindings()
 	for key, value := range sec.KeysHash() {
+		var annotation string
+		value, annotation, _ = strings.Cut(value, " # ")
+		value = strings.TrimSpace(value)
 		switch key {
 		case "$ex":
 			strokes, err := ParseKeyStrokes(value)
@@ -195,7 +204,8 @@ func LoadBindingSection(sec *ini.Section) (*KeyBindings, error) {
 			}
 			bindings.CompleteKey = strokes[0]
 		default:
-			binding, err := ParseBinding(key, value)
+			annotation = strings.TrimSpace(annotation)
+			binding, err := ParseBinding(key, value, annotation)
 			if err != nil {
 				return nil, err
 			}
@@ -766,7 +776,7 @@ func ParseKeyStrokes(keystrokes string) ([]KeyStroke, error) {
 	return strokes, nil
 }
 
-func ParseBinding(input, output string) (*Binding, error) {
+func ParseBinding(input, output, annotation string) (*Binding, error) {
 	in, err := ParseKeyStrokes(input)
 	if err != nil {
 		return nil, err
@@ -776,7 +786,8 @@ func ParseBinding(input, output string) (*Binding, error) {
 		return nil, err
 	}
 	return &Binding{
-		Input:  in,
-		Output: out,
+		Input:      in,
+		Output:     out,
+		Annotation: annotation,
 	}, nil
 }
diff --git a/config/binds_test.go b/config/binds_test.go
index dab3b9f1..b21c1887 100644
--- a/config/binds_test.go
+++ b/config/binds_test.go
@@ -13,7 +13,7 @@ func TestGetBinding(t *testing.T) {
 
 	bindings := NewKeyBindings()
 	add := func(binding, cmd string) {
-		b, _ := ParseBinding(binding, cmd)
+		b, _ := ParseBinding(binding, cmd, "")
 		bindings.Add(b)
 	}
 
diff --git a/doc/aerc-binds.5.scd b/doc/aerc-binds.5.scd
index 6bb2100e..a46b6427 100644
--- a/doc/aerc-binds.5.scd
+++ b/doc/aerc-binds.5.scd
@@ -53,6 +53,13 @@ The available contexts are:
 *[compose::review]*
 	keybindings for the composer, when reviewing the email before it's sent
 
+	To customize the description shown on the review screen, add a comment
+	(" # ") at the end of the keybinding.
+
+	Example:
+
+		p = :postpone<Enter> # I'll work on it later
+
 *[terminal]*
 	keybindings for terminal tabs