Metadata-Version: 2.4
Name: termcolours
Version: 0.9.3
Summary: Interactive terminal color picker
Author: pykhaz
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pyperclip
Description-Content-Type: text/markdown

# termcolours

[![CI](https://github.com/pykhaz/termcolours/actions/workflows/ci.yml/badge.svg)](https://github.com/pykhaz/termcolours/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/pykhaz/termcolours/blob/main/LICENSE)

Simple terminal colour chooser and ANSI code generator utility for Linux,
written in Python.

## Overview

`termcolours` is a small TUI (terminal user interface) utility
for working with true-colour (24-bit) ANSI escape sequences in the terminal.
It provides a simple way to generate foreground or background ANSI codes
from RGB colour values.

## Features

- Convert colours, passed as `RR;GG;BB` strings, to ANSI sequences
- Support for foreground and background colours
- Batch input (see [Usage](#usage))
- Named palettes generation (see [Usage](#usage))
- Input based on semi-colon separated RGB triplets
- Designed as a terminal application.

## Dependencies

- `pyperclip`

## Installation

```bash
pip install termcolours
```

Or install from source:
```bash
pip install -e .
```

## Usage

- Interactive mode: running `termcolours` without arguments prompts the user
for input (e.g. `9;149;9`).

- Batch input: `termcolours -f <file>`, where `<file>` is an `.ssv` file
containing colour codes -- each line should be of the form `RR;GG;BB;<fmt>`,
`<fmt>` being one of `decm`, `hexa` or `prct`.

- Named palette generation -- if `.ssv` files[^1] are stored in the `assets`
folder, `termcolours` will automatically generate a palette from them,
displaying a menu to choose from.

### Examples

#### Interactive mode

```shell
╭─user at main-frame in ~/some/folder 00-13-48 - 26:93:72
╰─∷   termcolours
termcolours v. 0.9.1 -- interactive mode
Enter a colour code (R;G;B, decimal), command or help > 9;149;9
```

<p align="center">
  <img src="assets/termcolours-basic-usage.png"
       alt="Terminal output showing a green colour bar generated by termcolours (RGB 9;149;9)"
       style="max-width:720px;">
</p>

##### Commands in interactive mode

- `fg/bg` to copy the current colour to the clipboard 
    (ANSI _foreground_/_background_, respectively).
- `decm`: sets conversion format from a _decimal_ triplet.
- `hexa`: sets conversion format from _hexadecimal_ triplet.
- `prct`: sets conversion format from _percentage_ triplet.
- `help`: prints _help_ message.
- `palette`: generates a named _palette_, from file in the `assets` folder.
- `quit`: exits the application.

#### Batch input

`termcolours -f <file>`

In the batch input mode any `.ssv` file with colours specified in the
correct format[^2] is read. All the parsed colours, along with `#hex` and
`int` triplets and with the corresponding ANSI codes, are printed to `stdout`
after which the program quits.

#### Named palette

Typing `palette` in the interactive mode invokes the method. The user is
presented with a menu of available palettes, corresponding to `.ssv` files
stored in the `assets` folder. The palette is then generated and printed to
`stdout`, after which the program quits.

```shell
╭─user at main-frame in ~/some/folder 00-13-48 - 26:93:72
╰─∷   termcolours
termcolours v. 0.9.1 -- interactive mode
Enter a colour code (R;G;B, decimal), command or help > palette
'ansi16' | 'forest_vibes' | 'gruvbox' | 'khaz' | 'material_basic'
'navy_light_blue' | 'nord' | 'simple' | 'solarized' | 'turquoise_depths'
Enter a palette name> khaz
```

<p align="center">
  <img src="assets/termcolours-palette-mode.png"
       alt="Terminal output showing a green colour bar generated by termcolours (RGB 9;149;9)"
       style="max-width:720px;">
</p>

## Input format

Input semi-colon separated triplets might be in any of the following forms:

- decimal, e.g. `10;90;255` (name: `decm`)
- hexadecimal, e.g. `a;5a;ff` (name: `hexa`)
- percentage, e.g. `0.04;0.355;1` (name: `prct`)

Invalid input values or formats will result in an error.

## License

MIT

[^1]: File with the first line in the form
`# palette: <name>; filename: <filenamename>.ssv` the palette will show
in the menu as a `<name>` option.
[^2]: See [Input format](#input-format)
