doc/haskellmode.txt

   1 *haskellmode.txt*       Haskell Mode Plugins    02/05/2009
   2
   3 Authors:
   4     Claus Reinke <claus.reinke@talk21.com> ~
   5
   6 Homepage:
   7     http://projects.haskell.org/haskellmode-vim
   8
   9 CONTENTS                                                         *haskellmode*
  10
  11     1. Overview                                     |haskellmode-overview|
  12         1.1 Runtime Requirements                    |haskellmode-requirements|
  13         1.2 Quick Reference                         |haskellmode-quickref|
  14     2. Settings                                     |haskellmode-settings|
  15       2.1 GHC and web browser                       |haskellmode-settings-main|
  16       2.2 Fine tuning - more configuration options  |haskellmode-settings-fine|
  17     3. GHC Compiler Integration                     |haskellmode-compiler|
  18     4. Haddock Integration                          |haskellmode-haddock|
  19         4.1 Indexing                                |haskellmode-indexing|
  20         4.2 Lookup                                  |haskellmode-lookup|
  21         4.3 Editing                                 |haskellmode-editing|
  22     5. Hpaste Integration                           |haskellmode-hpaste|
  23     6. Additional Resources                         |haskellmode-resources|
  24
  25 ==============================================================================
  26                                                         *haskellmode-overview*
  27 1. Overview ~
  28
  29     The Haskell mode plugins provide advanced support for Haskell development
  30     using GHC/GHCi on Windows and Unix-like systems. The functionality is
  31     based on Haddock-generated library indices, on GHCi's interactive
  32     commands, or on simply activating (some of) Vim's built-in program editing
  33     support in Haskell-relevant fashion. These plugins live side-by-side with
  34     the pre-defined |syntax-highlighting| support for |haskell| sources, and
  35     any other Haskell-related plugins you might want to install (see
  36     |haskellmode-resources|).
  37
  38     The Haskell mode plugins consist of three filetype plugins (haskell.vim,
  39     haskell_doc.vim, haskell_hpaste.vim), which by Vim's |filetype| detection
  40     mechanism will be auto-loaded whenever files with the extension '.hs' are
  41     opened, and one compiler plugin (ghc.vim) which you will need to load from
  42     your vimrc file (see |haskellmode-settings|).
  43
  44
  45                                                     *haskellmode-requirements*
  46 1.1 Runtime Requirements ~
  47
  48     The plugins require a recent installation of GHC/GHCi. The functionality
  49     derived from Haddock-generated library indices also requires a local
  50     installation of the Haddock documentation for GHC's libraries (if there is
  51     no documentation package for your system, you can download a tar-ball from
  52     haskell.org), as well as an HTML browser (see |haddock_browser|). If you
  53     want to use the experimental hpaste interface, you will also need Wget.
  54
  55     * GHC/GHCi ~
  56       Provides core functionality. http://www.haskell.org/ghc
  57
  58     * HTML library documentation files and indices generated by Haddock ~
  59       These usually come with your GHC installation, possibly as a separate
  60       package. If you cannot get them this way, you can download a tar-ball
  61       matching your GHC version from  http://www.haskell.org/ghc/docs/
  62
  63     * HTML browser with basic CSS support ~
  64       For browsing Haddock docs.
  65
  66     * Wget ~
  67       For interfacing with http://hpaste.org.
  68
  69       Wget is widely available for modern Unix-like operating systems. Several
  70       ports also exist for Windows, including:
  71
  72       - Official GNU Wget (natively compiled for Win32)
  73         http://www.gnu.org/software/wget/#downloading
  74
  75       - UnxUtils Wget (natively compiled for Win32, bundled with other ported
  76         Unix utilities)
  77         http://sourceforge.net/projects/unxutils/
  78
  79       - Cygwin Wget (emulated POSIX in Win32, must be run under Cygwin)
  80         http://cygwin.com/packages/wget/
  81
  82                                                     *haskellmode-quickref*
  83 1.2 Quick Reference ~
  84
  85 |:make|               load into GHCi, show errors (|quickfix| |:copen|)
  86 |_ct|                 create |tags| file
  87 |_si|                 show info for id under cursor
  88 |_t|                  show type for id under cursor
  89 |_T|                  insert type declaration for id under cursor
  90 |balloon|             show type for id under mouse pointer
  91 |_?|                  browse Haddock entry for id under cursor
  92 |_?1|                 search Hoogle for id under cursor
  93 |_?2|                 search Hayoo! for id under cursor
  94 |:IDoc| {identifier}  browse Haddock entry for unqualified {identifier}
  95 |:MDoc| {module}      browse Haddock entry for {module}
  96 |:FlagReference| {s}  browse Users Guide Flag Reference for section {s}
  97 |_.|                  qualify unqualified id under cursor
  98 |_i|                  add 'import <module>(<identifier>)' for id under cursor
  99 |_im|                 add 'import <module>' for id under cursor
 100 |_iq|                 add 'import qualified <module>(<identifier>)' for id under cursor
 101 |_iqm|                add 'import qualified <module>' for id under cursor
 102 |_ie|                 make imports explit for import statement under cursor
 103 |_opt|                add OPTIONS_GHC pragma
 104 |_lang|               add LANGUAGE pragma
 105 |i_CTRL-X_CTRL-O|     insert-mode completion based on imported ids (|haskellmode-XO|)
 106 |i_CTRL-X_CTRL-U|     insert-mode completion based on documented ids (|haskellmode-XU|)
 107 |i_CTRL-N|            insert-mode completion based on imported sources
 108 |:GHCi|{command/expr} run GHCi command/expr in current module
 109
 110 |:GHCStaticOptions|   edit static GHC options for this buffer
 111 |:DocSettings|        show current Haddock-files-related plugin settings
 112 |:DocIndex|           populate Haddock index
 113 |:ExportDocIndex|     cache current Haddock index to a file
 114 |:HpasteIndex|        Read index of most recent entries from hpaste.org
 115 |:HpastePostNew|      Submit current buffer as a new hpaste
 116
 117
 118 ==============================================================================
 119                                                         *haskellmode-settings*
 120 2. Settings ~
 121
 122     The plugins try to find their dependencies in standard locations, so if
 123     you're lucky, you will only need to set |compiler| to ghc, and configure
 124     the location of your favourite web browser. You will also want to make
 125     sure that |filetype| detection and |syntax| highlighting are on. Given the
 126     variety of things to guess, however, some dependencies might not be found
 127     correctly, or the defaults might not be to your liking, in which case you
 128     can do some more fine tuning. All of this configuration should happen in
 129     your |vimrc|.
 130 >
 131         " enable syntax highlighting
 132         syntax on
 133
 134         " enable filetype detection and plugin loading
 135         filetype plugin on
 136 <
 137
 138                                                    *haskellmode-settings-main*
 139 2.1 GHC and web browser ~
 140
 141                                                  *compiler-ghc* *ghc-compiler*
 142     To use the features provided by the GHC |compiler| plugin, use the
 143     following |autocommand| in your vimrc:
 144 >
 145         au BufEnter *.hs compiler ghc
 146 <
 147                                                                        *g:ghc*
 148     If the compiler plugin can't locate your GHC binary, or if you have
 149     several versions of GHC installed and have a preference as to which binary
 150     is used, set |g:ghc|:
 151 >
 152         :let g:ghc="/usr/bin/ghc-6.6.1"
 153 <
 154                                                            *g:haddock_browser*
 155     The preferred HTML browser for viewing Haddock documentation can be set as
 156     follows:
 157 >
 158         :let g:haddock_browser="/usr/bin/firefox"
 159 <
 160
 161                                                    *haskellmode-settings-fine*
 162 2.2 Fine tuning - more configuration options ~
 163
 164     Most of the fine tuning is likely to happen for the haskellmode_doc.vim
 165     plugin, so you can check the current settings for this plugin via the
 166     command |:DocSettings|. If all the settings reported there are to your
 167     liking, you probably won't need to do any fine tuning.
 168
 169                                                 *g:haddock_browser_callformat*
 170     By default, the web browser|g:haddock_browser| will be started
 171     asynchronously (in the background) on Windows or when vim is running in a
 172     GUI, and synchronously (in the foreground) otherwise. These settings seem
 173     to work fine if you are using a console mode browser (eg, when editing in
 174     a remote session), or if you are starting a GUI browser that will launch
 175     itself in the background. But if these settings do not work for you, you
 176     can change the default browser launching behavior.
 177
 178     This is controlled by |g:haddock_browser_callformat|. It specifies a
 179     format string which uses two '%s' parameters, the first representing the
 180     path of the browser to launch, and the second is the documentation URL
 181     (minus the protocol specifier, i.e. file://) passed to it by the Haddock
 182     plugin.  For instance, to launch a GUI browser on Unix-like systems and
 183     force it to the background (see also |shellredir|):
 184 >
 185         :let g:haddock_browser_callformat = '%s file://%s '.printf(&shellredir,'/dev/null').' &'
 186 <
 187                                                             *g:haddock_docdir*
 188     Your system's installed Haddock documentation for GHC and its libraries
 189     should be automatically detected. If the plugin can't locate them, you
 190     must point |g:haddock_docdir| to the path containing the master index.html
 191     file for the subdirectories 'libraries', 'Cabal', 'users_guide', etc.:
 192 >
 193         :let g:haddock_docdir="/usr/local/share/doc/ghc/html/"
 194 <
 195                                                       *g:haddock_indexfiledir*
 196     The information gathered from Haddock's index files will be stored in a
 197     file called 'haddock_index.vim' in a directory derived from the Haddock
 198     location, or in $HOME. To configure another directory for the index file,
 199     use:
 200 >
 201         :let g:haddock_indexfiledir="~/.vim/"
 202 <
 203                                                                       *g:wget*
 204     If you also want to try the experimental hpaste functionality, you might
 205     you need to set |g:wget| before the |hpaste| plugin is loaded (unless wget
 206     is in your PATH):
 207 >
 208         :let g:wget="C:\Program Files\wget\wget.exe"
 209 <
 210
 211     Finally, the mappings actually use|<LocalLeader>|behind the scenes, so if
 212     you have to, you can redefine|maplocalleader|to something other than '_'.
 213     Just remember that the docs still refer to mappings starting with '_', to
 214     avoid confusing the majority of users!-)
 215
 216 ==============================================================================
 217                                                   *haskellmode-compiler* *ghc*
 218 3. GHC Compiler Integration ~
 219
 220     The GHC |compiler| plugin sets the basic |errorformat| and |makeprg| to
 221     enable |quickfix| mode using GHCi, and provides functionality for show
 222     info (|_si|), show type (|_t| or mouse |balloon|), add type declaration
 223     (|_T|), create tag file (|_ct|), and insert-mode completion
 224     (|i_CTRL-X_CTRL-O|) based on GHCi browsing of the current and imported
 225     modules.
 226
 227     To avoid frequent calls to GHCi, type information is cached in Vim. The
 228     cache will be populated the first time a command depends on it, and will
 229     be refreshed every time a |:make| goes through without generating errors
 230     (if the |:make| does not succeed, the old types will remain available in
 231     Vim).  You can also unconditionally force reloading of type info using
 232     |:GHCReload| (if GHCi cannot load your file, the type info will be empty).
 233
 234
 235     In addition to the standard|quickfix| commands, the GHC compiler plugin
 236     provides:
 237
 238                                                                   *:GHCReload*
 239 :GHCReload              Reload modules and unconditionally refresh cache of
 240                         type info. Usually, |:make| is prefered, as that will
 241                         refresh the cache only if GHCi reports no errors, and
 242                         show the errors otherwise.
 243
 244                                                            *:GHCStaticOptions*
 245 :GHCStaticOptions       Edit the static GHC options (more generally, options
 246                         that cannot be set by in-file OPTIONS_GHC pragmas)
 247                         for the current buffer. Useful for adding hidden
 248                         packages (-package ghc), or additional import paths
 249                         (-isrc; you will then also want to augment |path|).
 250                         If you have static options you want to set as
 251                         defaults, you could use b:ghc_staticoptions, eg:
 252 >
 253                         au FileType haskell let b:ghc_staticoptions = '-isrc'
 254                         au FileType haskell setlocal path += src
 255 <
 256
 257                                                                        *:GHCi*
 258 :GHCi {command/expr}    Run GHCi commands/expressions in the current module.
 259
 260                                                                          *_ct*
 261 _ct                     Create |tags| file for the current Haskell source
 262                         file. This uses GHCi's :ctags command, so it will work
 263                         recursively, but will only list tags for exported
 264                         entities.
 265
 266                                                                         *_opt*
 267 _opt                    Shows a menu of frequently used GHC compiler options
 268                         (selecting an entry adds the option as a pragma to the
 269                         start of the file). Uses popup menu (GUI) or :emenu
 270                         and command-line completion (CLI).
 271
 272                                                                        *_lang*
 273 _lang                   Shows a menu of the LANGUAGE options supported by GHC
 274                         (selecting an entry adds the language as a pragma to
 275                         the start of the file). Uses popup menu (GUI) or
 276                         :emenu and command-line completion (CLI).
 277
 278                                                                          *_si*
 279 _si                     Show extended information for the name under the
 280                         cursor. Uses GHCi's :info command. Output appears in
 281                         |preview-window| (when done, close with |:pclose|).
 282
 283                                                                           *_t*
 284 _t                      Show type for the name under the cursor. Uses cached
 285                         info from GHCi's :browse command.
 286
 287                                                                           *_T*
 288 _T                      Insert type declaration for the name under the cursor.
 289                         Uses cached info from GHCi's :browse command.
 290
 291                                 *haskellmode-XO* *haskellmode-omni-completion*
 292 CTRL-X CTRL-O           Standard insert-mode omni-completion based on the
 293                         cached type info from GHCi browsing current and
 294                         imported modules. Only names from the current and from
 295                         imported modules are included (the completion menu
 296                         also show the type of each identifier).
 297
 298 ==============================================================================
 299                                                *haskellmode-haddock* *haddock*
 300 4. Haddock Integration ~
 301
 302     Haskell mode integrates with Haddock-generated HTML documentation,
 303     providing features such as navigating to the Haddock entry for the
 304     identifier under the cursor (|_?|), completion for the identifier under
 305     the cursor (|i_CTRL-X_CTRL-U|), and adding import statements (|_i| |_im|
 306     |_iq| |_iqm|) or module qualifier (|_.|) for the identifier under the
 307     cursor.
 308
 309     These commands operate on an internal Haddock index built from the
 310     platform's installed Haddock documentation for GHC's libraries. Since
 311     populating this index takes several seconds, it should be stored as a
 312     file called 'haddock_index.vim' in the directory specified by
 313     |g:haddock_indexfiledir|.
 314
 315     Some commands present a different interface (popup menu or command-line
 316     completion) according to whether the current Vim instance is graphical or
 317     console-based (actually: whether or not the GUI is running). Such
 318     differences are marked below with the annotations (GUI) and (CLI),
 319     respectively.
 320
 321     |:DocSettings| shows the settings for this plugin. If you are happy with
 322     them, you can call |:ExportDocIndex| to populate and write out the
 323     documentation index (should be called once for every new version of GHC).
 324
 325                                                                 *:DocSettings*
 326 :DocSettings            Show current Haddock-files-related plugin settings.
 327
 328
 329                                                         *haskellmode-indexing*
 330 4.1 Indexing ~
 331
 332                                                                    *:DocIndex*
 333 :DocIndex               Populate the Haddock index from the GHC library
 334                         documentation.
 335
 336                                                              *:ExportDocIndex*
 337 :ExportDocIndex         Cache the current Haddock index to a file (populate
 338                         index first, if empty).
 339
 340
 341                                                           *haskellmode-lookup*
 342 4.2 Lookup ~
 343
 344                                                                           *_?*
 345 _?                      Open the Haddock entry (in |haddock_browser|) for an
 346                         identifier under the cursor, selecting full
 347                         qualifications from a popup menu (GUI) or via
 348                         command-line completion (CLI), if the identifier is
 349                         not qualified.
 350
 351                                                                          *_?1*
 352 _?1                     Search Hoogle (using |haddock_browser|) for an
 353                         identifier under the cursor.
 354
 355
 356                                                                          *_?2*
 357 _?2                     Search Hayoo! (using |haddock_browser|) for an
 358                         identifier under the cursor.
 359
 360                                                                        *:IDoc*
 361 :IDoc {identifier}      Open the Haddock entry for the unqualified
 362                         {identifier} in |haddock_browser|, suggesting possible
 363                         full qualifications.
 364
 365                                                                        *:MDoc*
 366 :MDoc {module}          Open the Haddock entry for {module} in
 367                         |haddock_browser| (with command-line completion for
 368                         the fully qualified module name).
 369
 370                                                               *:FlagReference*
 371 :FlagReference {s}      Browse Users Guide Flag Reference for section {s}
 372                         (with command-line completion for section headers).
 373
 374
 375                                                          *haskellmode-editing*
 376 4.3 Editing ~
 377
 378                                                                           *_.*
 379 _.                      Fully qualify the unqualified name under the cursor
 380                         selecting full qualifications from a popup menu (GUI)
 381                         or via command-line completion (CLI).
 382
 383                                                                     *_iq* *_i*
 384 _i _iq                  Add 'import [qualified] <module>(<identifier>)'
 385                         statement for the identifier under the cursor,
 386                         selecting fully qualified modules from a popup menu
 387                         (GUI) or via command-line completion (CLI), if the
 388                         identifier is not qualified.  This currently adds one
 389                         import statement per call instead of merging into
 390                         existing import statements.
 391
 392                                                                   *_iqm* *_im*
 393 _im                     Add 'import [qualified] <module>' statement for the
 394                         identifier under the cursor, selecting fully qualified
 395                         modules from a popup menu (GUI) or via command-line
 396                         completion (CLI), if the identifier is not qualified.
 397                         This currently adds one import statement per call
 398                         instead of merging into existing import statements.
 399
 400                                                                          *_ie*
 401 _ie                     On an 'import <module>' line, in a correctly loadable
 402                         module, temporarily comment out import and use :make
 403                         'not in scope' errors to explicitly list imported
 404                         identifiers.
 405
 406                                 *haskellmode-XU* *haskellmode-user-completion*
 407 CTRL-X CTRL-U           User-defined insert mode name completion based on all
 408                         names known to the Haddock index, including package
 409                         names. Completions are presented in a popup menu which
 410                         also displays the fully qualified module from which
 411                         each entry may be imported.
 412
 413                         CamelCode shortcuts are supported, meaning that
 414                         lower-case letters can be elided, using only
 415                         upper-case letters and module qualifier separators (.)
 416                         for disambiguation:
 417
 418                           pSL    -> putStrLn
 419                           C.E.t  -> Control.Exception.t
 420                           C.M.MP -> Control.Monad.MonadPlus
 421
 422                         To reduce unwanted matches, the first letter of such
 423                         shortcuts and the first letter after each '.' have to
 424                         match directly.
 425
 426 ==============================================================================
 427                                                  *haskellmode-hpaste* *hpaste*
 428 5. Hpaste Integration ~
 429
 430     This experimental feature allows browsing and posting to
 431     http://hpaste.org, a Web-based pastebin tailored for Haskell code.
 432
 433
 434                                                                 *:HpasteIndex*
 435 :HpasteIndex            Read the most recent entries from hpaste.org. Show an
 436                         index of the entries in a new buffer, where ',r' will
 437                         open the current highlighted entry [and ',p' will
 438                         annotate it with the current buffer].
 439
 440                                                               *:HpastePostNew*
 441 :HpastePostNew          Submit current buffer as a new hpaste entry.
 442                         [This, and ',p' above, are temporarily disabled,
 443                          needs update to new hpaste.org layout]
 444
 445 ==============================================================================
 446                                                        *haskellmode-resources*
 447 6. Additional Resources ~
 448
 449     An quick screencast tour through of these plugins is available at:
 450
 451     http://projects.haskell.org/haskellmode-vim/screencasts.html
 452
 453     Other Haskell-related Vim plugins can be found here:
 454
 455     http://www.haskell.org/haskellwiki/Libraries_and_tools/Program_development#Vim
 456
 457     Make sure to read about Vim's other program-editing features in its online
 458     |user-manual|. Also have a look at Vim tips and plugins at www.vim.org -
 459     two other plugins I tend to use when editing Haskell are AlignPlugin.vim
 460     (to line up regexps for definitions, keywords, comments, etc. in
 461     consecutive lines) and surround.vim (to surround text with quotes,
 462     brackets, parentheses, comments, etc.).
 463
 464 ==============================================================================
 465  vim:tw=78:ts=8:ft=help: