acorde-io 0.15.0

MusicXML / MIDI / ABC / MSCZ parsers and serializer for acorde-core
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use acorde_core::Score;
use serde::{Deserialize, Serialize};

/// Version of the serialized import/export report contract.
pub const REPORT_SCHEMA_VERSION: u32 = 1;

fn default_report_schema_version() -> u32 {
    REPORT_SCHEMA_VERSION
}

/// Severity of an interchange diagnostic.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum DiagnosticSeverity {
    Info,
    Warning,
    Error,
}

/// A source-grounded note about an import or export decision.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Diagnostic {
    pub code: String,
    pub severity: DiagnosticSeverity,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_location: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preserved_value: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub loss_reason: Option<String>,
}

impl Diagnostic {
    pub fn info(code: impl Into<String>, preserved_value: impl Into<String>) -> Self {
        Self {
            code: code.into(),
            severity: DiagnosticSeverity::Info,
            source_location: None,
            preserved_value: Some(preserved_value.into()),
            loss_reason: None,
        }
    }
}

/// Result of importing a notation document, including conversion diagnostics.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImportReport {
    /// Version of the serialized report shape.
    #[serde(default = "default_report_schema_version")]
    pub schema_version: u32,
    /// Stable lowercase format identifier for the source document.
    #[serde(default)]
    pub format: String,
    pub score: Score,
    #[serde(default)]
    pub diagnostics: Vec<Diagnostic>,
}

impl ImportReport {
    pub fn new(score: Score) -> Self {
        Self {
            schema_version: REPORT_SCHEMA_VERSION,
            format: "unknown".to_string(),
            score,
            diagnostics: Vec::new(),
        }
    }

    pub fn for_format(score: Score, format: impl Into<String>) -> Self {
        Self {
            format: format.into(),
            ..Self::new(score)
        }
    }
}

/// Result of exporting a notation document, including conversion diagnostics.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ExportReport<T> {
    /// Version of the serialized report shape.
    #[serde(default = "default_report_schema_version")]
    pub schema_version: u32,
    /// Stable lowercase format identifier for the output document.
    #[serde(default)]
    pub format: String,
    pub output: T,
    #[serde(default)]
    pub diagnostics: Vec<Diagnostic>,
}

impl<T> ExportReport<T> {
    pub fn new(output: T) -> Self {
        Self {
            schema_version: REPORT_SCHEMA_VERSION,
            format: "unknown".to_string(),
            output,
            diagnostics: Vec::new(),
        }
    }

    pub fn for_format(output: T, format: impl Into<String>) -> Self {
        Self {
            format: format.into(),
            ..Self::new(output)
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn diagnostic_round_trips_with_optional_fields() {
        let mut diagnostic = Diagnostic::info("musicxml.title", "A score");
        diagnostic.source_location = Some("/score-work/title".to_string());
        let json = serde_json::to_string(&diagnostic).expect("diagnostic serializes");
        let restored: Diagnostic = serde_json::from_str(&json).expect("diagnostic parses");
        assert_eq!(restored, diagnostic);
    }

    #[test]
    fn reports_default_to_no_loss() {
        let report = ImportReport::new(Score::default());
        assert_eq!(report.schema_version, REPORT_SCHEMA_VERSION);
        assert_eq!(report.format, "unknown");
        assert!(report.diagnostics.is_empty());
        let output = ExportReport::new("output");
        assert_eq!(output.schema_version, REPORT_SCHEMA_VERSION);
        assert_eq!(output.format, "unknown");
        assert!(output.diagnostics.is_empty());
    }

    #[test]
    fn legacy_export_report_defaults_to_current_schema() {
        let restored: ExportReport<String> =
            serde_json::from_str(r#"{"format":"musicxml","output":"output","diagnostics":[]}"#)
                .expect("legacy report parses");
        assert_eq!(restored.schema_version, REPORT_SCHEMA_VERSION);
    }
}