`wezterm.format({})`¶

Since: Version 20210314-114017-04b7cedd

The functionality described in this section requires version 20210314-114017-04b7cedd of wezterm, or a more recent version.

wezterm.format can be used to produce a formatted string with terminal graphic attributes such as bold, italic and colors. The resultant string is rendered into a string with wezterm compatible escape sequences embedded.

wezterm.format accepts a single array argument, where each element is a FormatItem.

This example logs the text Hello, then the date/time, underlined, in purple text on a blue background to the stderr of the wezterm process:

local wezterm = require 'wezterm'

local success, date, stderr = wezterm.run_child_process { 'date' }

wezterm.log_info(wezterm.format {
  { Attribute = { Underline = 'Single' } },
  { Foreground = { AnsiColor = 'Fuchsia' } },
  { Background = { Color = 'blue' } },
  { Text = 'Hello ' .. date .. ' ' },
  'ResetAttributes',
  { Text = 'this text has default attributes' },
})

Possible values for the FormatItem elements are:

{Text="Hello"} - the text Hello. The string can be any string expression, including escape sequences that are not supported directly by wezterm.format.
{Attribute={Underline="None"}} - disable underline
{Attribute={Underline="Single"}} - enable single underline
{Attribute={Underline="Double"}} - enable double underline
{Attribute={Underline="Curly"}} - enable curly underline
{Attribute={Underline="Dotted"}} - enable dotted underline
{Attribute={Underline="Dashed"}} - enable dashed underline
{Attribute={Intensity="Normal"}} - set normal intensity
{Attribute={Intensity="Bold"}} - set bold intensity
{Attribute={Intensity="Half"}} - set half intensity
{Attribute={Italic=true}} - enable italics
{Attribute={Italic=false}} - disable italics
{Foreground={AnsiColor="Black"}} - set foreground color to one of the ansi color palette values (index 0-15) using one of the names Black, Maroon, Green, Olive, Navy, Purple, Teal, Silver, Grey, Red, Lime, Yellow, Blue, Fuchsia, Aqua or White.
{Foreground={Color="yellow"}} - set foreground color to a named color or rgb value like #ffffff.
{Background={AnsiColor="Black"}} - set the background color to an ansi color as per Foreground above.
{Background={Color="blue"}} - set the background color to a named color or rgb value as per Foreground above.
"ResetAttributes" - reset all attributes to default. (Since: Version 20220807-113146-c2fee766)

This example shows how to use arbitrary escape sequences to change the underline color:

local wezterm = require 'wezterm'
wezterm.log_info(wezterm.format {
  -- turn on underlines
  { Attribute = { Underline = 'Single' } },
  -- make the underline red
  { Text = '\x1b[58:2::255:0:0m' },
  -- and say hello
  { Text = 'hello' },
})

wezterm.format({})¶

`wezterm.format({})`¶