extract-frontmatter 2.0.0

# Table of Contents <!-- omit in toc -->

- [Overview](#overview)
  - [Versioning](#versioning)
- [Usage](#usage)
  - [Selectors](#selectors)
  - [Modifiers](#modifiers)
  - [Example](#example)

# Overview

A library that allows a user to extract an arbitrary number of lines of "front-matter" from the start of any multiline string.

Note that absolutely no parsing of extracted front-matter is performed; this is designed to output its results for another library to then parse.

## Versioning

This project follows [Semantic Versioning principals](https://semver.org/) starting with `v1.0.0`

# Usage

To use this library:

1. Instantiate an instance of `Extractor`
2. Call a selector method on it
3. Call zero or more modifier methods on it
4. Call:
    - `extract()` (for a `String`), or
    - `collect()` (for a `Vec<&str>`)

## Selectors

| Method                                   | Description                                                      |
| ---------------------------------------- | ---------------------------------------------------------------- |
| `select_by_terminator(terminator: &str)` | Selects lines until the first one equal to `terminator` is found |
| `select_by_prefix(prefix: &str)`         | Selects consecutive lines starting with `prefix`                 |
| `select_by_line_count(count: usize)`     | Selects `count` lines                                            |

## Modifiers

| Method                       | Description                                                    |
| ---------------------------- | -------------------------------------------------------------- |
| `strip_prefix(prefix: &str)` | Strips the given `prefix` from all returned lines              |
| `strip_whitespace()`         | Strips leading and trailing whitespace from all returned lines |
| `discard_first_line()`       | Skips the first line to be returned                            |
| `discard_last_line()`        | Skips the last line to be returned                             |

## Example

Given a variable `input` with the following text:

```md
root:
  child1: true
  child2: two
---

# Example

This is an example Markdown file.
```

... and the following code:

```rust
use extract_frontmatter::Extractor;

let mut extractor = Extractor::new(input);
extractor.select_by_terminator("---");

let output: String = extractor.extract();
```

... the variable `output` will contain:

```yml
root:
  child1: true
  child2: two
```