asyncomplete-muttgoobook.vim/README.md

asyncomplete-muttgoobook.vim

A vim plugin for mail files to select email addresses from the mutt aliases file, and Google Contacts (using goobook).

Prerequisites

• This has been tested with the vim-plug minimalist Vim plugin manager. Other plugin managers may work.
• This is designed to work with the asyncomplete code completion subsystem, which is writtin in pure Vim (v8) script.
• goobook for interacting with your Google Contacts from the command line. This has been tested with Goobook 3.5.2, but 1.x may work if your distribution still uses Python 2.7+.
• This is designed to work in mutt, but is not mutt-specific (except for reading ${HOME}/.mutt/aliases). Using vim to edit the file type mail should be enough to get it working.

As of this writing (2023-04-30), this has only been tested in Vim v9, but is also writtin in Vim v8 script so should work in older versions.

Installation

1. Clone this repository into your Vim plugin directory. For vim-plug in Vim on Linux, this is usually ${HOME}/.vim/plugged, but vim-plug will place it here automatically if you merely configure $MYVIMRC properly. Place the following line between call plug#begin(..) and call plug#end():

   call plug#begin('...')
   " ...
   Plug 'https://git.eldon.me/trey/asyncomplete-muttgoobook.vim'
   
   " ...
   call plug#end()
   

   Then, inside Vim, run :PlugInstall. You can check that the muttgoobook plugin is installed successfully with :PlugStatus.

2. Configure Vim in $MYVIMRC to load the muttgoobook source using the following:

   autocmd User asyncomplete_setup call asyncomplete#register_source({
       \ 'name':       'muttgoobook',
       \ 'allowlist':  ['mail'],
       \ 'completor':  function('asyncomplete#sources#muttgoobook#completor'),
       \ })
   

   If you want to have other file types to use this plugin, you may add them to the allowlist above.

3. By default, this plugin tries to determine if the cursor is in an email address field ('From:', 'To:', 'Cc:', 'Bcc:', in English). The matching is case-insensitive. If you use another language, that names these fields differently, you can modify this in $MYVIMRC by adding the g:muttgoobook_address_fields global variable. This is designed to be a Vim regular expression, replace ['from', 'to', 'b\?cc'] accordingly:

   let g:muttgoobook_address_fields = '^\s*\(from\|to\|b\?cc\):\s*'
   

   The above pattern is the default if this variable isn't specified.

4. Also, if your mutt aliases file is in a different path than ${HOME}/.mutt/aliases, you can override it in $MYVIMRC with the global variable g:mutt_aliases: ```vim let g:mutt_aliases = '~/.mutt/aliases'

   Again, what appears above is the default if not set explicitly to
   something else.  Any double-quotes (`"`) and backslashes (`\`) in the mutt
   aliases file will be removed before pasting the results of the completion
   to the currently edited mail file.
   
   

How to use it

If asyncomplete is installed correctly and is working, editing a file type of mail should show the popup completion menu after you've typed the first three characters of the name or email address, as long as the cursor is in a From:, To:, Cc:, or Bcc field. Case doesn't matter for the name of the address field, and the cursor can be in a multi-line list of names/email addresses.

The listing of the popup completion menu will show mutt aliases and names from goobook that match the string entered thus far. You can further limit the results returned in the popup completion menu by typing more characters. Select the alias or name and press Enter, and the value from the alias will be pasted (for mutt aliases), and the name and email address from Google Contacts (goobook). Values from mutt aliases will be pasted verbatim except backslashes (\) and double-quotes (") will be removed. Email addresses from goobook will appear between angle brackets (< and >).

TODO

• possibly set up some kind of trigger to post an email address from the mutt aliases file or Google Contacts, within the body of the message.
• Maybe integrate with other CLI contact services, but the project may need to be renamed
• Perform more testing!