| *haskellmode.txt* Haskell Mode Plugins 02/05/2009 |
| |
| Authors: |
| Claus Reinke <claus.reinke@talk21.com> ~ |
| |
| Homepage: |
| http://projects.haskell.org/haskellmode-vim |
| |
| CONTENTS *haskellmode* |
| |
| 1. Overview |haskellmode-overview| |
| 1.1 Runtime Requirements |haskellmode-requirements| |
| 1.2 Quick Reference |haskellmode-quickref| |
| 2. Settings |haskellmode-settings| |
| 2.1 GHC and web browser |haskellmode-settings-main| |
| 2.2 Fine tuning - more configuration options |haskellmode-settings-fine| |
| 3. GHC Compiler Integration |haskellmode-compiler| |
| 4. Haddock Integration |haskellmode-haddock| |
| 4.1 Indexing |haskellmode-indexing| |
| 4.2 Lookup |haskellmode-lookup| |
| 4.3 Editing |haskellmode-editing| |
| 5. Hpaste Integration |haskellmode-hpaste| |
| 6. Additional Resources |haskellmode-resources| |
| |
| ============================================================================== |
| *haskellmode-overview* |
| 1. Overview ~ |
| |
| The Haskell mode plugins provide advanced support for Haskell development |
| using GHC/GHCi on Windows and Unix-like systems. The functionality is |
| based on Haddock-generated library indices, on GHCi's interactive |
| commands, or on simply activating (some of) Vim's built-in program editing |
| support in Haskell-relevant fashion. These plugins live side-by-side with |
| the pre-defined |syntax-highlighting| support for |haskell| sources, and |
| any other Haskell-related plugins you might want to install (see |
| |haskellmode-resources|). |
| |
| The Haskell mode plugins consist of three filetype plugins (haskell.vim, |
| haskell_doc.vim, haskell_hpaste.vim), which by Vim's |filetype| detection |
| mechanism will be auto-loaded whenever files with the extension '.hs' are |
| opened, and one compiler plugin (ghc.vim) which you will need to load from |
| your vimrc file (see |haskellmode-settings|). |
| |
| |
| *haskellmode-requirements* |
| 1.1 Runtime Requirements ~ |
| |
| The plugins require a recent installation of GHC/GHCi. The functionality |
| derived from Haddock-generated library indices also requires a local |
| installation of the Haddock documentation for GHC's libraries (if there is |
| no documentation package for your system, you can download a tar-ball from |
| haskell.org), as well as an HTML browser (see |haddock_browser|). If you |
| want to use the experimental hpaste interface, you will also need Wget. |
| |
| * GHC/GHCi ~ |
| Provides core functionality. http://www.haskell.org/ghc |
| |
| * HTML library documentation files and indices generated by Haddock ~ |
| These usually come with your GHC installation, possibly as a separate |
| package. If you cannot get them this way, you can download a tar-ball |
| matching your GHC version from http://www.haskell.org/ghc/docs/ |
| |
| * HTML browser with basic CSS support ~ |
| For browsing Haddock docs. |
| |
| * Wget ~ |
| For interfacing with http://hpaste.org. |
| |
| Wget is widely available for modern Unix-like operating systems. Several |
| ports also exist for Windows, including: |
| |
| - Official GNU Wget (natively compiled for Win32) |
| http://www.gnu.org/software/wget/#downloading |
| |
| - UnxUtils Wget (natively compiled for Win32, bundled with other ported |
| Unix utilities) |
| http://sourceforge.net/projects/unxutils/ |
| |
| - Cygwin Wget (emulated POSIX in Win32, must be run under Cygwin) |
| http://cygwin.com/packages/wget/ |
| |
| *haskellmode-quickref* |
| 1.2 Quick Reference ~ |
| |
| |:make| load into GHCi, show errors (|quickfix| |:copen|) |
| |_ct| create |tags| file |
| |_si| show info for id under cursor |
| |_t| show type for id under cursor |
| |_T| insert type declaration for id under cursor |
| |balloon| show type for id under mouse pointer |
| |_?| browse Haddock entry for id under cursor |
| |_?1| search Hoogle for id under cursor |
| |_?2| search Hayoo! for id under cursor |
| |:IDoc| {identifier} browse Haddock entry for unqualified {identifier} |
| |:MDoc| {module} browse Haddock entry for {module} |
| |:FlagReference| {s} browse Users Guide Flag Reference for section {s} |
| |_.| qualify unqualified id under cursor |
| |_i| add 'import <module>(<identifier>)' for id under cursor |
| |_im| add 'import <module>' for id under cursor |
| |_iq| add 'import qualified <module>(<identifier>)' for id under cursor |
| |_iqm| add 'import qualified <module>' for id under cursor |
| |_ie| make imports explit for import statement under cursor |
| |_opt| add OPTIONS_GHC pragma |
| |_lang| add LANGUAGE pragma |
| |i_CTRL-X_CTRL-O| insert-mode completion based on imported ids (|haskellmode-XO|) |
| |i_CTRL-X_CTRL-U| insert-mode completion based on documented ids (|haskellmode-XU|) |
| |i_CTRL-N| insert-mode completion based on imported sources |
| |:GHCi|{command/expr} run GHCi command/expr in current module |
| |
| |:GHCStaticOptions| edit static GHC options for this buffer |
| |:DocSettings| show current Haddock-files-related plugin settings |
| |:DocIndex| populate Haddock index |
| |:ExportDocIndex| cache current Haddock index to a file |
| |:HpasteIndex| Read index of most recent entries from hpaste.org |
| |:HpastePostNew| Submit current buffer as a new hpaste |
| |
| |
| ============================================================================== |
| *haskellmode-settings* |
| 2. Settings ~ |
| |
| The plugins try to find their dependencies in standard locations, so if |
| you're lucky, you will only need to set |compiler| to ghc, and configure |
| the location of your favourite web browser. You will also want to make |
| sure that |filetype| detection and |syntax| highlighting are on. Given the |
| variety of things to guess, however, some dependencies might not be found |
| correctly, or the defaults might not be to your liking, in which case you |
| can do some more fine tuning. All of this configuration should happen in |
| your |vimrc|. |
| > |
| " enable syntax highlighting |
| syntax on |
| |
| " enable filetype detection and plugin loading |
| filetype plugin on |
| < |
| |
| *haskellmode-settings-main* |
| 2.1 GHC and web browser ~ |
| |
| *compiler-ghc* *ghc-compiler* |
| To use the features provided by the GHC |compiler| plugin, use the |
| following |autocommand| in your vimrc: |
| > |
| au BufEnter *.hs compiler ghc |
| < |
| *g:ghc* |
| If the compiler plugin can't locate your GHC binary, or if you have |
| several versions of GHC installed and have a preference as to which binary |
| is used, set |g:ghc|: |
| > |
| :let g:ghc="/usr/bin/ghc-6.6.1" |
| < |
| *g:haddock_browser* |
| The preferred HTML browser for viewing Haddock documentation can be set as |
| follows: |
| > |
| :let g:haddock_browser="/usr/bin/firefox" |
| < |
| |
| *haskellmode-settings-fine* |
| 2.2 Fine tuning - more configuration options ~ |
| |
| Most of the fine tuning is likely to happen for the haskellmode_doc.vim |
| plugin, so you can check the current settings for this plugin via the |
| command |:DocSettings|. If all the settings reported there are to your |
| liking, you probably won't need to do any fine tuning. |
| |
| *g:haddock_browser_callformat* |
| By default, the web browser|g:haddock_browser| will be started |
| asynchronously (in the background) on Windows or when vim is running in a |
| GUI, and synchronously (in the foreground) otherwise. These settings seem |
| to work fine if you are using a console mode browser (eg, when editing in |
| a remote session), or if you are starting a GUI browser that will launch |
| itself in the background. But if these settings do not work for you, you |
| can change the default browser launching behavior. |
| |
| This is controlled by |g:haddock_browser_callformat|. It specifies a |
| format string which uses two '%s' parameters, the first representing the |
| path of the browser to launch, and the second is the documentation URL |
| (minus the protocol specifier, i.e. file://) passed to it by the Haddock |
| plugin. For instance, to launch a GUI browser on Unix-like systems and |
| force it to the background (see also |shellredir|): |
| > |
| :let g:haddock_browser_callformat = '%s file://%s '.printf(&shellredir,'/dev/null').' &' |
| < |
| *g:haddock_docdir* |
| Your system's installed Haddock documentation for GHC and its libraries |
| should be automatically detected. If the plugin can't locate them, you |
| must point |g:haddock_docdir| to the path containing the master index.html |
| file for the subdirectories 'libraries', 'Cabal', 'users_guide', etc.: |
| > |
| :let g:haddock_docdir="/usr/local/share/doc/ghc/html/" |
| < |
| *g:haddock_indexfiledir* |
| The information gathered from Haddock's index files will be stored in a |
| file called 'haddock_index.vim' in a directory derived from the Haddock |
| location, or in $HOME. To configure another directory for the index file, |
| use: |
| > |
| :let g:haddock_indexfiledir="~/.vim/" |
| < |
| *g:wget* |
| If you also want to try the experimental hpaste functionality, you might |
| you need to set |g:wget| before the |hpaste| plugin is loaded (unless wget |
| is in your PATH): |
| > |
| :let g:wget="C:\Program Files\wget\wget.exe" |
| < |
| |
| Finally, the mappings actually use|<LocalLeader>|behind the scenes, so if |
| you have to, you can redefine|maplocalleader|to something other than '_'. |
| Just remember that the docs still refer to mappings starting with '_', to |
| avoid confusing the majority of users!-) |
| |
| ============================================================================== |
| *haskellmode-compiler* *ghc* |
| 3. GHC Compiler Integration ~ |
| |
| The GHC |compiler| plugin sets the basic |errorformat| and |makeprg| to |
| enable |quickfix| mode using GHCi, and provides functionality for show |
| info (|_si|), show type (|_t| or mouse |balloon|), add type declaration |
| (|_T|), create tag file (|_ct|), and insert-mode completion |
| (|i_CTRL-X_CTRL-O|) based on GHCi browsing of the current and imported |
| modules. |
| |
| To avoid frequent calls to GHCi, type information is cached in Vim. The |
| cache will be populated the first time a command depends on it, and will |
| be refreshed every time a |:make| goes through without generating errors |
| (if the |:make| does not succeed, the old types will remain available in |
| Vim). You can also unconditionally force reloading of type info using |
| |:GHCReload| (if GHCi cannot load your file, the type info will be empty). |
| |
| |
| In addition to the standard|quickfix| commands, the GHC compiler plugin |
| provides: |
| |
| *:GHCReload* |
| :GHCReload Reload modules and unconditionally refresh cache of |
| type info. Usually, |:make| is prefered, as that will |
| refresh the cache only if GHCi reports no errors, and |
| show the errors otherwise. |
| |
| *:GHCStaticOptions* |
| :GHCStaticOptions Edit the static GHC options (more generally, options |
| that cannot be set by in-file OPTIONS_GHC pragmas) |
| for the current buffer. Useful for adding hidden |
| packages (-package ghc), or additional import paths |
| (-isrc; you will then also want to augment |path|). |
| If you have static options you want to set as |
| defaults, you could use b:ghc_staticoptions, eg: |
| > |
| au FileType haskell let b:ghc_staticoptions = '-isrc' |
| au FileType haskell setlocal path += src |
| < |
| |
| *:GHCi* |
| :GHCi {command/expr} Run GHCi commands/expressions in the current module. |
| |
| *_ct* |
| _ct Create |tags| file for the current Haskell source |
| file. This uses GHCi's :ctags command, so it will work |
| recursively, but will only list tags for exported |
| entities. |
| |
| *_opt* |
| _opt Shows a menu of frequently used GHC compiler options |
| (selecting an entry adds the option as a pragma to the |
| start of the file). Uses popup menu (GUI) or :emenu |
| and command-line completion (CLI). |
| |
| *_lang* |
| _lang Shows a menu of the LANGUAGE options supported by GHC |
| (selecting an entry adds the language as a pragma to |
| the start of the file). Uses popup menu (GUI) or |
| :emenu and command-line completion (CLI). |
| |
| *_si* |
| _si Show extended information for the name under the |
| cursor. Uses GHCi's :info command. Output appears in |
| |preview-window| (when done, close with |:pclose|). |
| |
| *_t* |
| _t Show type for the name under the cursor. Uses cached |
| info from GHCi's :browse command. |
| |
| *_T* |
| _T Insert type declaration for the name under the cursor. |
| Uses cached info from GHCi's :browse command. |
| |
| *haskellmode-XO* *haskellmode-omni-completion* |
| CTRL-X CTRL-O Standard insert-mode omni-completion based on the |
| cached type info from GHCi browsing current and |
| imported modules. Only names from the current and from |
| imported modules are included (the completion menu |
| also show the type of each identifier). |
| |
| ============================================================================== |
| *haskellmode-haddock* *haddock* |
| 4. Haddock Integration ~ |
| |
| Haskell mode integrates with Haddock-generated HTML documentation, |
| providing features such as navigating to the Haddock entry for the |
| identifier under the cursor (|_?|), completion for the identifier under |
| the cursor (|i_CTRL-X_CTRL-U|), and adding import statements (|_i| |_im| |
| |_iq| |_iqm|) or module qualifier (|_.|) for the identifier under the |
| cursor. |
| |
| These commands operate on an internal Haddock index built from the |
| platform's installed Haddock documentation for GHC's libraries. Since |
| populating this index takes several seconds, it should be stored as a |
| file called 'haddock_index.vim' in the directory specified by |
| |g:haddock_indexfiledir|. |
| |
| Some commands present a different interface (popup menu or command-line |
| completion) according to whether the current Vim instance is graphical or |
| console-based (actually: whether or not the GUI is running). Such |
| differences are marked below with the annotations (GUI) and (CLI), |
| respectively. |
| |
| |:DocSettings| shows the settings for this plugin. If you are happy with |
| them, you can call |:ExportDocIndex| to populate and write out the |
| documentation index (should be called once for every new version of GHC). |
| |
| *:DocSettings* |
| :DocSettings Show current Haddock-files-related plugin settings. |
| |
| |
| *haskellmode-indexing* |
| 4.1 Indexing ~ |
| |
| *:DocIndex* |
| :DocIndex Populate the Haddock index from the GHC library |
| documentation. |
| |
| *:ExportDocIndex* |
| :ExportDocIndex Cache the current Haddock index to a file (populate |
| index first, if empty). |
| |
| |
| *haskellmode-lookup* |
| 4.2 Lookup ~ |
| |
| *_?* |
| _? Open the Haddock entry (in |haddock_browser|) for an |
| identifier under the cursor, selecting full |
| qualifications from a popup menu (GUI) or via |
| command-line completion (CLI), if the identifier is |
| not qualified. |
| |
| *_?1* |
| _?1 Search Hoogle (using |haddock_browser|) for an |
| identifier under the cursor. |
| |
| |
| *_?2* |
| _?2 Search Hayoo! (using |haddock_browser|) for an |
| identifier under the cursor. |
| |
| *:IDoc* |
| :IDoc {identifier} Open the Haddock entry for the unqualified |
| {identifier} in |haddock_browser|, suggesting possible |
| full qualifications. |
| |
| *:MDoc* |
| :MDoc {module} Open the Haddock entry for {module} in |
| |haddock_browser| (with command-line completion for |
| the fully qualified module name). |
| |
| *:FlagReference* |
| :FlagReference {s} Browse Users Guide Flag Reference for section {s} |
| (with command-line completion for section headers). |
| |
| |
| *haskellmode-editing* |
| 4.3 Editing ~ |
| |
| *_.* |
| _. Fully qualify the unqualified name under the cursor |
| selecting full qualifications from a popup menu (GUI) |
| or via command-line completion (CLI). |
| |
| *_iq* *_i* |
| _i _iq Add 'import [qualified] <module>(<identifier>)' |
| statement for the identifier under the cursor, |
| selecting fully qualified modules from a popup menu |
| (GUI) or via command-line completion (CLI), if the |
| identifier is not qualified. This currently adds one |
| import statement per call instead of merging into |
| existing import statements. |
| |
| *_iqm* *_im* |
| _im Add 'import [qualified] <module>' statement for the |
| identifier under the cursor, selecting fully qualified |
| modules from a popup menu (GUI) or via command-line |
| completion (CLI), if the identifier is not qualified. |
| This currently adds one import statement per call |
| instead of merging into existing import statements. |
| |
| *_ie* |
| _ie On an 'import <module>' line, in a correctly loadable |
| module, temporarily comment out import and use :make |
| 'not in scope' errors to explicitly list imported |
| identifiers. |
| |
| *haskellmode-XU* *haskellmode-user-completion* |
| CTRL-X CTRL-U User-defined insert mode name completion based on all |
| names known to the Haddock index, including package |
| names. Completions are presented in a popup menu which |
| also displays the fully qualified module from which |
| each entry may be imported. |
| |
| CamelCode shortcuts are supported, meaning that |
| lower-case letters can be elided, using only |
| upper-case letters and module qualifier separators (.) |
| for disambiguation: |
| |
| pSL -> putStrLn |
| C.E.t -> Control.Exception.t |
| C.M.MP -> Control.Monad.MonadPlus |
| |
| To reduce unwanted matches, the first letter of such |
| shortcuts and the first letter after each '.' have to |
| match directly. |
| |
| ============================================================================== |
| *haskellmode-hpaste* *hpaste* |
| 5. Hpaste Integration ~ |
| |
| This experimental feature allows browsing and posting to |
| http://hpaste.org, a Web-based pastebin tailored for Haskell code. |
| |
| |
| *:HpasteIndex* |
| :HpasteIndex Read the most recent entries from hpaste.org. Show an |
| index of the entries in a new buffer, where ',r' will |
| open the current highlighted entry [and ',p' will |
| annotate it with the current buffer]. |
| |
| *:HpastePostNew* |
| :HpastePostNew Submit current buffer as a new hpaste entry. |
| [This, and ',p' above, are temporarily disabled, |
| needs update to new hpaste.org layout] |
| |
| ============================================================================== |
| *haskellmode-resources* |
| 6. Additional Resources ~ |
| |
| An quick screencast tour through of these plugins is available at: |
| |
| http://projects.haskell.org/haskellmode-vim/screencasts.html |
| |
| Other Haskell-related Vim plugins can be found here: |
| |
| http://www.haskell.org/haskellwiki/Libraries_and_tools/Program_development#Vim |
| |
| Make sure to read about Vim's other program-editing features in its online |
| |user-manual|. Also have a look at Vim tips and plugins at www.vim.org - |
| two other plugins I tend to use when editing Haskell are AlignPlugin.vim |
| (to line up regexps for definitions, keywords, comments, etc. in |
| consecutive lines) and surround.vim (to surround text with quotes, |
| brackets, parentheses, comments, etc.). |
| |
| ============================================================================== |
| vim:tw=78:ts=8:ft=help: |