• 1. Installation
• 1.1 Requirements for Unix
• 1.2 Requirements for Windows
• 1.3 Installation
• 2. Usage
• 2.1 General Usage
• 2.2 Special keys
• 2.3 Registering functions
• 3. Options
• 3.1 General
• 3.2 Keyboard
• 3.3 Unix
• 3.4 Windows
• 4. API (Beta)
• 4.1 conque_term#open(command, [buf_opts], [remain])
• 4.2 conque_term#subprocess(command)
• 4.3 conque_term#get_instance( [terminal_number] )
• 4.4 CONQUE_OBJECT.write(text)
• 4.5 CONQUE_OBJECT.writeln(text)
• 4.6 CONQUE_OBJECT.read( [timeout], [update_buffer] )
• 4.7 CONQUE_OBJECT.set_callback( funcname )
• 4.8 CONQUE_OBJECT.close()
• 4.9 Registering functions
• 5. Misc
• 5.1 Known bugs
• 5.2 Contribute
• 5.3 Feedback

1. Installation

Conque is designed for both Unix and Windows operating systems, however the requirements are slightly different. Please check section below corresponding to your installed OS.

1.1 Requirements for Unix

• GVim 7.0+ with +python and/or +python3
• Python 2.3+ and/or 3.x
• Unix-like OS: Linux, OS X, Solaris, Cygwin, etc

The most common stumbling block is getting a version of Vim which has the python interface enabled. Most all software package managers will have a copy of Vim with Python support, so that is often the easiest way to get it. If you're compiling Vim from source, be sure to use the --enable-pythoninterp option, or --enable-python3interp for Python 3. On OS X the best option is MacVim, which installs with Python support by default.

1.2 Requirements for Windows

• GVim 7.3 with +python and/or +python3
• Python 2.7 and/or 3.1
• Modern Windows OS (XP or later)

Conque only officially supports the latest GVim 7.3 Windows installer available at www.vim.org. If you are currently using Vim 7.2 or earlier you will need to upgrade to 7.3 for Windows support. The Windows installer already has the +python/+python3 interface built in.

The official 7.3 release of Vim for Windows only works with Python versions 2.7 and/or 3.1. You can download and install Python from their website http://www.python.org/download

If you are compiling Vim + Python from source on Windows, the requirements become only Vim 7.3+ and Python 2.7+.

1.3 Installation

Download the latest vimball from http://conque.googlecode.com

Open the .vba file with Vim and run the following commands:

    :so %
    :q

That's it! The :ConqueTerm command will be available the next time you start Vim. You can delete the .vba file when you've verified Conque was successfully installed.

2. Usage

2.1 General Usage

Type :ConqueTerm <command> to launch an application in the current buffer. Eg:

    :ConqueTerm bash
    :ConqueTerm mysql -h localhost -u joe_lunchbox Menu
    :ConqueTerm Powershell.exe

Use :ConqueTermSplit or :ConqueTermVSplit to open Conque in a new horizontal or vertical buffer. Use :ConqueTermTab to open Conque in a new tab.

In insert mode you can interact with the shell as you would expect in a normal terminal. All key presses will be sent to the terminal, including control characters. See |conque-term-special-keys| for more information, particularly regarding the <Esc> key.

In normal mode you can use Vim commands to browse your terminal output and scroll back through the history. Most all Vim functionality will work, such as searching, yanking or highlighting text.

2.2 Special keys

There are several keys which can be configured to have special behavior with Conque.

2.2.1 Send text to Conque

Conque gives you three different commands to send text from a different buffer, probably a source code file, to the Conque terminal buffer. All three are configurable to use your choice of key combinations.

To send a visually selected range of text to an existing terminal buffer, press the <F9> key.

To send the entire contents of the file you are editing to an existing terminal buffer, press the <F10> key.

Finally, to execute the current file in a new terminal buffer press the <F11> key. This will split the screen with a new Conque buffer. The file you are editing must be executable for this command to work.

See |conque-term-options| for information about configuring these commands.

2.2.2 Toggle terminal input mode

If you want to use insert mode to edit the terminal screen, press <F8>. You will now be able to edit the terminal output freely without your cursor jumping the the active prompt line. This may be useful if you want to reformat terminal output for readability.

While the terminal is paused new output will not be displayed on the screen until you press <F8> again to resume.

You can configure Conque to use a different key with the |ConqueTerm_ToggleKey| option.

2.2.3 Sending the <Esc> key press

By default if you press the <Esc> key in a Conque buffer you will leave insert mode. But what if you want the <Esc> character to be sent to your terminal? There are two options. By default, pressing <Esc> twice will send one <Esc> character to the terminal and you will remain in insert mode, while pressing it once will leave insert mode.

Alternatively you can use the |ConqueTerm_EscKey| option to choose a different key for leaving insert mode. If a custom key is set, then all <Esc> key presses will be sent to the terminal.

2.3 Registering functions

Conque allows you to write your own VimScript functions which will be called at certain events. See the API section |conque-term-events| for more.

3. Options

You can set the following options in your .vimrc (default values shown)

3.1 General

3.1.1 Python version

Conque will work with either Python 2.x or 3.x, assuming the interfaces have been installed. By default it will try to use Python 2 first, then will try Python 3. If you want Conque to use Python 3, set this variable to 3.

Note: even if you set this to 3, if you don't have the python3 interface Conque will fall back to using Python 2.

    let g:ConqueTerm_PyVersion = 2

3.1.2 Fast Mode

Disable features which could make Conque run slowly. This includes most terminal colors and some unicode support. Set this to 1 to enable fast mode.

      let g:ConqueTerm_FastMode = 0

3.1.3 Color support

Terminal colors have the potential to slow down terminal screen rendering, depending on how many colors are used and how fast the computer is. This option allows you to choose how much color support will be enabled.

If set to 0, terminal colors will be disabled. This will allow the terminal to render most quickly. Syntax highlighting will still work. For example highlighting quoted strings or MySQL output.

If set to 1, terminal colors will be enabled, but only for the most recent 200 lines of terminal output. Older output will be periodically stripped of color highlighting to keep the display responsive.

If set to 2, terminal colors will always be enabled. If your programs don't use color output very frequently this is a good choice.

Note: Color support is automatically disabled in "fast mode".

    let g:ConqueTerm_Color = 1

3.1.4 Session Support

Vim's :mksession command allows you to save your current buffer configuration to a file, which can be loaded at a later time after you've closed Vim.

By default, Conque buffers are not restored. This is mostly for safety reasons; you may not want Vim to automatically re-run a destructive command.

However, if you're not working with missile launch code, and want Vim to restart your Conque buffers when you load a session file, set this variable to 1. Note your original subprocess and shell output will not be restored, but the same command will be started in your buffer.

    let g:ConqueTerm_SessionSupport = 0

3.1.5 Keep updating terminal buffer

If set to 1 then your Conque buffers will continue to update after you've switched to another buffer.

Note: Conque buffers may continue to update, but they will not scroll down as new lines are added beyond the bottom of the visible buffer area. This is a limitation of the Vim scripting language for which I haven't found a workaround.

    let g:ConqueTerm_ReadUnfocused = 1

3.1.6 Insert mode when entering buffer

If set to 1 then you will automatically go into insert mode when you enter the buffer. This diverges from normal Vim behavior. If 0 you will still be in normal mode.

    let g:ConqueTerm_InsertOnEnter = 0

3.1.7 Close buffer when program exits

If you want your terminal buffer to be closed and permanently deleted when the program running inside of it exits, set this option to 1. Otherwise the buffer will become a simple text buffer after the program exits, and you can edit the program output in insert mode.

    let g:ConqueTerm_CloseOnEnd = 0

3.1.8 Hide start messages

Unused. Startup messages are always hidden.

    let g:ConqueTerm_StartMessages = 0

3.1.9 Regex for highlighting your prompt

Use this regular expression for sytax highlighting your terminal prompt. Your terminal will generally run faster if you use Vim highlighting instead of terminal colors for your prompt. You can also use it to do more advanced syntax highlighting for the prompt line.

    let g:ConqueTerm_PromptRegex = '^\w\+@[0-9A-Za-z_.-]\+:[0-9A-Za-z_./\~,:-]\+\$'

3.1.10 Choose Vim syntax type

Set the buffer syntax. The default 'conque' has highlighting for MySQL, but not much else.

    let g:ConqueTerm_Syntax = 'conque'

3.2 Keyboard

3.2.1 The <Esc> key

If a custom key is set, then all <Esc> key presses will be sent to the terminal and you must use this custom key to leave insert mode. If left to the default value of '<Esc>' then you must press it twice to send the escape character to the terminal, while pressing it once will leave insert mode.

Note: You cannot use a key which is internally coded with the escape character. This includes the <F-> keys and often the <A-> and <M-> keys. Picking a control key, such as <C-k> will be your best bet.

    let g:ConqueTerm_EscKey = '<Esc>'

3.2.2 Toggle terminal input mode

Press this key to pause terminal input and output display. You will then be able to edit the terminal screen as if it were a normal text buffer. Press this key again to resume terminal mode.

    let g:ConqueTerm_ToggleKey = '<F8>'

3.2.3 Enable <C-w> in insert mode

If set to 1 then you can leave the Conque buffer using the <C-w> commands while you're still in insert mode. If set to 0 then the <C-w> character will be sent to the terminal. If both this option and ConqueTerm_InsertOnEnter are set you can go in and out of the terminal buffer while never leaving insert mode.

    let g:ConqueTerm_CWInsert = 0

3.2.4 Execute current file in Conque

Press this key to execute the file you're currently editing in a Conque buffer. Is equivelent to running the command :ConqueTermSplit YOUR_FILE. Your file must be executable for this command to work correctly.

    let g:ConqueTerm_ExecFileKey = '<F11>'

3.2.5 Send current file contents to Conque

Press this key to send your entire file contents to the most recently opened Conque buffer as keyboard input.

    let g:ConqueTerm_SendFileKey = '<F10>'

3.2.6 Send selected text to Conque

Use this key to send the currently selected text to the most recently created Conque buffer.

    let g:ConqueTerm_SendVisKey = '<F9>'

3.2.7 Function Keys

By default, function keys (the F1-F12 row at the top of your keyboard) are not passed to the terminal. Set this option to 1 to send these key events.

Note: Unless you configured |ConqueTerm_SendVisKey| and |ConqueTerm_ToggleKey| to use different keys, <F8> and <F9> will not be sent to the terminal even if you set this option to 1.

    let g:ConqueTerm_SendFunctionKeys = 0

3.3 Unix

3.3.1 Choose your terminal type, Unix ONLY

Use this option to tell Conque what type of terminal it should identify itself as. Conque officially uses the more limited VT100 terminal type for developement and testing, although it supports some more advanced features such as colors and title strings.

You can change this setting to a more advanced type, namely 'xterm', but your results may vary depending on which programs you're running.

    let g:ConqueTerm_TERM = 'vt100'

3.4 Windows

3.4.1 Python executable, Windows ONLY

The Windows version of Conque needs to know the path to the python.exe executable for the version of Python Conque is using. If you installed Python in the default location, or added the Python directory to your system path, Conque should be able to find python.exe without you changing this variable.

For example, you might set this to 'C:\Program Files\Python27\python.exe'

    let g:ConqueTerm_PyExe = ''

3.4.2 Windows character code page

Set the "code page" Windows will use for your console. Leave this value set to zero to use the environment code page.

Note: Displaying unicode characters on Conque for Windows needs work.

      let g:ConqueTerm_CodePage = 0

3.4.3 Terminal color method, Windows ONLY

Vim syntax highlighting by coordinate (e.g. the 3-7th characters on the 42nd line) can be very slow. If you set this variable to 'conceal', you can use the new conceal feature to render terminal colors. Requires Vim 7.3 and only works on the Windows version of Conque. This will make colors render faster, however it will also add hidden characters to the screen, which may be annoying if you're copying and pasting terminal output out of the Conque buffer. Set this to an empty string '' to disable concealed highlighting.

    let g:ConqueTerm_ColorMode = 'conceal'

4. VimScript API (Beta)

The Conque scripting API allows you to create and interact with Conque terminals with the VimScript language. This API is still in beta stage.

4.1 conque_term#open(command, [buf_opts], [remain])

The open() function will create a new terminal buffer and start your command.

The command must be an executable, either an absolute path or relative to your system path.

You can pass in a list of vim commands buf_opts which will be executed after the new buffer is created but before the command is started. These are typically commands to alter the size, position or configuration of the buffer window.

Note: If you don't pass in a command such as 'split', the terminal will open in the current buffer.

If you don't want the new terminal buffer to become the new active buffer, set remain to 1. Only works if you create a split screen using options.

Returns a Conque terminal object.

Examples:

    let my_terminal = conque_term#open('/bin/bash')
    let my_terminal = conque_term#open('ipython', ['split', 'resize 20'], 1)

4.2 conque_term#subprocess(command)

Starts a new subprocess with your command, but no terminal buffer is ever created. This may be useful if you need asynchronous interaction with a subprocess, but want to handle the output on your own.

Returns a Conque terminal object.

Example:

    let my_subprocess = conque_term#subprocess('tail -f /var/log/foo.log')

4.3 conque_term#get_instance( [terminal_number] )

Use the get_instance() function to retrieve an existing terminal object. The terminal could have been created either with the user command :ConqueTerm or with an API call to conque_term#open() or subprocess().

Use the optional terminal_number to retrieve a specific terminal instance. Otherwise if the current buffer is a Conque terminal, it will be returned, else the most recently created terminal. The terminal number is what you see at the end of a terminal buffer name, e.g. "bash - 2".

Returns a Conque terminal object.

Example:

    nnoremap <F4> :call conque_term#get_instance().writeln('clear')<CR>

4.4 CONQUE_OBJECT.write(text)

Once you have a terminal object from open(), subprocess() or get_instance() you can send text input to it with the write() method.

No return value.

Examples:

    call my_terminal.write("whoami\n")
    call my_terminal.write("\<C-c>")

4.5 CONQUE_OBJECT.writeln(text)

The same as write() except adds a \r character to the end if your input.

Examples:

    call my_subprocess.writeln('make')

4.6 CONQUE_OBJECT.read( [timeout], [update_buffer] )

Read new output from a Conque terminal subprocess. New output will be returned as a string, and the terminal buffer will also be updated by default.

If you are reading immediately after calling the write() method, you may want to wait timeout milliseconds for output to be ready.

If you want to prevent the output from being displayed in the terminal buffer, set update_buffer to 0. This option has no effect if the terminal was created with the subprocess() function, since there never is a buffer to update.

Returns output string.

Note: The terminal buffer will not automatically scroll down if the new output extends beyond the bottom of the visible buffer. Vim doesn't allow "unfocused" buffers to be scrolled at the current version, although hopefully this will change.

Examples:

    call my_terminal.writeln('whoami')
    let output = my_terminal.read(500)
    call my_terminal.writeln('ls -lha')
    let output = my_terminal.read(1000, 1)

4.7 CONQUE_OBJECT.set_callback( funcname )

Register a callback function for this subprocess instance. This function will automatically be called whenever new output is available. Only practical with subprocess() objects.

Conque checkes for new subprocess output once a second when Vim is idle. If new output is found your function will be called.

Pass in the callback function name funcname as a string.

No return value.

Note: this method requires the g:ConqueTerm_ReadUnfocused option to be set.

Note: this method is experimental, results may vary.

Example:

    let sp = conque_term#subprocess('tail -f /home/joe/log/error_log')

    function! MyErrorAlert(output)
        echo a:output
    endfunction

    call sp.set_callback('MyErrorAlert')

4.8 CONQUE_OBJECT.close()

Kill your terminal subprocess. Sends the ABORT signal. You probably want to close your subprocess in a more graceful manner with the write() method, but this can be used when needed. Does not close the terminal buffer, if it exists.

This method will be called on all existing Conque subprocesses when Vim exits.

Example:

    let term = conque_term#open('ping google.com', ['belowright split'])
    call term.read(5000)
    call term.close()

4.9 Registering functions

Conque provides the option to register callback functions which will be executed at several different events. The currently available events are:

• after_startup - After your application has loaded into the buffer.
• buffer_enter - When you switch to a Conque buffer.
• buffer_leave - When you leave a Conque buffer.

You may use the function conque_term#register_function(event, function_name) to add additional hooks at a particular event. The second argument should be the name of a callback function which has one parameter, the current terminal object (see|conque-term-api|for more about terminal objects).

For example:

  function MyConqueStartup(term)

      " set buffer syntax using the name of the program currently running
      let syntax_associations = { 'ipython': 'python', 'irb': 'ruby' }

      if has_key(syntax_associations, a:term.program_name)
          execute 'setlocal syntax=' . syntax_associations[a:term.program_name]
      else
          execute 'setlocal syntax=' . a:term.program_name
      endif

      " shrink window height to 10 rows
      resize 10

      " silly example of terminal api usage
      if a:term.program_name == 'bash'
          call a:term.writeln('svn up ~/projects/*')
      endif
      
  endfunction

  call conque_term#register_function('after_startup', 'MyConqueStartup')

5. Misc

5.1 Known bugs

The following are known limitations:

- Font/color highlighting is imperfect and slow. If you don't care about

color in your shell, set g:ConqueTerm_Color = 0 in your .vimrc

- Conque only supports the extended ASCII character set for input, not utf-8. - VT100 escape sequence support is not complete. - Alt/Meta key support in Vim isn't great in general, and conque is no

exception. Pressing <Esc><Esc>x or <Esc><M-x> instead of <M-x> works in most cases.

5.2 Contribute

The two contributions most in need are improvements to Vim itself. I currently use hacks to capture key press input from the user, and to poll the terminal for more output. The Vim todo.txt document lists proposed improvements to give users this behavior without hacks. Having a key press event should allow Conque to work with multi- byte input. If you are a Vim developer, please consider prioritizing these two items:

- todo.txt (Autocommands, line ~3137)

8 Add an event like CursorHold that is triggered repeatedly, not just

once after typing something.

5.3 Feedback

Bugs, suggestions and patches are all welcome.

For more information visit http://conque.googlecode.com

Check out the latest from svn at http://conque.googlecode.com/svn/trunk/

vim:tw=78:ts=8:ft=help:norl: