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 `>`).

NOTE:  If you're entering multiple names and email addresses, one at a time
separated by commas (`,`), subsequent names and addresses need to be on a
separate line (mutt requires these subsequent lines to be prefixed with spaces
or tabs, or else it won't consider the subsequent lines to be part of the same
address field.  This does not apply to multiple addresses in the same mutt
alias.

## 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.
* Groups from Google Contacts have not been tested, the behavior may be
  undefined if the goobook query returns multiple addresses.
* Maybe integrate with other CLI contact services, but the project may need to
  be renamed
* Perform more testing!