Skip to content

macros

All PTG-builtin TIM macros.

apply_default_macros(lang)

Applies all macros in DEFAULT_MACROS.

Parameters:

Name Type Description Default
lang MarkupLanguage

The language to apply the macros to.

 required
Source code in pytermgui/markup/macros.py 
28
29
30
31
32
33
34
35
36
def apply_default_macros(lang: MarkupLanguage) -> None:
    """Applies all macros in `DEFAULT_MACROS`.

    Args:
        lang: The language to apply the macros to.
    """

    for name, value in DEFAULT_MACROS.items():
        lang.define(name, value)

export_macro(func)

A decorator to add a function to DEFAULT_MACROS.

Source code in pytermgui/markup/macros.py 
18
19
20
21
22
23
24
25
def export_macro(func: MacroTemplate) -> MacroTemplate:
    """A decorator to add a function to `DEFAULT_MACROS`."""

    name = "_".join(func.__name__.split("_")[1:])  # type: ignore

    DEFAULT_MACROS[f"!{name}"] = func

    return func

macro_align(width, alignment, content)

Aligns given text using fstrings.

Parameters:

Name Type Description Default
width str

The width to align to.

 required
alignment str

One of "left", "center", "right".

 required
content str

The content to align; implicit argument.

 required
Source code in pytermgui/markup/macros.py 
60
61
62
63
64
65
66
67
68
69
70
71
@export_macro
def macro_align(width: str, alignment: str, content: str) -> str:
    """Aligns given text using fstrings.

    Args:
        width: The width to align to.
        alignment: One of "left", "center", "right".
        content: The content to align; implicit argument.
    """

    aligner = "<" if alignment == "left" else (">" if alignment == "right" else "^")
    return f"{content:{aligner}{width}}"

macro_expand(lang, tag)

Expands a tag alias.

Source code in pytermgui/markup/macros.py 
74
75
76
77
78
79
80
81
@export_macro
def macro_expand(lang: MarkupLanguage, tag: str) -> str:
    """Expands a tag alias."""

    if not tag in lang.user_tags:
        return tag

    return lang.get_markup(f"\x1b[{lang.user_tags[tag]}m ")[:-1]

macro_gradient(base_str, item)

Creates an xterm-256 gradient from a base color.

This exploits the way the colors are arranged in the xterm color table; every 36th color is the next item of a single gradient.

The start of this given gradient is calculated by decreasing the given base by 36 on every iteration as long as the point is a valid gradient start.

After that, the 6 colors of this gradient are calculated and applied.

Source code in pytermgui/markup/macros.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
@export_macro
def macro_gradient(base_str: str, item: str) -> str:
    """Creates an xterm-256 gradient from a base color.

    This exploits the way the colors are arranged in the xterm color table; every
    36th color is the next item of a single gradient.

    The start of this given gradient is calculated by decreasing the given base by 36 on
    every iteration as long as the point is a valid gradient start.

    After that, the 6 colors of this gradient are calculated and applied.
    """

    if not base_str.isdigit():
        raise ValueError(f"Gradient base has to be a digit, got {base_str}.")

    base = int(base_str)
    if base < 16 or base > 231:
        raise ValueError("Gradient base must be between 16 and 232")

    while base > 52:
        base -= 36

    colors = []
    for i in range(6):
        colors.append(base + 36 * i)

    return _apply_colors(colors, item)

macro_lower(text)

Turns the text into lowercase.

Source code in pytermgui/markup/macros.py 
46
47
48
49
50
@export_macro
def macro_lower(text: str) -> str:
    """Turns the text into lowercase."""

    return text.lower()

macro_rainbow(item)

Creates rainbow-colored text.

Source code in pytermgui/markup/macros.py 
111
112
113
114
115
116
117
@export_macro
def macro_rainbow(item: str) -> str:
    """Creates rainbow-colored text."""

    colors = ["red", "orange", "yellow", "green", "blue", "indigo", "violet"]

    return _apply_colors(colors, item)

macro_shuffle(item)

Shuffles a string using shuffle.shuffle on its list cast.

Source code in pytermgui/markup/macros.py 
84
85
86
87
88
89
90
91
@export_macro
def macro_shuffle(item: str) -> str:
    """Shuffles a string using shuffle.shuffle on its list cast."""

    shuffled = list(item)
    shuffle(shuffled)

    return "".join(shuffled)

macro_title(text)

Turns the text into titlecase.

Source code in pytermgui/markup/macros.py 
53
54
55
56
57
@export_macro
def macro_title(text: str) -> str:
    """Turns the text into titlecase."""

    return text.title()

macro_upper(text)

Turns the text into uppercase.

Source code in pytermgui/markup/macros.py 
39
40
41
42
43
@export_macro
def macro_upper(text: str) -> str:
    """Turns the text into uppercase."""

    return text.upper()