    ______     ____
   / ____/  __/ __ )____ _____  ____  ___  _____
  / __/ | |/_/ __  / __ `/ __ \/ __ \/ _ \/ ___/
 / /____>  </ /_/ / /_/ / / / / / / /  __/ /
/_____/_/|_/_____/\__,_/_/ /_/_/ /_/\___/_/

ASCII art banners for Elixir applications

Print a startup banner from priv/banner.txt when your application boots, and render any text with FIGlet fonts.

Read the docs Hex package Source code

{:exbanner, "~> 0.3"}

Elixir 1.15+ and OTP 25+. MIT licensed.

A product by

Same output as figlet

Full width, fitting and horizontal smushing, checked byte for byte against figlet 2.2.5 in 329 of the 333 bundled fonts.

Works in releases

The banner lives in priv/ and prints before your application logs, in mix run, iex -S mix and releases.

333 fonts

From the classic FIGlet distribution to hundreds of community fonts, each one credited to its author. Bring any other font with :font_paths.

Safe by default

No code evaluation, and no escape sequences from files, hostnames or environment variables reach your terminal or your logs.

Startup banner

Tell ExBanner which application owns the banner. Without :otp_app nothing is printed, so a library that depends on ExBanner never adds a banner to your application.

config/config.exs

config :exbanner, otp_app: :my_app

priv/banner.txt

$[gold] __  __            _
|  \/  |_   _     / \   _ __  _ __
| |\/| | | | |   / _ \ | '_ \| '_ \
| |  | | |_| |  / ___ \| |_) | |_) |
|_|  |_|\__, | /_/   \_\ .__/| .__/
        |___/          |_|   |_|$[reset]
$[dimgray]$app v$version | Elixir $elixir_version | OTP $otp_release$[reset]

$ mix run --no-halt

 __  __            _
|  \/  |_   _     / \   _ __  _ __
| |\/| | | | |   / _ \ | '_ \| '_ \
| |  | | |_| |  / ___ \| |_) | |_) |
|_|  |_|\__, | /_/   \_\ .__/| .__/
        |___/          |_|   |_|
my_app v1.2.0 | Elixir 1.18.3 | OTP 27

Placeholders

banner.txt is plain text. ExBanner replaces these names, in the same style as Logger formats. Any other $ stays as written, so ASCII art full of $$$$ is safe.

Placeholder	Value
`$app`	The `:otp_app` name
`$version`	Application version
`$description`	Application description
`$elixir_version`	`System.version()`
`$otp_release`	`System.otp_release()`
`$exbanner_version`	ExBanner version
`$node`	`node()`
`$hostname`	Host name
`$release`	`RELEASE_NAME`, empty outside a release
`$schedulers`	`System.schedulers_online()`

Add your own values with :vars, and colors from Bunt with $[red], $[gold] or $[bright]. Colors are dropped when ANSI is disabled or when the banner goes to Logger.

Configuration

Option	Default	Description
`:otp_app`	`nil`	Application that owns the banner. Required to print anything.
`:location`	`priv/banner.txt`	A path, or `{:priv, app, "file.txt"}`.
`:mode`	`:console`	`:console`, `:log` or `:off`.
`:mix_tasks`	`:all`	`:all`, `:none`, or task names such as `["phx.server", "run"]`.
`:vars`	`%{}`	Extra placeholders.
`:font_paths`	`[]`	Directories with your own `.flf` fonts.

Rendering text

Render any text with a FIGlet font. Long text wraps at word boundaries, like figlet -w. Characters missing from a font lose their accents (ç becomes c) or become ?, and are never dropped silently.

iex> ExBanner.print("Hello", font: :small)
 _  _     _ _
| || |___| | |___
| __ / -_) | / _ \
|_||_\___|_|_\___/
:ok

iex> ExBanner.render("Hi", font: :term)
{:ok, "Hi\n"}

iex> ExBanner.render("Hi", font: :nope)
{:error, {:unknown_font, "nope"}}

iex> ExBanner.print("Hello", font: :slant, color: :darkorange)

iex> ExBanner.showcase("Hello", match: "small")
font: :cybersmall  (1/16)
...

Function	Returns
`render(text, opts)`	`{:ok, string}` or `{:error, reason}`
`render!(text, opts)`	The string, or raises `ExBanner.Error`
`print(text, opts)`	`:ok`, with `:color` and `:device` options
`show()`	Prints the startup banner on demand
`showcase(text, opts)`	Prints the text in every font, page by page, to help choose one
`fonts()`	The bundled font names

Fonts

Every font below is rendered by ExBanner itself. Each one is credited to its author on the credits page, and any font is removed on request of its author. Use any other .flf or .tlf file by pointing :font_paths to its directory.

Security

ExBanner never evaluates code from banner.txt or from font files.
Control characters, ANSI escape sequences and Unicode bidirectional overrides are removed from banner files, placeholder values, rendered text and font glyphs.
Placeholder values are always a single line, so a hostname or an environment variable cannot fake a log line.
Only ExBanner emits ANSI sequences, from a fixed list of colors and styles. Nothing moves the cursor or clears the screen.
Font and color names are never converted to atoms.
A failure while printing the startup banner is logged as a warning and never stops your application.