Skip to content

A quick and user-friendly way to style your text using ANSI codes

License

Notifications You must be signed in to change notification settings

akrantz01/antsi

Repository files navigation

Antsi

A quick and user-friendly way to style your text using ANSI codes.

Built around a delightfully simple markup language, there's no messing about with codes or style resets. All the ANSI code conversion, handling of overlapping styles, and terminal support is automatically handled for you.

Usage

You can either download wheels from the Releases tab or install it from PyPI:

pip install antsi

The function you'll most likely care about is colorize. Colorize is responsible for converting any styled markup within the provided source to ANSI escape sequences. The styled markup syntax can be found below.

You can use the following code to test that it's working as expected.

import antsi

print(antsi.colorize("Hello [fg:green](there!)"))
print(antsi.colorize("It looks like [fg:black;bg:white;deco:bold,blink](antsi) is working!"))

If you're planning on doing any string manipulation or templating with styled markup, you'll want to escape the substituted text to prevent any unexpected colors or errors. The escape function ensures that any control characters are properly escaped.

Styled Markup

Styled markup is a decidedly simple language that is make for ease of use and readability. There's no unruly sequences of numbers and characters that you'll forget what they mean in a week, just words and a couple memorable abbreviations.

Styled markup can appear anywhere within a piece of text. It can even be nested infinitely! The only requirements are that it start with a style specifier and is followed by some content. It will always be in the form:

[ <style specifier(s)> ]( <content> )

For example, Hello [fg:green](there), user! which will make only "there" be colored green. Everything else will be the default text color.

Content

The content is what the style specifier applies to. It always immediately follows a style specifier and must be wrapped in parentheses. Any whitespace within the content will be emitted as-is unless escaped using a backslash (\).

Important

Putting any character(s) between the style specifier and content is explicitly disallowed.

The content can contain any characters, and it can even contain other styled markup! If you want to use any square brackets or parentheses in the content, they must be escaped.

Tip

When nesting styled markup, the styles of the parent markup will also be applied unless explicitly overridden. However, there is currently no way to remove text decorations from the children of nested markup.

Style Specifiers

Style specifiers are surrounded by square brackets ([]) and contain the directives for applying style to the content immediately following them. They are essentially a list of key-value pairs, where the key denotes the type of style.

The styles within a specifier will ignore whitespace to facilitate readability. However, whitespace cannot exist in the middle of a key or value (i.e. bl ue will cause an error). The benefit of this is that [ fg: red ; bg: blue ] will be parsed the same as [fg:red;bg:blue], so use whatever style you prefer.

Examples:

Style Specifier Meaning
[fg:red] Red foreground
[bg:blue] Blue background
[deco:bold] Bold text
[deco:bold,blink] Bold and blinking
[fg:red;bg:white] Red foreground and white background
[bg:blue;fg:white;deco:bold] White foreground, blue background, and bold
[deco:bold,underline;fg:cyan] Cyan foreground, bold, and underlined
[fg:red;bg:white;fg:blue] Blue foreground and white background (last specifier wins)

Important

If any tags are repeated in the specifier, the value of the last tag takes precedence. This means that tags which can accept multiple values (i.e. deco) are not merged.

As show above, there are currently three specifiers that are allowed: fg ( foreground), bg (background), and deco (decoration).

Foreground color (fg)

Format: fg:<color>

Changes the color of the text itself. Currently only the standard color pallet is implemented, providing 8 colors with a standard and a bright variant. The bright variant can be chosen by prefixing the color with bright-.

Tip

Colors will appear differently depending on the terminal being used.

Color Standard Code Bright Code
Default default N/A
Black black bright-black
Red red bright-red
Green green bright-green
Yellow yellow bright-yellow
Blue blue bright-blue
Magenta magenta bright-magenta
Cyan cyan bright-cyan
White white bright-white

Background color (bg)

Format: bg:<color>

Changes the color of the text background. It accepts the same colors as fg.

Text decoration (deco)

Format: deco:<decoration>,[<decoration>...]

Applies additional text decorations like bolding, dimming, blinking, etc. Unlike the foreground and background, multiple text decorations can be applied at the same time using a comma-separated list.

Tip

Support for decorations may differ between terminals.

Decoration Code(s)
Bold bold
Dim dim, faint
Italic italic
Underline underline
Fast Blink fast-blink, blink-fast
Slow Blink slow-blink, blink-slow
Invert invert, reverse
Hide hide, conceal
Strikethrough strike-through, strikethrough

Escape Sequences

There are a handful of control characters that must be escaped to include them anywhere in your text. This includes text outside styled markup.

Character Sequence
\ \\
[ \[
] \]
( \(
) \)

Beyond these characters, you can also escape any whitespace (i.e. spaces, tabs, newlines, and carriage returns) to make writing multi-line text easier. All you need to do is prefix it with a backslash (\).

Contributing

Any and all contributions are welcome! Some ideas if you can't think of anything:

  • Improve the documentation
  • Add some functionality that might be missing
  • Report (or even fix) any bugs

If you don't have time to contribute yourself but still wish to support the project, sponsorship would be greatly appreciated!

License

Licensed under the MIT license (or http://opensource.org/licenses/MIT).