Humdrum Extras

prettystar manpage


COMMAND

    prettystar -- Sort and organize tandem interpretations across multiple spines.

SYNOPSIS

    prettystar [options[inputs[> output]

OPTIONS

-b string Process only the specified interpretation blocks
-f Print filenames before output from certain options
-F string Treat one or more interpretation blocks as if it were the first block
-k Insert default key signature, *k[], if no key signature found in first interpretation block of file.
-l List the interpretation blocks present in the input
-L Generate a list of all interpretations of a particular type
-s string Search for interpretation blocks which contain the specified interpretation
-S List all interpretation types which can be searched for with the -s option.
-t Show the interpretation type when displaying interpretation blocks with -l
-u Display a list of uncategorized tandem interpretations
-w Give warnings about unknown interpretations or ill-formatted interpretation lines
--last Move unknown tandem interpretations after known ones in each interpretation block

DESCRIPTION

    The prettystar program is designed to organize tandem interpretations across multiple spines so that each row of tandem interpretations relates to a specific category of interpretation such as clef, key signature, time signature, etc. The name of the program comes from pretty as in pretty print, and star as in the star character (*) which starts tandem interpretation tokens. Useful applications of the program include: (1) post-processing output from the assemble program when creating a full score; (2) guaranteeing a particular interpretation order as input to another program, or (3) basic error checking of tandem interpretations.

    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.

    input
    output

    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.

    input
    output

    Interpretation blocks

    Only 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.

    input
    prettystar -lt

    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.

    input
    output

    Block selection

    The -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:

    input
    prettystar
    prettystar -b 1
    prettystar -b 2

    Interpretation searching

    The -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.

    input
    prettystar -s clef

    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.

    prettystar -S

    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 warnings

    The -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.

    input
    prettystar -w

    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:

    input
    prettystar -w

    Unknown interpretations

    The -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.

    input
    output

    To place all unknown interpretations after the known ones in each interpretation block, use the --last option:

    input
    prettystar --last

    Default key signature inclusion

    The -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.

    input
    prettystar
    prettystar -k

    First interpretation block

    The -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.

    input
    prettystar -k
    prettystar -k -F 2

    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.

    input
    prettystar
    prettystar -F 2

LIMITATIONS

    Only **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 compiled prettystar program can be downloaded for the following platforms:
    • Linux (i386 processors) (dynamically linked) compiled on 13 Dec 2012.
    • Windows compiled on 29 Jun 2012.
    • Mac OS X/i386 compiled on 13 Nov 2013.

    The source code for the program was last modified on 15 Jun 2012. Click here to go to the full source-code download page.