Crate parse_changelog

Source
Expand description

Simple changelog parser, written in Rust.

§Usage

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

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

ⓘ Note

We recommend disabling default features because they enable CLI-related dependencies which the library part does not use.

§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`."
);

§Optional features

§Supported 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 or prefix format. For example:

# [0.2.0]

description...

# 0.1.0

description...
§Prefixes

You can include characters before the version as prefix.

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

By default only “v”, “Version “, “Release “, and “” (no prefix) are allowed as prefixes.

To customize the prefix format, use the Parser::prefix_format method (library) or --prefix-format option (CLI).

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

The default version format is based on Semantic Versioning.

This is parsed by using the following regular expression:

^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z\.-]+)?(\+[0-9A-Za-z\.-]+)?$|^Unreleased$

ⓘ Note

To get the ‘Unreleased’ section in the CLI, you need to explicitly specify ‘Unreleased’ as the version.

To customize the version format, use the Parser::version_format method (library) or --version-format option (CLI).

§Suffixes

You can freely include characters after the version.

# 0.1.0 - 2020-01-01
       ^^^^^^^^^^^^^
  • create-gh-release-action: GitHub Action for creating GitHub Releases based on changelog. This action uses this crate for changelog parsing.

Structs§

Error
An error that occurred during parsing changelog or configuring the parser.
ParseIter
An iterator over release notes.
Parser
A changelog parser.
Release
A release note for a version.

Functions§

parse
Parses release notes from the given text.
parse_iter
Returns an iterator over all release notes in the given text.

Type Aliases§

Changelog
A changelog.