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

Basic data access

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 (Accessing individual lines)

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 (Accessing spine data)

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").

HumdrumRecord line types

Each HumdrumRecord is a certain enumerated type.

Use the HumdrumRecord::getType() function to access the type of a line. But for better code readability, the following helper HumdrumRecord functions interface with these enumerations:

In addition there are a few composite test for line types:

"rid -GLI" (Remove all lines except for data lines)

The Humdrum Tool rid with the -GLI options can be implemented using the following C++ code:

#include "humdrum.h"
int main(int argc, char** argv) {
   HumdrumFile hfile(argv[1]);
   for (int i=0; i<hfile.getNumLines(); i++) {
      if (!(hfile[i].isData() || hfile[i].isMeasure())) continue;
      std::cout << hfile[i] << std::endl;
   }
   return 0;
}

The above code will only print lines which are data or barlines. The official Humdrum file specification does not technically distinguish between barlines and data, but in practice and from a logical point of view they must be separated. So when using the Humdrum Extras C++ parser for Humdrum files, a line of data should not contain a mixture of data (or null tokens) and barlines.

"rid -GLId" (Remove comments, interpretations and null data)

#include "humdrum.h"
int main(int argc, char** argv) {
   HumdrumFile hfile(argv[1]);
   for (int i=0; i<hfile.getNumLines(); i++) {
      if (!(hfile[i].isData() || hfile[i].isMeasure())) continue;
      if (hfile[i].isNull()) continue;
      std::cout << hfile[i] << std::endl;
   }
   return 0;
}

The HumdrumRecord::isNull() returns true if all fields in the record are equal to the string "." (called a null record in Humdrum terminology—not related to a NULL pointer in C).

User-specified Options

"myrid -M -C -I" (Handling command-line options)

The Humdrum Extras code contains a helper class called Options which can be used to manage command-line options. The following example program implements the options -M (suppress measure lines), -C (suppress comments), -I (suppress interpretations) in a C++ implementation of the Humdrum Toolkit rid program.

The Options class can be used to define multiple aliases for the same option, such as a short abbreviation and a long form. The options are formulated on the command line according to POSIX rules for options: single-letter options are preceded by a single dash. Multiple-letter options are preceeded by two dashes. When a single-letter option does not require it's own argument, they can be globbed together into a list of options preceded by a single dash. Here are various program usages for the code below:

Note in the following source code, an extra include directive does not need to be added, since the declaration of the Options class is included in humdrum.h. If you want to use the Options class independent of the HumdrumFile parser, you can instead include the file "Options.h".

#include "humdrum.h"
int main(int argc, char** argv) {
   Options opts;
   opts.define("M|no-measures:b", "remove measures");
   opts.define("C|no-comments:b", "remove comments");
   opts.define("I|no-interpretations:b", "remove interpretations");
   opts.process(argc, argv);
   int measuresQ = !opts.getBoolean("no-measures");
   int commentsQ = !opts.getBoolean("no-comments");
   int interpQ = !opts.getBoolean("no-interpretations");
   HumdrumFile hfile(opts.getArg(1));
   for (int i=0; i<hfile.getNumLines(); i++) {
      if (hfile[i].isMeasure() && !measureQ) continue;
      if (hfile[i].isComment() && !commentQ) continue;
      if (hfile[i].isInterpretation() && !interpQ) continue;
      std::cout << hfile[i] << std::endl;
   }
   return 0;
}

The code "HumdrumFile hfile(opts.getArg(1));" reads data from the first argument on the command line. Note that argument counts are indexed from 1 rather than 0. Perhaps not a great thing to do, but was intended to allow for similar behavior with command-line string arrays in C, where the name of the command is stored in array element 0, and the first argument (or option) is stored in array element 1. To access the name of the command, use the Options::getCommand() function.

Option definitions

Notice the Options::define() function calls in the above program. These are used to define the options that an Options variable will search for when the Options::process() function is called. The .define() function takes two arguments (the second one optional). The first argument is the definition string, and the second is a human-readable description of the option.

The option definition string has the basic format:

The OptionName can include aliases which are added to the Option name, separated by a pipe (|) character:

For example:

Is the definition of the option "M" or equivalently "no-measures" which is a boolean type (which means that it sets a true/false switch for the option). For boolean options, there is no default value—they are "false" if not given as an argument to the program, and turned to "true" when given as input to a program.

There are four Options data types:

In terms of implementation, there are really only two types: booleans (with out parameters) and non-booleans (with parameters). Within a C++ program you can acess the original string form of the option's parameter, or you can convert it into an int or a double at runtime. For example, if an option "number" is defined, you can get the integer version of the number with .getInteger("number"), or the double version of the number with .getDouble("number"), or you can check to see if the option was set from the input arguments to the program with .getBoolean("number").

Here are some example option definitions with option names, option aliases, and option types:

When options names (or option aliases) are a single character, the space between the option name and it parameter is optional, as in "command -m 10" or "command -m10". When an option has multiple characters, the space is not optional, although an equals sign can be substituted for the space: "command --value 5.23" and "command --value=5.23". When a string option contains spaces, or other special characters reserved for shell syntax, (such as [;&$|?*\]). The multi-word option must be enclosed in quotes. To insert a quote into the string option place a backslash before it: \". To prevent the command-line parser from looking inside of the string use single quotes: "command -t 'funny $tring'". In this case the final input will be "funny $tring". If double quotes were used, $tring would be interpreted as an environmental variable and its value would be substituted, usually resulting in "funny ", since you are not likely to have the shell variable $tring defined.

Default option values

The final component of the option definition is a default value to use if no input is given for that option on the command-line. If no default value is given in the definition, the default value will be zero. For example, if this option definition is given:

   options.define("v|val|value=i:10", "an integer value");

Then here are different behaviors when accessing that option's value in C++:

User-set option:

  program -v 20
     options.getInteger("value")      → 20
     options.getInteger("val")        → 20
     options.getInteger("v")          → 20

Default option:

  program
     options.getInteger("value")      → 10
     options.getInteger("val")        → 10
     options.getInteger("v")          → 10

Accessing option values

As mentioned previously, the .getBoolean, .getInteger, .getDouble and .getString accessor functions are used to extract an option value from the Options database after .process() has been called on the argc and argv input parameters to main(). All of the get functions can be applied to any option type. For example, using the option definition:

   .define("t|tempature=d:80.6 Farenheit", "temperature setting")

can be used to extract any of the four option types in C++:

  .getBoolean("temperature")           → 1 (true) if set via the command-line.
                                       → 0 (false) if not set via the command-line.
  .getInteger("temperature")           → 80
  .getDouble("temperature")            → 80.6
  .getString("temperature")            → "80.6 Farenheit"

Input from piped data or file(s)

Most of the previous program examples expect a single filename as input for processing. The following program example (humecho4 is more flexible, allowing for multiple input files. If no filenames are given, then standard input will be read as the input data:

#include "humdrum.h"
int main(int argc, char** argv) {
   Options options(argc, argv);
   options.process();
   HumdrumFile hfile;
   int numinputs = options.getArgCount();
   for (int i=1; i<=numinputs || i==0; i++) {
      if (numinputs < 1) {
         hfile.read(std::cin); // read from standard input
      } else {
         hfile.read(options.getArg(i));
      }
      // do something with the Humdrum data here:
      std::cout << hfile;
   }
   return 0;
}

         file 1                   file 2
         ========                 =========

         **kern                   **kern
         1c                       2cc
         2d                       4b
         4e                       2a
         *-                       *-

**kern
1c
2d
4e
*-
**kern
2cc
4b
2a
*-

  humecho4 file.krn
  humecho4 file1.krn file2.krn file3.krn
  cat file.krn | humecho4
  humecho4

#include "humdrum.h"
int main(int argc, char** argv) {
   Options options(argc, argv);
   options.process();
   HumdrumFile hfile;
   hfile.read(options.getArg(1));
   char buffer[1024] = {0};
   for (int i=0; i<hfile.getNumLines(); i++) {
      if (!hfile[i].isData()) continue; // ignore non-data lines
      for (int j=0; j<hfile[i].getFieldCount(); j++) {
         if (strcmp("**kern", hfile[i].getExInterp(j)) != 0) continue;
         if (strcmp(".", hfile[i][j]) == 0) continue; // ignore null tokens
         int count = hfile[i].getTokenCount(j);
         for (int k=0; k<count; k++) {
            cout << "(" << i+1 <<"," << j+1 << "," << k+1 << ")\t"
                 << hfile[i].getToken(buffer, j, k) << endl;
         } 
      }
   }
   return 0;
}

if (strcmp("**kern", hfile[i].getExInterp(j)) != 0) continue;

**kern	**text	**kern
4C	ig-	4c
4D 4E	-no-	.
4F	-red	.
.	.	4d 4e
4r	.	.
4G 4A 4B	text	.
*-	*-	*-

  (2,1,1) 4C
  (2,3,1) 4c
  (3,1,1) 4D
  (3,1,2) 4E
  (4,1,1) 4F
  (5,3,1) 4d
  (5,3,2) 4e
  (6,1,1) 4r
  (7,1,1) 4G
  (7,1,2) 4A
  (7,1,3) 4B

#include "humdrum.h"
using namespace std;
int main(int argc, char** argv) {
   Options options(argc, argv);
   options.process();
   HumdrumFile hfile;
   int restcount   = 0;
   int nullcount   = 0;
   int attackcount = 0;
   int tiedcount   = 0;
   int chordcount  = 0;
   for (int arg=1; arg <= options.getArgCount() || arg == 0; arg++) {
      if (options.getArgCount() == 0) {  hfile.read(cin); } 
      else { hfile.read(options.getArg(arg)); }
      char buffer[1024] = {0};
      for (int i=0; i<hfile.getNumLines(); i++) {
         if (!hfile[i].isData()) continue;
         for (int j=0; j<hfile[i].getFieldCount(); j++) {
            if (!hfile[i].isExInterp(j, "**kern")) continue;
            int count = hfile[i].getTokenCount(j);
            if (count > 1) chordcount++;
            for (int k=0; k<count; k++) {
               hfile[i].getToken(buffer, j, k);
               if (strchr(buffer, 'r') != NULL)   { restcount++; } 
               else if (strcmp(buffer, ".") == 0) { nullcount++; } 
               else if (strchr(buffer, '_') != NULL) { /* ignore */ }
               else if (strchr(buffer, ']') != NULL) { tiedcount++; } 
               else { attackcount++; }
            }
         }   
      }
   }
   cout << "Note attacks: " << attackcount << endl;   
   cout << "Tied notes  : " << tiedcount   << endl;
   cout << "Chords      : " << chordcount  << endl;   
   cout << "Rests       : " << restcount   << endl;
   cout << "Null Tokens : " << nullcount   << endl;   
   return 0;
}

**kern	**text	**kern
4C	ig-	4c
4D 4E	-no-	.
4F	-red	.
.	.	4d 4e
4r	.	.
4G 4A 4B	text	.
*-	*-	*-

  Note attacks: 10
  Tied notes  : 0
  Chords      : 3
  Rests       : 1
  Null Tokens : 5

  kerninfo h://wtc/wtc1p04.krn
  Note attacks: 675
  Tied notes  : 85
  Chords      : 14
  Rests       : 69
  Null Tokens : 967