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
serde
— Implementsserde::Serialize
trait for parse-changelog types.
§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
^^^^^^^^^^^^^
§Related Projects
- 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.
- Parse
Iter - 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.