0
# Text Rendering
1

2
Core functionality for converting plain text into ASCII art using FIGlet fonts. This module provides both simple utility functions and programmatic access to text rendering capabilities.
3

4
## Capabilities
5

6
### Basic Text Conversion
7

8
Converts text to ASCII art using the specified font and options. This is the most commonly used function for simple text-to-ASCII art conversion.
9

10
```python { .api }
11
def figlet_format(text: str, font: str = "standard", **kwargs) -> FigletString:
12
    """
13
    Convert text to ASCII art using specified font.
14
    
15
    Parameters:
16
    - text (str): Text to convert to ASCII art
17
    - font (str): Font name to use (default: "standard")
18
    - direction (str): Text direction ("auto", "left-to-right", "right-to-left") 
19
    - justify (str): Text justification ("auto", "left", "center", "right")
20
    - width (int): Output width in characters (default: 80)
21
    
22
    Returns:
23
    FigletString: ASCII art representation of the text
24
    
25
    Raises:
26
    FontNotFound: If the specified font cannot be located
27
    FontError: If there is a problem parsing the font file
28
    CharNotPrinted: If width is insufficient to print a character
29
    """
30
```
31

32
#### Usage Example
33

34
```python
35
import pyfiglet
36

37
# Basic usage with default font
38
result = pyfiglet.figlet_format("Hello")
39
print(result)
40

41
# Using a different font
42
result = pyfiglet.figlet_format("Hello", font="big")
43
print(result)
44

45
# With additional formatting options
46
result = pyfiglet.figlet_format(
47
    "Centered Text", 
48
    font="slant", 
49
    justify="center",
50
    width=60
51
)
52
print(result)
53
```
54

55
### Direct Console Output
56

57
Prints ASCII art text directly to stdout with optional color support. Useful for terminal applications that need immediate colored output.
58

59
```python { .api }
60
def print_figlet(text: str, font: str = "standard", colors: str = ":", **kwargs) -> None:
61
    """
62
    Print ASCII art text directly to stdout with color support.
63
    
64
    Parameters:
65
    - text (str): Text to convert and print
66
    - font (str): Font name to use (default: "standard")  
67
    - colors (str): Color specification in "foreground:background" format
68
    - direction (str): Text direction ("auto", "left-to-right", "right-to-left")
69
    - justify (str): Text justification ("auto", "left", "center", "right") 
70
    - width (int): Output width in characters (default: 80)
71
    
72
    Returns:
73
    None: Prints to stdout
74
    
75
    Raises:
76
    FontNotFound: If the specified font cannot be located
77
    FontError: If there is a problem parsing the font file
78
    InvalidColor: If color specification is invalid
79
    """
80
```
81

82
#### Usage Example
83

84
```python
85
import pyfiglet
86

87
# Basic printing
88
pyfiglet.print_figlet("Hello World")
89

90
# With colors (red text on blue background)
91
pyfiglet.print_figlet("Colored Text", colors="red:blue")
92

93
# Only foreground color
94
pyfiglet.print_figlet("Red Text", colors="red:")
95

96
# Only background color  
97
pyfiglet.print_figlet("Blue Background", colors=":blue")
98

99
# RGB colors
100
pyfiglet.print_figlet("RGB Text", colors="255;100;50:0;0;255")
101
```
102

103
## Color Specifications
104

105
The `colors` parameter accepts several formats:
106

107
- **Named colors**: Use COLOR_CODES keys (RED, GREEN, BLUE, YELLOW, etc.)
108
- **RGB format**: "R;G;B" values from 0-255
109
- **Foreground only**: "color:" (trailing colon)
110
- **Background only**: ":color" (leading colon)  
111
- **Both**: "foreground:background"
112

113
Available named colors: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, LIGHT_GRAY, DEFAULT, DARK_GRAY, LIGHT_RED, LIGHT_GREEN, LIGHT_YELLOW, LIGHT_BLUE, LIGHT_MAGENTA, LIGHT_CYAN, WHITE, RESET
114

115
## Text Direction and Justification
116

117
- **Direction**: Controls text flow direction, typically determined by font properties when set to "auto"
118
- **Justification**: Controls text alignment within the specified width
119
- **Width**: Sets maximum output width for line breaking and justification
120

121
## Return Type
122

123
Both functions work with `FigletString`, an enhanced string type that supports ASCII art manipulation methods like `reverse()`, `flip()`, and whitespace normalization.