- a simple utility to output formatted input with an exact (visual) width and height
- the output is the same as the input except that the its lines and columns shown when outputted to a terminal are as given
- terminal color sequences are preserved and don't contribute to the width
- other ANSI sequences are not handled and would break output
- emojis and other unicode wide characters will usually have the correct width
- NOTE: cannot guarentee exact visual width because unicode character widths aren't handled consistently
- libgrapheme is used to detect unicode grapheme clusters
- terminal ANSI mode 2027 supported to detect if grapheme clusters should be used
- tabs are set to a width of 4 spaces by default
- align to 4 space columns as expected
- considering utf-8 allows codepoints up to 6 bytes that can be 0-2 columns wide and clustered together with other codepoints to form new characters, this is more complicated than it seems
- used somewhat standard C standard library functions
mbrlen
,mbrtowc
, andwcwidth
for unicode character width - used libgrapheme for grapheme cluster length
- ANSI color escape sequences handled manually
- used somewhat standard C standard library functions
- Usage:
$ visualbox --help
Usage: visualbox [ --help|-h ] [ --no-mode-2027|-N ] [ --force-cluster|-f ] [ --file|-f file = - ] [ --tabs|-t tabs = 4 ] --width|-w|--rows rows [ --delim|-d delim = │ ] --height|-h|--columns columns [ file = - ] width height
file taken as positional argument
[ --help|-h ] Print this help message
[ --file|-f file = - ] file to output (default stdin)
--width|-w|--rows rows width of output (required)
--height|-h|--columns columns height of output (required)
[ --tabs|-t tabs = 4 ] number of spaces per tab
[ --delim|-d delim = │ ] delimeter to print at end of line
[ --force-cluster|-f ] force length to clustered grapheme
[ --no-mode-2027|-N ] don't check if terminal can use clustering
- if file is omitted, then
visualbox
will read fromstdin
- width and height are mandatory
- width and height can be given as positional args if file is specified (use '-' for stdin)
- delim is an arbitrary string (default to │)
- tabs is an int of how many spaces tabs should amount to (default to 4)
- can also specify whether to force clustering or whether to skip check for if terminal supports clustering
- I created this to use in my bat-minimap script
- I use this script for previewing text files in
lf
- I use this script for previewing text files in
- TODO update screenshot, this is super old
- relies on clparser submodule
- builds statically against clparser/libparseargs.a
- relies on libgrapheme submodule
- builds statically against libgrapheme/libgrapheme.a
- if undesired, grapheme support can be easily removed by building with
NO_LIBGRAPHEME=1
make option- see config.mk
- build with
make(1)
- install with
make install
- installs locally to ~/.local/bin by default
- tweak the directories in config.mk to choose where it gets installed