---
layout: markdown
title: Editor Integration
---

# Text Editor Integration

This section assumes you already have a working binary of *boxes*. Binaries for some platforms can be obtained through
the [download page]({{ site.baseurl}}/download.html). Should your platform be missing from the list, you can still
download the source distribution and compile your own binary. This sounds harder than it is.

Although *boxes* can be useful when used on the command line, the more frequent use case will be as a filter tied to
your editor. So, how can *boxes* be tied to your editor?

Example config file entries are featured so far for [Vim](https://www.vim.org/), [Jed](https://www.jedsoft.org/jed/),
[Emacs](https://www.gnu.org/software/emacs/), [Sublime Text](https://www.sublimetext.com/), and
[NotePad++](https://notepad-plus-plus.org/). If you know how to to this in other editors, please feel free to add that
information to this page via GitHub or just let me know in the GitHub issues.


## Integration with Vim

To call filters from vim, you need to press `!` in visual mode or `!!` in normal mode. So the easiest way to tie in
*boxes* with vim is by adding the following four lines to your *.vimrc*:

    vmap ,mc !boxes -d c-cmt<CR>
    nmap ,mc !!boxes -d c-cmt<CR>
    vmap ,xc !boxes -d c-cmt -r<CR>
    nmap ,xc !!boxes -d c-cmt -r<CR>

`<CR>` should be there literally; just paste the lines directly from your browser window. This would comment out the
current line or the lines you have marked when you press `,mc` (for *make comment*). Comments can be removed in the
same way by pressing `,xc`. Should you feel that `,mc` is too long a combination to type, feel free to choose a shorter
one. The above example assumes you are using the standard boxes config file, which features the *c-cmt* design. Of
course, the same technique works for any other designs.

While the above example is nice, it does not offer much convenience when you are editing different languages a lot,
because you need to remember the hotkey for each different box design. Fortunately, vim has a feature called
*autocommands*. They can be used to automatically change the meaning of a key combination depending on what file you
edit (any many other things too, of course). Autocommand syntax is

    au[tocmd] [group] {event} {pat} [nested] {cmd}

We can leave out the group. For `{event}`, we choose `BufEnter`, which is generated every time you enter a new buffer,
e.g. when starting vim or when switching between open files. `{pat}` is a file glob, and `{cmd}` is our call to *boxes*.

The lines below are from the author's *.vimrc*. They can be pasted directly from your browser window. Their effect is
that `,mc` and `,xc` always generate the correct comments for many languages, including C, C++, HTML, Java, lex, yacc,
shell scripts, Perl, etc. The default key binding is to generate shell comments using a pound sign (file glob of `*` at
the start).

    autocmd BufEnter * nmap ,mc !!boxes -d pound-cmt<CR>
    autocmd BufEnter * vmap ,mc !boxes -d pound-cmt<CR>
    autocmd BufEnter * nmap ,xc !!boxes -d pound-cmt -r<CR>
    autocmd BufEnter * vmap ,xc !boxes -d pound-cmt -r<CR>
    autocmd BufEnter *.html nmap ,mc !!boxes -d html-cmt<CR>
    autocmd BufEnter *.html vmap ,mc !boxes -d html-cmt<CR>
    autocmd BufEnter *.html nmap ,xc !!boxes -d html-cmt -r<CR>
    autocmd BufEnter *.html vmap ,xc !boxes -d html-cmt -r<CR>
    autocmd BufEnter *.[chly],*.[pc]c nmap ,mc !!boxes -d c-cmt<CR>
    autocmd BufEnter *.[chly],*.[pc]c vmap ,mc !boxes -d c-cmt<CR>
    autocmd BufEnter *.[chly],*.[pc]c nmap ,xc !!boxes -d c-cmt -r<CR>
    autocmd BufEnter *.[chly],*.[pc]c vmap ,xc !boxes -d c-cmt -r<CR>
    autocmd BufEnter *.C,*.cpp,*.java nmap ,mc !!boxes -d java-cmt<CR>
    autocmd BufEnter *.C,*.cpp,*.java vmap ,mc !boxes -d java-cmt<CR>
    autocmd BufEnter *.C,*.cpp,*.java nmap ,xc !!boxes -d java-cmt -r<CR>
    autocmd BufEnter *.C,*.cpp,*.java vmap ,xc !boxes -d java-cmt -r<CR>
    autocmd BufEnter .vimrc*,.exrc nmap ,mc !!boxes -d vim-cmt<CR>
    autocmd BufEnter .vimrc*,.exrc vmap ,mc !boxes -d vim-cmt<CR>
    autocmd BufEnter .vimrc*,.exrc nmap ,xc !!boxes -d vim-cmt -r<CR>
    autocmd BufEnter .vimrc*,.exrc vmap ,xc !boxes -d vim-cmt -r<CR>

**Syntax Highlighting in Vim**

There is a [Vim syntax file](https://raw.githubusercontent.com/{{ site.github }}/master/boxes.vim) for *boxes*
configuration files, which you can install to have the *boxes* config colorized. On Windows, the file must be placed
in the directory *VIM_INSTALL_DIR\vimfiles\syntax*.  
Activate by `set syn=boxes`.


<a name="jed">&nbsp;</a>

## Integration with Jed

[Andreas Heiduk](https://github.com/asheiduk) kindly provided the following excerpt from his *.jedrc*:

    %!% Ripped from "pipe.sl"
    
    variable Last_Process_Command = Null_String;
    
    define do_process_region(cmd) {
       variable tmp;
       tmp = make_tmp_file ("/tmp/jedpipe");
       cmd = strncat (cmd, " > ", tmp, " 2>&1", 4);
    
       !if (dupmark ()) error ("Mark not set.");
    
       if (pipe_region (cmd))
       {
          error ("Process returned a non-zero exit status.");
       }
       del_region ();
       () = insert_file (tmp);
       () = delete_file (tmp);
    }
    
    
    define process_region ()
    {
       variable cmd;
       cmd = read_mini ("Pipe to command:", Last_Process_Command, "");
       !if (strlen (cmd)) return;
    
       Last_Process_Command = cmd;
       do_process_region(cmd);
    }
    
    
    %-----------------------------------------------------------------------
    
    if( BATCH == 0 ){
    
       setkey("process_region",	"\e|");		% ESC-Pipe :-)
       add_completion("process_region");
       
       % define some often used filters
       setkey("do_process_region(\"tal\")",	"\et")	% tal on esc-t
    }

I think it calls [tal](https://thomasjensen.com/software/tal/) when you press `ESC-t` (second but last line). Thus,
you would have to add a similar line to call *boxes*.
<a name="emacs">&nbsp;</a>


## Integration with Emacs

[Jason L. Shiffer](https://github.com/zerotao) kindly submitted the following information on integrating *boxes* with
Emacs:

The simple interface (only a single box style, but easy):

    (defun boxes-create ()
        (interactive)
        (shell-command-on-region (region-beginning) (region-end) "boxes -d c-cmt2" nil 1 nil))
    
    (defun boxes-remove ()
        (interactive)
        (shell-command-on-region (region-beginning) (region-end) "boxes -r -d c-cmt2" nil 1 nil))

Jason also wrote a [*boxes* mode for Emacs](boxes.el). Remember to update its design list when you add new designs to
your config file.
<a name="sublime">&nbsp;</a>


## Integration with Sublime

[Marco Andreolli](https://github.com/drazde) found a way to integrate *boxes* with Sublime Text&nbsp;3
(from [#47](https://github.com/{{ site.github }}/issues/47)):

1. Open Sublime Text 3
1. Install [Package Control](https://packagecontrol.io/installation) and restart Sublime.
1. Choose *Tools &rarr; Command Palette...* from the main menu and select *Package Control: Install Package*, then
   choose [FilterPipes](https://packagecontrol.io/packages/FilterPipes).
1. Choose *Tools &rarr; Command Palette...* from the main menu and select *FilterPipes: My Custom Filters Plugin*
1. In the following file open dialog, open
   <code class="highlighter-rouge">%APPDATA%\Sublime Text&nbsp;3\&#8203;Packages\&#8203;MyCustomFilterPipes\&#8203;Default.sublime-commands</code>.
   This is the default on Windows, but if you are on other operating systems, the dialog should already be open
   in the correct folder.
1. Before the closing `]`, add the following:
   ```
   {   /* Boxes stone */
       "caption": "FilterPipes: Boxes stone",
       "command": "filter_pipes_process",
       "args": {
           "command": ["boxes", "-d", "stone", "-a", "c", "-s", "80"]
       }
   }
   ```
   Be sure to add a comma after the previous entry, so that the list is continued properly.
1. Now you have a new command *Boxes stone* which will create a *stone* styled box of 80 characters in width around
   the selected text. In may be accessed via the command palette like above, or you might want to define a hotkey or
   a macro to do it.
1. Add more FilterPipes commands for other designs, or for removing and repairing your ASCII art boxes.

<a name="notepadplusplus">&nbsp;</a>


## Integration with Notepad++

In order to integrate *boxes* with Notepad++, first make sure that *boxes* is on your `PATH`. On Windows, this usually
means boxes.exe and boxes.cfg must be located in a directory which is on the `PATH` environment variable. This method
of *boxes* integration works only on Windows, because afaik, Notepad++ is available only on Windows.

We use the NppExec plugin. Install NppExec via PluginManager:

1. Display PluginManager via the main menu: *Plugin &rarr; Plugin Manager &rarr; Show Plugin Manager*
1. If NppExec is not on the *Installed* tab already, go to the *Available* tab and select NppExec from the list.
1. Press **Install**.
1. Restart Notepad++

   <div class="bxLargeImageWrapper">
   <img src="{{ site.baseurl }}/images/editor-npp-pluginmanager.png" alt="Plugin Manager" width="670" height="493" />
   </div>

Once the NppExec plugin is available, proceed with *boxes* integration:

1. Go to *Plugins &rarr; NppExec &rarr; Execute ...*
1. Paste the following script into the text area:

   <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>NPP_CONSOLE 0  
cls
cmd.exe /c exit %RANDOM%
set tempfile = $(SYS.TEMP)\NppBoxes_$(EXITCODE).out.txt
set ascfile = $(SYS.TEMP)\NppBoxes_$(EXITCODE).in.txt
sel_saveto $(ascfile) :a
cmd.exe /c <span class="mark-hilite">boxes -d nuke -s 80 -pt1 -ac</span> "$(ascfile)" > "$(tempfile)"
sel_loadfrom $(tempfile)
cmd.exe /c del /f /q "$(tempfile)" "$(ascfile)"</code></pre></div></div>

   This script is inspired by a [post by Peter Jones](https://notepad-plus-plus.org/community/topic/16158/2) on the
   Notepad++ forum. It works via temp files in ANSI format. (That's the `:a` argument to the `sel_saveto` command.)
   This is compatible with boxes, and also helps avoiding byte order marks at the beginning of the temp file.  
   The <span class="mark-hilite">green part</span> marks the place where you configure the box. In this case, we'll
   get a *nuke* box 80 characters wide, with the text centered in it and an extra blank line at the top.
1. Press **Save...** and give it a meaningful name, for example `boxes nuke 80`.
1. Press **Save** on the *Script name* input box.

   <div class="bxLargeImageWrapper">
   <img src="{{ site.baseurl }}/images/editor-npp-script.png" alt="NppExec Script" width="472" height="277" />
   </div>

1. Go to *Plugins &rarr; NppExec &rarr; Advanced Options ...*
1. In the *Associated Script* dropdown, select the `boxes nuke 80` script entry created previously, then press
   **Add/Modify** to add it to the list of *Menu items*.
1. Optionally select *Place to the Macros submenu*, if you want an entry for this in the *Macros* menu.
1. Press **OK**, and if asked, restart Notepad++.

   <div class="bxLargeImageWrapper">
   <img src="{{ site.baseurl }}/images/editor-npp-options.png" alt="NppExec Advanced Options" width="530" height="511" />
   </div>

1. Go to *Macro &rarr; Modify Shortcut/Delete Macro...* to call up the Shortcut mapper.
1. Select the *Plugin commands* tab, and type `boxes` into the filter line at the bottom of the dialog window.
1. Choose our `boxes nuke 80` entry and press **Modify**:

   <div class="bxLargeImageWrapper">
   <img src="{{ site.baseurl }}/images/editor-npp-shortcut.png" alt="Shortcut mapper" width="677" height="290" />
   </div>

1. Assign a shortcut key, for example Ctrl+Shift+B.
1. Make sure that the Shortcut mapper reports `No shortcut conflicts for this item` in the status area.

That's it, finally! Now you can select any piece of text in the Notepad++ editor and draw the `nuke 80` box around it
by pressing your assigned shortcut:

                                      _ ._  _ , _ ._
                                    (_ ' ( `  )_  .__)
                                  ( (  (    )   `)  ) _)
                                 (__ (_   (_ . _) _) ,__)
                                     `~~`\ ' . /`~~`
                                     ,::: ;   ; :::,
                                    ':::::::::::::::'
     ___________________________jgs______/_ __ \___________________________________
    |                                                                              |
    |                                LOOK AT THAT!                                 |
    |______________________________________________________________________________|