============================== Company GHC |travis| |melpa|

.. contents:: Table of Contents .. sectnum::

Overview

| Company-mode completion back-end for haskell-mode via ghc-mod. | It runs when the major mode is derived from haskell-mode.

Installation

Depends

• cl-lib
• company-mode_

• ghc-mod_

  In order to make company-ghc work, ghc-comp-init needs to be called once. It is called by ghc-init, so if you follow ghc-mod manual_, there is nothing else to do about it. Otherwise (if you don't want to call ghc-init), ensure ghc-comp-init is called before using company-ghc.

Optional Dependency

• hoogle_ command and its database (hoogle data) for doc-buffer support and hoogle search completion.

Setup from MELPA_

1. Install from MELPA_

   | :kbd:M-x package-install RET company-ghc RET

2. Add company-ghc to company-backends after loading company-mode and ghc-mod

   .. code:: emacs-lisp

   (add-to-list 'company-backends 'company-ghc)

Setup from Git

1. Install from Git::

   git clone https://github.com/iquiw/company-ghc.git

2. Add company-ghc to company-backends after loading company-mode and ghc-mod

   .. code:: emacs-lisp

   (add-to-list 'load-path "/path/to/company-ghc") (add-to-list 'company-backends 'company-ghc)

Feature

Completion

The following completions are available.

1. Pragma names. (ghc-pragma-names)

   .. image:: images/pragma.png :alt: Completion for pragma

2. Language extensions. (ghc-language-extensions)

   .. image:: images/language.png :alt: Completion for language extensions

3. GHC option flags. (ghc-options-flags)

   .. image:: images/option.png :alt: Completion for GHC options

4. Import module names. (ghc-modules-names)

   .. image:: images/module.png :alt: Completion for import modules

5. Variables and functions in import spec. (ghc-module-keyword)

   .. image:: images/impspec.png :alt: Completion for import specs

6. Qualified imported keywords.

   .. image:: images/qualified.png :alt: Completion for qualified imported keywords

7. Keywords from imported modules.

   .. image:: images/keyword.png :alt: Completion for keywords of imported modules

Show type info in minibuffer

• Type info of completion candidate is displayed in minibuffer, given by ghc-modi browse -d.

  Only when ghc-modi browse -d does not provide type info, company-ghc-show-info (t, oneline or nomodule) is used to determine how type info given by ghc-modi info is displayed.

  Default value of company-ghc-show-info is nil since when ghc-modi info is called, ghc-mod pops up error if the current buffer contains error.

  .. image:: images/showinfo.png :alt: Show info in minibuffer (nomodule)

Show module name as annotation

• Module name is displayed as completion annotation if company-ghc-show-module is non-nil (default) as in the above images.

Display Hoogle document as doc-buffer

• If hoogle_ is installed and its database is prepared, then pressing :kbd:<f1> displays hoogle searched documentation in the doc-buffer.

  .. image:: images/doc-buffer.png :alt: Display documentation in docbuffer

Locate source

• When a function in the local project is selected as completion candidate, pressing :kbd:C-w (company-show-location) shows its source. It uses information from ghc-mod info, and works only when company-ghc-show-info is non-nil.

Special completion command

1. In-module completion (:kbd:M-x company-ghc-complete-in-module)

   It takes a module name in minibuffer, and provides candidates from keywords defined in the specified module. You can use this as an alternative to :browse command of GHCi.

   .. image:: images/in-module.png :alt: In-module completion

2. Hoogle search completion (:kbd:M-x company-ghc-complete-by-hoogle)

   It takes a query text in minibuffer, and provide candidates from hoogle_ search results. For example, candidates is like the following if the query is (a -> b) -> (f a -> f b).

   .. image:: images/hoogle-search.png :alt: Hoogle search completion

   If you want to get more search results at a time, increase the value of company-ghc-hoogle-search-limit (default 20).

Note

• Currently, company-ghc treats all symbols as completion prefix unless it starts from line beginning. This means other back-ends after company-ghc have no chance to provide completion candidates in haskell-mode.

  As of now, if you want to use other back-ends with company-ghc, use grouped back-end like below.

  .. code:: emacs-lisp

  (add-to-list 'company-backends '(company-ghc :with company-dabbrev-code))

• company-ghc add automatic scan module function to local after-save-hook. It might cause serious problem if there is a bug in it. If you have any trouble at save, turn off autoscan by :kbd:M-x company-ghc-turn-off-autoscan.

  If customized variable company-ghc-autoscan is nil, autoscan won't be added to local after-save-hook.

  If scan module is not performed in the buffer, completion by company-ghc does not work properly. scan module can be invoked by :kbd:M-x company-ghc-scan-modules.

• company-ghc does not try to browse keywords in a module if the module failed to be browsed once.

  If you want company-ghc to browse failed modules again, use :kbd:M-x company-ghc-clear-failed-cache.

  To make all modules browsed again, use :kbd:M-x company-ghc-clear-all-cache.

Diagnostic

There are some cases that completion by company-ghc does not work. If there is something wrong, run :kbd:M-x company-ghc-diagnose, which shows diagnostic info like the following::

• company-ghc backend found: company-ghc
• automatic scan module is enabled

• ghc-boot process has been done

  Module Alias Candidates

  Data.Maybe - 12 Data.Map M 111 Data.Attoparsec.ByteString.Char8 - 76 Control.Applicative - 22 Prelude - 212

The first item shows if company-ghc is added to company-backends or not.

The second item shows if company-ghc auto scan is enabled or not.

The third item shows if ghc-boot has been processed properly.

The table shows rows of imported module in the current buffer, its qualified import alias and number of candidates in the module.

If company-ghc-autoscan is non-nil but company-ghc auto scan is disabled, it is possibly initialization step of company-ghc is not performed by some reason. Check company-ghc configuration. For workaround, run :kbd:M-x company-ghc-turn-on-autoscan manually.

If ghc-boot process has not been done or failed to run, check ghc-mod configuration (Ref. ghc-mod manual_) or whether ghc-mod boot command from shell or command prompt succeeds in the project directory.

If some module is not in the table, it is possibly bug of company-ghc.

Number of candidates is nil initially, and gets filled when completion for the corresponding module is performed. If number of candidates is 0 or nil after completion, it might be problem related to ghc-mod. Try again with setting ghc-debug to t and see if there is any error in *GHC Debug* buffer.

License

Licensed under the GPL 3+ license.

.. _company-mode: https://company-mode.github.io/ .. _haskell-mode: https://github.com/haskell/haskell-mode .. _ghc-mod: http://www.mew.org/~kazu/proj/ghc-mod/en/ .. _ghc-mod manual: http://www.mew.org/~kazu/proj/ghc-mod/en/preparation.html .. _haskell-docs: https://github.com/chrisdone/haskell-docs .. _hoogle: https://hackage.haskell.org/package/hoogle .. _MELPA: https://melpa.org/ .. |travis| image:: https://api.travis-ci.org/iquiw/company-ghc.svg?branch=master :target: https://travis-ci.org/iquiw/company-ghc .. |melpa| image:: https://melpa.org/packages/company-ghc-badge.svg :target: https://melpa.org/#/company-ghc