0
# Color and Style Optimization
1

2
Low-level optimization functions for processing color stacks using deterministic push-down automaton algorithms. These functions are used internally by HueString to minimize ANSI escape sequences while maintaining visual consistency and preventing terminal color pollution.
3

4
## Capabilities
5

6
### String Colorization
7

8
Apply optimized ANSI escape sequences to a string based on a color/style stack.
9

10
```python { .api }
11
def colorize(string: str, stack: tuple) -> str:
12
    """
13
    Apply optimal ANSI escape sequences to the string.
14
    
15
    Args:
16
        string (str): The text to colorize
17
        stack (tuple): Tuple of color/style codes to apply
18
        
19
    Returns:
20
        str: String with ANSI escape sequences applied, or original string if no codes
21
    """
22
```
23

24
**Usage:**
25
```python
26
from hues.huestr import colorize
27
from hues.colortable import FG, BG, STYLE
28

29
# Apply red foreground and black background
30
result = colorize('Hello', (FG.red, BG.black))
31
print(result)  # \033[31;40mHello\033[0m
32
```
33

34
### Reset Handling
35

36
Handle reset codes in color stacks, breaking the stack when a reset (zero) is encountered.
37

38
```python { .api }
39
def zero_break(stack: tuple) -> tuple:
40
    """
41
    Handle Resets in input stack.
42
    Breaks the input stack if a Reset operator (zero) is encountered.
43
    
44
    Args:
45
        stack (tuple): Input stack of color/style codes
46
        
47
    Returns:
48
        tuple: Stack with everything before reset removed
49
    """
50
```
51

52
**Usage:**
53
```python
54
from hues.dpda import zero_break
55
from hues.colortable import FG, STYLE
56

57
# Reset clears previous styles
58
stack = (FG.red, FG.blue, STYLE.reset, FG.green)
59
result = zero_break(stack)
60
print(result)  # (32,) - only green remains
61
```
62

63
### Color Squashing
64

65
Remove duplicate colors of the same type, keeping only the last occurrence.
66

67
```python { .api }
68
def annihilate(predicate: tuple, stack: tuple) -> tuple:
69
    """
70
    Squash and reduce the input stack.
71
    Removes elements matching predicate, keeping only the last match.
72
    
73
    Args:
74
        predicate (tuple): Tuple of codes to match and squash
75
        stack (tuple): Input stack of color/style codes
76
        
77
    Returns:
78
        tuple: Stack with duplicates removed, last match preserved
79
    """
80

81
def annihilator(predicate: tuple):
82
    """
83
    Build a partial annihilator for given predicate.
84
    
85
    Args:
86
        predicate (tuple): Codes to create annihilator for
87
        
88
    Returns:
89
        function: Partial function for annihilating those codes
90
    """
91
```
92

93
**Usage:**
94
```python
95
from hues.dpda import annihilate, annihilator
96
from hues.colortable import FG
97

98
# Remove duplicate foreground colors, keep last
99
stack = (FG.red, FG.blue, FG.green)
100
result = annihilate(FG, stack)
101
print(result)  # (32,) - only green remains
102

103
# Create reusable annihilator
104
fg_annihilator = annihilator(FG)
105
result = fg_annihilator(stack)
106
```
107

108
### Deduplication
109

110
Remove duplicate style codes while preserving order.
111

112
```python { .api }
113
def dedup(stack: tuple) -> tuple:
114
    """
115
    Remove duplicates from the stack in first-seen order.
116
    
117
    Args:
118
        stack (tuple): Input stack of color/style codes
119
        
120
    Returns:
121
        tuple: Stack with duplicates removed, first occurrence kept
122
    """
123
```
124

125
**Usage:**
126
```python
127
from hues.dpda import dedup
128
from hues.colortable import STYLE
129

130
# Remove duplicate styles
131
stack = (STYLE.bold, STYLE.italic, STYLE.bold, STYLE.underline)
132
result = dedup(stack)
133
print(result)  # (1, 3, 4) - bold appears only once
134
```
135

136
### Function Application
137

138
Apply a sequence of optimization functions to a stack.
139

140
```python { .api }
141
def apply(funcs: tuple, stack: tuple) -> tuple:
142
    """
143
    Apply functions to the stack, passing result to next function.
144
    
145
    Args:
146
        funcs (tuple): Tuple of functions to apply in sequence
147
        stack (tuple): Initial stack to process
148
        
149
    Returns:
150
        tuple: Final processed stack
151
    """
152
```
153

154
**Usage:**
155
```python
156
from hues.dpda import apply, zero_break, dedup
157
from hues.colortable import FG, STYLE
158

159
# Apply multiple optimization steps
160
stack = (FG.red, STYLE.bold, STYLE.reset, FG.blue, STYLE.bold)
161
optimizations = (zero_break, dedup)
162
result = apply(optimizations, stack)
163
print(result)  # (34, 1) - blue and bold after reset
164
```
165

166
## Optimization Pipeline
167

168
HueString uses a standard optimization pipeline to process color stacks:
169

170
1. **zero_break**: Handle reset codes, clearing previous styles
171
2. **annihilator(FG + HI_FG)**: Squash foreground colors to last value
172
3. **annihilator(BG + HI_BG)**: Squash background colors to last value  
173
4. **dedup**: Remove duplicate style values
174

175
This ensures minimal ANSI sequences while maintaining the intended appearance:
176

177
```python
178
from functools import partial
179
from hues.dpda import zero_break, annihilator, dedup, apply
180
from hues.colortable import FG, BG, HI_FG, HI_BG
181

182
OPTIMIZATION_STEPS = (
183
    zero_break,
184
    annihilator(FG + HI_FG),
185
    annihilator(BG + HI_BG), 
186
    dedup,
187
)
188
optimize = partial(apply, OPTIMIZATION_STEPS)
189

190
# This is how HueString optimizes color stacks
191
optimized = optimize((FG.red, FG.blue, BG.white, STYLE.bold, STYLE.bold))
192
```