0
# Color Support
1

2
ANSI color support for terminal output with foreground/background color specifications and RGB color values. PyFiglet provides comprehensive color management for terminal-based ASCII art display.
3

4
## Capabilities
5

6
### Color Parsing
7

8
Parses color specifications in various formats and converts them to ANSI escape sequences.
9

10
```python { .api }
11
def parse_color(color: str) -> str:
12
    """
13
    Parse foreground:background color specification into ANSI codes.
14
    
15
    Parameters:
16
    - color (str): Color specification in "foreground:background" format
17
    
18
    Returns:
19
    str: ANSI escape sequence for the specified colors
20
    
21
    Format examples:
22
    - "red:blue" - red foreground, blue background
23
    - "red:" - red foreground only
24
    - ":blue" - blue background only  
25
    - "255;100;50:0;0;255" - RGB foreground:background
26
    
27
    Raises:
28
    InvalidColor: If color specification is invalid
29
    """
30
```
31

32
### ANSI Code Generation
33

34
Converts individual color specifications to ANSI escape codes.
35

36
```python { .api }
37
def color_to_ansi(color: str, isBackground: bool) -> str:
38
    """
39
    Convert color specification to ANSI escape sequence.
40
    
41
    Parameters:
42
    - color (str): Color name or RGB specification
43
    - isBackground (bool): True for background color, False for foreground
44
    
45
    Returns:
46
    str: ANSI escape sequence for the color
47
    
48
    Supported formats:
49
    - Named colors: "RED", "GREEN", "BLUE", etc.
50
    - RGB format: "255;128;0" (values 0-255)
51
    
52
    Raises:
53
    InvalidColor: If color name not found or RGB format invalid
54
    """
55
```
56

57
## Usage Examples
58

59
### Basic Color Usage
60

61
```python
62
import pyfiglet
63

64
# Print with named colors
65
pyfiglet.print_figlet("Hello", colors="red:blue")
66

67
# Foreground only
68
pyfiglet.print_figlet("Red Text", colors="red:")
69

70
# Background only  
71
pyfiglet.print_figlet("Blue Background", colors=":blue")
72

73
# No colors (default)
74
pyfiglet.print_figlet("Plain Text", colors=":")
75
```
76

77
### RGB Color Usage
78

79
```python
80
import pyfiglet
81

82
# RGB foreground and background
83
pyfiglet.print_figlet("RGB Colors", colors="255;100;50:0;128;255")
84

85
# RGB foreground only
86
pyfiglet.print_figlet("RGB Foreground", colors="200;50;100:")
87

88
# RGB background only
89
pyfiglet.print_figlet("RGB Background", colors=":50;200;100")
90
```
91

92
### Advanced Color Usage
93

94
```python
95
from pyfiglet import parse_color, color_to_ansi, print_figlet
96

97
# Generate ANSI codes manually
98
fg_code = color_to_ansi("RED", False)
99
bg_code = color_to_ansi("BLUE", True)
100
reset_code = "\033[0m"
101

102
print(f"{fg_code}{bg_code}Colored Text{reset_code}")
103

104
# Parse complex color specifications
105
ansi_codes = parse_color("LIGHT_GREEN:DARK_GRAY")
106
print(f"{ansi_codes}Terminal Text\033[0m")
107

108
# Programmatic color application
109
colors = ["red:black", "green:white", "blue:yellow"]
110
for i, color in enumerate(colors):
111
    print_figlet(f"Line {i+1}", colors=color, font="small")
112
```
113

114
## Named Colors
115

116
PyFiglet supports the following named colors via the `COLOR_CODES` constant:
117

118
### Standard Colors
119
- **BLACK** (30)
120
- **RED** (31)  
121
- **GREEN** (32)
122
- **YELLOW** (33)
123
- **BLUE** (34)
124
- **MAGENTA** (35)
125
- **CYAN** (36)
126
- **LIGHT_GRAY** (37)
127
- **DEFAULT** (39)
128

129
### Bright Colors
130
- **DARK_GRAY** (90)
131
- **LIGHT_RED** (91)
132
- **LIGHT_GREEN** (92) 
133
- **LIGHT_YELLOW** (93)
134
- **LIGHT_BLUE** (94)
135
- **LIGHT_MAGENTA** (95)
136
- **LIGHT_CYAN** (96)
137
- **WHITE** (97)
138

139
### Special
140
- **RESET** (0) - Resets all formatting
141

142
## Color Format Specifications
143

144
### Named Color Format
145
- Case-insensitive color names from `COLOR_CODES`
146
- Examples: "red", "GREEN", "Light_Blue"
147

148
### RGB Format
149
- Three semicolon-separated values: "R;G;B"
150
- Each value must be 0-255
151
- Examples: "255;0;0" (red), "128;128;128" (gray)
152

153
### Combined Format
154
- Foreground and background separated by colon
155
- Either component can be empty
156
- Examples:
157
  - "red:blue" - red text on blue background
158
  - "red:" - red text, default background
159
  - ":blue" - default text, blue background
160
  - "255;0;0:0;0;255" - red text on blue background (RGB)
161

162
## Error Handling
163

164
Color functions raise `InvalidColor` exceptions for:
165
- Invalid RGB format (wrong number of components, values outside 0-255 range)
166
- Unknown named colors  
167
- Malformed color specifications
168

169
```python
170
from pyfiglet import InvalidColor, print_figlet
171

172
try:
173
    print_figlet("Test", colors="invalid_color:bad_bg")
174
except InvalidColor as e:
175
    print(f"Color error: {e}")
176
    
177
try:
178
    print_figlet("Test", colors="300;400;500:")  # Invalid RGB values
179
except InvalidColor as e:
180
    print(f"RGB error: {e}")
181
```
182

183
## ANSI Escape Sequences
184

185
PyFiglet generates standard ANSI escape sequences:
186
- Foreground colors: `\033[{code}m`  
187
- Background colors: `\033[{code+10}m`
188
- RGB colors: `\033[38;2;R;G;Bm` (foreground) or `\033[48;2;R;G;Bm` (background)
189
- Reset: `\033[0m`
190

191
## Platform Support
192

193
Color support depends on terminal capabilities:
194
- **Full support**: Unix/Linux terminals, Windows Terminal, modern terminal emulators
195
- **Limited support**: Traditional Windows Command Prompt (basic colors only)
196
- **No support**: Non-terminal output (files, pipes) - ANSI codes appear as text
197

198
## Integration with Print Functions
199

200
The `print_figlet()` function automatically handles:
201
- Color code generation and application
202
- Reset sequence after output
203
- Stdout writing for proper color display
204
- Cross-platform terminal detection