boxes - text mode box and comment drawing filter
boxes [-hlmrv] [-a format] [-d design]
[-e eol] [-f file] [-i indent] [-k bool]
[-n encoding] [-p pad] [-q query] [-s size]
[-t tabopts] [infile [outfile]]
Boxes is a text filter which can draw any kind of box
around its input text. Box design choices range from simple boxes to complex
ASCII art. A box can also be removed and repaired, even if it has been badly
damaged by editing of the text inside. Since boxes may be open on any side,
boxes can also be used to create regional comments in any programming
language. New box designs can be added and shared by appending to a
configuration file.
boxes is a command line tool, but also integrates with any
text editor that supports filters. The boxes website has examples on
how to configure editor integration for various text editors:
<URL:https://boxes.thomasjensen.com/editors.html>
Options offered by boxes are the following:
- -a string
- Alignment/positioning of text inside box. This option takes a format
string argument which is read from left to right. The format string may
not contain whitespace and must consist of one or more of the following
components:
hx - horizontal alignment of the input text
block inside a potentially larger box. Possible values for
x are l (ell, for left alignment), c (center), or
r (right). This does not affect the justification of text lines
within the input text block (use the j argument instead).
vx - vertical alignment of the input text block inside a
potentially larger box. Possible values for x are
t (for top alignment), c (center), or b (bottom).
jx - justification of lines within the input text block.
Possible values for x are l (ell, for left
justification), c (center), or r (right). This does not
affect the alignment of the input text block itself within the box. Use
the h and v arguments for input text block
positioning.
Short hand notations (can be combined with the above
arguments):
l (ell) - short for
hlvcjl
c - short for hcvcjc
r - short for hrvcjr
The factory default setting for -a is
hlvt.
- -c string
- Command line design definition for simple cases. The argument of this
option is the definition for the "west" (W) shape. The defined
shape must consist of exactly one line, i.e. no multi-line shapes are
allowed. The -c option is intended as a shortcut for those cases
where simple regional comments are to be created, which only need a
certain character or sequence of characters to be placed in front of every
line. In such cases, it is much more convenient to simply specify
-c than to do a complete design definition in one's config file,
where the only shape defined is the west shape.
This option implies a -d and does not access the config file.
-c may of course be used in conjunction with any of the other
options. By default, -c is not specified.
- -d string
- Design selection. The one argument of this option is the name of the
design to use, which may either be a design's primary name or any of its
alias names.
- -e eol
- Override line terminator. eol can be CR, LF,
or CRLF. The default is to use the
system-specific line terminator, which means CRLF on Windows,
and LF otherwise. This option should only be used in an emergency,
because normally the system-specific line terminator will be just fine.
This option is considered experimental, and may go away in a future
version of boxes. Let us know in
<URL:https://github.com/ascii-boxes/boxes/issues/60> if you
think we should keep it.
- -f string
- Use alternate config file. The one argument of this option is the name of
a valid boxes config file. The argument of -f can also be a
directory which contains a configuration file. More information on this
topic below in the CONFIGURATION FILE section.
- --help
- -h
- Print usage information.
- -i string
- Indentation mode. Possible arguments are text (indent text inside
of box), box (indent box, not text inside of box), or none
(throw away indentation). Arguments may be abbreviated. The default is
box.
- -k bool
- Kill leading/trailing blank lines on removal. The value of bool is
either true or false. This option only takes
effect in connection with -r. If set to
true, leading and trailing blank lines will be removed
from the output. If set to false, the entire
content of the former box is returned. The default is
false, if both the top and the bottom part of the box are
open, as is the case with most regional comments. If the box's
design defines a top part or a bottom part, the default is
true.
- -l
- (ell) List designs. Produces a listing of all available box designs in the
config file, along with a sample box and information about its creator.
Also checks the syntax of the entire config file. If used together with
-d, displays detailed information about the specified
design.
- -m
- Mend box. This removes a (potentially broken) box as with
-r, and redraws it afterwards. The mended box is drawn
according to the options given. This may be important to know when
it comes to restoring padding, indentation, etc. for the mended
box. Implies -k false.
- -n encoding
- Character encoding. Overrides the character encoding of the input and
output text. Choose from the list shown by iconv -l. If an invalid
character encoding is specified here, UTF-8 is used as a fallback.
The default is to use the system encoding, which is normally the best
course of action. So don't specify this option unless you have to.
- -p string
- Padding. Specify padding in spaces around the input text block for all
sides of the box. The argument string may not contain whitespace and must
consist of a combination of the following characters, each followed by a
number indicating the padding in spaces:
a - (all) give padding for all sides at once
h - (horiz) give padding for both horizontal sides
v - (vertical) give padding for both vertical sides
b - (bottom) give padding for bottom (south) side
l - (left) give padding for left (west) side
t - (top) give padding for top (north) side
r - (right) give padding for right (east) side
Example: -p a4t2 would define the
padding to be 4 characters on all sides, except for the top of the
box, where the input text block will be only 2 lines away from the
box.
By default, unless specified otherwise in the config file, no padding is
used.
- -q query
- Query designs by tag. In contrast to -l, this will only
print the matching design names. This option is normally used
stand-alone; if used in combination with other options, behavior is
undefined. The query argument is a comma-separated list
of tags which can be present on a design in order to match. A tag may
optionally be prefixed with + in order to require that it be
present, or with - in order to exclude designs which have that tag.
Each tag can only occur once per query.
This option is intended for use by scripts. Alias names are printed below
their primary design name, and postfixed with (alias).
Example: boxes -q programming,-comment
- -r
- Remove an existing box. Which design to use is detected automatically. In
order to save time or in case the detection does not decide correctly,
combine with -d to specify the design. The default is to draw a new
box.
- -s
widthxheight
- Box size. This option specifies the desired box size in units of columns
(for width) and lines (for height). If only a single number is given as
argument, this number specifies the desired box width. A single number
prefixed by 'x' specifies only the box height. The actual resulting box
size may vary depending on the individual shape sizes of the chosen
design. Also, other command line options may influence the box size (such
as -p).
By default, the smallest possible box is created around the text.
- -t string
- Tab handling. This option controls how tab characters in the input text
are handled. The option string must always begin with a uint number
indicating the distance between tab stops. It is important that this value
be set correctly, or tabulator characters will upset your input text. The
correct tab distance value depends on the settings used for the text you
are processing. A common value is 8.
Immediately following the tab distance, an optional character can be
appended, telling boxes how to treat the leading tabs. The
following options are available:
e - expand tabs into spaces
k - keep tabs as close to what they were as possible
u - unexpand tabs. This makes boxes turn as many spaces as
possible into tabs.
In order to maintain backwards compatibility, the -t
string can be just a number. In that case, e is assumed
for tab handling, which removes all tabs and replaces them with spaces.
The factory default for the -t option is simply 8, which is just
such a case.
For example, you could specify -t 4u in order to have
your leading tabs unexpanded. In the box content, tabs are always
converted into spaces. The tab distance in this example is 4.
- -v
- Print out current version number.
Boxes will look for the configuration file in several
places, some of which are given by the XDG specification.
- 1. -f option [file or dir]
- When a configuration file is specified on the command line, we will use
that. The -f option can also specify a directory. Any location
specified via -f must exist, or boxes will terminate with an
error.
- 2. BOXES environment variable [file or dir]
- If no config file is specified on the command line, boxes will
check for the BOXES environment variable, which may contain a filename or
directory to use. Any location specified via the BOXES environment
variable must exist, or boxes will terminate with an error.
- 3. $HOME [dir]
- 4. $XDG_CONFIG_HOME/boxes [dir]
- 5. $HOME/.config/boxes [dir]
- 6. /etc/boxes/boxes-config [file]
- 7. /etc/xdg/boxes [dir]
- 8. /usr/local/share/boxes [dir]
- 9. /usr/share/boxes [dir]
- Either one of these last two directory locations might have the same name
as the global config file from 6. That's fine. It just means that
we first look for a file of that name, and then for a directory containing
the file.
The XDG environment variable XDG_CONFIG_DIRS is not
supported. However, its default value is supported via steps 8 and
9 above.
- In the above list, whenever a step
is designated with [dir], the following file names will be found, in this
order:
-
1. .boxes
2. box-designs
3. boxes-config
4. boxes
As soon as the first valid file is found, we use that and stop the
search.
The recommended location for a user-specific configuration file is
$HOME/.boxes or $HOME/.config/boxes/.boxes. A global
configuration file should be located at /etc/boxes/boxes-config. But
all of the other locations are fully supported, too.
The syntax of boxes config files is described on the
website at
<URL:https://boxes.thomasjensen.com/config-syntax.html>.
Examples on how to invoke boxes may be found on the website
at <URL:https://boxes.thomasjensen.com/examples.html>.
Try
echo "Good Bye World!" | boxes -d nuke
Boxes also combines nicely with other tools. Try
figlet "boxes . . . !" | lolcat -f | boxes -d
unicornthink
The boxes website is
<URL:https://boxes.thomasjensen.com/>. It contains a number of
examples illustrating this manual page as well as more in-depth
documentation.
Boxes was made by Thomas Jensen and the boxes
contributors. It has been lovingly maintained since 1999.
For a full list of contributors, see
<URL:https://boxes.thomasjensen.com/team.html#contributors>
and <URL:https://github.com/ascii-boxes/boxes/graphs/contributors>.
Please refer to the boxes website for the maintainer's current email
address.
This is boxes version 2.2.0.
boxes is free software under the terms of the GNU General
Public License, version 3. Details in the LICENSE file:
<URL:https://raw.githubusercontent.com/ascii-boxes/boxes/v2.2.0/LICENSE>
Boxes recognizes the following environment variables:
BOXES
Absolute path of the boxes configuration file. If this is specified, it
must refer to an existing file or directory.
HOME
The user's home directory.
- XDG_CONFIG_HOME
- The root of the configuration file location as per the XDG
specification.