Humdrum Extras

Humdrum Extras is a set of command-line programs and C++ parser library for processing Humdrum files. The programs can be compiled for Linux, Apple OS X, or Windows (primarily within cygwin, but also in Visual C++). The Humdrum Extras library can be used to parse Humdrum files independent of the example programs provided with the package.

Example Programs

The primary intent of the Humdrum Extras package is for user-based processing of Humdrum files as an auxiliary to the Humdrum Toolkit. Since the programs are compiled from C++, they process data much faster than programs written in interpreted languages, such as AWK which is the main development language for the Humdrum Toolkit.

Documentation for example programs can be found on the web at extras.humdrum.org/man. The source code for these programs is found in the download file, within the src-programs directory, or they can be viewed online.

Programming Examples

humecho.cpp

Here is a very simple C++ program called humecho.cpp that uses the Humdrum file parser in the Humdrum Extras library:

#include "humdrum.h"
#include <iostream>

int main(int argc, char** argv) {
   HumdrumFile hfile;
   if (argc > 1) hfile.read(argv[1]);
   else hfile.read(std::cin);
   std::cout << hfile;
   return 0;
}

This program will take one Humdrum file as an argument (or standard input) and echo the contents of the Humdrum file to standard output. To compile this program using the Humdrum Extras makefiles, place humecho.cpp in the directory humextra/src-programs, and then type "make humecho. The humecho program can be utilized in several ways, including downloading from the web, or using the humdrum:// (or hum:// or h:// abbreviations):

   cat file.krn | bin/humecho           | less     # standard input
   bin/humecho file.krn                 | less     # command-line argument
   bin/humecho h://wtc/wtc1f01.krn      | less     # humdrum:// URI
   bin/humecho http://y.z.com/file.krn  | less     # URL

humecho2.cpp

The humecho program shows how to access the datafile in its entirety. The following source code for humecho2.cpp demonstrates how to access lines in the file individually. A HumdrumFile class essentially consists of an array of HumdrumRecord classes, and HumdrumRecord classes essentially are character strings which print tab-delimited with cout:

#include "humdrum.h"

int main(int argc, char** argv) {
   HumdrumFile hfile;
   if (argc > 1) hfile.read(argv[1]);
   else hfile.read(std::cin);
   for (int i=0; i<hfile.getNumLines(); i++) {
      std::cout << hfile[i] << std::endl;
   }
   return 0;
}

hfile.getNumLines() returns the number of text lines in the Humdrum file stored in the hfile variable. So the for loop iterates through each line in the file and prints it to standard output.

humecho3.cpp

An even more verbose version of humecho is given below. The humecho3 program implements the << operator as a second for-loop. Each HumdrumRecord representing a line of music can be thought of as an array of strings, with each string being one token in the Humdrum File structure.

#include "humdrum.h"

int main(int argc, char** argv) {
   HumdrumFile hfile;
   if (argc > 1) hfile.read(argv[1]);
   else hfile.read(std::cin);
   for (int i=0; i<hfile.getNumLines(); i++) {
      std::cout << "\t" << hfile[i][0];
      for (int j=1; j<hfile[i].getFieldCount(); j++) {
         std::cout << "\t" << hfile[i][j] << std::endl;
      }
      std::cout << std::endl;
   }
   return 0;
}

HumdrumRecords always contain at least one field, so the code "cout << hfile[i][0];" will not cause an invalid array access in any situation. Both [] operators used on the hfile variable (first to access a HumdrumRecord, and the second for a const char*) are checked for a valid range, and the program will exit with an error if an out-of-range value is requested.

The code hfile[i].getFieldCount() returns the number of "fields" on the line. This is a non-standard term for Humdrum files, since "spines" and "tokens" can have somewhat ambiguous meanings. The field count is a count of the spines, but if the spines split the count would include the subspines as well. Global comments and reference records are always element 0 in a HumdrumRecord line. Empty lines, which are technically not allowed in Humdrum files, are also acessed as an empty string at element 0.

Note that hfile[i][j] is a const char* and not a char*. If you want to change the contents of a field, you would have to use hfile[i].changeField(j, "new string").