[−][src]Crate parse_changelog

A simple changelog parser, written in Rust.

Examples

let changelog = "\
# 0.1.2 - 2020-03-01

- Bug fixes.

# 0.1.1 - 2020-02-01

- Added `Foo`.
- Added `Bar`.

# 0.1.0 - 2020-01-01

Initial release
";

// Parse changelog.
let changelog = parse_changelog::parse(changelog).unwrap();

// Get the latest release.
assert_eq!(changelog[0].version, "0.1.2");
assert_eq!(changelog[0].title, "0.1.2 - 2020-03-01");
assert_eq!(changelog[0].notes, "- Bug fixes.");

// Get the specified release.
assert_eq!(changelog["0.1.0"].title, "0.1.0 - 2020-01-01");
assert_eq!(changelog["0.1.0"].notes, "Initial release");
assert_eq!(changelog["0.1.1"].title, "0.1.1 - 2020-02-01");
assert_eq!(
    changelog["0.1.1"].notes,
    "- Added `Foo`.\n\
     - Added `Bar`."
);

The key of the map returned does not include prefixes such as "v", "Version ", etc.

let changelog_a = "\
# Version 0.1.0 - 2020-01-01
Initial release
";
let changelog_b = "\
# v0.1.0 - 2020-02-01
Initial release
";

let changelog_a = parse_changelog::parse(changelog_a).unwrap();
let changelog_b = parse_changelog::parse(changelog_b).unwrap();
// Not `changelog_a["Version 0.1.0"]`
assert_eq!(changelog_a["0.1.0"].version, "0.1.0");
assert_eq!(changelog_a["0.1.0"].title, "Version 0.1.0 - 2020-01-01");
assert_eq!(changelog_a["0.1.0"].notes, "Initial release");
// Not `changelog_b["v0.1.0"]`
assert_eq!(changelog_b["0.1.0"].version, "0.1.0");
assert_eq!(changelog_b["0.1.0"].title, "v0.1.0 - 2020-02-01");
assert_eq!(changelog_b["0.1.0"].notes, "Initial release");

Format

By default, this crate is intended to support markdown-based changelogs that have the title of each release starts with the version format based on Semantic Versioning. (e.g., Keep a Changelog's changelog format.)

Headings

The heading for each release must be Atx-style (1-6 #) or Setext-style (= or - in a line under text), and the heading levels must match with other releases.

Atx-style headings:

# 0.1.0

## 0.1.0

Setext-style headings:

0.1.0
=====

0.1.0
-----

Titles

The title of each release must start with a text or a link text (text with [ and ]) that starts with a valid version format. For example:

# [0.2.0]

description...

# 0.1.0

description...

You can also include characters before the version as prefix.

## Version 0.1.0
   ^^^^^^^^

By default only "v", "Version " and "Release " are allowed as prefixes and can be customized using the Parser::prefix_format method.

You can freely include characters after the version (this crate does not parse it).

# 0.1.0 - 2020-01-01
       ^^^^^^^^^^^^^

Versions

## v0.1.0 -- 2020-01-01
    ^^^^^

The default version format is MAJOR.MINOR.PATCH(-PRE_RELEASE)?(+BUILD_METADATA)?, and is based on Semantic Versioning. (Pre-release version and build metadata are optional.)

This is parsed using the following regular expression:

^\d+\.\d+\.\d+(-[\w\.-]+)?(\+[\w\.-]+)?$

To customize the version format, use the Parser::version_format method.

Structs

Parser	A changelog parser.
Release	A release note for a version.