ANSI Code Generator

This bash script will generate the proper ANSI escape sequences to move the cursor around the screen, make text bold, add colors and do much more. It is designed to help you colorize words and bits of text.

If it helps, you can think of it as a curses / ncurses library for bash, or a tool that helps you using tricks from DOS's ANSI.SYS. Or you might consider this to be your magic highlighter that has always been missing from bash.

Demonstrations

Colors

--color-table

--color-codes

Installation

Download ansi and put it somewhere in your path. Make sure that it is executable (chmod a+x ansi works well). Bash will need to be present, but it is often installed by default. No external commands are used; this only uses bash's built-in features.

# Download
curl -OL git.io/ansi

# Make executable
chmod 755 ansi

# Copy to somewhere in your path
sudo mv ansi /usr/local/bin/

Not all features will work with all terminals. Your terminal determines if particular codes work. You can override the terminal detection logic and force ansi to output color codes with the environment variable ANSI_FORCE_SUPPORT set to any non-empty value.

[BPM] Installation

This package is also published as a [BPM] library. This means it can be loaded into other scripts or installed easily. The ansi library does not need any dependencies from BPM in order to work.

To use this as a standalone command, first install [BPM] and then run: bpm install ansi

To use this as a library, list ansi as a dependency in your bpm.ini file and include these lines at the top of your shell script:

. bpm
bpm::include ansi

Once loaded into the environment, the list of library functions below are available for your use.

Upgrading Issues

The newer version of ansi has reversed an earlier decision about newlines at the end. Previously, calling ansi test would write "test" to the screen without a newline and ansi -n test would add a newline. As of August 2018, this has switched and ansi test will write out "test" with a newline. The -n flag is also switched. Sorry for the inconvenience that the earlier decision has caused and future confusion due to this flag switching. The goal is to align more closely with echo.

Usage

ansi [OPTIONS] [TEXT TO DISPLAY]

The OPTIONS are numerous and are detailed below. You can specify as many as you like. Option processing stops at the first unknown option and at --. Options are applied in the order specified on the command line. Colors are reset and attributes are restored to default unless --no-restore is used.

Examples

It often helps when one can see how to use a new tool, so here's how this library can be used.

Command-Line

# Write "Tests pass" in green on its own line
ansi --green --newline "Tests pass"

# Change the terminal's title to the working directory and
# do not write anything to the terminal.
ansi --title="$(pwd)" --no-newline

# Reset the terminal colors, reset to the default font, move the cursor
# to row 1 column 1, and show the cursor if it was previously hidden.
# This long line is the same as the --reset option.
ansi --erase-display=2 --position=1,1 --show-cursor \
    --reset-font --reset-color

# Find out how many lines the terminal can display
ansi --report-window-chars | cut -d , -f 1

Need more? Check out the examples/ folder.

Command-Line Options

When using the ansi command from a shell script or a prompt, there are a plethora of different options you can use. The syntax for using these options is as follows:

ansi [OPTIONS] [TEXT TO DISPLAY]

All options must be placed first. See the Examples section for more information. You can also see the entire list of options by running ansi --help.

Display Manipulation

The short version of these options comes from the command they are implementing.

• --insert-chars[=N], --insert-char[=N], --ich[=N] - Insert blanks at cursor, shifting the line right.
• --erase-display[=N], --ed[=N] - Erase in display. 0=below, 1=above, 2=all, 3=saved.
• --erase-lines[=N], --erase-line[=N], --el[=N] - Erase in line. 0=right, 1=left, 2=all.
• --insert-lines[=N], --insert-line[=N], --il[=N]
• --delete-lines[=N], --delete-line[=N], --dl[=N]
• --delete-chars[=N], --delete-char[=N], --dch[=N]
• --scroll-up[=N], --su[=N]
• --scroll-down[=N], --sd[=N]
• --erase-chars[=N], --erase-char[=N], --ech[=N]
• --repeat[=N], --rep[=N] - Repeat preceding character N times.

Cursor

The short version of these options comes from the command they are implementing.

• --up[=N], --cuu[=N]
• --down[=N], --cud[=N]
• --forward[=N], --cuf[=N]
• --backward[=N], --cub[=N]
• --next-line[=N], --cnl[=N]
• --previous-line[=N], --prev-line[=N], --cpl[=N]
• --column[=N], --cha[=N]
• --position[=[ROW],[COL]], --cup[=[ROW],[COL]]
• --tab-forward[=N] - Move forward N tab stops.
• --tab-backward[=N] - Move backward N tab stops.
• --column-relative[=N], --hpr[=N]
• --line[=N], --vpa[=N]
• --line-relative[=N], --vpr[=N]
• --save-cursor - Saves the cursor position. By default, this will restore the cursor after writing text to the terminal unless you use --no-restore.
• --restore-cursor - This just restores the cursor position. Normally this executes at the end when you use --save-cursor.
• --hide-cursor - This also will show the cursor at the end unless you use --no-restore.
• --show-cursor

Text (Attributes)

All of these options will automatically reset to normal text unless --no-reset is used. Below, the codes are grouped into similar functionality and the flag to disable that attribute is listed with the group it controls, so you can correlate the flags more easily.

• --bold and --faint can be reset with --normal
• --italic and --fraktur can be reset with --plain
• --underline and --double-underline are reset with --no-underline
• --blink and --rapid-blink are reset with --no-blink
• --inverse is removed with --no-inverse
• --invisible is changed back with --visible
• --strike is reset with --no-strike
• --frame and --encircle are reset with --no-border
• --overline is removed with --no-overline
• --ideogram-right, --ideogram-right-double, --ideogram-left, --ideogram-left-double, and --ideogram-stress are all removed with --reset-ideogram
• --font=NUM sets the font. NUM must be a single digit from 0 through 9. Font 0 is the default font.

Text (Foreground)

All of these options will automatically reset to the default color unless --no-reset is used. To preview the colors, use --color-table.

• --black and --black-intense
• --red and --red-intense
• --green and --green-intense
• --yellow and --yellow-intense
• --blue and --blue-intense
• --magenta and --magenta-intense
• --cyan and --cyan-intense
• --white and --white-intense
• --color=CODE lets you use one of 256 codes - preview the codes using --color-codes
• --rgb=R,G,B sets a specific color

Text (Background)

All of these options will automatically reset to the default color unless --no-reset is used. To preview the colors, use --color-table.

• --bg-black and --bg-black-intense
• --bg-red and --bg-red-intense
• --bg-green and --bg-green-intense
• --bg-yellow and --bg-yellow-intense
• --bg-blue and --bg-blue-intense
• --bg-magenta and --bg-magenta-intense
• --bg-cyan and --bg-cyan-intense
• --bg-white and --bg-white-intense
• --bg-color=CODE lets you use one of 256 codes - preview the codes using --color-codes
• --bg-rgb=R,G,B sets a specific color

Text (Reset)

These options force a reset of colors. This is useful if you used --no-reset or are correcting the appearance of a misbehaving terminal.

• --reset-attrib - Reset all attributes
• --reset-foreground - Reset the foreground to default
• --reset-background - Reset the background to default
• --reset-color - Reset all color-related settings
• --reset-font - Reset the font to the primary font

Reporting

All of these commands send a special code to the terminal. The terminal responds as though someone typed something very fast. In order for these to work, ansi must read from stdin directly. This won't work if you are piping in a file or replace stdin in another way.

The ANSI codes are written to stdout in order that the terminal might respond immediately. The result of the report is written to stdout.

• --report-position - ROW,COL
• --report-window-state - "open" or "iconified"
• --report-window-position - X,Y
• --report-window-pixels - HEIGHT,WIDTH
• --report-window-chars - ROWS,COLS
• --report-screen-chars - ROWS,COLS (this is for the entire screen)
• --report-icon
• --report-title

Miscellaneous

• --color-table - Display a color table.
• --color-codes - Show all of the 256 color codes.
• --icon=NAME - Set the icon.
• --title=TITLE - Set the title of the terminal.
• --no-restore - Do not issue reset codes when changing colors and saving the cursor. For example, if you use --green then the text will automatically be reset to the default color when the command terminates. With --no-restore set, the text will stay green and subsequent commands that output will keep writing in green until something else changes the terminal.
• -n, --no-newline - Do not add a newline at the end.
• --bell - Add the terminal's bell sequence to the output.
• --reset - Reset all colors, clear the screen, show the cursor, restore the primary font, and move