dolltool/README.md

119 lines
3.1 KiB
Markdown

# dolltool
A simple dollcode encoder, decoder, and generator inside your terminal :3
## About
Being technical, this is a high-performance, arbitrary-precision ternary encoder
and decoder formatted into patterns using a set of block symbols (`▖`, `▘`,
`▌`), also known as a 2-track pharmacode. Additionally, this program can
generate codes based on patterns entered by the user.
This project was inspired by [noe](https://noe.sh/) and its [dollcode transcoder](https://noe.sh/dollcode/).
## Installation
### Arch Linux
You can install this package from the AUR with the package name `dolltool`, or
alternatively by cloning the repository and using `makepkg -si` inside the `pkg/`
directory.
### Other
Clone the repository then `cd` into the directory and run:
```bash
cargo install --path .
```
This will install the `dolltool` binary to your `~/.cargo/bin` directory, so to
execute anywhere from inside your terminal you must add `~/.cargo/bin` to your path.
## Usage
### Encoding
If an integer is passed to encode it will by default be encoded as an integer:
```bash
$ dolltool -e 123
▖▖▖▖▌
```
If you would like to encode an integer as text instead you must pass the `-t`
(`--text`) argument:
```bash
$ dolltool -e 123 -t
▖▘▖▖ ▖▘▖▘ ▖▘▖▌
```
Finally, any non-integer patterns will automatically be encoded as text:
```bash
$ dolltool -e "hello world :3"
▌▘▖▘ ▌▖▌▘ ▌▘▘▌ ▌▘▘▌ ▌▘▌▌ ▌▖▘ ▌▌▌▘ ▌▘▌▌ ▌▌▖▌ ▌▘▘▌ ▌▖▌▖ ▌▖▘ ▖▌▖▖ ▖▘▖▌
```
### Decoding
This works the same for both integers and text:
```bash
$ dolltool -d ▖▖▖▖▌
123
```
```bash
$ dolltool -d "▌▘▖▘ ▌▖▌▘ ▌▘▘▌ ▌▘▘▌
▌▘▌▌ ▌▖▘ ▌▌▌▘ ▌▘▌▌ ▌▌▖▌ ▌▘▘▌ ▌▖▌▖ ▌▖▘ ▖▌▖▖ ▖▘▖▌"
hello world :3
```
### Generation
Generates random codes based on a user-defined pattern:
- `n`: Number (0-9)
- `l`: Letter (a-z)
- `a`: Alphanumeric (0-9, a-z)
```bash
$ dolltool -g "nn-lll" -c 3
74-igm :: ▖▘▌▖ ▖▘▘▖ ▖▖▘▌ ▌▘▖▌ ▌▘▖▖ ▌▘▌▖
01-ldc :: ▖▖▌▌ ▖▘▖▖ ▖▖▘▌ ▌▘▘▌ ▌▖▌▖ ▌▖▘▌
44-mpx :: ▖▘▘▖ ▖▘▘▖ ▖▖▘▌ ▌▘▌▖ ▌▌▖▖ ▌▌▌▌
```
If the generation pattern contains only numbers it will use the integer encoding
method as opposed to the string encoding method:
```bash
$ dolltool -g "nnnnnn" -c 3
933737 :: ▖▖▌▖▌▌▘▘▖▖▘▖▘
088231 :: ▌▌▌▌▘▘▌▘▖▖
439614 :: ▖▌▌▌▘▘▘▘▌▘▘▌
```
## How it Works
dolltool uses a bijective base-3 system, this means unlike standard base-3 which
uses 0, 1, and 2, it uses 1, 2, and 3. This removes the leading zeros which are
often present in standard base-3.
Symbol | Value
-------|-----
`▖` |1
`▘` |2
`▌` |3
## License
Copyright (c) 2026 ika4422, under [GNU GPL-3.0-or-later](https://www.gnu.org/licenses/).
See the `LICENSE` file or run:
```bash
dolltool --license
```