Download - MAIN PAGE

Boxes Example Page

Remember, boxes is designed to be tied to your editor as a text filter. So these examples assume you need only push a single key (or at least very few) in order to call boxes. Don't be worried by seemingly long argument lists - you'll only have to type them once. :-)

Unless stated otherwise, the input used for these examples is the following:

Default action

boxes

Draws a standard box of the first valid design found in your config file. If you have the config file as it comes with the boxes distribution, you get a "C" box, as you can see above.

Choosing a different design

boxes -d parchment

The -d design_name option selects another design from your config file.

Positioning of text inside box

boxes -d diamonds -a hcvc

The -a format option can be used to position the input text inside a box which is larger than needed for our text. hcvc stands for "horizontally centered, vertically centered".
Note that the box was drawn in this size because the shapes that compose it are very big, so that it is not possible to fit the box tighter around our text. Note also that the input lines themselves are not centered; hc only centers the input text block as a whole.

Line justification

boxes -d simple -a jr

This uses the third possible argument to the -a option, j. jr stands for "justification right" - consequences are obvious.

Quick alignment/positioning

boxes -d dog -a c

Since noone really wants to type -a hcvcjc only to actually center text inside a box, there are shorthand notations (l, c, and r).
Note the blank line at the bottom of the box (after little, but before the dashes) which is necessary to make the bottom of the box look right. If the blank line was not there, the box would end on a closing parenthesis, thus looking broken.

Box size specification

boxes -d html -s 40

Using -s 40, we have set the box width to 40 characters.

Box size specification (2)

boxes -d peek -a c -s 40x11

You see, -s 40x11 sets both width and height. Guess how one can influence the height alone. :-)

Padding

boxes -d shell -p a1l2

Normally, the padding values depend on the design. The "shell" design has no default padding, so we can see the effects of our command line option unchanged. a1l2 stands for "all 1, left 2" tells boxes to put one space (or empty line, in the vertical direction) around the input text block, except for the left side where two spaces shall be used.

Padding (2)

boxes -p h0v0

This uses again the default design, which by default features a horizontal padding value of one space (as you know from the very first example). By specifying -p h0v0, we set all padding to zero ("horizontal 0, vertical 0"). The same could have been achieved by -p h0 or -p a0, of course.

Regional comments

Imagine you want to comment out the following C code:

boxes -d c-cmt

Note that the closing comment tags in the input text have been escaped by adding a backslash between the asterisk and the slash. This way, the comments that have been commented out along with the rest of the code will not interfere with the new comments.

boxes -r

Should you decide to reactivate the code previouly commented out, the escaped closing comment tags are changed back into normal ones.
This is achieved by the replace and reverse statements in the config file entry describing this particular box design. If you want this to work recursively, simply add more such statements.

Box removal

Imagine your once beautiful box in "C" style like this in your editor, after you are done editing the text inside:

boxes -r

The box correctly removed even though it's been badly damaged by editing of the text inside. Obviously, the box design was correctly autodected as being "C".
Note there is only a single leading space in the output text, whereas there are two leading spaces in the input text. This is because the "C" box design has a default horizontal padding of one space. Since boxes assumes it has added the padding space, it also attempts to removes the same number of spaces when removing the box. Thus, if you were to add a new box around the text, the box internal indentation would be retained. It is easily possible to use this feature to make an editor key mapping which repairs a box for you (see installation in the documentation section).

Box removal (2)

Imagine an HTML comment box like the follwing, and imagine that boxes does not correctly autodetect it as being an HTML box:

boxes -r -d html

In such cases, as you see, -d design_name can be added to the -r command in order to tell boxes which design exactly to remove. It is always a good thing to use the -d option, because it makes autodetection unnecessary. Autodetection takes more time, because the entire config file must be parsed instead of just the one design needed, and all designs must be matched against the input text in order to see which one fits best.

Indentation handling

For this example, our input text is indented by four spaces:

boxes -d java-cmt -i box

The default indent mode is box, which indents the box by the same value as the input text was indented. As shown here, this is useful when adding regional comments to your source code, e.g. when "commenting out" a large portion of your code. IMHO, it is generally preferable to indent comments by the same value as the code they refer to, so they don't upset the code structure.

boxes -d vim-cmt -i text

By specifying -i text, the box is made to start at column zero and any input text indentation is retained inside the box.

boxes -d pound-cmt -i none

Finally, it is also possible to throw away any indentation altogther by specifying -i none.

Use of Regular Expressions

boxes -d headline

The replace and reverse statements may contain regular expressions and backreferences, which can be used for more elaborate text modifications.

boxes -d headline -r

Download - MAIN PAGE