SYNOPSIS
OPTIONS
DESCRIPTION
Using the program without options will sort all contiguous blocks of tandem interpretations into a default ordering and will move interpretations around independently in each spine to match interpretations by line between the spines. Notice in the following example that the tandem interpretations (most tokens starting with "*") are re-arranged so that the interpretations in the two spines are coordinated in the output from the prettystar program.
If one spine has an interpretation of one type while another spine does not, a null interpretation will be added to the lacking spine. In the following example, the first spine is lacking an instrument number and meter symbol, while the second spine lacks an instrument abbreviation and time signature.
Interpretation blocksOnly contiguous lines of tandem interpretations will be rearranged by prettystar. If a comment, data, or spine manipulator line divide two blocks of tandem interpretations, these two blocks will be processed separately. Spine manipulators (*^, *v, *x, *+, and *- as well as exclusive interpretations starting with **) are treated differently from tandem interpretations and must not be mixed on the same line with tandem interpretations (any other token starting with *). Such tandem interpretation regions in a file can be displayed by using the -l option to list the interpretation blocks. The -t option can also be given at the same time as the -l option. This will display a local-comment styled line underneath each interpretation line, showing the category of each interpretation.
Each interpretation block is listed in the output after a global-comment styled line which enumerates the block and gives the starting and ending line number in the file for the block. A special sorting case occurs for thru labels depending on the interpretation block number. In the first interpretation block, thru labels (such as "*>A") are placed after thru expansion directives and most other types of interpretations. However, in subsequent interpretation blocks, the thru labels is placed before all other tandem interpretations in the block, since these interpretations typically apply to the following data, and the thru label marks the beginning of a new musical segment.
Block selectionThe -b option can be use to selectively process interpretation blocks. The -b option takes a string which lists the blocks to process, starting with 1 for the first block. Individual blocks can be separated by commas (,) and/or spaces, or ranges of block numbers can be given by a dash between the starting and ending block numbers. In addition, the dollar sign ($) can be used to represent the last block in the file, with an optional number after the dollar sign indicating a block number before the end block, such as $1 for the penultimate block, $2 for two blocks before the end, etc. Block numbers and ranges do not have to occur in sequential order. For example, here is selective processing of the first or second block of tandem interpretations in a file:
Interpretation searchingThe -s option can be used to search for interpretation blocks which contain a particular interpretation type. In the following example, clef interpretation tokens are present in interpretation blocks 1 and 2.
Regular expressions can be given as argument strings to the -s option. To indicate a regular expression rather than an interpretation type, place a slash before and after the regular expression. Here is an example which searches for interpretations only containing lower-case letters:
prettystar -s '/^\*[a-z]+$/'
The -S option (capitalized) can be used to generate a list of interpretation types that can be searched for with the -s or -L options.
The -L option can be used to generate a list of all interpretations of a certain category which are found in the input data. Similar to the -s option, the -L option accepts regular expressions instead of an interpretation category as an argument. For example, List all tempo markings, you can do either of these two equivalent commands:
prettystar -L tempo
prettystar -L '/^\*MM\d/'
Syntax warningsThe -w option can be used to print a list of warnings about tandem interpretations in input files. Warnings will be printed if different types if interpretations are found on the same line. When giving multiple input files, you can add the -f option to print the filename when there are any warnings in the file.
Mixing spine manipulators (*^, *v, *x, *+, and *- as well as exclusive interpretations starting with **) and tandem interpretations is an error in the Humdrum file structure. Using the -w option will also note these cases as errors:
Unknown interpretationsThe -u option can be used to list all unknown tandem interpretations. This option is also useful for checking for invalid tandem interpretations, such as when "*k[f#" is missing the final bracket. The option "-L unknown" functions in a similar manner to "-u".The -f option can be used in conjunction with -u when searching for unknown/invalid tandem interpretations in multiple files. This option will print the filename before the list of unknown interpretations.
prettystar -uf *.krn
When rearranging tandem interpretations, unknown interpretations will not be coordinated between spines unless they are already aligned in the input. If unknown interpretations are on the same line as a known interpretation, the unknown interpretations will be separated from the known interpretations and placed on a separate line.
To place all unknown interpretations after the known ones in each interpretation block, use the --last option:
Default key signature inclusionThe -k option can be used to insert empty key signatures in **kern spines in the first interpretation block of the file. If no key signature is given for a particular spine, the key signature "*k[]" will be added. Note in the following example that without the -k option, the first spine has a null interpretation on the key signature line (middle box below). When adding the -k option, this null interpretation is changed to "*k[]". Also note in the second occurrence of a key signature in the file, the second spine still has a null interpretation since this is the second interpretation block in the file.
First interpretation blockThe -F option can be used to treat interpretation blocks other than the first one as the first block. This is useful for inserting a default key signature or sorting by thru labels in interpretation blocks which are not first. The -F option expects a block list similar to the -b option. In the following example, note that the default key signature "*k[]" is added to the second interpretation block instead of the first one in the last example box.
A method to force a default key signature within the first interpretation block within the file which contains a key signature, even if the key signature is not found in the first interpretation block in the file:
prettystar -k -F `prettystar file.krn -s keysig | sed 's/,.*//'` file.krn
The -F option is also useful for controlling the sorting of thru labels. If the thru expansion is not found in the first interpretation block, the -F option can be used to sort a non-first block as if it were the initial block.
LIMITATIONSOnly **kern tandem interpretations are understood by prettystar. Tandem interpretations related to other exclusive interpretations may be added in the future. Future versions of the prettystar program may allow for user-control of the sorting order and also allow for user-defined interpretations to be sorted within pre-defined interpretations. DOWNLOAD
The source code for the program was last modified on 15 Jun 2012. Click here to go to the full source-code download page. |
