mirror of
https://github.com/ascii-boxes/boxes.git
synced 2025-03-03 08:41:23 +01:00
267 lines
12 KiB
HTML
267 lines
12 KiB
HTML
---
|
|
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"> </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"> </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"> </a>
|
|
|
|
|
|
## Integration with Sublime
|
|
|
|
[Marco Andreolli](https://github.com/drazde) found a way to integrate *boxes* with Sublime Text 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 → Command Palette...* from the main menu and select *Package Control: Install Package*, then
|
|
choose [FilterPipes](https://packagecontrol.io/packages/FilterPipes).
|
|
1. Choose *Tools → 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 3\​Packages\​MyCustomFilterPipes\​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"> </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 → Plugin Manager → 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 → NppExec → 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 → NppExec → 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 → 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! |
|
|
|______________________________________________________________________________|
|