GUIDO-NA Parser Kit
-------------------

Version 0.63 [2003/11/11]

The GUIDO-NA Parser Kit is about to be officially released. However, this is 
not yet the official release. We therefore ask you not to distribute this version
of the GUIDO-NA Parser Kit and, in case you encounter any problems using it,
to notify us as soon as possible.



Introduction & Overview
-----------------------

The GUIDO-NA Parser Kit for C++ provides support for realising import of
files in GUIDO Music Notation Format (GMN files). It has been developed
in the context of implementing Advanced GUIDO support for the notation
software NoteAbility and reflects some of the requirements which arose
in the context of this particular project. However, we feel that
this Parser Kit will be a good basis for implementing GUIDO import
in the context of various music processing software.

The GUIDO-NA Parser Kit provides a higher-level programming interface
to the underlying GUIDO Parser Kit. The kit contains the following files:

readme.txt - this file, contains information on how to use the Parser Kit
           (text file in ASCII format)
parser_t.c - parser module (C source file, generated using GNU's Bison
           parser generator)
lexyy.c - scanner module (C source file, generated using GNU's Flex
           scanner generator)
guido.h - header file for lower-level parser interface (C header file)
guido.cpp - implementation file for the lower-level parser interface (C source file),
strlist.h - header file for string list module (C header file)
strlist.c - implementation file for string list module (C source file)
naguido.h - header file for GUIDO-NA parser interface (C header file)
naguido.cpp - implementation file for GUIDO-NA parser interface (C source file)
test.hpp - header file for test class, interfacing the GUIDO-NA parser (C++ header file)
test.cpp - imlementation file for test class, interfacing the GUIDO-NA parser (C++ source file)
gd-na.cpp - test application using GUIDO-NA parser interface (C++ source file)
makefile - makefile for sample application gd-na (using G++ as
           standard C compiler)
test.gmn - sample GUIDO Music Notation (GMN) file, can be used for 
           testing purposes.

Optional (not required for using the Parser Kit, but might be useful
when realising native parsers for languages other than C):

parser - parser definition file (GNU Bison source file), used to
           generate parser_t.c
scanner - scanner definition file (GNU Flex source file), used to
           generate lexyy.c
myflex - modified scanner skeleton file (GNU Flex skeleton file),
	   used to generate lexyy.c

More GMN files can be obtained from the GUIDO Music Notation Page
(www.informatik.tu-darmstadt.de/AFS/CM/GUIDO), section Demos.
The Basic GUIDO Specification can be obtained from the GUIDO Music
Notation Page, section Documentation.



How to use the GUIDO-NA Parser Kit
----------------------------------

To use the GUIDO-NA Parser Kit within a software application, 
the parser functions in the application specific part of file naguido.cpp
have to be implemented; furthermore, the modules naguido, guido, and strlist have to be linked to the application (see makefile for gd-na).

Typically, an application using the GUIDO-NA Parser Kit calls the
parser function na_parseGMNFile(fname) to parse the gmn-file named fname.
When called, this function reads the contents of the specified gmn-file and
calls a number of action functions whenever a piece of data (like a note or
a tag) has been parsed. These action functions are C++ functions which have
to be provided by the application. Their headers are defined in naguido.h
and they should be implemented in the application specific section of
naguido.cpp. The following action functions are called from the parser:

	na_segmInit: at the beginning of a GUIDO segment
	na_segmExit: at the end of a GUIDO segment

	na_seqInit: at the beginning of each sequence (voice)
	na_seqExit: at the end of each sequence (voice)

	na_seqAppendNote: after each complete note or rest that has been parsed 
			  (the properties of the note are passed as parameters 
			   to this function)

	na_chordInit: at the beginning of a chord
	na_seqAppendChord: after a complete chord has been parsed

	na_tagStart: for each tag, after its name has been parsed
	na_tagEnd: for each tag, at the end of its range
	(tags for which no range is specified will still trigger both function calls)

	na_tagAdd: for each tag, after its parameter list has been parsed

	na_parseError: if an error occurs while parsing (in particular, for incorrect syntax 
		       of gmn data)


Furthermore, there is a set of functions which is used to retrieve information
about tag parameters after a tag's parameter list has been parsed:

	na_getTagArgType(int n): returns type of tag parameter no. n
	na_getTagArgName(int n): returns name of tag parameter no. n 
				 (if a name has been specified explicitly, "" otherwise)
	na_getTagArgInt(int n): returns integer value of tag parameter no. n 
	na_getTagArgFloat(int n): returns float value of tag parameter no. n 
	na_getTagArgStr(int n): returns string value of tag parameter no. n
	na_getTagArgUnit(int n): returns unit of tag parameter no. n 
				 (if a unit has been specified explicitly, "" otherwise)

These functions have to be called within the implementation of function na_tagAdd,
see also file naguido.cpp.

More detailed documentation of the parser functions can be found in the header file
naguido.h.


The sample application gd_na demonstrates how the Parser Kit can be used
in the context of a simple application. We strongly suggest the following
procedure for using the GUIDO-NA Parser Kit in the context of another 
application:

1. Check that all the required files are present (see above). Remember,
  you don't need to actually generate the parser and scanner from the
  definition files, since we provide the respective C files.
  
2. Compile the sample application gd-na using the makefile from 
  the GUIDO-NA Parser Kit. You might need to substitute the name of the
  C++ compiler (g++) in the makefile. You will see a lot of warnings
  stemming from the files parser_t.c and lexyy.c; you can safely ignore
  these as they are only artifacts from the automatically generated
  parser and scanner.
  
3. Run gd-na on the test file test.gmn. The output you see reports
  each parser function as it is called, incuding the actual values of
  its parameters. You should run gd-na on different gmn-files to get a feeling
  on how and when the individual actions are called.
 
4. Integrate the parser, as used by gd-na, into your application.
  In order to do that you will probably copy the files naguido.h, naguido.cpp,
  guido.h, guido.cpp, parser_t.c and lexyy.c into your application source directory.
  You then include the interface definition files naguido.h and guido.h
  in the source file of your application that has to call the parser and insert
  the call to na_parseGMNFile into your source. (The files test.hpp and test.cpp 
  contain an example of how this can be done.)
  Keep in mind that when linking your application you now have to include
  the object files obtained from guido.cpp, naguido.cpp, and strlist.c.
  
5. Test this version of your application by trying to parse test.gmn.
  You should get the same output as produced by gd-na.
  
6. Decide on a data structure your application needs for the internal
  representation of GUIDO notation data. You should not implement this
  data structure in naguido.cpp but somewhere else where it will be 
  accessed from the action functions.
  
7. Modifify the action functions provided by naguido.cpp according to the
  needs of your application. Ideally, the action functions should contain
  only some book-keeping code and functions calls which serve to 
  further process or store the data within your application.

  IMPORTANT: Any dynamic data (pointer types) provided by the parser, such 
  as string arguments of action functions, are allocated using malloc
  and will be automatically freed by the parser after exiting from the 
  respective action function. You therefore have to copy this data into your 
  own structures if you want to keep it.

8. If required, modify the parser error function na_parseError, as provided 
  in naguido.cpp, according to your own needs.
  


On the GUIDO-NA Parser Architecture
-----------------------------------

Although in order to use the GUIDO-NA Parser Kit, only the file naguido.cpp needs 
to be adapted to the respective application, it might be of interest to get an idea
of the underlying parser architecture. The parser is built in three layers.
Layer 0 consists of a parser and scanner that has been realised using Lex and Yacc.
This layer is accessed from layer 1, where low-level action functions are called
from within the layer 0 parser. Although it is possible to use this layer for integrating
a GUIDO parser in applications (by modifying the application specific section of
guido.cpp), most applications will benefit from the higher-level interface
of the GUIDO NA Parser Kit (layer 2). This is based on a specific layer 1 implementation
which mainly collects certain low-level data, such as note attributes or tag parameters,
into larger logical units. Since the layer 0 parser and scanner are extremely efficient,
and furthermore, parsing is typically not a very time-critical process,
the overhead caused by the additional layers is relatively insignificant, such 
that there is typically no reason for directly accessing lower layers of the parser design.



Conditions of Use
-----------------

The GUIDO-NA Parser Kit is absolutely free, you can use it in the context 
of any application (freeware, shareware, commercial) you want to without
any obligations.

However, we ask you to: 

- notify us about any application supporting GUIDO Notation you realised
  which might be interesting for others. We will be happy to include
  a link and a short description of your application into our GUIDO website
  and other GUIDO related information.

- acknowlegde using the GUIDO-NA Parser Kit within your software. This 
  is an act of courtesy only and implies absolutely no obligations for you.

- not to redistribute the GUIDO Parser Kit in other than its original
  form without contacting us first.

- contact us if you have any problems, suggestions, or comments regarding 
  GUIDO Music Notation or this GUIDO-NA Parser Kit (for contact address,
  see information below).
  


Problems?
---------

Should you encounter any problems in using the GUIDO-NA Parser Kit,
please contact by email (hoos@salieri.org), we will be
happy to help you. You should also refer to our GUIDO Notation Page at 
www.salieri.org/GUIDO for more information on 
GUIDO, example gmn-files, updates of the GUIDO-NA Parser Kit, tools and 
applications supporting GUIDO Notation and the latest news on GUIDO.


