gabc-parser

Crates.iogabc-parser
lib.rsgabc-parser
version0.1.1
sourcesrc
created_at2018-08-15 05:35:11.506232
updated_at2018-08-16 19:48:39.696541
descriptionA library for parsing, manipulating, and converting gabc files
homepage
repositoryhttps://github.com/saybaar/gabc-parser
max_upload_size
id79520
size66,712
(saybaar)

documentation

README

gabc-parser

gabc-parser is a Rust library to parse and analyze gabc, a typesetting language for Gregorian chant. It provides functions to parse a gabc file, represent and manipulate it as a Rust struct, and automatically convert to JSON and Lilypond.

Documentation is available at docs.rs.

Using this library

To use this library, you will need to include it in a Rust project's Cargo.toml:

[dependencies]
gabc-parser = "0.1.1"

and load it in a Rust file:

extern crate gabc-parser;

If you're looking for a standalone program to convert gabc files to JSON or Lilypond, try gabc-converter, a simple command-line program that uses this library. gabctk is another good option for Lilypond conversion.

Local development

To run the library locally, clone this repository with git clone https://github.com/saybaar/gabc-parser.git. To use the local version in another Rust project, use the following in Cargo.toml:

[dependencies]
gabc-parser = { path = "<path to local gabc-parser>" }

In the gabc-parser directory, run cargo build to build the current version (which will then be used by any Rust project that refers to the local library) and cargo test to run the tests.

Example gabc files

The gabc files in /examples should all play nicely with this library. populus_sion.gabc is the canonical example in the gabc documentation, and the other examples are from gregobase.

Limitations

This library is under development and doesn't yet recognize all gabc syntax. Major gabc features not yet supported include:

  • Accidentals and flat clefs (e.g. "cb2")
  • gabc comments
  • Text above or below the staff

Auto-generated Lilypond may require adjustments, especially to the transposition range (which is c -> c' by default) or to correct formatting and alignment of lyrics.

Resources

Other gabc tools

  • gabctk: A toolkit for gabc, including conversion to Lilypond, abc, midi, and others. Written in Python and documented (only) in French.
  • gabc2mid: An earlier iteration of gabctk with midi conversion only. Written in Python with English documentation available.
  • gabc-to-ly: Conversion from gabc to Lilypond via a .csv file, which can be manually edited to add organ accompaniment chords. Written in Python.
  • lygre: Conversion from gabc to Lilypond. Written in Ruby.

Gregorio and gabc

gabc is part of the Gregorio project, which also includes the GregorioTeX tool for rendering gabc. GregorioTeX can be installed locally, which may be a complicated process. Web renderers like run.gregoriochant.org are a simpler option.

Lilypond

Lilypond files can be rendered with lilypond file.ly on a local installation, or through a web renderer like lilybin.


Copyright (c) 2018 Lydia Simmons
This software is licensed under the GNU General Public License v3.0. See the LICENSE file in this distribution for license terms.

Commit count: 61

cargo fmt