----- leanGUIDO class library ---------------

This class library should provide basic functionality and a
basic class library for reading and writing of GUIDO files.
It is designed as a general purpose class library with no specific 
application (like score viewing or MIDI playback) in mind. Therefore
it provides only the basic, general functions without unnecessary 
overhead. Specific functions for special application areas 
should be easy to add to the leanGUIDO class library.

For more information about GUIDO MusicNotation please
see http://www.salieri.org/GUIDO or http://www.noteserver.org

files:

lgobject.h	// base class for all other types
lgobject.cpp
lgtag.h		// GUIDO tags 
lgtag.cpp
lgtagarg.h	// tag arguments
lgtagarg.cpp	

lgevent.h	// GUIDO events
lgevent.cpp
lgempty.h	// GUIDO empty notes
lgempty.cpp
lgrest.h	// GUIDO rests
lgrest.cpp
lgnote.h	// GUIDO notes
lgnote.cpp

lgvoice.h	// voice - implicite data type
lgvoice.cpp

lgchord.h	// GUIDO chord
lgchord.cpp
lgsequence.h	// GUIDO sequence
lgsequence.cpp
lgsegment.h	// GUIDO segment
lgsegment.cpp
lgfactory.cpp	// the generic factory class
lgfactory.h

lgguido.cpp	// leanGUIDO adaption of naguido.coo of the GUIDO parser-kit
lgmain.cpp	// test commandline application

leanGUIDO.mcp	     // Metroworks Codewarrior porject file
leanGUIDO.dsw | .dsp // Microsoft VC++ project file
leanGUIDO.pbproj     // OS-X ProjectBuilder project file	
makefile	     // unix makefile

lgstructure.pdf // graphical overview about the pointer structures

Additional files needed for leanguido:

In addition to the lg-files the GUIDO parser-kit is needed
if parser-functions should be used. The parser-kit is
free available at http://www.salieri.org/GUIDO.
If you don't need parser functions you can undefine USE_GUIDO_PARSER in 
lgsegment.h.

Demo projects:
./gmntransp
	an easy gmn chromatic-transpose commandline tool which shows how to 
	add/change functions of the leanGUIDO classes
./striptags
  a little commandline tool for removing tags from a .gmn file

Documentation:
Additional documentation, class hirarchy can be generated by using the doxigen tool (http://www.doxygen.org).
A graphical overview about the pointer structures can be found in lgStruture.pdf


Structure of leanGUIDO :
lgSegment =  [lgSequence]*
lgSequence =  lgVoice 
lgVoice = ([lgTag]* + [lgEvent] + [lgTag]*)*
lgEvent = lgNote | lgRest | lgChord | lgEmpty
lgChord = [lgVoice]*  !a voice of a chord MUST include exactly a single lgNote but can include an arbitrary number of tags!
lgTag = tagName + [lgTagArg]*
lgTagArg = lgFloatArg | lgIntArg | lgStrArg


Syntax of a GUIDO file:

GUIDO file = segment | sequence
segment =  "{" + [sequence + ["," + sequence]* ]  + "}"
sequence =  "[" +  voice  + "]"
voice =  [event | chord]*  |    [tag]*  + voice   |  ( tag + "(" +  voice  + ")"   )*
event = note | rest | empty

note = pitch + [accidental] + [octave] + [duration]
pitch = "c"| "cis" | "d"  | "dis" | ...    % please see GUIDO spec for valid pitch classes and note names   
rest = "_" + [duration]
empty = "empty" + duration
octave = -oo...+oo   
accidental = "&"*  |  "#"*
duration = [ "*" + numerator  ] + " /" + denominator
numerator = integer
denominator = integer
chord = "{" + chordVoice + ["," +  chordVoice]* +  "}"
chordVoice = event  |  [tag]* + chordVoice  + [tag]* )   |  tag + "(" + chordVoice + ")"

tag = "\" + tagname + [ ":" + id ] +  ["<" +  tagArg  +  ["," +  tagArg]* +  ">"  ]
tagname = string
id = integer
tagArg = [argName + "=" ]  +   (  \" + strValue + \"   |  intValue  + [unit]   |   floatValue + [unit]  )
argName = string
unit = "mm" | "cm" | "hs" |  "pt"  | ...

Remarks:
-  [ a ] means a is optional
- a | b means a or b
- "c"  means character c
- \" means the " character
- + means conactenation
- a*  means nothing, a  or many times a
- a + b | c+ d  means a+b or c+d
- a + (b | c ) + d means  a + b + d or a + c + d





Usage:
- leanGUIDO includes functinality for reading a .gmn files, buidling up an  
 internal data-structure and writing .gmn files
- leanGUIDO does not check the semantics and implicite ranges of tags!
- \tagname(...) ranges of a GUIDO file will be stored as two separate, crosslinked tags (lgTag(tagName) + lgTag(")") )
- leanGUIDO should be used as base class for higher level GUIDO classes for specific applications or application areas like score-rendering, playback, analysis, ...
- insert/delete functions for tags and events should be implemened in derived classes.
- leanGUIDO can be used without the GUIDO parser kit. 
- for using derived classes own lgFactory classes needs to be defined. Please see the demo projects for details.

Remarks:
- lgObject->next() does not look inside chords! Use lgChord->firstObject for 
  determining chords
- lgVoice is nearly equal to lgSequence. Inside chords a lgVoice must contain only a single note (and arbitrary number of tags)! 
- some of the parser-kit files are written in C! please set the "force C++ compilation" of your compiler (i.e. Metroworks CodeWarrioir) to OFF. 

Examples:
In the directory gmntransp you find an example application using leanGUIDO for implementing a simple GUIDO transpose tool.
In the directory striptags you find an commandline tool for removing tags from a .gmn file

License:
leanGUIDO is under LGPL license. Please feel free to use it in your own projects.


Please send all questions and remarks to kilian@noteserver.org

Juergen Kilian/SALIERI Project 2003/11/11

