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](https://github.com/junegunn/vim-plug) minimalist Vim plugin manager.  Other plugin managers may work.
* This is designed to work with the [asyncomplete](https://github.com/prabirshrestha/asyncomplete.vim) code completion subsystem, which is writtin in pure Vim (v8) script.
* [goobook](http://gitlab.com/goobook/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()`: 
    ```vim
    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`.
1.  Configure Vim in $MYVIMRC to load the `muttgoobook` source using the following:  
    ```vim
    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.

1.  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:
    ```vim
    let g:muttgoobook_address_fields = '^\s*\(from\|to\|b\?cc\):\s*'
    ```
    The above pattern is the default if this variable isn't specified.
1.  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!