parse-changelog

A changelog parser, written in Rust.

Installation

To use this crate as a command line tool, run the following command:

cargo install parse-changelog

To use this crate as a library, add this to your Cargo.toml:

[dependencies]
parse-changelog = { version = "0.1", default-features = false }

When using this crate as a library, we recommend disabling the default feature due to the default feature enables CLI-related dependencies.

Compiler support: requires rustc 1.45+

Examples (as a command line tool)

Usage:

$ parse-changelog --help
parse-changelog
Parses changelog and returns a release note for the specified version

USAGE:
    parse-changelog <PATH> [VERSION]

OPTIONS:
        --version-format <PATTERN>    Specify version format
        --prefix <PATTERN>            Alias for --prefix-format
        --prefix-format <PATTERN>     Specify prefix format
    -h, --help                        Prints help information
    -V, --version                     Prints version information

ARGS:
    <PATH>       Path to the changelog file
    <VERSION>    Specify version (by default, select the latest release)

Gets release note for Rust 1.46.0:

$ curl -sSf https://raw.githubusercontent.com/rust-lang/rust/master/RELEASES.md > rust-releases.md
$ parse-changelog rust-releases.md 1.46.0

Output of the above command.

Examples (as a library)

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 releases = parse_changelog::parse(changelog).unwrap();

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

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

Format

By default, this crate is intended to support most markdown-based changelogs that have the title of each release starts with the version.

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. For example:

## Version 0.1.0

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

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

# v0.1.0 - 2020-01-01

Versions

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 (library), or use --version-format option ().

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

parse-changelog 0.1.0