scion-backend-vim
=================

This is the vim backend belonging to the http://github.com/MarcWeber/nominolo/scion project.

The vim files have been put into a separate repository because Thomas Schilling can't support it.
So he proposed using independent release cycles.


repository information
======================
For each release / branch of scion-lib this vim backend repository will have
the same branch suffixed by -vim. Thus if you use devel branch of scion
checkout the devel-vim branch. If something doesn't work it's a bug and you
should contact me.

INSTALLATION & USAGE:
=====================

See VIM troubleshooting below if you have problems.

Installation
------------

Copy paste the following lines into your `~/.vimrc`

    " First line: You really want this:
    set nocompatible

    " make vim load the plugin/haskell_scion.vim,
    " make it know about ftplugin/haskell.vim, autoload/* files
    exec 'set runtimepath+='.expand("~/path/scion-<version>/vim_runtime_path/")

    " this makes vim actually load the ftplugin file
    " As vim user you should already have this in your .vimrc
    filetype plugin on

    " How to connect to scion?
    " recommended: vim spawns a scion instance itself:
    let g:scion_connection_setting = [ 'scion', expand("<path/to/scion-server>")]
    
    " to connect to a running scion instance listening on TCP/IP port 4005 use:
    " let g:scion_connection_setting = [ 'socket',  ["localhost", 4005] ]


Usage
-----

You store certain settings in a configuration file.  (Note: This
feature is currently experimental and details may change in future
Scion releases.)  To generate an initial configuration file run

    :WriteSampleConfigScion

To load a component (a Cabal library or executable, or just a single
file) use one of:

    :LoadComponentScion library
    :LoadComponentScion executable:cabal_executable_name
    :LoadComponentScion file:cabal_executable_name
    :LoadComponentScion

The last one is a shortcut for `file:<this buf>`.  You can use completion.

At this point you should already get some compilation errors.  After
modifying the file, use

    :BackgroundTypecheckFileScion

to re-typecheck just the current file.

If the file typechecks you can move the cursor onto an identifier and
use the command

    :ThingAtPointScion

You should see something like this, which is the (instantiated) type
of the identifier at the point:

      {'Just': 'print :: [Char] -> IO ()'}
    
Have a look at `vim_runtime_path/ftplugin/haskell.vim` to see a list of all
commands which are implemented yet.
    
`BackgroundTypecheckFileScion` should be called automatically after
buf write.  If you don't like this set `g:dont_check_on_buf_write` or
overwrite `g:haskell_qf_hook` to change open/close quickfix and jump to
first *error* behaviour.

Note: To navigate haskell sources use tag files. Haskell tag files are
      generated by hasktagse (-> hackage) See :h tags

## troubleshooting
The server outputs some messages.
connection type:

  TCP/IP:
  messaeges should be print to console

  TCP/IP or STDIN/OUT (server started by Vim:
  try :py print scion_stdout
  This should print the last 200 lines of "rubbish" the vim client didn't
  understand. For troubleshooting starting the server manually is the best
  option


## VIM troubleshooting:

  * Check python version:

    " Does your vim support Python?
    :echo "expected: 1, got: ".has('python')

    " which version?
    :py import sys
    :py print "python version should be >= 2.4, your python version is:\n \n%s"%sys.version


      Vim mode requires Python support (version 2.4 or later).  Vim 7.2 or
      later has Python support enabled by default.  However, not every
      distribution of Vim includes a recent enough version of Python.
      Notably, MacVim is only linked against version 2.3.5 to be compatible
      with OS X 10.4.  You will need to build it from source, which is
      however reasonably fast.


  * Is your ~/.vimrc read? Try:

    :echo g:scion_connection_setting

    If you see red lines you pasted the configuration into the wrong file.
    See :h .vimrc

  * ~ ($HOME) expansion: use expand("path") or expand("$HOME").'/rel-path'

  * For testing purposes you can source all .vim files this way:
    "source <scion-backend-vim-home>/vim_runtime_path/plugin/haskell_scion.vim

    However there should be no reason to do so!

CONTACT
=====================
Contact me on irc.freenode.net or send an email to marco-oweber@gmx.de