Skip to content

Commit

Permalink
Update docs and changelog
Browse files Browse the repository at this point in the history
  • Loading branch information
@hedgecrw
hedgecrw committed Nov 4, 2024
1 parent 647b3a1 commit cac39fa
Show file tree
Hide file tree
Showing 3 changed files with 60 additions and 27 deletions.
12 changes: 10 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,16 @@

### Added

* `no_std`
* Library has been made `no_std` compatible
* `std` feature (enabled by default) allows direct file reading/writing
* Public functionality to allow parsing to/from data buffer in addition to files
* Internal zip file reader/writer with no external dependencies
* Error documentation

### Fixed

None
* Removed dependency on `zip` crate
* Switched from `libflate` to `miniz_oxide` for DEFLATE implementation
* Fixed incorrect `32nd` duration parsing string
* Removed all naked `unwrap()` calls
* Lots of clippy cleanups
38 changes: 25 additions & 13 deletions musicxml/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
//!
//! ```toml
//! [dependencies]
//! musicxml = "1.0"
//! musicxml = "1.1"
//! ```
//!
//! # Parsing MusicXML Files
Expand Down Expand Up @@ -150,7 +150,9 @@ use elements::{ScorePartwise, ScoreTimewise};
/// The specified file can be either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the file does not exist, cannot be read, or is not a valid MusicXML file, an
/// error message will be returned.
pub fn read_score_partwise(path: &str) -> Result<ScorePartwise, String> {
parser::parse_score_partwise_from_file(path)
}
Expand All @@ -160,7 +162,9 @@ pub fn read_score_partwise(path: &str) -> Result<ScorePartwise, String> {
/// The specified file can be either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the file does not exist, cannot be read, or is not a valid MusicXML file, an
/// error message will be returned.
pub fn read_score_timewise(path: &str) -> Result<ScoreTimewise, String> {
parser::parse_score_timewise_from_file(path)
}
Expand All @@ -170,7 +174,8 @@ pub fn read_score_timewise(path: &str) -> Result<ScoreTimewise, String> {
/// The specified data should have been read directly from either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the data cannot be parsed or does not represent valid MusicXML contents, an error message will be returned.
pub fn read_score_data_partwise(data: Vec<u8>) -> Result<ScorePartwise, String> {
parser::parse_score_partwise_from_data(data)
}
Expand All @@ -180,19 +185,22 @@ pub fn read_score_data_partwise(data: Vec<u8>) -> Result<ScorePartwise, String>
/// The specified data should have been read directly from either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the data cannot be parsed or does not represent valid MusicXML contents, an error message will be returned.
pub fn read_score_data_timewise(data: Vec<u8>) -> Result<ScoreTimewise, String> {
parser::parse_score_timewise_from_data(data)
}

/// Writes a [ScorePartwise] object into a MusicXML file.
///
/// If the `compressed` parameter is set to `true`, the MusicXML file will be written as a compressed `.mxl` file.
/// If the `write_as_timewise` parameter is set to `true`, the MusicXML file will be converted into a timewise format and
/// written as a `<score-timewise>` element.
/// If the `write_as_timewise` parameter is set to `true`, the MusicXML file will be converted into a timewise
/// format and written as a `<score-timewise>` element.
///
/// # Errors
/// TODO
///
/// If the file cannot be written or the data cannot be serialized into a valid MusicXML format, an error message
/// will be returned.
pub fn write_partwise_score(
path: &str,
score: &ScorePartwise,
Expand All @@ -205,11 +213,13 @@ pub fn write_partwise_score(
/// Writes a [ScoreTimewise] object into a MusicXML file.
///
/// If the `compressed` parameter is set to `true`, the MusicXML file will be written as a compressed `.mxl` file.
/// If the `write_as_partwise` parameter is set to `true`, the MusicXML file will be converted into a partwise format and
/// written as a `<score-partwise>` element.
/// If the `write_as_partwise` parameter is set to `true`, the MusicXML file will be converted into a partwise
/// format and written as a `<score-partwise>` element.
///
/// # Errors
/// TODO
///
/// If the file cannot be written or the data cannot be serialized into a valid MusicXML format, an error message
/// will be returned.
pub fn write_timewise_score(
path: &str,
score: &ScoreTimewise,
Expand All @@ -226,7 +236,8 @@ pub fn write_timewise_score(
/// format and written as a `<score-timewise>` element.
///
/// # Errors
/// TODO
///
/// If the data cannot be serialized into a valid MusicXML format, an error message will be returned.
pub fn write_partwise_score_data(
score: &ScorePartwise,
compressed: bool,
Expand All @@ -242,7 +253,8 @@ pub fn write_partwise_score_data(
/// format and written as a `<score-partwise>` element.
///
/// # Errors
/// TODO
///
/// If the data cannot be serialized into a valid MusicXML format, an error message will be returned.
pub fn write_timewise_score_data(
score: &ScoreTimewise,
compressed: bool,
Expand Down
37 changes: 25 additions & 12 deletions musicxml/src/parser/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -143,10 +143,10 @@ fn convert_xml_partwise_to_timewise(xml: XmlElement) -> Result<XmlElement, Strin
.attributes
.iter()
.find(|(key, _)| key == "number")
.unwrap()
.ok_or("Missing \"number\" attribute in <measure> element")?
.1
.parse()
.unwrap();
.map_err(|err| format!("Invalid \"number\" attribute in <measure> element: {}", err))?;
measures
.entry(measure_number)
.or_insert_with(|| XmlElement {
Expand Down Expand Up @@ -196,7 +196,7 @@ fn convert_xml_timewise_to_partwise(xml: XmlElement) -> Result<XmlElement, Strin
.attributes
.iter()
.find(|(key, _)| key == "id")
.unwrap()
.ok_or("Missing \"id\" attribute in <measure> element")?
.1
.clone();
parts
Expand Down Expand Up @@ -234,7 +234,8 @@ fn convert_xml_timewise_to_partwise(xml: XmlElement) -> Result<XmlElement, Strin
/// element being parsed be a top-level element such as `<score-partwise>` or `<score-timewise>`.
///
/// # Errors
/// TODO
///
/// If the string cannot be parsed into a valid MusicXML element, an error message will be returned.
pub fn parse_from_xml_str<T: ElementDeserializer>(str: &str) -> Result<T, String> {
let xml = xml_parser::parse_from_string(str)?;
T::deserialize(&xml)
Expand All @@ -254,7 +255,9 @@ pub fn parse_to_xml_str<T: ElementSerializer>(data: &T, pretty_print: bool) -> S
/// The specified file can be either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the file does not exist, cannot be read, or is not a valid MusicXML file, an
/// error message will be returned.
pub fn parse_score_partwise_from_file(path: &str) -> Result<ScorePartwise, String> {
let contents = get_musicxml_contents_from_file(path)?;
let xml = xml_parser::parse_from_string(&contents)?;
Expand All @@ -266,7 +269,9 @@ pub fn parse_score_partwise_from_file(path: &str) -> Result<ScorePartwise, Strin
/// The specified file can be either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the file does not exist, cannot be read, or is not a valid MusicXML file, an
/// error message will be returned.
pub fn parse_score_timewise_from_file(path: &str) -> Result<ScoreTimewise, String> {
let contents = get_musicxml_contents_from_file(path)?;
let xml = xml_parser::parse_from_string(&contents)?;
Expand All @@ -278,7 +283,8 @@ pub fn parse_score_timewise_from_file(path: &str) -> Result<ScoreTimewise, Strin
/// The specified data should have been read directly from either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the data cannot be parsed or does not represent valid MusicXML contents, an error message will be returned.
pub fn parse_score_partwise_from_data(data: Vec<u8>) -> Result<ScorePartwise, String> {
let contents = get_musicxml_contents(data)?;
let xml = xml_parser::parse_from_string(&contents)?;
Expand All @@ -290,7 +296,8 @@ pub fn parse_score_partwise_from_data(data: Vec<u8>) -> Result<ScorePartwise, St
/// The specified data should have been read directly from either a `.musicxml` file or a compressed `.mxl` file.
///
/// # Errors
/// TODO
///
/// If the data cannot be parsed or does not represent valid MusicXML contents, an error message will be returned.
pub fn parse_score_timewise_from_data(data: Vec<u8>) -> Result<ScoreTimewise, String> {
let contents = get_musicxml_contents(data)?;
let xml = xml_parser::parse_from_string(&contents)?;
Expand All @@ -306,7 +313,9 @@ pub fn parse_score_timewise_from_data(data: Vec<u8>) -> Result<ScoreTimewise, St
/// The `pretty_print` parameter specifies whether the MusicXML file should be written with indentation and newlines.
///
/// # Errors
/// TODO
///
/// If the file cannot be written or the data cannot be serialized into a valid MusicXML format, an error message
/// will be returned.
pub fn parse_score_partwise_to_file(
path: &str,
score: &ScorePartwise,
Expand All @@ -332,7 +341,9 @@ pub fn parse_score_partwise_to_file(
/// The `pretty_print` parameter specifies whether the MusicXML file should be written with indentation and newlines.
///
/// # Errors
/// TODO
///
/// If the file cannot be written or the data cannot be serialized into a valid MusicXML format, an error message
/// will be returned.
pub fn parse_score_timewise_to_file(
path: &str,
score: &ScoreTimewise,
Expand All @@ -359,7 +370,8 @@ pub fn parse_score_timewise_to_file(
/// and newlines.
///
/// # Errors
/// TODO
///
/// If the data cannot be serialized into a valid MusicXML format, an error message will be returned.
pub fn parse_score_partwise_to_data(
score: &ScorePartwise,
compressed: bool,
Expand All @@ -384,7 +396,8 @@ pub fn parse_score_partwise_to_data(
/// and newlines.
///
/// # Errors
/// TODO
///
/// If the data cannot be serialized into a valid MusicXML format, an error message will be returned.
pub fn parse_score_timewise_to_data(
score: &ScoreTimewise,
compressed: bool,
Expand Down

0 comments on commit cac39fa

Please sign in to comment.