diff options
Diffstat (limited to '.vim/doc/haskellmode.txt')
| -rw-r--r-- | .vim/doc/haskellmode.txt | 456 |
1 files changed, 456 insertions, 0 deletions
diff --git a/.vim/doc/haskellmode.txt b/.vim/doc/haskellmode.txt new file mode 100644 index 0000000..905349c --- /dev/null +++ b/.vim/doc/haskellmode.txt @@ -0,0 +1,456 @@ +*haskellmode.txt* Haskell Mode Plugins 23/04/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 for the current buffer. + Useful for adding hidden packages (-package ghc). + + *: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: |