template-readme.hbs

# string-mutilator

A JavaScript library for mutilate strings.

[![MIT license][license-badge]][license]


## Motivation background

Most of the code from this project was created during a personal codegolf
competition to distort the appearance of strings as much as possible but
without actually destroying their contents.

So the name [`mutilator`][mutilator] come into my mind.

> mutilator (plural mutilators)
> 1. Agent noun of mutilate; one who mutilates.

This sounds unnecessarily brutal for now, but I assure you that no strings
will be harmed permanently, as long as the functions are used correctly. :smirk:

So I decided to combine these "strange" functions into one library.
More or less just for fun.


## Demo

A [comprehensive demo][pseudo-cipherer-demo] of all functions can be found in
the demonstration of this library/package in the demo project
[`pseudeo-chiperer`][pseudo-cipherer-repo].


## Table of content

1. [Modules](#user-content-module)
2. [Functions](#user-content-functions)
3. [Involutory functions](#user-content-involutory-functions)
4. [Using the CLI](#user-content-using-the-cli)


{{>main}}


## Involutory functions

> An [involutory function][involution], is a function f that is its own inverse.

### List of involutory functions

* [`flipBits`](#flipBits)
* [`reverse`](#reverse)
* [`reverseBits`](#reverseBits)
* [`rot13`](#rot13)

**Example**

```js
import { rot13 } from '@0x04/string-mutilator';

rot13(rot13('Hello World!')) === 'Hello World!';
// > true
```

### List of involutory functions with negated arguments

* [`charCase.invert`](#module_stringMutilator/charCase..invert)
* [`shift`](#shift)
* [`shiftBits`](#shiftBits)

**Example**

```js
import { shift } from '@0x04/string-mutilator';

shift(shift('Hello World!', 5), -5) === 'Hello World!';
// > true
```

### List of involutory functions with counter function

* [`compressor.pack`](#module_stringMutilator/compressor..pack) / [`compressor.unpack`](#module_stringMutilator/compressor..unpack)
* [`unicode.fixSurrogates`](#module_stringMutilator/unicode..fixSurrogates) / [`unicode.unfixSurrogates`](#module_stringMutilator/unicode..unfixSurrogates)

**Examples**

```js
import { compressor } from '@0x04/string-mutilator';

compressor.unpack(compressor.pack('Hello World!')) === 'Hello World!';
// > true
```

### List of non involutory functions

* [`compressor.signature`](#module_stringMutilator/compressor..signature)
* [`gobbledygook`](#gobbledygook)
* [`jumble`](#jumble)
* [`rockdotize`](#rockdotize)
* [`scramble`](#scramble)
* [`toMANS`](#toMANS)

```js
import { jumble } from '@0x04/string-mutilator';

jumble(jumble('Hello World!')) === 'Hello World!';
// > false
```


## Using the CLI

### Install

**To use it in your project**

```bash
$ npm install --save @0x04/string-mutilator
```

**To use it globally**

```bash
$ npm install --global @0x04/string-mutilator
```

### General usage

```plain
$ string-mutilator --help

  Functions for mutilating strings.

  Usage
  $ string-mutilator <function> <string> [argument]...

    Functions
      charCase.invert
      compressor.pack
      compressor.unpack
      compressor.signature
      charCase.snakeCase
      charCase.camelCase
      charCase.kebabCase
      charCase.dotCase
      charCase.pascalCase
      charCase.capitalize
      flipBits
      gobbledygook
      jumble
      reverse
      reverseBits
      rockdotize
      rot13
      scramble
      shift
      shiftBits
      toMANS
      unicode.fixSurrogates
      unicode.unfixSurrogates

    Examples
      $ string-mutilator shift "Hello World!" 6
      $ string-mutilator charCase.invert "Hello World!"
      $ string-mutilator toMANS "Hello World!" 4
```


## License

&copy; 2019 by [Oliver Kühn][0x04]. Released under the [MIT license][license].


<!-- Badges -->
[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge
[license]: ./license


<!-- Links -->
[0x04]: mailto:ok@0x04.de
[pseudo-cipherer-demo]: https://0x04.github.io/pseudo-cipherer
[pseudo-cipherer-repo]: https://github.com/0x04/pseudo-cipherer

<!-- Appendix -->
[involution]: https://en.wikipedia.org/wiki/Involution_(mathematics)
[mutilator]: https://en.wiktionary.org/wiki/mutilator