:notebook_with_decorative_cover: The interactive scratchpad for hackers.
# codi.vim [![Gitter](https://badges.gitter.im/codi-vim/Lobby.svg)](https://gitter.im/codi-vim/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) <a href='https://ko-fi.com/V7V81YYAA' target='_blank'><img height='20' src='https://www.ko-fi.com/img/githubbutton_sm.svg' alt='Buy Me a Coffee at ko-fi.com' /></a>

The interactive scratchpad for hackers.

![Codi demo.](assets/codi.gif)

_Using Codi as a Python scratchpad through the
[shell wrapper](#shell-wrapper)_

![Codi expand demo.](assets/codi_expand.png)

_Using :CodiExpand on a javascript object_

Codi is an interactive scratchpad for hackers, with a similar interface to
[Numi](https://numi.io). It opens a pane synchronized to your main buffer
which displays the results of evaluating each line *as you type* (with NeoVim
or Vim with `+job` and `+channel`, asynchronously). It's extensible to nearly
any language that provides a REPL (interactive interpreter)!

Languages with built-in support:
Python, JavaScript, CoffeeScript, Haskell, PureScript, Ruby, OCaml, R,
Clojure/ClojureScript, PHP, Lua, C++, Julia, Elm, Elixir, TypeScript, Mathjs, Haxe

[Pull requests](https://github.com/metakirby5/codi.vim/pulls)
for new language support welcome!

*Note:* without async support, evaluation will trigger on cursor hold rather
than text change.

For more information, check out the [documentation](doc/codi.txt).

## Installation

Use your favorite package manager
([vim-plug](https://github.com/junegunn/vim-plug),
[Vundle](https://github.com/VundleVim/Vundle.vim),
[pathogen.vim](https://github.com/tpope/vim-pathogen)),
or add this directory to your Vim runtime path.

For example, if you're using vim-plug, add the following line to `~/.vimrc`:

```
Plug 'metakirby5/codi.vim'
```

### Dependencies

- OS X, Linux and limited Windows support
- Vim 7.4 (with `+job` and `+channel` for asynchronous evaluation) or
  NeoVim (still in its infancy - please report bugs!)
- `uname`
- If not using NeoVim, `script` (BSD or Linux, man page should say at least
  2013)

Each interpreter also depends on its REPL. These are loaded on-demand. For
example, if you only want to use the Python Codi interpreter, you will not
need `ghci`.

Default interpreter dependencies:

  - Python:       `python` (Note: Python 3 requires config - see `:h codi-configuration`)
  - JavaScript:   `node`
  - CoffeeScript: `coffee`
  - Haskell:      `ghci` (be really careful with lazy evaluation!)
  - PureScript    `pulp psci`
  - Ruby:         `irb`
  - OCaml:        `ocaml`
  - R:            `R`
  - Clojure:      `planck`
  - PHP:          `psysh`
  - Lua:          `lua`
  - C++:          `cling`
  - Julia:        `julia`
  - Elm:          `elm`
  - Elixir:       `iex`
  - TypeScript:   `tsun`
  - Mathjs:       `mathjs`
  - Haxe:         `ihx` (installed with `haxelib install ihx`)

## Usage

- `Codi [filetype]` activates Codi for the current buffer, using the provided
  filetype or the buffer's filetype.
- `Codi!` deactivates Codi for the current buffer.
- `Codi!! [filetype]` toggles Codi for the current buffer, using the provided
  filetype or the buffer's filetype.
- `CodiNew [filetype]` creates a new scratch buffer with Codi in it.
- `CodiSelect` opens a select menu and creates a new scratch buffer with the
  selected filetype and Codi in it. Only available on neovim.
- `CodiExpand` expands the output of the current line in a popup menu to
  display multi-line content. Only available on neovim.

### Shell wrapper

A nice way to use Codi is through a shell wrapper that you can stick in your
`~/.bashrc`:

```sh
# Codi
# Usage: codi [filetype] [filename]
codi() {
  local syntax="${1:-python}"
  shift
  vim -c \
    "let g:startify_disable_at_vimenter = 1 |\
    set bt=nofile ls=0 noru nonu nornu |\
    hi ColorColumn ctermbg=NONE |\
    hi VertSplit ctermbg=NONE |\
    hi NonText ctermfg=0 |\
    Codi $syntax" "$@"
}
```

### Options

- `g:codi#interpreters` is a list of user-defined interpreters.
  See the [documentation](doc/codi.txt) for more information.
- `g:codi#aliases` is a list of user-defined interpreter filetype aliases.
  See the [documentation](doc/codi.txt) for more information.

The below options can also be set on a per-interpreter basis via
`g:codi#interpreters`:

- `g:codi#autocmd` determines what autocommands trigger updates.
  See the [documentation](doc/codi.txt) for more information.
- `g:codi#width` is the width of the Codi split.
- `g:codi#rightsplit` is whether or not Codi spawns on the right side.
- `g:codi#rightalign` is whether or not to right-align the Codi buffer.
- `g:codi#autoclose` is whether or not to close Codi when the associated
  buffer is closed.
- `g:codi#raw` is whether or not to display interpreter results without
  alignment formatting (useful for debugging).
- `g:codi#sync` is whether or not to force synchronous execution. No reason to
  touch this unless you want to compare async to sync.

### Autocommands

- `CodiEnterPre`, `CodiEnterPost`: When a Codi pane enters.
- `CodiUpdatePre`, `CodiUpdatePost`: When a Codi pane updates.
- `CodiLeavePre`, `CodiLeavePost`: When a Codi pane leaves.

## FAQ

- _Why doesn't X work in Codi, when it works in a normal source file?_
  - Codi is not meant to be a replacement for actually running your program;
    it supports nothing more than what the underlying REPL supports. This is
    why Haskell language pragmas don't work and OCaml statements must end with
    `;;`.
- _Codi leaves a bunch of old processes running, what's going on?_
  - The cause of this issue is still unknown, but it happens infrequently. See
    `:h codi-introduction-warnings` for more information.
- _Codi doesn't seem to work on my setup._
  - Check `:h codi-introduction-gotchas`.

## Thanks to

- [@DanielFGray](https://github.com/DanielFGray) and
  [@purag](https://github.com/purag) for testing, feedback, and suggestions
- [@Joaquin-V](https://github.com/Joaquin-V) for helping me discover critical
  bugs with vanilla settings
- Everyone who has reported an issue or sent in a pull request :)
