Many editors have a feature allowing you to pipe some segment of the text in the editor through an external program, and replace the existing text with the results of that external program. To use zprint in this environment, you must then:
- Install zprint to format whole files
- Instruct your editor to send the text to zprint and use the result
See here for information on how to install zprint to format whole files.
In this case, the external program though which you will pipe the text will be zprint.
There are two aspects to using zprint effectively in your editing environment, and a third that can help:
-
How to move to the start of a function definition? [nice to have]
-
How to select the text to send to zprint? [required]
-
How to actually send the text to zprint? [required]
You may find one command that will do both #2 and #3 (see vim, below). But they might be separate commands or keystrokes that you might want to make a macro or user defined command in your editor.
In the discussions below, the name of the zprint program is zprint.
In this context, zprint will read Clojure source from stdin, and produce
formatted Clojure source on stdout.
There is a vim plugin to run zprint when you close a file.
If you want to format individual definitions while running vim, make sure that you install zprint to format entire files.
In vim, if your cursor is at the top level left parenthesis of a
function definition, you can type !a(zprint.
This will pipe everything to the balanced
right parenthesis through zprint, formatting the entire function.
There are other ways to mark all of the text between parentheses in vim.
You can also pass an options map to zprint, though
you have to enclose it in single quotes. For instance, you
could type this: !a(zprint '{:width 90}' and have
zprint format the result for 90 columns instead of the default 80.
There is an emacs plugin for zprint.
First, see here for information on how to install zprint to format whole files.
Emacs seems to have several ways to move to the top of a function definition and to then mark a region bounded by parentheses, and your personal configuration may have even more. I'll leave it to you to find the best way to do that in your environment.
To pipe a region through a filter and replace the region with the
returned text use C-u M-| zprint RET.
Of course you don't have to limit what you send to just the characters
of a function definition. You can send multiple function defintions,
or you can include ;!zprint {...} formatting directives. You can
even send a whole buffer through the filter. What you cannot do is send
an unbalanced set of delimiters (parentheses, braces, brackets) through
the filter. If you do, it will return an error and the unmodified original
text.
In Sublime Text, you can use the External Command plugin to send either the entire file or your current selection to this executable.
Once you've installed External Command (manually or via Package
Control), place the following in your
sublime-keymap file (where we assume zprint is the name of the program
which runs zprint, and KYBRD SHORTCUT is what you want to use
to do this operation when editing):
{ "keys": ["KYBRD SHORTCUT"], "command": "filter_through_command", "args": { "cmdline": "zprint" } }
At this point, you can use your keyboard shortcut to send the entire file to your executable.
If you have selected text, it will send your current selection to
the executable and replace only that selection with the output. You
can also use Selection > Expand Selection to Brackets (defaults
to Ctrl-Shift-m) to select between parentheses and repeat it once
to include the parentheses themseleves. If you are deep within a
function, you may need to repeat it several times to get to the
top level. There may be other ways to get to the top level.
The atom editor has a zprint plugin.
I would suggest that you check the documentation for your editor or
IDE for how to send text to the fmt filter, as the answer to that
will tell you how to send text to zprint, which acts similarly to fmt,
though of course operating to format Clojure source instead of word wrapping
text (which is what fmt does).
You then want to figure out how to send all of the items between balanced parentheses to an external program.
Then put these together.
If you get this to work in an editor not yet listed here, please file an issue and tell me how to you did it, and I'll update the instructions here. Even better would be to create a pull request for this file with detailed instructions!