galant

A Gleam library for creating colored and decorated strings for the terminal using ANSI Escape Sequences

Installation

To install from Hex

gleam add galant

Documentation can be found at https://hexdocs.pm/galant.

Overview

galant is a Gleam library that creates colored and decorated strings for the terminal. It has a fluent API which can be composed for matching various use-cases. Here is a simple example of how a styled string can be created.

open()
|> text("Basic ")
|> start_bold()
|> magenta("galant")
|> end_bold()
|> text(" example")
|> to_string()
|> io.println()

Basic galant example

Usage

galant supports some different options for coloring and styling text for the terminal using ANSI Escape Sequences. The most direct way is to use the various text-styling functions to create a styling sequence that can be transformed into a styled string. This method introduces the basic api and is the basic building block which can be used to compose reusable element later on.

The open() function can be used to start a new styling sequence and is followed by one or more styling functions. The sequence can be terminated with a call to to_string() which will produce a string with the relevant ANSI Escape Sequences.

  open()
  |> green("I'm the mighty frog")
  |> to_string()
  |> io.println()

I’m the mighty frog

To add color and decoration to a piece of text the start_{color/decoration} functions can be used. For decorations there also exists a corresponding end_{decoration} function which is useful for decorating only parts of a text. These functions can be used in conjunction with the text(String) function which will insert a piece of text in the styling sequence.

open()
|> start_yellow()
|> start_bold()
|> text("I'm a very bold lemon ")
|> end_bold()
|> text("and I'm normal banana")
|> to_string()
|> io.println()

I’m a very bold lemon and I’m a normal banana

Furthermore styling sequences can be captured by replacing the to_string() with the save() function and utilizing the placeholder() function somewhere in the sequence. This will return a style-function that takes one String argument and can then be used in other styling sequences to style a string accordingly.

let party_style =
  open()
  |> start_magenta()
  |> start_italic()
  |> start_underline()
  |> placeholder()
  |> save()

open()
|> text("Welcome to ")
|> party_style("the party!!")
|> to_string()
|> io.println()

Welcome to the party!!

Finally the same principle as with save() can be used but with to_string_styler() on a sequence with a placeholder. This will create a function that can be applied to a string to directly style it without the need to include it in another styling sequence.

I'm not very good at " <> correction("speling") <> " all the " <> correction("wurds")

I’m not very good at speling all the wurds

Colors

The 8 standard colors black, white, red, green, blue, magenta and cyan all have their corresponding named functions.

If you target terminal supports 256 colors or RGB (Truecolor) colors can be applied with the same principles using the color_256 (for 256 colors) and color_rgb/color_hex functions.

open()
|> text("In Xterm this color is called ")
|> color_256("DarkOrange3", 166)
|> to_string()
|> io.println()

In Xterm this color is called> DarkOrange3

open()
|> text("A pastel palette\n")
|> color_bg_rgb("     ", 231, 231, 238)
|> color_bg_hex("     ", 0xE9FAE3)
|> color_bg_hex("     ", 0xDEE8D5)
|> color_bg_hex("     ", 0xD5C7BC)
|> color_bg_rgb("     ", 172, 146, 166)
|> to_string()
|> io.println()

A pastel palette

                      

Text decoration

Text decorations have their own named functions, like bold and italic and few more. Beware that not all decorations may be supported in all terminals.