vimsh/vimsh.readme

   1 :: vimsh readme ::
   2
   3     vimsh is a python script and vim script that allow a user to run
   4     a shell within a [g]vim buffer.  There are certain requirements and
   5     some limitations depending on your platform so please read on.  vimsh
   6     works on both the console and GUI versions of vim so from this point on
   7     references to vim also include GUI versions of vim.
   8
   9     *********************************************************************
  10     NOTE:
  11
  12         If you like this script and vim users are allowed to vote on new
  13         features in vim again, PLEASE put in a vote for vi editing in the ex
  14         command window ( not the new command window/buffer ).  It's the only
  15         new feature I would like vim to have.
  16     *********************************************************************
  17
  18 :: vimsh requirements ::
  19
  20     requirements summary:
  21
  22         python enabled vim ( +python )
  23         operating system that supports pty (unix) -or- popen/pipes (Windows)
  24         python 2.2 or higher, may work with 2.0, but not tested.
  25             Tested w/ 2.2 and 2.3.
  26
  27     requirements in detail:
  28
  29     vimsh requires a python enabled vim ( +python ), run
  30     :ver to see if you have +python for your build of vim.
  31
  32     vimsh also requires that your operating system supports
  33     either pty ( pseudo ttys ) -or- the popen family of calls.
  34     Most unix variants have support for pty in one form or another
  35     and most other platforms, for instance Windows, support popen.
  36
  37     I have tested vimsh on the following configurations, newer releases
  38     are not always tested with all platforms:
  39
  40         vim 6.0-6.2 / Slackware Linux 8.0 / python 2.2b2, 2.2.3, 2.3.X
  41         vim 6.0-6.2 / Gentoo Linux        / python 2.3.3
  42         vim 6.0-6.2 / WinNT 4.0           / Activestate Python 2.2
  43         vim 6.0-6.2 / Win2K               / Standard Python 2.2
  44         vim 6.0-6.2 / WinXP               / Standard Python 2.2
  45         vim 6.0-6.2 / FreeBSD 4.6-4.9     / python 2.2.X, 2.3.X
  46
  47     The pty library is 'unsupported' by python on some platforms
  48     but I have received reports of success on these platforms
  49     in addition to the ones I have tested on:
  50
  51     QNX
  52     Solaris( waiting for confirmation of fix )
  53
  54 :: running vimsh ::
  55
  56     You can run vimsh by sourcing the file vimsh.vim on the ex
  57     command line like this assuming you are in the directory that
  58     vimsh.vim is located:
  59
  60         :source vimsh.vim
  61
  62     It is much easier to assign a key mapping to load it.  <Leader> is what
  63     ever you use as your leader sequence, I personally use '\'.
  64
  65     A useful mapping might be:
  66
  67          nmap <Leader>sh           :source <path_to_script>/vimsh.vim<CR>
  68
  69     I use one like this:
  70
  71          nmap \sh                  :source <path_to_script>/vimsh.vim<CR>
  72
  73     There is a python script, vimsh.py, that needs to be in the same directory
  74     as vimsh.vim.  It should have been included in the .tar.gz or .zip file
  75     you downloaded as well as this file, a TODO file, and the ChangeLog.
  76
  77     Putting the scripts in your plugin directory is *NOT* recommended.
  78
  79     You can also have multiple buffers using vimsh:
  80
  81             :VimShNewBuf foo
  82
  83     will create a new additional vimsh buffer with the name _foo_.
  84
  85 :: vimsh license ::
  86
  87     Use at your own risk.  I'm not responsible if it hoses your
  88     machine.  All I ask is that I'm made aware of changes so I can
  89     incorporate them into my version, that and my contact info stays in
  90     the script.
  91
  92 :: vimsh limitations ::
  93
  94     Running a shell within vim has it's limitations due to the fact
  95     that vim doesn't have the code necessary to run an interactive
  96     shell.  vimsh uses different methods to allow this to happen
  97     using python.
  98
  99     general limitations:
 100
 101         Can only execute line oriented programs, no vim within vim stuff,
 102         emacs, [n]curses, pagers, etc.
 103
 104     pty:
 105
 106         The best support and formatting.  Most unix platforms support ptys.
 107         You can run interactive line based commands like ftp, telnet, rm,
 108         ping, cp, ssh, etc.
 109
 110         Only current limitation is involving commands that have
 111         continuous output (ping) or slow commands (ftp). You will need
 112         to use the refresh key (F5, remappable) to see output sometimes.
 113         I've tried everything I can possibly think of to try and get it
 114         to work but nothing has. See vimsh.vim for what's been tried,
 115         I'm open to suggestions. If vim ever gets an idle processing
 116         function, akin to CursorHold, but without the limitations, this
 117         will work properly.
 118
 119     popen:
 120
 121         Only non-interactive programs are supported.  Since this mostly applies
 122         to the Windows platform, this means you can run programs like:
 123
 124             dir, findstr, type, attrib, set, ping, etc.
 125
 126             Interactive programs like ftp, telnet, ssh will *not* work
 127             correctly.
 128
 129         This is because these programs seem to use buffered output or write
 130         directly to the console using the Windows Console API.  Unfortunately,
 131         this means that without pty functionality for windows ( or a lot of
 132         work on my part ), these commands cannot be run within vimsh.
 133
 134         Also commands that wait on standard input currently cannot
 135         be interrupted w/ ctrl-c.  i.e. running 'findstr foo', since
 136         there is no file spec the command will wait and hang the shell
 137         session within vim.  Just delete the buffer if this happens (:bd).
 138
 139 :: vimsh customization ::
 140
 141     It is recommended not to modify the vimsh.py or vimsh.vim to customize
 142     vimsh.  Support exists in vimsh to retreive settings that have been
 143     set in your .[g]vimrc or equivalent.
 144
 145     Here are some examples of how it would look in a .vimrc:
 146
 147           let g:vimsh_prompt_override = 1               ##  will not use normal prompt from your 'real' shell
 148           let g:vimsh_prompt_pty      = "%m%#"          ##  specify overriden prompt
 149           let g:vimsh_split_open      = 0               ##  run vimsh in the current buffer
 150           let g:vimsh_sh              = "/bin/zsh"      ##  shell to run within vimsh
 151
 152     The list of variables was getting too long and that meant I had to duplicate
 153     what was already in vimsh.py in this file, so please read vimsh.py for variables
 154     that can be customized.  Look for the section in the file labeled 'customization'.
 155
 156 :: vimsh notes ::
 157
 158     The timeouts for reading are set low ( <= 0.2 sec ) for local filesystem
 159     and application use. If you plan on running telnet/ftp/ssh etc, pretty
 160     much any network based app, you can bump up the timeouts if you
 161     have a slower connection.  This is not an exact science. If you're not
 162     seeing all of the output or having to hit enter to see output you can
 163     bump the timeout up.  Being conservative won't hurt. See the mappings for
 164     setting the timeouts for reads and refreshing output.  If you don't want
 165     to change the timeouts you can just press <Enter> or <F5> (or whatever you
 166     have mapped the page output key to) to check for more output from the
 167     command.
 168
 169 :: vimsh tips ::
 170
 171     If you run tcsh or csh the following will allow you to have a better
 172     environment when using vimsh.
 173
 174     Add these to your .vimrc:
 175
 176         let g:vimsh_pty_prompt_override = 0
 177         let g:vimsh_sh                  = '/bin/tcsh'
 178         let $VIMSH                      = 1
 179
 180     The $VIMSH can then be detected in your .cshrc to do special processing.
 181     For instance, vimsh doesn't support ANSI escape sequences yet so I unalias
 182     ls with color:
 183
 184         if ($?VIMSH) then
 185             unalias ls
 186         endif
 187
 188 :: vimsh help ::
 189
 190     Feel free to email me (bsturk@adelphia.net) with issues regarding
 191     vimsh or if you've found a bug etc.  Please read this file, the
 192     ChangeLog, and the TODO to see if I already know about the issue, or
 193     is a known limitation before contacting me.  If you do email me please
 194     include the output of :ver from vim, the version of python you have
 195     installed, what operating system you are running, and the output
 196     of running vimsh w/ _DEBUG_ set to 1 in vimsh.py in your email.
 197
 198 :: vimsh info ::
 199
 200     The latest version is always available @
 201          http://users.adelphia.net/~bsturk/vim.html
 202
 203     Please send bug reports, suggestions, and other email to
 204         bsturk@adelphia.net