/yi

The Haskell-Scriptable Editor

Primary LanguageHaskellGNU General Public License v2.0GPL-2.0

Yi

Travis Hackage Hackage-Deps

Yi is a collection of packages that serve as building blocks for making your very own text editor.

Installation

Just running stack install yi or cabal install -j yi would be akin to unwrapping a box of lego and finding an assembled spaceship there. Note that this way, it will not be possible to use a custom configuration.

In order to have a personalized configuration, it is necessary to use Yi as libraries to create your own text editor.

A good starting point is choosing an example configuration of your liking in the example-configs directory, building it, running it, and tinkering with it.

Static vs dynamic

Yi used to have a dynamic configuration (à la Xmonad). So each time after the configuration was changed, Yi needed recompilation before starting.

Now, it's recommended to use a static configuration which makes it possible to distribute binaries without the entire Haskell ecosystem.

Dynamic configuration is still available using a separate package.

See this article for more detailed explanations about static and dynamic configuration.

Static example configurations

The static example configurations don't need to be placed in any specific directory (but you can still use ~/.config/yi).

  1. Copy the example configuration (only the contents of the folder) to your yi folder.
  2. Install the configuration (with stack install or cabal install). Make sure the folder where stack (or cabal) installs executables is on your PATH.
  3. Run Yi with the command found in the package.yaml file under the executables line (i.e. yi-vty-emacs for the emacs config). You can also change the executable name here.

Dynamic example configurations

You can install this just like the static configuration. Make sure to copy the example configuration in the ~/.config/yi folder. After step 3, you should be able to just use the yi command to launch Yi. If you change your configuration file Yi automatically detects your changes and rebuilds itself.

See this documentation page for more detailed installation instructions. Hacking instructions if you're using the nix package manager are also there.

Configuration

Yi, as a library, can be categorized into four parts :

  • Frontends are responsible for rendering the editor state and passing user events to the core ;

  • Actions describe how to interact with the editor, and it's the part that makes most of Yi. It is structured around a stack of three monadic DSLs:

    • BufferM for all buffer-local operations, like insertion, deletion of text, and annotation of buffer contents. It can be understood as a monad that encapsulates the state of one buffer.
    • EditorM for editor-level operations, e.g., opening and closing windows and buffers. Operations involving more than one buffer are handled at this level too.
    • YiM for IO-level operations. There, one can operate on files, processes, etc. This is the only level where IO can be performed.

  • Keymaps represent how to trigger actions, they serve as the basis to use or to create the ones you need;

  • Glue code, how the three other parts are shaped together.

External configuration examples

Some people share their Yi configurations here on github.

Documentation

Please visit the Yi website.

Reporting bugs and feature requests

Please report issues (including documentation ones) on GitHub.

Mailing List

Our mailing list is yi-devel, hosted at Google Groups. Please ask us questions on this list! All development discussion occurs on this list.

IM channels

IRC: #yi@Freenode Please note that it is rather slow (very slow compared to #haskell), so be prepared to stay for longer than 5 minutes.

Matrix: #yi:matrix.org

How to support developers

Reading material

There are some papers which might interest you.