Draft Proposal

Contents
    1. Objectives
    2. A high level schema
    3. ABCp Core
    4. Handling ABC files
    5. Usage scenarios
    6. Things to do

1. Objectives

An idea was discussed in the abcusers list to create a "general purpose" ABC parser.

The expected benefits are:

• To ease the creation of new ABC tools

• To consolidate the ABC syntax

It is a requirement for ABCp to be, to the maximum possible extent, language, HW and OS independent.

It also should leave space for enhancements and improvements.

It will be used to create both graphical and command line tools.

This document sketches a proposal for the high level architecture of such parser.

  The aim of this project, in the end, is not to create another ABC tool but to open up endless possibilities for writers of musical applications.

2. A high level schema

  Any "ABC-aware" applications could have (one day or another) the following architecture:

• Application (G)UI is the user interface. Could be as thick as a graphical one or as thin as a couple of switch in the command line. Ultimately it captures the user interaction with the application;
   
• Application Code is the "application specific" code. An application could be specific for the ABC world or could be only interested in importing tunes in ABC format (which could even be not the primary format) for its own purpose;
   
• Application Scripts are an interesting point. They are script that will access the ABCp core function and possibly the Application Code functions.
  Harmony Assistant, for example, can be extended with Lua scripts that can access the application internal functions;
   
• Core ABCp is the piece of software we are about to write. It will have all the functions to open ABC files, create an internal rapresentation and manipulate it;
   
• Extensions contain those advanced functions that could not be needed by some application. Among the extensions, for example, there could be functions to generate MIDI, to convert to/from MusicXML, ...
  Those functions will be tipically written in C (or accessed through a C) but could be equally well written in Lua.
   

3. ABCp core

  The figure below shows the "internals" of the ABCp Core.

  It will be seen by the host application as a C/C++ library that can be linked either statically or dinamically (DLL, .so, ...). This allows a great flexibiliy since almost all languages have mechanisms to access such libraries.

  The functions in ABCp will be written either as Lua scripts or C functions. The decision on which language to use for a given function will be taken depending on the complexity of the task, the needing for extermely high performance, the willingness of offering other programmers the ability of personalize the function and other factors not foreseeable at the moment.

  An API will be defined so that the host application (and the Lua scripts) will be able to consistenly manipulate ABC files.

4. Handling ABC files

  The figure below shows how an ABC file is supposed to be loaded and manipulated.

  Actually the first component should be a "event triggering scanner" that together with the handler scripts will form the complete parser.

  The parser will create an internal rapresentation of the ABC file (I can envisage some form of a tree being used) that will be accessed through an API that will be as much as possible meaningful from a "musical" point of view.

  Note that for certain tasks, this internal rapresentation could not be needed. To create an index of the ABC file, for example, one could simply replace the event handlers in the parser to respond to the appropriate fields ("X:", "T:", .. ).

5. Usage scenarios

  Let's go through some scenario to better understand how all this is supposed to work.

• My application is not in C. How am I supposed to access ABCp?
  Being ABCp a C library, there should be already an established method to access it. If you are programming in Java JNI could be an option, if you are programming under Windows the distribution as DLL should serve you well. I'm pretty sure something similar exists for Mac but I don't know the Apple platform well enough to answer this question;
   
• My application already has its own file format, what's in ABCp for me?
  You can use it for the sole purpose of importing or exporting tunes;
   
• I just want to write a tool for eliminating duplicate tunes in my songbooks!
  You could write a Lua script and execute it with the abcp command line tool. Lua is a very powerful yet simple to learn language. How much difficult is to implement the task, will depend on the API (and on the task, of course);
   
• Why should I expose my application internal function to Lua? I don't want my application to be scriptable!
  You are not forced to do it! The fact that some of the ABCp functions are in Lua is completely transparent to your application. Only the C interface is exposed.
  Anyway, may I suggest you to consider making you app scriptable? It may be worthwile to you and your user;
   
• I already use the scripting language X can I use it instead of Lua?
  Well, we can't support every scripting language in the world. Maybe you could take the C functions and create a different version of ABCp.
  Anyway, I would prefer this not to happen. If a single scripting language is used, a sort of "script repository" could be built that will bring a great value to the users.

6. Things to do

Just a quick list. Any comment is welcome!

1. Agree on an ABC syntax
   We might implement the 2.0 standard or we could try to include as many externsions as we can. Both approach have their disadvanages: the first might kill the project beause no one relly wants to skip their favourite extension in favour if another ABC syntax and we will have to convert tons of already existing abc files. The second will kill the project because the syntax will became a nightmare to implement and maintain.
   A right balance may only be found we the most representative abc users and abc tool makers.
    
2. Define a suitable internal represention.
   This is tied to the next point. The representation must be easy from a computer point of view (I can envisage some form of tree representation) but also should help to easily implement the API.
    
3. Define a powerful (but easy-to-use) API.
   This must be done in a way that has a "musical" meaning. No way we can simply say that the ABC file is a tree and we can move from the root up to the leaves in preorder. Someone will kill us, not the project! :).
   So, we must define it in terms of voices, parts, ... Input from people with a strong music background is required!
    
4. Agree on a scripting language.
   Needless to say I sponsor Lua (compact, fast, robust, easy to embed and to port) but I'm ready to start a comparison with other languages (Python, Ruby and Tcl/tk come to my mind).
    
5. Agree on a programming language
   I would use plain old ANSI C. Platform specific language are out of question (no VB for example) and Java is everything but embeddable (not to mention the hassle of having an up to date JVM). To keep things simple I won't use C++ with all his many unnecessary complications.
   Again, this is just my opinion! A debate must be held and a decision taken before starting.
    
6. Define architectural design
   The figures above are only for illustrative purpose. Much more thought and details should be added!
    
7. ... Add your favorite point here!