chordsketch-convert 0.5.0

ChordPro ↔ iReal Pro format-conversion bridge (trait scaffold)
Documentation

chordsketch-convert

crates.io

ChordPro ↔ iReal Pro format-conversion bridge (trait scaffold).

This crate is the trait scaffold for the bidirectional converter tracked under #2050. It deliberately ships only the public API shape — every conversion function returns ConversionError::NotImplemented until the direction-specific follow-up issues land.

Part of the ChordSketch project.

Installation

Add via cargo add (resolves to the latest published version automatically):

cargo add chordsketch-convert

Or pin manually — replace VERSION with the value shown on the badge above:

[dependencies]
chordsketch-convert = "VERSION"

Quick start

use chordsketch_chordpro::ast::Song;
use chordsketch_convert::{ConversionError, chordpro_to_ireal};

let song = Song::new();
match chordpro_to_ireal(&song) {
    Ok(output) => {
        let _ireal = output.output;
        for warning in output.warnings {
            eprintln!("warning: {} ({:?})", warning.message, warning.kind);
        }
    }
    Err(ConversionError::NotImplemented(tracking)) => {
        eprintln!("conversion stub — see {tracking}");
    }
    Err(e) => eprintln!("conversion failed: {e}"),
}

API

Item Signature Notes
Converter<S, T> fn convert(&self, source: &S) -> Result<ConversionOutput<T>, ConversionError> Generic trait every direction implements.
ConversionOutput<T> struct with output: T and warnings: Vec<ConversionWarning> Successful (possibly lossy) result. lossless(t) and with_warnings(t, ws) constructors.
ConversionError enum (NotImplemented, InvalidSource, UnrepresentableTarget) Failure modes; new variants are appended only.
ConversionWarning, WarningKind struct + 3-variant enum (LossyDrop, Approximated, Unsupported) Non-fatal information loss surfaced to the caller.
ChordProToIreal, IrealToChordPro unit struct, Converter impls Marker types for the two directions.
chordpro_to_ireal, ireal_to_chordpro free fn wrappers Ergonomic shortcuts for the marker-type convert calls.

Roadmap

Direction Tracking issue
iReal → ChordPro (tempo / style as directives) #2053
ChordPro → iReal (lossy lyrics drop) #2061
Auto-detect input format in CLI #2066
Expose across WASM / NAPI / FFI #2067

Relationship to chordsketch-convert-musicxml

chordsketch-convert-musicxml predates this crate and binds the ChordPro AST to MusicXML directly via free functions. The new chordsketch-convert crate is the conversion home for formats that share a small intermediate concept set (warnings, lossy drops, approximations) — namely the ChordPro ↔ iReal bridge and its expected MusicXML / Guitar Pro siblings. Consolidating the musicxml converter into this crate is tracked in a future cleanup; it would be a breaking change that does not block v0.3.0.

Links

License

MIT.