Metadata-Version: 2.4
Name: formatting-library
Version: 1.2.4
Summary: A Python library for terminal text formatting, colors, and ASCII art
Project-URL: Homepage, https://github.com/Kundaliel/terminal_formatter
Project-URL: Repository, https://github.com/Kundaliel/terminal_formatter
Project-URL: Issues, https://github.com/Kundaliel/terminal_formatter/issues
Project-URL: PyPI, https://pypi.org/project/formatting-library/
Author-email: Kundaliel <kundaliel.official@gmail.com>
License: MIT License
        Copyright (c) 2025 Kundaliel
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: C,ansi,ascii,colors,formatting,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Terminals
Classifier: Topic :: Text Processing
Requires-Python: >=3.8
Requires-Dist: pillow>=8.0.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: pytest>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Kundaliel's Formatting Library

[![PyPI version](https://badge.fury.io/py/formatting-library.svg)](https://badge.fury.io/py/formatting-library)
[![Python versions](https://img.shields.io/pypi/pyversions/formatting-library.svg)](https://pypi.org/project/formatting-library/)

A Python library for terminal text formatting, colors, and ASCII art rendering.

## Features

- RGB color support for foreground and background
- Rainbow text effects
- Image to ASCII art conversion
- Animated/slow printing
- Text color codes
- Terminal cursor control and manipulation
- C library integration for performance-critical operations
- Esoteric programming language execution (Befunge, LOLCODE)

## Installation

```bash
pip install formatting-library
```

## Quick Start

```python
from terminal_formatter import rainbow_text, slow_print, img_to_ascii

# Rainbow text
print(rainbow_text("Hello, World!"))

# Slow printing with custom speed
slow_print("This text appears slowly...", speed=20)

# Convert image to ASCII art
ascii_art = img_to_ascii("path/to/image.jpg")
print(ascii_art)
```

## Documentation

### Color Functions

```python
from terminal_formatter import rgb_fore, rgb_back, RGB, RESET

# Using RGB values directly
print(f"{rgb_fore([255, 0, 0])}Red text{RESET}")

# Using RGB class
red = RGB(255, 0, 0)
print(f"{red.to_foreground()}Red text{RESET}")

# Background colors
print(f"{rgb_back([0, 255, 0])}Green background{RESET}")
```

### Rainbow Text

```python
from terminal_formatter import rainbow_text

# Foreground rainbow
print(rainbow_text("This text has rainbow colors!"))

# Background rainbow
print(rainbow_text("Rainbow background!", background=True))
```

### Terminal Control

```python
from terminal_formatter import clear_screen, set_cursor_position, Terminal

# Clear the screen
clear_screen()

# Move cursor to specific position
set_cursor_position(10, 5)  # Move cursor to row 10, column 5

# Replace current line
Terminal.replace_current_line("New text on this line")
```

### Text Formatting

```python
from terminal_formatter import align, substitute

# Text alignment
text = "Hello World"
print(align(text, 20, "center"))   # Center align in 20 characters
print(align(text, 20, "right"))    # Right align
print(align(text, 20, "left"))     # Left align

# Text substitution
original = "Hello World"
modified = substitute(original, "Python", 6)  # Replace from position 6
print(modified)  # Output: "Hello Python"
```

### Slow Printing

```python
from terminal_formatter import slow_print, PrintOptions, RGB

# Basic slow print
slow_print("This appears character by character!")

# Custom options
options = PrintOptions(
    speed=15.0,  # Characters per second
    text_color=[255, 100, 50],  # Orange text
    background_color=[0, 0, 0],  # Black background
    newline_delay=1.0  # Pause at newlines
)
slow_print("Customized slow text!", options)
```

### Text Color Codes

```python
from terminal_formatter import formatted

# Use text color codes
text = "&cRed &aGreen &9Blue &lBold &nUnderline &rReset"
print(formatted(text))

# Available codes:
# &0-&f: Colors (0=black, f=white, etc.)
# &l: Bold
# &n: Underline  
# &o: Italic
# &r: Reset
```

### Image to ASCII Art

```python
from terminal_formatter import img_to_ascii

# Convert any image to colorful ASCII art
ascii_art = img_to_ascii("photo.jpg")
print(ascii_art)

# Works with various image formats: JPG, PNG, GIF, etc.
```

### Print Boxes

```python
from terminal_formatter import ccb_gen

# Create decorative text boxes
ccb_gen("Important Message")
# Output:
# # ================= #
# # Important Message #
# # ================= #
```

## Advanced Usage

### Custom RGB Colors

```python
from terminal_formatter import RGB, ColorFuncs

# Create RGB color objects
red = RGB(255, 0, 0)
green = RGB(0, 255, 0)
blue = RGB(0, 0, 255)

# Use in dual colors (background + foreground)
print(f"{red.to_dual(blue)}Red background, blue text{RESET}")

# Static methods
print(f"{ColorFuncs.rgb_fore([128, 64, 192])}Custom purple{RESET}")
```

### Terminal Manipulation

```python
from terminal_formatter import Terminal

# Terminal control
Terminal.scroll_cursor(-3)  # Move cursor up 3 lines
Terminal.replace_line(5, "New content for line 5")
Terminal.set_cursor_position(1, 1)  # Top-left corner
```

### Esoteric Programming Languages

Execute esoteric programming languages directly from Python:

```python
from terminal_formatter import Esoteric, runBefunge, runLOLCODE

# Run Befunge programs
Esoteric.runBefunge("hello.bf")

# Run LOLCODE programs
Esoteric.runLOLCODE("hello.lol")

# Or use the convenient aliases
runBefunge("program.bf")
runLOLCODE("script.lol")
```

**Supported Languages:**
- **Befunge**: A two-dimensional esoteric programming language
  - Supported platforms: Linux, macOS
- **LOLCODE**: An esoteric language based on lolspeak
  - Supported platforms: Linux, macOS, Windows

**Requirements:**
- Language interpreters are included in the package under `_bin/` directory
- Executables are platform-specific and selected automatically

**Example Befunge Program (hello.bf):**
```befunge
"!dlroW ,olleH">:#,_@
```

**Example LOLCODE Program (hello.lol):**
```lolcode
HAI 1.2
  VISIBLE "Hello, World!"
KTHXBYE
```

### C Library Integration

⚠️ **Security Warning**: The CBuilder class uses `os.system()` to compile C code and creates directories on your filesystem. Only use with trusted C source files and in secure environments. The build process will:
- Execute GCC compiler commands via shell
- Create a `build/` directory in the specified location
- Generate `.so` shared library files
- Overwrite existing files with the same name

For performance-critical operations, you can compile and use C libraries:

```c
// main.c
#include <stdio.h>
#include <stdint.h>

void say(char *input) {
    printf("%s\n", input);
}

int fast_multiply(int a, int b) {
    return a * b;
}
```

```python
# main.py
from terminal_formatter import CBuilder
import ctypes

# Build the C library
builder = CBuilder(".", "main")

# Define functions with proper types
say = builder.define_function("say", [ctypes.c_char_p])
multiply = builder.define_function("fast_multiply", 
                                 [ctypes.c_int, ctypes.c_int], 
                                 ctypes.c_int)

# Use the functions
say(b"Hello from C!")
result = multiply(42, 24)
print(f"42 * 24 = {result}")
```

## Color Reference

### Rainbow Colors
The built-in rainbow uses these RGB values:
- Light Red: `(255, 179, 179)`
- Light Orange: `(255, 217, 179)`
- Light Yellow: `(255, 255, 179)`
- Light Green: `(179, 255, 179)`
- Light Blue: `(179, 179, 255)`
- Light Purple: `(217, 179, 255)`

### Text Color Codes
- `&0` - Black
- `&1` - Dark Blue
- `&2` - Dark Green
- `&3` - Dark Aqua
- `&4` - Dark Red
- `&5` - Dark Purple
- `&6` - Gold
- `&7` - Gray
- `&8` - Dark Gray
- `&9` - Blue
- `&a` - Green
- `&b` - Aqua
- `&c` - Red
- `&d` - Light Purple
- `&e` - Yellow
- `&f` - White
- `&l` - Bold
- `&n` - Underline
- `&o` - Italic
- `&r` - Reset

## Requirements

- Python 3.8+
- Pillow (for image processing)
- GCC (for C library compilation)
- Platform-specific esoteric language interpreters (included in package)

## Examples

### Create a Colorful Banner

```python
from terminal_formatter import rainbow_text, ccb_gen, clear_screen

clear_screen()
ccb_gen("WELCOME")
print()
print(rainbow_text("- Terminal Formatter Demo -"))
print(rainbow_text("=" * 50))
```

### Animated Greeting

```python
from terminal_formatter import slow_print, PrintOptions, clear_screen

clear_screen()
options = PrintOptions(speed=10, text_color=[0, 255, 0])
slow_print("Hello! Welcome to Terminal Formatter!", options)
```

### Image Gallery

```python
from terminal_formatter import img_to_ascii
import os

for filename in os.listdir("images/"):
    if filename.lower().endswith(('.png', '.jpg', '.jpeg')):
        print(f"\n--- {filename} ---")
        print(img_to_ascii(f"images/{filename}"))
```

### Esoteric Language Runner

```python
from terminal_formatter import runBefunge, runLOLCODE

# Create a simple Befunge program
with open("countdown.bf", "w") as f:
    f.write("""\
>                                        v
@,*25,++:*:*:+111,,,,,,,,,,,"Hello World"<
    """)

# Run it
print("Running Befunge countdown:")
runBefunge("countdown.bf")

# Create a LOLCODE program
with open("greeting.lol", "w") as f:
    f.write("""
HAI 1.4
  VISIBLE "O HAI, can I haz cheezburger?"
KTHXBYE
""")

# Run it
print("\nRunning LOLCODE greeting:")
runLOLCODE("greeting.lol")
```

### Performance Comparison

```python
from terminal_formatter import CBuilder, ctypes
import time

# Python version
def python_factorial(n):
    if n <= 1:
        return 1
    return n * python_factorial(n - 1)

# C version (factorial.c)
builder = CBuilder(".", "factorial")
c_factorial = builder.define_function("factorial", [ctypes.c_int], ctypes.c_int)

# Benchmark
start = time.time()
python_result = python_factorial(20)
python_time = time.time() - start

start = time.time()
c_result = c_factorial(20)
c_time = time.time() - start

print(f"Python: {python_result} ({python_time:.6f}s)")
print(f"C: {c_result} ({c_time:.6f}s)")
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Changelog

### v1.2.0
- Added Esoteric class for running esoteric programming languages
- Support for Befunge execution on Linux and macOS
- Support for LOLCODE execution on Linux, macOS, and Windows
- New convenience aliases: `runBefunge` and `runLOLCODE`

### v1.1.0
- Added CBuilder class for C library integration
- Support for compiling and loading C shared libraries
- Dynamic function binding with ctypes
- Performance optimization through C extensions

### v1.0.0
- Initial release with RGB color support
- Rainbow text effects
- Image to ASCII conversion
- Terminal control functions
- Text formatting utilities