<!--suppress HtmlDeprecatedAttribute -->
<p align="center">
<a href="https://pypi.org/project/NcduColors/">
<img src="https://img.shields.io/badge/PyPi-blue?logo=PyPi&logoColor=white&label=Install%20on&labelColor=green&color=blue&cacheSeconds=36000" alt="Install on PyPi" width="75%">
</a>
</p>
# Table of content
> - [What is it?](#what-is-it)
> - [Why?](#why)
> - [Why not just contributing to Ncdu or forking it?](#why-not-just-contributing-to-ncdu-or-forking-it)
> - [What about changing the default color palette?](#what-about-changing-the-default-color-palette)
> - [Installation](#installation)
> - [**How to use**](#how-to-use)
> - [0. If you want to patch a _copy_ of Ncdu](#0-if-you-want-to-patch-a-copy-of-ncdu)
> - [1. Extract the default configuration](#1-extract-the-default-configuration)
> - [1.1 Make a backup](#11-make-a-backup)
> - [2. Edit the configuration file](#2-edit-the-configuration-file)
> - [3. Apply the new configuration](#3-apply-the-new-configuration)
> - [4. Done](#4-done)
> - [Reverting and recovering from errors](#reverting-and-recovering-from-errors)
> - [Table of reference](#table-of-reference)
> - [Config object](#config-object)
> - [Theme object](#theme-object)
> - [Key object](#key-object)
> - [Color object](#color-object)
> - [Attribute object](#attribute-object)
> - [Examples](#examples)
> - [What has changed?](#what-has-changed)
> - [Tests](#tests)
> - [Future improvements](#future-improvements)
> - [License](#license)
## What is it?
NcduColors is a Python zero-dependency, pre-2.0 Ncdu themes patcher.
[Ncdu](https://dev.yorhel.nl/ncdu) (NCurses Disk Usage) is a text-user interface disk usage analyzer. It relies on the Ncurses library.
### Why?
> _"I really don't see why anyone would spend time theming a disk usage analyzer they (probably) won't use every day, so I'm hesitant to bloat ncdu with even more config options."_ - Ncdu developer
Software accessibility is a great issue. Ncdu users know it, too.
The [3-bit and 4-bit](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) basic terminal color palette is almost unusable. Every terminal software uses its own palette. No standard seems to be followed at all.
Because of this, the two colorful themes, `dark` and `darkbg`, are hardly usable for many.
<sup>_Something is definitely off_</sup></div>
Many users ([first](https://code.blicky.net/yorhel/ncdu/issues/191),
[second](https://code.blicky.net/yorhel/ncdu/issues/202),
[third](https://code.blicky.net/yorhel/ncdu/issues/203), and so on) complained about color issues. I thought it'd be nice to find a solution which could work for the many, not only for me. Also, I use Ncdu a lot, so this definitely was not a waste of time (at the very least, it was a fun learning experience!).
### Why not just contributing to Ncdu or forking it?
Contributing or forking Ncdu was an option.
However, there are a few issues with this approach:
- The Ncdu developer [said](https://code.blicky.net/yorhel/ncdu/issues/191) he's quite hesitant to add more themes support to Ncdu.
- Even if the needed changes were to be made *now*, many users on LTS distributions couldn't benefit for months or even **years**. Think of Debian and Ubuntu-based distributions.
- Forks are harder to compile, to use, to install and to update for regular users. Also let's not fool ourselves, **Linux package management is a mess**.
- Forks rely on developers who fork the original project and are more prone to become [abandonware](https://en.wikipedia.org/wiki/Abandonware) due to their nature, rightfully expected to be "secondary" compared to the mainline project.
Instead, NcduColors's approach allows you to change colors **now** and **how** you want, while still retaining the possibility to update Ncdu officially, using your package manager, whenever new versions are available (though you will have to re-patch it).
And: you can uninstall NcduColors while preserving your customised Ncdu.
### What about changing the default color palette?
This approach was considered on Ncdu's side, but I think that there will always be someone who doesn't like it. You can't always satisfy everyone when it comes to accessibility issues.
Thus, allowing everybody to painlessy (more or less) patch their own copy of Ncdu seemed the right choice to me.
Also: not everyone loves the black and white (`off`) theme.
## Installation
Install NcduColors from [PyPI](https://pypi.org/project/NcduColors/) using Pip:
```bash
pip install ncducolors
```
## How to use
You have two choices:
- You can patch a **copy** of Ncdu (you won't - usually - need root permissions)
- start from [step 0](#0-if-you-want-to-patch-a-copy-of-ncdu)
- You can patch Ncdu in-place (you'll - most likely - need root permissions)
- skip to [step 1](#1-extract-the-default-configuration)
### 0. If you want to patch a _copy_ of Ncdu
You need to _copy_ `ncdu` - namely `$(command -v ncdu)` - into another `$PATH` directory.
A safe choice could be `/usr/local/bin` - you can view all of them running `tr : '\n' <<< "$PATH"` (beware of the order of priority)
> Actually, you can copy Ncdu wherever you want.
>
> A `$PATH` directory is needed just to be able to run Ncdu from anywhere.
> _From now on, all the steps are in common._
> _**Don't forget** to specify `--ncdu <PATH_TO_NCDU>` in the arguments._
### 1. Extract the default configuration
Run:
```bash
ncducolors extract-default-config ncdu-config.json
```
> In case of failure, please open an issue.
#### 1.1 Make a backup
It's a good practice to always make backups, even if not strictly needed.
```bash
cp ncdu-config.json ncdu-defaults.json
```
### 2. Edit the configuration file
Use your editor of choice to edit the values.
<u>_Don't_</u> edit the `offset`: it could corrupt the binary.
```bash
xdg-open ncdu-config.json
```
> Have a look to the [table of reference](#table-of-reference) for some help.
Once finished, **save** and go ahead.
### 3. Apply the new configuration
This is the first and only "dangerous" step - well, not really, since you can always [fix Ncdu](#reverting-and-recovering-from-errors).
Close Ncdu before applying the new configuration, or it won't work.
```bash
ncducolors apply-config ncdu-config.json
```
> If you are editing Ncdu in-place, you may need to run NcduColors as **root** (and, if you
installed NcduColors as an unprivileged user, this fixes the "command not found" error).
>
> ```bash
> sudo -E env "PATH=$PATH" ncducolors apply-config ncdu-config.json
> ```
### 4. Done
That's all. You can now run `ncdu` (or `./path/to/your/copy/of/ncdu`).
You can now either:
- Continue to improve your theme jumping back to [step 2](#2-edit-the-configuration-file).
- [Revert](#reverting-and-recovering-from-errors) to your default installation.
- Uninstall NcduColors.
### Reverting and recovering from errors
In case something goes wrong, or you just want the plain old Ncdu, don't worry. You can fix it quite easily.
1. Try to apply the default config using `ncducolors apply-config ./ncdu-defaults.json`
2. Try to revert using `ncducolors revert --config ./ncdu-config.json` (the config
is needed just to obtain the offset - in fact, you can use `ncducolors revert --offset N` too)
3. If you did a [backup](#11-make-a-backup), use `cp backup-of-ncdu "$(command -v ncdu)"` (you may need to be `root`).
4. Reinstall Ncdu using your package manager of choice.
## Table of reference
### Config object
| key | type | notes |
|--------|--------------------------------------------------------------------|-------------------------------------------------------|
| ncdu | [Path](https://docs.python.org/3/library/pathlib.html) (as string) | Overridden by `--ncdu`; autoresolved if `null` |
| offset | Integer | Depends on the binary |
| off | [Theme](#theme-object) | Black and white theme |
| dark | [Theme](#theme-object) | Dark, colorful theme |
| darkbg | [Theme](#theme-object) (if available) | Like `dark` with forced black background (Ncdu 1.17+) |
### Theme object
| key | type | notes |
|-----------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| default | [Key](#key-object) | Used for most of the UI:<br/> - file names (unselected)<br/>- help pages |
| box_title | [Key](#key-object) | Used for windows titles:</br>- "ncdu help"</br>- "Item info"</br> - "Confirm delete" |
| hd | [Key](#key-object) | - Header base text<br/>- Footer base text</br>- Help page title (selected) |
| sel | [Key](#key-object) | File row (selected) |
| num | [Key](#key-object) | Numbers only, without unit:<br/> - file size (unselected)</br>- size in percentage (unselected)</br>- child items count (unselected)</br>- disk usage (Item view)</br>- apparent size (Item view) |
| num_hd | [Key](#key-object) | Numbers only, without unit (footer) |
| num_sel | [Key](#key-object) | Numbers only, without unit:<br/> - file size (selected)</br>- size in percentage (selected) |
| key | [Key](#key-object) | Highlighted keys ("Item info", "ncdu help") |
| key_hd | [Key](#key-object) | - "?" (header)</br>- "1", "2", "3" ("ncdu help"; selected) |
| dir | [Key](#key-object) | - File name (directories; unselected)<br/>- Current directory (under the header) |
| dir_sel | [Key](#key-object) | File name (directories; selected) |
| flag | [Key](#key-object) | - File rows's leftmost character (unselected)<br/>- Flags ("ncdu help" -> "2:Format") |
| flag_sel | [Key](#key-object) | File rows's leftmost character (selected) |
| graph | [Key](#key-object) | Graphical size percentage (unselected) |
| graph_sel | [Key](#key-object) | Graphical size percentage (selected) |
### Key object
| key | type | notes |
|-----|--------------------------------|------------------|
| fg | [Color](#color-object) | Foreground color |
| bg | [Color](#color-object) | Background color |
| a | [Attribute](#attribute-object) | Attribute flags |
### Color object
#### 3-bit and 4-bit colors
Standard colors and high intensity colors - have a look [here](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) - 3-bit and 4-bit colors are terminal-dependent, thus their usage is discouraged (prefer [8-bit colors](#8-bit-colors), if possible).
| name | bit value |
|-----------------------|-----------|
| Black | 0 |
| Red | 1 |
| Green | 2 |
| Yellow | 3 |
| Blue | 4 |
| Magenta | 5 |
| Cyan | 6 |
| White | 7 |
| Bright_Black ("Gray") | 8 |
| Bright_Red | 9 |
| Bright_Green | 10 |
| Bright_Yellow | 11 |
| Bright_Blue | 12 |
| Bright_Magenta | 13 |
| Bright_Cyan | 14 |
| Bright_White | 15 |
Note: these first 16 colors are aliased to `Color0`, `Color1`, and so on, until `Color15`.
In other words, each of the first 16 colors can be represented in two different ways.
This way, `Color0` is Black, `Color8` is Bright_Black (or Gray), and so on.
#### 8-bit colors
Even 8-bit colors are serialized in the format `ColorN`, where `N` is any number from 0 to 255.
<!--suppress HtmlDeprecatedAttribute -->
<img alt="8-bit 216 colors cube (3D)" hspace="10px" align="right" width="100px" height="125px" src="assets/images/cube_animated_preview.webp">
- Colors 0 to 15 are the [3-bit and 4-bit colors](#3-bit-and-4-bit-colors), so nothing new there;
- Colors 16 to 231 are:
- part of a 6 × 6 × 6 RGB cube (216 colors in total);
- mathematical formula: $${\textbf{N} = 36 \cdot \color{red}{\textbf{R}} + 6 \cdot \color{green}{\textbf{G}} + \color{blue}{\textbf{B}} + 16}$$, with $${0 \le \color{red}{\textbf{R}}, \color{green}{\textbf{G}}, \color{blue}{\textbf{B}} \le 5}$$;
- look to [this nice palette](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) for more information and for the lookup-table;
- Colors 232 to 255 are a grayscale from dark gray (`Color232`) to light gray (`Color255`) in 24 steps.
- `Color232` (Dark gray) is aliased to `Gray1`, while `Color255` (Light gray) is aliased to `Gray24`, and so on for the colors in the middle.
#### 24-bit colors
Seems like there's no simple way to support them (without recreating the entire binary): NcduColors can only allocate 16 bits for the foreground color and 16 bits for the background color.
#### Default colors
It's the case of `null` value (preferred) or any other unknown color name.
For example, in a white over black terminal, foreground color becomes white and background color becomes black.
### Attribute object
| name | bit value | [notes](https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html) | does it work? |
|------------|----------------|-----------------------------------------------------------------------|--------------------------|
| Standout | 2<sup>16</sup> | Best highlighting mode of the terminal | yes |
| Underline | 2<sup>17</sup> | Underlining | yes |
| Reverse | 2<sup>18</sup> | Reverse video | yes |
| Blink | 2<sup>19</sup> | Blinking | yes |
| Dim | 2<sup>20</sup> | Half bright | yes |
| Bold | 2<sup>21</sup> | Extra bright or bold | yes |
| Altcharset | 2<sup>22</sup> | Alternate character set | theoretical support only |
| Invisible | 2<sup>23</sup> | Invisible or blank mode | yes |
| Protect | 2<sup>24</sup> | Protected mode ("_selective erase_") | theoretical support only |
| Horizontal | 2<sup>25</sup> | | theoretical support only |
| Left | 2<sup>26</sup> | | theoretical support only |
| Low | 2<sup>27</sup> | | theoretical support only |
| Right | 2<sup>28</sup> | | theoretical support only |
| Top | 2<sup>29</sup> | | theoretical support only |
| Vertical | 2<sup>30</sup> | | theoretical support only |
Internally, the attributes are expressed as the sum of each single flag, stored in a 4-bit long unsigned integer.
When serialized as a string, the object is expressed as each attribute's name concatenated by the plus ('+') character.
A value of `null` resets all attributes.
> Note: some texts might appear to be dimmed, but since their attributes are hardencoded elsewhere, they can't be edited via NcduColors.
> Remember: not every terminal supports all the available attributes, and sometimes they might deliberately decide to ignore them (e.g. `Blink`), while others may support it but with different behavior.
## Examples
Check the [examples/](assets/examples) subdirectory.
## What has changed?
Using the [colordiff](https://command-not-found.com/colordiff) and [xxd](https://command-not-found.com/xxd) packages, you can compare your patched Ncdu binary with the old one.
```bash
export NC_LENGTH=360 # or 240, for older versions of Ncdu (pre-1.7)
export NC_THEMES_NUMBER=3 # or 2, for older versions of Ncdu (pre-1.7)
export NC_OFFSET=$(printf '0x%x' 123456) # offset
export NC_BACKUP="/path/to/unpatched/ncdu"
export NC_CURRENT="$(command -v ncdu)"
colordiff -y \
<(xxd -c $NC_THEMES_NUMBER -s $NC_OFFSET -l $NC_LENGTH $NC_BACKUP) \
<(xxd -c $NC_THEMES_NUMBER -s $NC_OFFSET -l $NC_LENGTH $NC_CURRENT)
```
This will output a 15-rows long hex dump, wide 2 or 3 columns (in groups of 2x4 bytes).
<sup>_Example - Ncdu 1.15.1 defaults compared to a custom theme_</sup>
## Tests
You need to install `autoreconf`, `autoupdate` and a C compiler to run the tests; `gcc` is recommended.
## Future improvements
- Add support for Ncdu2 (the newer Zig version).
## License
[MIT License](LICENSE.txt).
This means you can use it everywhere, in both private and commercial contexts, for every possible purpose (you can even re-distribute it), as long as you preserve copyright and license notices.
Raw data
{
"_id": null,
"home_page": "https://github.com/Midblyte/NcduColors",
"name": "NcduColors",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "ncdu themes",
"author": "Midblyte",
"author_email": "ncducolors@midblyte.anonaddy.me",
"download_url": "https://files.pythonhosted.org/packages/b9/30/bbbf99b94d8a23362a857754ead1eb8dd9fcc2f7f00e80d76fffb568e038/NcduColors-0.0.2.tar.gz",
"platform": null,
"description": "![NcduColors preview](assets/images/colorful_preview.png \"Preview of Ncdu fully Red, Green, Yellow, Blue, Magenta, Cyan\")\n\n<!--suppress HtmlDeprecatedAttribute -->\n<p align=\"center\">\n <a href=\"https://pypi.org/project/NcduColors/\">\n <img src=\"https://img.shields.io/badge/PyPi-blue?logo=PyPi&logoColor=white&label=Install%20on&labelColor=green&color=blue&cacheSeconds=36000\" alt=\"Install on PyPi\" width=\"75%\">\n </a>\n\n \n \n \n\n</p>\n\n\n# Table of content\n\n> - [What is it?](#what-is-it)\n> - [Why?](#why)\n> - [Why not just contributing to Ncdu or forking it?](#why-not-just-contributing-to-ncdu-or-forking-it)\n> - [What about changing the default color palette?](#what-about-changing-the-default-color-palette)\n> - [Installation](#installation)\n> - [**How to use**](#how-to-use)\n> - [0. If you want to patch a _copy_ of Ncdu](#0-if-you-want-to-patch-a-copy-of-ncdu)\n> - [1. Extract the default configuration](#1-extract-the-default-configuration)\n> - [1.1 Make a backup](#11-make-a-backup)\n> - [2. Edit the configuration file](#2-edit-the-configuration-file)\n> - [3. Apply the new configuration](#3-apply-the-new-configuration)\n> - [4. Done](#4-done)\n> - [Reverting and recovering from errors](#reverting-and-recovering-from-errors)\n> - [Table of reference](#table-of-reference)\n> - [Config object](#config-object)\n> - [Theme object](#theme-object)\n> - [Key object](#key-object)\n> - [Color object](#color-object)\n> - [Attribute object](#attribute-object)\n> - [Examples](#examples)\n> - [What has changed?](#what-has-changed)\n> - [Tests](#tests)\n> - [Future improvements](#future-improvements)\n> - [License](#license)\n\n\n## What is it?\n\nNcduColors is a Python zero-dependency, pre-2.0 Ncdu themes patcher.\n\n[Ncdu](https://dev.yorhel.nl/ncdu) (NCurses Disk Usage) is a text-user interface disk usage analyzer. It relies on the Ncurses library.\n\n\n### Why?\n\n> _\"I really don't see why anyone would spend time theming a disk usage analyzer they (probably) won't use every day, so I'm hesitant to bloat ncdu with even more config options.\"_ - Ncdu developer\n\nSoftware accessibility is a great issue. Ncdu users know it, too.\n\nThe [3-bit and 4-bit](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) basic terminal color palette is almost unusable. Every terminal software uses its own palette. No standard seems to be followed at all.\n\nBecause of this, the two colorful themes, `dark` and `darkbg`, are hardly usable for many.\n\n![Example of the mess of 3-bit and 4-bit colors compatibility has caused](assets/images/broken_dark.png \"Ncdu 1.15.1 dark theme on Konsole\")\n\n<sup>_Something is definitely off_</sup></div>\n\nMany users ([first](https://code.blicky.net/yorhel/ncdu/issues/191),\n[second](https://code.blicky.net/yorhel/ncdu/issues/202),\n[third](https://code.blicky.net/yorhel/ncdu/issues/203), and so on) complained about color issues. I thought it'd be nice to find a solution which could work for the many, not only for me. Also, I use Ncdu a lot, so this definitely was not a waste of time (at the very least, it was a fun learning experience!).\n\n\n### Why not just contributing to Ncdu or forking it?\n\nContributing or forking Ncdu was an option.\n\nHowever, there are a few issues with this approach:\n\n- The Ncdu developer [said](https://code.blicky.net/yorhel/ncdu/issues/191) he's quite hesitant to add more themes support to Ncdu.\n\n- Even if the needed changes were to be made *now*, many users on LTS distributions couldn't benefit for months or even **years**. Think of Debian and Ubuntu-based distributions.\n\n- Forks are harder to compile, to use, to install and to update for regular users. Also let's not fool ourselves, **Linux package management is a mess**.\n\n- Forks rely on developers who fork the original project and are more prone to become [abandonware](https://en.wikipedia.org/wiki/Abandonware) due to their nature, rightfully expected to be \"secondary\" compared to the mainline project.\n\nInstead, NcduColors's approach allows you to change colors **now** and **how** you want, while still retaining the possibility to update Ncdu officially, using your package manager, whenever new versions are available (though you will have to re-patch it).\n\nAnd: you can uninstall NcduColors while preserving your customised Ncdu.\n\n\n### What about changing the default color palette?\n\nThis approach was considered on Ncdu's side, but I think that there will always be someone who doesn't like it. You can't always satisfy everyone when it comes to accessibility issues.\n\nThus, allowing everybody to painlessy (more or less) patch their own copy of Ncdu seemed the right choice to me.\n\nAlso: not everyone loves the black and white (`off`) theme.\n\n\n## Installation\n\nInstall NcduColors from [PyPI](https://pypi.org/project/NcduColors/) using Pip:\n\n```bash\npip install ncducolors\n```\n\n## How to use\n\nYou have two choices:\n\n- You can patch a **copy** of Ncdu (you won't - usually - need root permissions) \n - start from [step 0](#0-if-you-want-to-patch-a-copy-of-ncdu)\n\n- You can patch Ncdu in-place (you'll - most likely - need root permissions)\n - skip to [step 1](#1-extract-the-default-configuration)\n\n\n### 0. If you want to patch a _copy_ of Ncdu\n\nYou need to _copy_ `ncdu` - namely `$(command -v ncdu)` - into another `$PATH` directory.\n\nA safe choice could be `/usr/local/bin` - you can view all of them running `tr : '\\n' <<< \"$PATH\"` (beware of the order of priority)\n\n> Actually, you can copy Ncdu wherever you want.\n> \n> A `$PATH` directory is needed just to be able to run Ncdu from anywhere.\n\n> _From now on, all the steps are in common._\n> _**Don't forget** to specify `--ncdu <PATH_TO_NCDU>` in the arguments._\n\n\n### 1. Extract the default configuration\n\nRun:\n\n```bash\nncducolors extract-default-config ncdu-config.json\n```\n\n> In case of failure, please open an issue.\n\n#### 1.1 Make a backup\n\nIt's a good practice to always make backups, even if not strictly needed.\n\n```bash\ncp ncdu-config.json ncdu-defaults.json\n```\n\n\n### 2. Edit the configuration file\n\nUse your editor of choice to edit the values.\n<u>_Don't_</u> edit the `offset`: it could corrupt the binary.\n\n```bash\nxdg-open ncdu-config.json\n```\n\n> Have a look to the [table of reference](#table-of-reference) for some help.\n\nOnce finished, **save** and go ahead.\n\n\n### 3. Apply the new configuration\n\nThis is the first and only \"dangerous\" step - well, not really, since you can always [fix Ncdu](#reverting-and-recovering-from-errors).\n\nClose Ncdu before applying the new configuration, or it won't work.\n\n```bash\nncducolors apply-config ncdu-config.json\n```\n\n> If you are editing Ncdu in-place, you may need to run NcduColors as **root** (and, if you\ninstalled NcduColors as an unprivileged user, this fixes the \"command not found\" error).\n>\n> ```bash\n> sudo -E env \"PATH=$PATH\" ncducolors apply-config ncdu-config.json\n> ```\n\n\n### 4. Done\n\nThat's all. You can now run `ncdu` (or `./path/to/your/copy/of/ncdu`).\n\nYou can now either:\n- Continue to improve your theme jumping back to [step 2](#2-edit-the-configuration-file).\n- [Revert](#reverting-and-recovering-from-errors) to your default installation.\n- Uninstall NcduColors.\n\n\n### Reverting and recovering from errors\n\nIn case something goes wrong, or you just want the plain old Ncdu, don't worry. You can fix it quite easily.\n\n1. Try to apply the default config using `ncducolors apply-config ./ncdu-defaults.json`\n2. Try to revert using `ncducolors revert --config ./ncdu-config.json` (the config\n is needed just to obtain the offset - in fact, you can use `ncducolors revert --offset N` too)\n3. If you did a [backup](#11-make-a-backup), use `cp backup-of-ncdu \"$(command -v ncdu)\"` (you may need to be `root`).\n4. Reinstall Ncdu using your package manager of choice.\n\n\n## Table of reference\n\n### Config object\n\n| key | type | notes |\n|--------|--------------------------------------------------------------------|-------------------------------------------------------|\n| ncdu | [Path](https://docs.python.org/3/library/pathlib.html) (as string) | Overridden by `--ncdu`; autoresolved if `null` |\n| offset | Integer | Depends on the binary |\n| off | [Theme](#theme-object) | Black and white theme |\n| dark | [Theme](#theme-object) | Dark, colorful theme |\n| darkbg | [Theme](#theme-object) (if available) | Like `dark` with forced black background (Ncdu 1.17+) |\n\n\n### Theme object\n\n| key | type | notes |\n|-----------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| default | [Key](#key-object) | Used for most of the UI:<br/> - file names (unselected)<br/>- help pages |\n| box_title | [Key](#key-object) | Used for windows titles:</br>- \"ncdu help\"</br>- \"Item info\"</br> - \"Confirm delete\" |\n| hd | [Key](#key-object) | - Header base text<br/>- Footer base text</br>- Help page title (selected) |\n| sel | [Key](#key-object) | File row (selected) |\n| num | [Key](#key-object) | Numbers only, without unit:<br/> - file size (unselected)</br>- size in percentage (unselected)</br>- child items count (unselected)</br>- disk usage (Item view)</br>- apparent size (Item view) |\n| num_hd | [Key](#key-object) | Numbers only, without unit (footer) |\n| num_sel | [Key](#key-object) | Numbers only, without unit:<br/> - file size (selected)</br>- size in percentage (selected) |\n| key | [Key](#key-object) | Highlighted keys (\"Item info\", \"ncdu help\") |\n| key_hd | [Key](#key-object) | - \"?\" (header)</br>- \"1\", \"2\", \"3\" (\"ncdu help\"; selected) |\n| dir | [Key](#key-object) | - File name (directories; unselected)<br/>- Current directory (under the header) |\n| dir_sel | [Key](#key-object) | File name (directories; selected) |\n| flag | [Key](#key-object) | - File rows's leftmost character (unselected)<br/>- Flags (\"ncdu help\" -> \"2:Format\") |\n| flag_sel | [Key](#key-object) | File rows's leftmost character (selected) |\n| graph | [Key](#key-object) | Graphical size percentage (unselected) |\n| graph_sel | [Key](#key-object) | Graphical size percentage (selected) |\n\n### Key object\n\n| key | type | notes |\n|-----|--------------------------------|------------------|\n| fg | [Color](#color-object) | Foreground color |\n| bg | [Color](#color-object) | Background color |\n| a | [Attribute](#attribute-object) | Attribute flags |\n\n\n### Color object\n\n#### 3-bit and 4-bit colors\n\nStandard colors and high intensity colors - have a look [here](https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit) - 3-bit and 4-bit colors are terminal-dependent, thus their usage is discouraged (prefer [8-bit colors](#8-bit-colors), if possible).\n\n| name | bit value |\n|-----------------------|-----------|\n| Black | 0 |\n| Red | 1 |\n| Green | 2 |\n| Yellow | 3 |\n| Blue | 4 |\n| Magenta | 5 |\n| Cyan | 6 |\n| White | 7 |\n| Bright_Black (\"Gray\") | 8 |\n| Bright_Red | 9 |\n| Bright_Green | 10 |\n| Bright_Yellow | 11 |\n| Bright_Blue | 12 |\n| Bright_Magenta | 13 |\n| Bright_Cyan | 14 |\n| Bright_White | 15 |\n\nNote: these first 16 colors are aliased to `Color0`, `Color1`, and so on, until `Color15`.\nIn other words, each of the first 16 colors can be represented in two different ways.\n\nThis way, `Color0` is Black, `Color8` is Bright_Black (or Gray), and so on.\n\n\n#### 8-bit colors\n\nEven 8-bit colors are serialized in the format `ColorN`, where `N` is any number from 0 to 255.\n\n<!--suppress HtmlDeprecatedAttribute -->\n<img alt=\"8-bit 216 colors cube (3D)\" hspace=\"10px\" align=\"right\" width=\"100px\" height=\"125px\" src=\"assets/images/cube_animated_preview.webp\">\n\n- Colors 0 to 15 are the [3-bit and 4-bit colors](#3-bit-and-4-bit-colors), so nothing new there;\n- Colors 16 to 231 are:\n - part of a 6 \u00d7 6 \u00d7 6 RGB cube (216 colors in total);\n - mathematical formula: $${\\textbf{N} = 36 \\cdot \\color{red}{\\textbf{R}} + 6 \\cdot \\color{green}{\\textbf{G}} + \\color{blue}{\\textbf{B}} + 16}$$, with $${0 \\le \\color{red}{\\textbf{R}}, \\color{green}{\\textbf{G}}, \\color{blue}{\\textbf{B}} \\le 5}$$;\n - look to [this nice palette](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) for more information and for the lookup-table;\n- Colors 232 to 255 are a grayscale from dark gray (`Color232`) to light gray (`Color255`) in 24 steps.\n - `Color232` (Dark gray) is aliased to `Gray1`, while `Color255` (Light gray) is aliased to `Gray24`, and so on for the colors in the middle.\n\n\n#### 24-bit colors\n\nSeems like there's no simple way to support them (without recreating the entire binary): NcduColors can only allocate 16 bits for the foreground color and 16 bits for the background color.\n\n\n#### Default colors\n\nIt's the case of `null` value (preferred) or any other unknown color name.\n\nFor example, in a white over black terminal, foreground color becomes white and background color becomes black.\n\n\n### Attribute object\n\n| name | bit value | [notes](https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/attrib.html) | does it work? |\n|------------|----------------|-----------------------------------------------------------------------|--------------------------|\n| Standout | 2<sup>16</sup> | Best highlighting mode of the terminal | yes |\n| Underline | 2<sup>17</sup> | Underlining | yes |\n| Reverse | 2<sup>18</sup> | Reverse video | yes |\n| Blink | 2<sup>19</sup> | Blinking | yes |\n| Dim | 2<sup>20</sup> | Half bright | yes |\n| Bold | 2<sup>21</sup> | Extra bright or bold | yes |\n| Altcharset | 2<sup>22</sup> | Alternate character set | theoretical support only |\n| Invisible | 2<sup>23</sup> | Invisible or blank mode | yes |\n| Protect | 2<sup>24</sup> | Protected mode (\"_selective erase_\") | theoretical support only |\n| Horizontal | 2<sup>25</sup> | | theoretical support only |\n| Left | 2<sup>26</sup> | | theoretical support only |\n| Low | 2<sup>27</sup> | | theoretical support only |\n| Right | 2<sup>28</sup> | | theoretical support only |\n| Top | 2<sup>29</sup> | | theoretical support only |\n| Vertical | 2<sup>30</sup> | | theoretical support only |\n\nInternally, the attributes are expressed as the sum of each single flag, stored in a 4-bit long unsigned integer.\n\nWhen serialized as a string, the object is expressed as each attribute's name concatenated by the plus ('+') character.\n\nA value of `null` resets all attributes.\n\n> Note: some texts might appear to be dimmed, but since their attributes are hardencoded elsewhere, they can't be edited via NcduColors.\n\n> Remember: not every terminal supports all the available attributes, and sometimes they might deliberately decide to ignore them (e.g. `Blink`), while others may support it but with different behavior.\n\n\n## Examples\n\nCheck the [examples/](assets/examples) subdirectory.\n\n\n## What has changed?\n\nUsing the [colordiff](https://command-not-found.com/colordiff) and [xxd](https://command-not-found.com/xxd) packages, you can compare your patched Ncdu binary with the old one.\n\n```bash\nexport NC_LENGTH=360 # or 240, for older versions of Ncdu (pre-1.7)\nexport NC_THEMES_NUMBER=3 # or 2, for older versions of Ncdu (pre-1.7)\nexport NC_OFFSET=$(printf '0x%x' 123456) # offset\nexport NC_BACKUP=\"/path/to/unpatched/ncdu\"\nexport NC_CURRENT=\"$(command -v ncdu)\"\n\ncolordiff -y \\\n <(xxd -c $NC_THEMES_NUMBER -s $NC_OFFSET -l $NC_LENGTH $NC_BACKUP) \\\n <(xxd -c $NC_THEMES_NUMBER -s $NC_OFFSET -l $NC_LENGTH $NC_CURRENT)\n```\n\nThis will output a 15-rows long hex dump, wide 2 or 3 columns (in groups of 2x4 bytes).\n\n![Colordiff used to compare two binary sequences](assets/images/colordiff.png \"Ncdu 1.15.1 defaults compared to a custom theme\")\n\n<sup>_Example - Ncdu 1.15.1 defaults compared to a custom theme_</sup>\n\n\n## Tests\n\nYou need to install `autoreconf`, `autoupdate` and a C compiler to run the tests; `gcc` is recommended.\n\n\n## Future improvements\n\n- Add support for Ncdu2 (the newer Zig version).\n\n\n## License\n\n[MIT License](LICENSE.txt).\n\nThis means you can use it everywhere, in both private and commercial contexts, for every possible purpose (you can even re-distribute it), as long as you preserve copyright and license notices.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Ncdu themes patcher",
"version": "0.0.2",
"project_urls": {
"Documentation": "https://github.com/Midblyte/NcduColors#how-to-use",
"Homepage": "https://github.com/Midblyte/NcduColors",
"Source": "https://github.com/Midblyte/NcduColors",
"Tracker": "https://github.com/Midblyte/NcduColors/issues"
},
"split_keywords": [
"ncdu",
"themes"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a39c4f85532b933ccb57b38b9590db3e93b0b6dfb1c4ebac802bac3c6be92f7",
"md5": "f38b7c37ba6205a02f442690997d0e2a",
"sha256": "28829b1e2bc3cd4687693a28a0d4654c55ee23d98cf09c41a2b02cf464d2a3e2"
},
"downloads": -1,
"filename": "NcduColors-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f38b7c37ba6205a02f442690997d0e2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20106,
"upload_time": "2023-08-01T20:52:40",
"upload_time_iso_8601": "2023-08-01T20:52:40.195301Z",
"url": "https://files.pythonhosted.org/packages/9a/39/c4f85532b933ccb57b38b9590db3e93b0b6dfb1c4ebac802bac3c6be92f7/NcduColors-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b930bbbf99b94d8a23362a857754ead1eb8dd9fcc2f7f00e80d76fffb568e038",
"md5": "4a43a042fdb44bbf64d3ac1bd88ffcb1",
"sha256": "48705544e407db32ad49e0565df65095e2478005b9381f3a0ef02130f218392d"
},
"downloads": -1,
"filename": "NcduColors-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "4a43a042fdb44bbf64d3ac1bd88ffcb1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23976,
"upload_time": "2023-08-01T20:52:42",
"upload_time_iso_8601": "2023-08-01T20:52:42.151373Z",
"url": "https://files.pythonhosted.org/packages/b9/30/bbbf99b94d8a23362a857754ead1eb8dd9fcc2f7f00e80d76fffb568e038/NcduColors-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-01 20:52:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Midblyte",
"github_project": "NcduColors",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ncducolors"
}
JSON
