stitch-compute/README.md

compute stitch adjustments for knitting

# stitch-compute

[![Code coverage status][codecov-badge]][codecov-url]
[![CI status][ci-badge]][ci-url]

> Computes evenly distributed additional or combinatory stitches to adjust the length of a knitting row.

## Installation

```bash
$ npm install stitch-compute
```

## Usage

```typescript
import { StitchCompute } from 'stitch-compute';
```

### StitchCompute

Main class containing all public functions.

#### adjustEvenly( from, to )

Computes evenly distributed keeps (`K`), additions (`A`) and
combinations (`C`) to grow or shrink your knitting row
from `from` stitches to `to` stitches.

```typescript
const result = new StitchCompute().adjustEvenly(10, 11);
// returns "K5 A1 K5"
// meaning: keep 5 stitches, add 1 extra stitch, keep 5 stitches

const result = new StitchCompute().adjustEvenly(30, 25);
// returns "5x ( K2 C1 K2 )"
// meaning: keep 2 stitches, combine 2 stitches into 1, keep 2 stitches.
//          repeat all of this 5 times
```

Notes:

- `to` must be at least half of `from` and at most twice `from`

#### setFormatters( formatters )

Changes the output texts. `%d` will be replaced by a number, `%s` by a string. To the defaults can be set like this:

```typescript
import { StichCompute, FormatterSet } from 'stitch-compute';
const stitchComputer = new StitchCompute();
const formatters: FormatterSet = {
  keepStitches: 'K%d',
  addStitches: 'A%d',
  combineStitches: 'C%d',
  groupInstructions: '%dx ( %s )',
  listSeparator: ' '
};
stitchComputer.setFormatters(formatters);
// stitchComputer.adjustEvenly() will now use the new formatters
```

Notes:

- errors are thrown if the format strings don't include the required placeholders (see the defaults for what is required where)

## Tests

### Preparation

To run the tests or calculate the code coverage, all development dependencies have to be installed.
This can be done with:

```bash
$ npm install
```

### BDD tests

The BDD tests use the [Mocha](http://mochajs.org) test framework with [Chai](http://chaijs.com) assertions (expect/BDD style).
The tests can be run with:

```bash
$ npm test
```

Results will directly be shown in the console.

### Code Coverage

Code Coverage is calculated using the /nyc/ commandline frontend to the [Istanbul](https://istanbul.js.org/) project.
The code coverage can be calculated with:

```bash
$ npm run coverage
```

The code coverage report will be generated in the `coverage/` subdirectory. Browse `coverage/index.html` to see the report.

## License

[GNU GPL v3 or later](https://www.gnu.org/licenses/#GPL)

## Copyright

Copyright (C) 2021 Christian Garbs <mitch@cgarbs.de>  
Licensed under GNU GPL v3 or later.

stitch-compute is free software: you can redistribute it and/or modify  
it under the terms of the GNU General Public License as published by  
the Free Software Foundation, either version 3 of the License, or  
(at your option) any later version.

stitch-compute is distributed in the hope that it will be useful,  
but WITHOUT ANY WARRANTY; without even the implied warranty of  
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the  
GNU General Public License for more details.

You should have received a copy of the GNU General Public License  
along with stitch-compute. If not, see <http://www.gnu.org/licenses/>.

[codecov-badge]: https://codecov.io/gh/mmitch/stitch-compute-npm/branch/master/graph/badge.svg?token=qE6TI2Ehpx
[codecov-url]: https://codecov.io/github/mmitch/stitch-compute-npm?branch=master
[ci-badge]: https://github.com/mmitch/stitch-compute-npm/workflows/Node.js%20CI/badge.svg?branch=master
[ci-url]: https://github.com/mmitch/stitch-compute-npm/actions?query=workflow%3A%22Node.js+CI%22