File Comment API

In order to properly format a file, sometimes you want to alter the value of the zprint options map for a single function definition, or turn it off completely and then on again later. Or, possibly, set some defaults which hold while formatting only this file.

While the defaults that you have established with your ~/.zprintrc file may be perfectly appropriate for the vast majority of the functions and data given in a file, there are frequently one or two functions which would benefit from a different formatting configuration.

Trying to find the common denominator zprint configuration can be a frustrating effort, and isn't actually required. You can include lines in the file which will alter the zprint formatting. You can alter the formatting for the next function definition (really, the next top level form), or you can alter the formatting for the rest of the file. You can turn off all zprint processing for one top level form or until it is turned back on by another zprint formatting directive.

This is all possible because of the zprint comment API.

If a comment starts with the string ;!zprint, then the rest of the string will be parsed as a zprint options map.

For example:

;!zprint {:vector {:wrap? false}}

will turn off vector wrapping in the file and it will stay that way until the end of the file (or another ;!zprint comment alters it).

;!zprint API

You can format entire source files from the command line without calling any functions by using:

• lein-zprint leiningen plugin
• boot-fmt boot
• zprint-filter JVM based uberjar, starts in <1s
• zprint-clj zprint for node npm

each of which supports ;!zprint directives in source files.

There are two functions that you can call which support the ;!zprint directives.

zprint-file

zprint-file accepts an input file and an output file, and will zprint format the input file and write the results to the output file. It calls zprint-file-str to do the formatting. See the doc-string for details of its arguments.

zprint-file-str

The function zprint-file-str will accept a string which consists of an entire source file full of Clojure or Clojurescript source, and will format every form in that string. It will recognize ;!zprint directives during that processing. See the doc-string for details of its arguments.

;!zprint Directives

The formatting directives are only recognized when they start in column 1 and begin with:

;!zprint 

When zprint-file-str finds a comment line that begins with ;!zprint, it will read the rest of the line as a Clojure s-expression, and assume that it is a zprint options map. In addition, there is one additional key for the options map given to a ;!zprint directive beyond those used for other zprint option maps; the :format key. Using the ;!zprint API you can:

• Turn off formatting in the file:

;!zprint {:format :off}

• Turn the formatting back on in the file (it is on by default):

;!zprint {:format :on}

• Skip formatting the next non-whitespace, non-comment element in the file (e.g., the next definition):

;!zprint {:format :skip}

• Change the formatting used for the remainder of the file (until it is changed again, of course):

;!zprint {<<zprint-options>zprint-options>}

• Change the formatting used for just the next non-whitespace and non-comment element of the file (e.g., the next definition):

;!zprint {:format :next <<zprint-options>zprint-options>}

Example -- turn off [:vector :wrap?] for a single definition

The help text you get from (zprint nil :help) is organized as a vector of strings, one per line. If I were to run zprint-file-str on a string which contained the source file where the help is defined, it will wrap all of the elements of the vector (which in this case are strings of the help) as tightly as it can into 80 columns. When that happens, the help text doesn't read clearly in the source file, making it hard to modify.

Here are two definitions, essentially identical, of the beginning of the help text for zprint. The second is readable due to the ;!zprint directive in the source file:

(def help-str
  (vec-str-to-str [(about) "" " The basic call uses defaults, prints to stdout"
                   "" "   (zprint x)" ""
                   " All zprint functions also allow the following arguments:"
                   "" "   (zprint x <width>)" "   (zprint x <width> <options>)"
                   "   (zprint x <options>)"]))

;!zprint {:format :next :vector {:wrap? false}}

(def help-str-readable
  (vec-str-to-str [(about)
                   ""
                   " The basic call uses defaults, prints to stdout"
                   ""
                   "   (zprint x)"
                   ""
                   " All zprint functions also allow the following arguments:"
                   ""
                   "   (zprint x <width>)"
                   "   (zprint x <width> <options>)"
                   "   (zprint x <options>)"]))

Not getting what you expect?

The same validation used for option maps given to the zprint API at the repl is performed on the options map given to every ;!zprint directive.

If a ;!zprint directive contains an options map that is formatted incorrectly, you will get an exception indicating the problem. The exception will reference the particular ;!zprint directive by number, starting with 1, in the file-string given to zprint-file-str.