### Install Font Files

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples for installing font files or ZIP archives using -L or --load. This may require elevated privileges.

```bash
pyfiglet -L /path/to/font.flf
```

```bash
pyfiglet --load fonts_bundle.zip
```

```bash
# Install a single font
pyfiglet -L ~/Downloads/custom.flf
```

```bash
# Install a collection of fonts
pyfiglet -L ~/Downloads/fonts.zip
```

```bash
# May need sudo
sudo pyfiglet -L /tmp/fonts.zip
```

--------------------------------

### Output Width Examples

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples for setting the output width using -w or --width. This affects text wrapping and justification calculations.

```bash
pyfiglet -w 100 "Wider output"
```

```bash
pyfiglet -w 40 "Narrow output"
```

--------------------------------

### Font Selection Examples

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples demonstrating how to specify a font using the -f or --font options.

```bash
pyfiglet -f banner "Hello"
```

```bash
pyfiglet --font slant "World"
```

--------------------------------

### PyFiglet Font Management

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples for managing fonts, including listing available fonts, showing font information, installing custom fonts, and searching for fonts.

```bash
# List all fonts
pyfiglet -l | head -20
```

```bash
# Show font info
pyfiglet -i -f banner
```

```bash
# Install custom font
pyfiglet -L /path/to/fonts.zip
```

```bash
# Search for font
pyfiglet -l | grep banner
```

--------------------------------

### Quick Start: Programmatic Usage

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/README.md

Demonstrates how to use the Figlet class to render text with a specified font. Ensure the pyfiglet library is installed.

```python
from pyfiglet import Figlet

fig = Figlet(font='banner')
print(fig.renderText('Hello'))
```

--------------------------------

### Justification Examples

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples for setting text justification using -j or --justify. 'auto' adapts to direction, 'left', 'center', and 'right' align accordingly.

```bash
pyfiglet -j left "Test"
```

```bash
pyfiglet -j center "Centered"
```

```bash
pyfiglet -j right "Right-aligned"
```

--------------------------------

### FigletFont Class Quick Reference

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Instantiate FigletFont, get all fonts, check font validity, retrieve font info, and install fonts.

```python
font = FigletFont('banner')
all_fonts = FigletFont.getFonts()
is_valid = FigletFont.isValidFont('banner.flf')
info = FigletFont.infoFont('banner')
FigletFont.installFonts('/path/to/fonts.zip')
```

--------------------------------

### Command-Line Custom Font Installation

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/00-index.md

Installs custom fonts from a zip file using the command line.

```bash
# Install custom fonts
pyfiglet -L fonts.zip
```

--------------------------------

### Install Font File with PyFiglet CLI

Source: https://github.com/pwaller/pyfiglet/blob/main/README.md

Install a font file (single or ZIP archive) using the command line interface. May require root access.

```bash
pyfiglet -L <font file>
```

--------------------------------

### Minimal Example

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/11-usage-examples.md

Renders the given text using the default font. Requires importing the Figlet class.

```python
from pyfiglet import Figlet

fig = Figlet()
print(fig.renderText('Hello'))
```

--------------------------------

### PyFiglet Text Input Examples

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Demonstrates how to provide text input to pyfiglet, including single words, multiple words, and quoted phrases.

```bash
# Single word
pyfiglet Hello
```

```bash
# Multiple words (joined with space)
pyfiglet Hello World
```

```bash
pyfiglet "Hello World"
```

```bash
# With options
pyfiglet -f banner -w 100 "Long Message"
```

```bash
# No text provided (shows help)
pyfiglet
```

--------------------------------

### Install Fonts with installFonts

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/03-figlet-font.md

Installs a font file or a ZIP archive of fonts to the system font directory. It unpacks ZIP files and copies individual font files to the appropriate location.

```python
from pyfiglet import FigletFont

# Install a single font file
FigletFont.installFonts('/path/to/custom_font.flf')

# Install multiple fonts from a ZIP archive
FigletFont.installFonts('/path/to/fonts_bundle.zip')
```

--------------------------------

### Text Direction Examples

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples for setting text rendering direction using -D or --direction. 'auto' uses font metadata, 'left-to-right' forces LTR, and 'right-to-left' forces RTL.

```bash
pyfiglet -D auto "Test"
```

```bash
pyfiglet -D left-to-right "Test"
```

```bash
pyfiglet -D right-to-left "Test"
```

--------------------------------

### PyFiglet Advanced Combinations

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples combining multiple options for advanced ASCII art generation, including styling, transformations, and output normalization.

```bash
# Create title with specific styling
pyfiglet -f banner -j center -w 80 -c GREEN: "Centered Green Title"
```

```bash
# Create flipped, reversed, cleaned banner
pyfiglet -r -F -s -f standard "Transformed"
```

```bash
# Create normalized output
pyfiglet -n "One blank line before and after"
```

--------------------------------

### Example: Render ASCII Art Character by Character

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Demonstrates the process of rendering ASCII art by iterating through characters using the FigletBuilder. Ensure the FigletFont is initialized and rendering parameters are set.

```python
from pyfiglet import FigletFont, FigletBuilder

font = FigletFont('standard')
builder = FigletBuilder('Hi', font, 'left-to-right', 80, 'left')

# Render character by character
while builder.isNotFinished():
    builder.addCharToProduct()
    builder.goToNextChar()

result = builder.returnProduct()
```

--------------------------------

### Install Custom Fonts

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/11-usage-examples.md

Installs custom font files or font bundles, allowing them to be used with the Figlet class. Requires importing FigletFont and Figlet.

```python
from pyfiglet import FigletFont

# Install single font
FigletFont.installFonts('/path/to/myfont.flf')

# Install collection
FigletFont.installFonts('/path/to/fonts_bundle.zip')

# Then use it
from pyfiglet import Figlet
fig = Figlet(font='myfont')
print(fig.renderText('Hello'))
```

--------------------------------

### Basic Text Rendering

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/00-index.md

Renders the input text using the 'standard' font. Ensure the 'pyfiglet' library is installed.

```python
from pyfiglet import Figlet

fig = Figlet(font='standard')
print(fig.renderText('Hello'))
```

--------------------------------

### installFonts

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/03-figlet-font.md

Installs a font file or a ZIP archive of fonts to the system font directory, unpacking ZIP files and copying individual font files.

```APIDOC
## installFonts

### Description
Install a font file or ZIP archive of fonts to the system font directory. Unpacks ZIP files and copies individual font files. For development/site-packages installations, fonts are copied to the pyfiglet.fonts package directory. For zipped/frozen installations, fonts are copied to a user-writable directory.

### Method
`staticmethod`

### Signature
`installFonts(file_name: str) -> None`

### Parameters
#### Path Parameters
- **file_name** (str) - Required - Path to a single font file (`.flf`, `.tlf`) or ZIP archive containing fonts. ZIP files are unpacked and all entries with valid names are installed.

### Return Type
None (prints installation status to stdout)

### Example
```python
from pyfiglet import FigletFont

# Install a single font file
FigletFont.installFonts('/path/to/custom_font.flf')

# Install multiple fonts from a ZIP archive
FigletFont.installFonts('/path/to/fonts_bundle.zip')
```
```

--------------------------------

### Example FIGlet Font File Header

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/10-internal-implementation.md

An example of a complete header line for a FIGlet font file, illustrating the expected values for each field. This serves as a practical reference for font file analysis.

```text
flf2a$ 6 5 20 -1 2 0 64
```

--------------------------------

### Example Usage of FONT_DIRECTORIES

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Iterates through the FONT_DIRECTORIES tuple and prints each directory along with whether it exists as a directory on the system.

```python
from pyfiglet import FONT_DIRECTORIES
import os

print("Font search directories:")
for directory in FONT_DIRECTORIES:
    exists = "exists" if os.path.isdir(directory) else "does not exist"
    print(f"  {directory} ({exists})")
```

--------------------------------

### Complete PyFiglet Rendering Flow

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Demonstrates the high-level user-facing API for rendering text with PyFiglet, including font selection, width, and justification. This example shows the typical usage pattern.

```python
from pyfiglet import Figlet

# High level - user facing
fig = Figlet(font='banner', width=80, justify='left')
result = fig.renderText('Hello')
print(result)
```

--------------------------------

### Example Usage of DEFAULT_FONT

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Demonstrates that initializing Figlet with no font, with DEFAULT_FONT, or with the string 'standard' all produce the same output.

```python
from pyfiglet import Figlet, DEFAULT_FONT

# These are equivalent
fig1 = Figlet()
fig2 = Figlet(font=DEFAULT_FONT)
fig3 = Figlet(font='standard')

print(fig1.renderText('Test') == fig2.renderText('Test') == fig3.renderText('Test'))
```

--------------------------------

### Text Transformation: Reverse

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Example of using the -r or --reverse option to display a horizontally mirrored output.

```bash
pyfiglet -r "Mirror"
```

--------------------------------

### Figlet Class Quick Reference

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Instantiate Figlet with options and render text. Get available fonts and set a new font.

```python
fig = Figlet(font='standard', width=80, justify='auto', direction='auto')
output = fig.renderText('Text to render')
fonts = fig.getFonts()
fig.setFont(font='banner')
```

--------------------------------

### Example of a 3-Line Character Definition

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/10-internal-implementation.md

A concrete example of a 3-line character definition in a FIGlet font file, including the end markers. This demonstrates how ASCII art for a character is represented.

```text
    $$
   /$$
  /$$$$

```

--------------------------------

### PyFiglet Text Transformations

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples of applying text transformations such as mirroring (-r), flipping upside down (-F), and cleaning output (-s).

```bash
# Mirror/reverse the text
pyfiglet -r "Mirror"
```

```bash
# Upside down
pyfiglet -F "Flip"
```

```bash
# Both transformations
pyfiglet -r -F "Mirror and flip"
```

```bash
# Clean formatting
pyfiglet -s -f banner "No extra newlines"
```

--------------------------------

### PyFiglet Exit Status Example

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Illustrates checking the exit status of pyfiglet to determine success or failure, particularly for font-related errors.

```bash
pyfiglet -f standard "Test" && echo "Success" || echo "Failed"
pyfiglet -f nonexistent "Test" && echo "Success" || echo "Failed"
# Output: pyfiglet error: requested font 'nonexistent' not found.
#         Failed
```

--------------------------------

### Display Font Information

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Examples for displaying metadata from a font file using -i or --info_font. Requires specifying a font with -f or --font.

```bash
pyfiglet -i -f banner
```

```bash
pyfiglet --info_font --font slant
```

--------------------------------

### Collection Type Hints

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Shows examples of type hints for various collection types used within the library, including lists of strings, dictionaries mapping integers to lists of strings, and lists of lists of strings.

```python
list[str]       # List of font names
```

```python
dict[int, list[str]]  # Character definitions
```

```python
list[list[str]] # Line buffer queue
```

--------------------------------

### Text Transformation: Flip

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Example of using the -F or --flip option to display a vertically flipped (upside-down) output.

```bash
pyfiglet -F "Upside down"
```

--------------------------------

### Complete Text Transformation Workflow

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/04-figlet-string.md

Illustrates chaining multiple string transformations like flip, reverse, and newline stripping on rendered Figlet text. Also shows how to get normalized output and perform individual operations.

```python
from pyfiglet import Figlet

fig = Figlet(font='banner')
text = fig.renderText('HELLO')

# Chain transformations
result = text.flip().reverse().strip_surrounding_newlines()
print(result)

# Get normalized output for clean display
clean = text.normalize_surrounding_newlines()
print(f"Normalized output:\n{clean}")

# Individual operations
print("Original:")
print(text)

print("\nReversed:")
print(text.reverse())

print("\nFlipped:")
print(text.flip())
```

--------------------------------

### Handle Missing Fonts with Fallback

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/11-usage-examples.md

This example shows how to gracefully handle a `FontNotFound` error by checking if a user-specified font exists and falling back to a default font if it doesn't. It uses a try-except block to catch the specific exception.

```python
from pyfiglet import Figlet, FontNotFound, FigletFont

user_font = 'fancy_font'
fallback_font = 'standard'

try:
    if user_font in FigletFont.getFonts():
        fig = Figlet(font=user_font)
    else:
        print(f"Font '{user_font}' not found, using '{fallback_font}'")
        fig = Figlet(font=fallback_font)
    
    print(fig.renderText('Result'))

except FontNotFound as e:
    print(f"Unexpected error: {e}")
    fig = Figlet()
    print(fig.renderText('Fallback'))
```

--------------------------------

### Writing Colored Text with RESET_COLORS

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Example of writing text in red to the standard output and then resetting the color using `RESET_COLORS`. This demonstrates direct manipulation of terminal output with ANSI codes.

```python
import sys
from pyfiglet import RESET_COLORS

# Write colored text
sys.stdout.write(b'\033[31m')  # Red
sys.stdout.write(b'Red text')
sys.stdout.write(RESET_COLORS)  # Reset to default
sys.stdout.write(b'\n')
```

--------------------------------

### Example: Accessing FigletFont Character Data

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Demonstrates how to access and print the ASCII art definition and width for a specific character using FigletFont's internal storage.

```python
from pyfiglet import FigletFont

font = FigletFont('banner')

# Character for 'A' (code point 65)
char_a = font.chars[65]  # List of strings, one per line
width_a = font.width[65]  # Width in characters

print(f"Character 'A' definition ({width_a} chars wide):")
for line in char_a:
    print(line)
```

--------------------------------

### Display Help Message

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Show the help message detailing all available command-line options and their usage.

```bash
pyfiglet --help
```

--------------------------------

### FigletFont Class

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Internal class representing a loaded font, but available for advanced direct usage. It provides methods to load fonts, retrieve all available fonts, validate font files, get font information, and install new fonts.

```APIDOC
## FigletFont Class

### Description
Internal class representing a loaded font, usable for advanced scenarios. Provides methods for font management and information retrieval.

### Import
```python
from pyfiglet import FigletFont
```

### Usage Examples
```python
# Initialize FigletFont with a font name
font = FigletFont('banner')

# Get a list of all available fonts
all_fonts = FigletFont.getFonts()

# Check if a font file is valid
is_valid = FigletFont.isValidFont('banner.flf')

# Get information about a specific font
info = FigletFont.infoFont('banner')

# Install new fonts from a zip file
FigletFont.installFonts('/path/to/fonts.zip')
```
```

--------------------------------

### Basic Rendering via Command-Line

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/CONTENTS.txt

Shows how to render text using the pyfiglet command-line interface with a specific font. This is a quick way to generate ASCII art without writing Python code.

```bash
pyfiglet -f banner "Hello"
```

--------------------------------

### Get Font Information

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/11-usage-examples.md

Retrieves detailed information about a specific font, with an option to get only the title. Requires importing the FigletFont class.

```python
from pyfiglet import FigletFont

info = FigletFont.infoFont('banner')
print("Font info:")
print(info)

# Short version (first line only)
short_info = FigletFont.infoFont('banner', short=True)
print("Title:", short_info)
```

--------------------------------

### Command-Line Advanced Rendering

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/00-index.md

Uses command-line options for centering, coloring, and custom width.

```bash
# Centered, colored, custom width
pyfiglet -j center -w 100 -c GREEN: "Announcement"
```

--------------------------------

### Initialize FigletBuilder

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Initializes the builder with text and rendering parameters. Use this to set up the ASCII art generation process.

```python
def __init__(self, text: str, font: FigletFont, direction: str, 
             width: int, justify: str) -> None
```

--------------------------------

### Processed Character Example

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/10-internal-implementation.md

The result of processing the example 3-line character definition after removing end markers and trimming whitespace. This shows the clean ASCII art representation.

```text
    
   /
  /

```

--------------------------------

### PyFiglet Piping and Redirection

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Demonstrates how to use shell redirection to save output to a file and piping to process output with other commands.

```bash
# Save to file
pyfiglet -f banner "Title" > output.txt
```

```bash
# Pipe to another command
pyfiglet "Test" | cat
```

```bash
# Strip newlines when piping
pyfiglet -s "Clean" | tr '\n' ' '
```

```bash
# Append to file
pyfiglet -f slant "Appendage" >> output.txt
```

--------------------------------

### Import COLOR_CODES

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Access the COLOR_CODES dictionary to get ANSI color codes for terminal output.

```python
from pyfiglet import COLOR_CODES

for color_name in COLOR_CODES.keys():
    print(color_name)
```

--------------------------------

### Instantiate FigletFont Class

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/03-figlet-font.md

Demonstrates how to instantiate the FigletFont class to load a specific FIGlet font. This is rarely needed by users as the Figlet class handles font loading internally. Shows how to access font height and hard blank properties.

```python
from pyfiglet import FigletFont

# Load a font (rarely needed by users)
font = FigletFont(font='slant')
print(f"Font height: {font.height}")
print(f"Hard blank: {font.hardBlank}")
```

--------------------------------

### Import main Function

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Import the main function, the CLI entry point for the pyfiglet command.

```python
from pyfiglet import main
```

--------------------------------

### Example Usage of SHARED_DIRECTORY

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Prints the value of the SHARED_DIRECTORY constant and checks if the directory actually exists on the filesystem.

```python
from pyfiglet import SHARED_DIRECTORY
import os

print(f"Shared font directory: {SHARED_DIRECTORY}")
print(f"Directory exists: {os.path.exists(SHARED_DIRECTORY)}")
```

--------------------------------

### Basic PyFiglet Rendering

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Shows how to render simple ASCII art with the default font and with specified fonts like 'banner' and 'slant'.

```bash
# Simple ASCII art
pyfiglet "Hello"
```

```bash
# Different font
pyfiglet -f banner "Title"
```

```bash
# Slant font
pyfiglet -f slant "Welcome"
```

--------------------------------

### FigletString Type Example

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/04-figlet-string.md

Demonstrates that the output of fig.renderText() is an instance of the FigletString class, which is also a subclass of str.

```python
from pyfiglet import Figlet

fig = Figlet()
result = fig.renderText('Hello')
print(type(result))  # <class 'pyfiglet.FigletString'>
print(isinstance(result, str))  # True (also a string)
```

--------------------------------

### Demonstrate Color Combinations

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/11-usage-examples.md

Illustrates various color combinations, including named foreground and background colors, and RGB specifications for both. This helps visualize different text and background effects.

```python
from pyfiglet import print_figlet

combinations = [
    ('RED:', 'Red text'),
    ('GREEN:YELLOW', 'Green on yellow'),
    ('LIGHT_BLUE:BLACK', 'Light blue on black'),
    ('255;0;0:255;255;0', 'Red on yellow (RGB)'),
]

for color_spec, label in combinations:
    print(f"{label}:")
    print_figlet('Text', colors=color_spec)
    print()
```

--------------------------------

### color_to_ansi Function Usage

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Get ANSI escape codes for foreground and background colors using color_to_ansi.

```python
fg_code = color_to_ansi('RED', isBackground=False)
bg_code = color_to_ansi('BLUE', isBackground=True)
```

--------------------------------

### PyFiglet Formatting Options

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Demonstrates using formatting options like justification (-j) and width (-w) to control the appearance of the ASCII art.

```bash
# Centered, 100 chars wide
pyfiglet -j center -w 100 "Announcement"
```

```bash
# Right-aligned in 80 chars
pyfiglet -j right "Right text"
```

```bash
# Wrapped at 50 chars
pyfiglet -w 50 "This is a very long line that will wrap at spaces"
```

--------------------------------

### Character Rendering Process

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/10-internal-implementation.md

A simplified, step-by-step trace of how the pyfiglet library renders text using a specified font. It illustrates character loading, buffer initialization, rendering individual characters with smushing, and final output formatting.

```text
Step 1: Load font
  - height = 6
  - hardBlank = '$'
  - chars[ord('H')] = [' _   _  ', '| | | | ', '| |_| | ', '|  _  | ', '| | | | ', '|_| |_| ']
  - chars[ord('i')] = [' _ ', '| |', '| |', '| |', '| |', '|_|']

Step 2: Initialize builder
  - text = [72, 105]  (H, i)
  - buffer = ['', '', '', '', '', '']
  - iterator = 0

Step 3: Render 'H'
  - curChar = chars[72]
  - maxSmush = 0 (no previous character)
  - Add to buffer:
    buffer = [' _   _  ', '| | | | ', '| |_| | ', '|  _  | ', '| | | | ', '|_| |_| ']
  - iterator = 1

Step 4: Render 'i'
  - curChar = chars[105]
  - Calculate smush:
    - Check each line for overlap
    - Find safe smushing amount (typically 1)
  - maxSmush = 1
  - Apply smush and add:
    buffer = [' _   _  _ ',
              '| | | || |',
              '| |_| || |',
              '|  _  || |',
              '| | | || |',
              '|_| |_||_|']
  - iterator = 2

Step 5: Format output
  - Join with newlines
  - Replace hard blanks (none in this case)
  - Apply justification (none for left align)
  - Return as FigletString
```

--------------------------------

### Import Figlet Class

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Import the main Figlet class for ASCII art rendering.

```python
from pyfiglet import Figlet
```

--------------------------------

### Text Transformation: Strip Newlines

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Example of using the -s or --strip-surrounding-newlines option to remove leading and trailing empty lines.

```bash
pyfiglet -s "No extra newlines"
```

--------------------------------

### main Function Usage

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Execute the pyfiglet CLI entry point by calling the main function and exiting with its status code.

```python
import sys

sys.exit(main())
```

--------------------------------

### FigletProduct Constructor

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Initializes an empty product for accumulating rendered output.

```python
def __init__(self) -> None:
    pass
```

--------------------------------

### Initialize FigletRenderingEngine

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Demonstrates the initialization of the rendering engine. Users typically do not create this class directly; it's managed by the Figlet instance.

```python
from pyfiglet import Figlet, FigletRenderingEngine

fig = Figlet()
# Engine is created automatically:
# engine = FigletRenderingEngine(base=fig)
```

--------------------------------

### Text Transformation: Normalize Newlines

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Example of using the -n or --normalize-surrounding-newlines option to ensure exactly one blank line before and after the text.

```bash
pyfiglet -n "Normalized spacing"
```

--------------------------------

### List Available Colors

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Use the '-c list' command to display all supported color names and their RGB equivalents.

```bash
pyfiglet -c list
```

--------------------------------

### Advanced PyFiglet Font Operations

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Covers listing available fonts, checking font existence, retrieving font information, and installing new fonts.

```python
from pyfiglet import FigletFont, Figlet

# List fonts
all_fonts = FigletFont.getFonts()
print(f"Available: {len(all_fonts)} fonts")

# Check specific font
if 'banner' in all_fonts:
    fig = Figlet(font='banner')
else:
    fig = Figlet()

# Get font info
info = FigletFont.infoFont('banner')
print(f"Banner font info: {info}")

# Install new fonts
FigletFont.installFonts('fonts.zip')
```

--------------------------------

### Get Text Rendering Direction

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/01-figlet-class.md

Access the `direction` property to determine if text is rendered left-to-right or right-to-left. Initialization with 'auto' infers direction from the font.

```python
fig = Figlet(font='standard', direction='auto')
print(fig.direction)  # 'left-to-right'

fig = Figlet(font='standard', direction='right-to-left')
print(fig.direction)  # 'right-to-left'
```

--------------------------------

### Listing Available Colors with COLOR_CODES

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Demonstrates how to iterate through the `COLOR_CODES` dictionary to list all available color names. This snippet shows a practical way to inspect the supported color options.

```python
from pyfiglet import COLOR_CODES

# List all available colors
print("Available colors:")
for color_name in COLOR_CODES.keys():
    print(f"  {color_name}")

# Use in color specifications
color_spec = f"{list(COLOR_CODES.keys())[0]}:BLUE"  # BLACK:BLUE
```

--------------------------------

### Figlet Font Operations Signatures

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Provides type signatures for class methods related to font management, including getting available fonts, preloading, and validation.

```python
@classmethod
def getFonts(cls) -> list[str]
```

```python
@classmethod
def preloadFont(cls, font: str) -> str
```

```python
@classmethod
def isValidFont(cls, font: str) -> bool
```

```python
def setFont(self, **kwargs: str) -> None
```

--------------------------------

### Initialize Figlet Renderer

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/01-figlet-class.md

Initializes a Figlet renderer with specified font and rendering parameters. Use this to set up custom ASCII art generation.

```python
from pyfiglet import Figlet

# Basic usage with default font
fig = Figlet()
print(fig.renderText('Hello'))

# Using a specific font
fig = Figlet(font='slant')
print(fig.renderText('World'))

# With custom rendering options
fig = Figlet(font='banner', width=100, justify='center')
print(fig.renderText('Centered Text'))

# Right-to-left text
fig = Figlet(font='standard', direction='right-to-left')
print(fig.renderText('שלום'))
```

--------------------------------

### Get Available Fonts with getFonts

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/03-figlet-font.md

Retrieves a list of all available font names from package resources and system directories, filtering for valid FIGlet/Toilet font files.

```python
from pyfiglet import FigletFont

fonts = FigletFont.getFonts()
print(f"Total available fonts: {len(fonts)}")
print("Sample fonts:", fonts[:10])
print("Specific font available:", 'banner' in fonts)
```

--------------------------------

### Basic PyFiglet Usage

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Demonstrates the fundamental way to create a Figlet object and render text.

```python
from pyfiglet import Figlet

fig = Figlet(font='banner')
print(fig.renderText('Hello World'))
```

--------------------------------

### Import FigletString Class

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Import FigletString and Figlet for rendering text that returns a FigletString object.

```python
from pyfiglet import FigletString, Figlet
```

--------------------------------

### FIGcharacter with Code Tag Example

Source: https://github.com/pwaller/pyfiglet/blob/main/doc/figfont.txt

Demonstrates how to define FIGcharacters with explicit character codes using code tags. The number preceding the FIGcharacter is its Unicode code point.

```plaintext
161  INVERTED EXCLAMATION MARK
                        | _ @
                        |(_)
                        || |
                        || |
                        ||_|
                        |   @@
                        |162  CENT SIGN
                        |   _  @
                        |  | | @
                        | / __)@
                        || (__ @
                        | \   )@
                        |  |_| @@
```

--------------------------------

### Format Text to ASCII Art String

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/02-functions.md

Use `figlet_format` to render text as ASCII art and get the result as a string. It supports specifying fonts, width, and justification.

```python
from pyfiglet import figlet_format

# Basic usage
output = figlet_format('Hello')
print(output)

# With a specific font
output = figlet_format('World', font='banner')
print(output)

# With custom width and justification
output = figlet_format('Centered', font='slant', width=120, justify='center')
print(output)

# All in one-liner
print(figlet_format('Test', font='block', width=100, direction='left-to-right'))
```

--------------------------------

### Basic PyFiglet Command Structure

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

The fundamental structure for using pyfiglet, accepting options followed by text arguments.

```bash
pyfiglet [OPTIONS] TEXT [TEXT...]
```

--------------------------------

### Get List of Available Fonts

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/01-figlet-class.md

Call `getFonts` to retrieve a list of all font names available for use with the Figlet instance. This is useful for discovering and selecting different ASCII art styles.

```python
fig = Figlet()
available_fonts = fig.getFonts()
print(f"Total fonts available: {len(available_fonts)}")
print("First 5 fonts:", available_fonts[:5])
print("'slant' available:", 'slant' in available_fonts)
```

--------------------------------

### Get Text Justification Setting

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/01-figlet-class.md

Retrieve the `justify` property to see how text is aligned. 'auto' justification depends on the text's direction. Supported values are 'left', 'center', and 'right'.

```python
fig = Figlet(font='standard', justify='auto')
print(fig.justify)  # 'left' for LTR fonts

fig = Figlet(font='standard', justify='center')
print(fig.justify)  # 'center'
```

--------------------------------

### Display Version Information

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Print the current version of PyFiglet and exit the program.

```bash
pyfiglet --version
```

--------------------------------

### Print Figlet with Colors

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/CONTENTS.txt

Demonstrates how to print text using PyFiglet with specified foreground and background colors. Ensure the 'colors' parameter is correctly formatted.

```python
from pyfiglet import print_figlet
print_figlet('Text', colors='RED:BLUE')
```

--------------------------------

### Convenience Functions

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/CONTENTS.txt

Provides utility functions for quick string rendering, colored output, and color parsing.

```APIDOC
## Functions

- `figlet_format(text, font='standard', ...)`: A convenient function to render text directly without instantiating the `Figlet` class.
- `print_figlet(text, font='standard', color=None, ...)`: Renders text and prints it to the console, with support for color output.
- `parse_color(color_spec)`: Parses a color specification string into a usable format.
- `color_to_ansi(color)`: Converts a color representation into ANSI escape codes for terminal output.
```

--------------------------------

### Font Preloading for Faster Lookups

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/11-usage-examples.md

Shows how to preload frequently used fonts into a dictionary for quick access. If a font is not preloaded, it falls back to creating a new Figlet instance.

```python
from pyfiglet import Figlet, FigletFont

# Preload fonts you'll use frequently
fonts = {}
for font_name in ['banner', 'slant', 'standard', 'block']:
    try:
        fonts[font_name] = Figlet(font=font_name)
    except:
        pass

# Fast lookups
def render(text, font='standard'):
    if font in fonts:
        return fonts[font].renderText(text)
    else:
        return Figlet(font=font).renderText(text)
```

--------------------------------

### Internal State During Rendering

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Illustrates the step-by-step changes in the internal buffer during the rendering of text, showing how characters are added and how smushing affects the output. This is useful for understanding the rendering process at a lower level.

```python
# Initial state
buffer = ['', '', '', '', '', '']  # One empty string per font height

# After 'H'
buffer = ['  _',
          ' | |',
          ' | |',
          ' |_|',
          ' | |',
          ' | |']

# After 'He' (with smushing)
buffer = ['  _         ',
          ' | |  ___',
          ' | | / _ \',
          ' |_| |  __/',
          ' | | | |',
          ' | | | |']

# ... continues for each character
```

--------------------------------

### FigletBuilder Constructor

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Initializes the builder with text and rendering parameters. It sets up the internal state required for character-by-character ASCII art generation.

```APIDOC
## FigletBuilder Constructor

### Description
Initialize the builder with text and rendering parameters.

### Method Signature
```python
def __init__(self, text: str, font: FigletFont, direction: str, width: int, justify: str) -> None
```

### Parameters
#### Path Parameters
- **text** (str) - Required - Text to render (converted to list of Unicode codepoints).
- **font** (FigletFont) - Required - Font object with character definitions.
- **direction** (str) - Required - Text direction: `'left-to-right'` or `'right-to-left'`.
- **width** (int) - Required - Output width constraint in characters.
- **justify** (str) - Required - Justification: `'left'`, `'center'`, or `'right'`.

### Return type
None

### Example
```python
from pyfiglet import FigletFont, FigletBuilder

font = FigletFont('standard')
builder = FigletBuilder('Hi', font, 'left-to-right', 80, 'left')
```
```

--------------------------------

### Basic pyfiglet Invocation

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

The general syntax for invoking the pyfiglet command-line tool. If TEXT is omitted, help is displayed.

```bash
pyfiglet [OPTIONS] [TEXT...]
```

--------------------------------

### Optional Parameter Type Hint

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/06-types-and-constants.md

Demonstrates how to define an optional parameter with a default value using type hints. This is useful for parameters that have a sensible default.

```python
font: str = DEFAULT_FONT
```

--------------------------------

### Python Type Hints for PyFiglet

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/00-index.md

Demonstrates the use of Python type hints for static analysis with tools like mypy and pyright. This snippet shows how to import necessary types and annotate variables related to the Figlet class and its methods.

```python
from pyfiglet import Figlet
from typing import List

fig: Figlet = Figlet(font='banner')
fonts: List[str] = fig.getFonts()
output: str = fig.renderText('Test')
```

--------------------------------

### PyFiglet Error Handling

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Illustrates how to handle potential exceptions like FontNotFound, CharNotPrinted, and general FigletError during rendering.

```python
from pyfiglet import Figlet, FontNotFound, CharNotPrinted, FigletError

try:
    fig = Figlet(font='banner', width=100)
    output = fig.renderText('Long text with many words')
except FontNotFound:
    print("Font not found")
except CharNotPrinted:
    print("Text too wide")
except FigletError as e:
    print(f"Figlet error: {e}")
```

--------------------------------

### main Function

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

The command-line interface (CLI) entry point for pyfiglet. This function is invoked when the `pyfiglet` command is executed from the terminal.

```APIDOC
## main Function

### Description
CLI entry point. Called by the `pyfiglet` command.

### Import
```python
from pyfiglet import main
import sys
```

### Usage Example
```python
# This is typically called by the system when running the pyfiglet command
sys.exit(main())
```
```

--------------------------------

### returnProduct

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/07-rendering-engine.md

Completes the ASCII art rendering process, flushes any remaining buffer content, justifies lines, and returns the final output as a FigletString.

```APIDOC
## returnProduct

### Description
Complete rendering and return the final output.

### Method Signature
```python
def returnProduct(self) -> FigletString
```

### Process
1. Flushes any remaining buffer content
2. Justifies all lines
3. Replaces hardblank characters with spaces
4. Returns as `FigletString`

### Return type
FigletString

### Example
```python
result = builder.returnProduct()
```
```

--------------------------------

### No Text Provided Usage

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Shows the usage information displayed when the pyfiglet command is run without any text arguments.

```bash
$ pyfiglet
Usage: pyfiglet [options] [text..]

Options:
  -f FONT, --font FONT          font to render with (default: standard)
  ...

```

--------------------------------

### PyFiglet Color Output

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/08-cli-reference.md

Shows how to apply colors to the generated ASCII art using predefined color names or RGB values.

```bash
# Red text
pyfiglet -c RED: "Important"
```

```bash
# Blue background
pyfiglet -c :BLUE "Highlighted"
```

```bash
# RGB colors
pyfiglet -c 255;100;50: "Orange"
```

```bash
# List available colors
pyfiglet -c list
```

--------------------------------

### Render Figlet Text with Type Hints

Source: https://github.com/pwaller/pyfiglet/blob/main/_autodocs/09-module-api.md

Demonstrates how to render text using pyfiglet with type annotations. Use this function for static type checking with tools like mypy or pyright.

```python
from typing import List, Optional
from pyfiglet import Figlet, FigletString, FigletError

# All parameters and returns are typed
def render_figlet(text: str, 
                  font: str = 'standard',
                  width: int = 80) -> FigletString:
    fig = Figlet(font=font, width=width)
    return fig.renderText(text)

# Type checkers (mypy, pyright) will validate usage
output: FigletString = render_figlet('Test')
fonts: List[str] = Figlet().getFonts()
```