opusplus.core.lilypond
Class LilypondFileHandle

java.lang.Object
  opusplus.core.lilypond.LilypondFileHandle

All Implemented Interfaces:

java.lang.Cloneable

public class LilypondFileHandle

extends java.lang.Object

implements java.lang.Cloneable

The file naming scheme is encapsulated in this class. All Lilypond files generated by Opus+ use this format:

 NAME_v<000#>[_for_[_]][_bars_<#>_to_<#>].ly
 

Optional items are enclosed in square brackets, and numeric strings are indicated with # character. From left to right these tokens are as follows:

NAME is the name of the composition.

_v<000#> is the version number of this composition. So if multiple generations are done using the same parameters the files need not overwrite each other. Version numbers are padded with zeros so they remain in the correct order when viewed as files within the file system. The default digit width is 4, which is correct up to 10,000 versions. This width can be increased but not reduced.

_for_ is optional, and is only used where scores are generated separately for each instrument in the composition.

_ is a sub-optional capital letter distinguishing multiple occurrences of the same instrument name within the composition, for example duo written for two identical instruments.

_bars_<#>_to_<#> is also optional and is used when large compositions are broken up into smaller sections to enable Lilypond to process the resulting files.

Some examples. Suppose we have a composition called 'WholeLottaLove'. Single Instrument files will have the long instrument name appended so the 2nd version of the guitar part for this would be WholeLottaLove_v0002_for_Electric_Guitar.ly and for the bass WholeLottaLove_v0002_for_Electric_Bass_Pick.ly As this shows the long MIDI instrument name is used.

If there is a guitar duo then these will be numbered again i.e. WholeLottaLove_v0002_for_Electric_Guitar_A.ly and WholeLottaLove_v0002_for_Electric_Guitar_B.ly.

Bar sections of large compositions are similarly labelled with the bar ranges; to wit the second version of our song with 100 bars in each of two files would be WholeLottaLove_v0002_bars_1_to_100.ly, WholeLottaLove_v0002_bars_101_to_200.ly.

When this splitting into sections is combined with scores for single instruments we have for example: WholeLottaLove_v0002_for_Electric_Guitar_bars_1_to_100.ly and WholeLottaLove_v0002_for_Electric_Bass_Pick_bars_101_to_200.ly.

And finally in the extended long-play version of our song with a steaming guitar double act the names would be: WholeLottaLove_v0002_for_Electric_Guitar_A_bars_1_to_100.ly and WholeLottaLove_v0002_for_Electric_Guitar_B_bars_1_to_100.ly etc.

In the unlikely event that there are more than 26 parts for the same instrument, the instrument distinguishing character is doubled: AA, AB, AC .... AZ, BA, BB, BC etc.

Note LilypondFileHandle objects do not deal with file PATH information - only the NAMES of Lilypond files.

Author:

Adrian Marriott

LilypondFileHandle

public LilypondFileHandle(java.lang.String lyFileName)

Ctor that parses the details of the Lilypond file name out of the passed string.

LilypondFileHandle

public LilypondFileHandle(java.io.File lyFile)

Ctor that parses the details of the Lilypond file name out of the passed java.io.File object.

isValid

public boolean isValid()

Returns true if the name of the file is well-formed. It does not consider the existence or otherwise of such a file.

toString

public java.lang.String toString()

Returns the name of the Lilypond file as a string according to the current state of this object. This will have no path information, just the name of the file. Only valid names will be returned, if the current state of this object would result in an invalid name then null is returned.

Overrides:

toString in class java.lang.Object

toFile

public java.io.File toFile()

Returns a java.io.File object representing this Lilypond file according to the current state of this object. This will be located in the current working directory as specified in the SysParameters. Only valid file objects will be returned; if the current state of this object would result in an invalid Lilypond file name then null is returned. The existence or non-existence of a file by this name is not determined.

probeFile

public java.lang.Boolean probeFile()

Returns true if a file by this name exists in the current working directory as specified in the SysParameters, otherwise false. If the current state of this object is invalid then null is returned.

probeForNextVersion

public int probeForNextVersion()

This method examines the file system and searches for all files with the same root name, and calculates the next version number to use such that no clash with existing files will occur. It sets the version number of this object to the next version number and also returns it to the caller. This processing takes heed of the current file versioning strategy held in the system parameters. Note that this algorithm to derive the next version does not consider any Opus+ addenda on these file names such as instrument names or bar range information - it only uses the root name. This arrangement means that all files resulting from a single generation of the same composition will have exactly identical root names and version numbers, and so will be listed adjacently in any file sort order.

getRootName

public final java.lang.String getRootName()

Returns the root name of the Lilypond file.

setRootName

public final void setRootName(java.lang.String rootName)

Sets the root name of the Lilypond file. Cannot be blank or null.

getVersion

public final int getVersion()

Returns the version number of this Lilypond file

setVersion

public final void setVersion(int version)

Sets the version of this Lilypond file. Must be a positive integer or zero.

unsetVersion

public final void unsetVersion()

Turns off the versioning on this file

getInstrumentName

public final java.lang.String getInstrumentName()

Returns the name of the instrument playing this music. Only set when separate scores are created for each instrument, otherwise this will return null.

setInstrumentName

public final void setInstrumentName(java.lang.String instrument)

Specifies the name of the instrument playing this music. Should only set when separate scores are created for each instrument, otherwise this should be set to null.

setInstrumentName

public final void setInstrumentName(Instrument inst)

Specifies the name of the instrument playing this music. Should only set when separate scores are created for each instrument, otherwise this should be set to null.

setInstrumentName

public final void setInstrumentName(InstrumentId instId)

Specifies the type of instrument playing this music. Should only set when separate scores are created for each instrument, otherwise this should be set to null.

setInstrumentName

public final void setInstrumentName(DrumKit kit)

Specifies the name of the instrument playing this music. Should only set when separate scores are created for each instrument, otherwise this should be set to null.

setInstrumentName

public final void setInstrumentName(DrumKitId kitId)

Specifies the name of the instrument playing this music. Should only set when separate scores are created for each instrument, otherwise this should be set to null.

unsetInstrumentName

public void unsetInstrumentName()

Turns off the instrument naming on this file.

getInstrumentSuffix

public final java.lang.String getInstrumentSuffix()

Returns the instrument suffix string which distinguishes different instances of the same instrument playing in the same composition. This string will consist only of uppercase characters - typically a single capital letter. Null is returned if this optional property is unset.

setInstrumentSuffix

public final void setInstrumentSuffix(java.lang.String instrumentSuffix)

Sets the instrument suffix string which distinguishes different instances of the same instrument playing in the same composition. This string will consist only of uppercase characters - typically a single capital letter. Null is returned if this optional property is unset.

unsetInstrumentSuffix

public void unsetInstrumentSuffix()

Turns off the instrument suffix on this file.

getBarRangeStart

public final int getBarRangeStart()

For when large compositions are broken down into separate Lilypond files this returns the start of the bar range held in this file.

getBarRangeEnd

public final int getBarRangeEnd()

For when large compositions are broken down into separate Lilypond files this returns the end of the bar range held in this file.

setBarRange

public final void setBarRange(int barRangeStart,
                              int barRangeEnd)

For when large compositions are broken down into separate Lilypond files this sets the start of the bar range held in this file. Must be a positive integer or zero.

unsetBarRange

public void unsetBarRange()

Turns off the bar range information for this file.

getWidth

public final int getWidth()

Returns the number of zeros used as padding for the version number in the Lilypond file name. Defaults to 4 (i.e. up to 10,000 different version of any composition) and it cannot be set less than this, although it can be wider.

setWidth

public final void setWidth(int zeros)

Sets the number of zeros used as padding for the version number in the Lilypond file name. Defaults to 4 (i.e. up to 10,000 different version of any composition) and it cannot be set less than this, although it can be wider.

getStaveNumber

public final int getStaveNumber()

Returns the stave number for this instrument or a negative number if not set. The stave number is required when generating Lilypond for separate instruments; it just makes it easier to write the correct music into the each file.

setStaveNumber

public final void setStaveNumber(int staveNumber)

Sets the stave number for this instrument. Must be a positive integer or zero.

unsetStaveNumber

public final void unsetStaveNumber()

Unsets the stave number.

getSuffixString

public static java.lang.String getSuffixString(int index)

Returns the numbered suffix string. This will be a string of capitals from the following sequence: A, B, C ... Z, AA, AB, AC ... AZ, BA, BB etc. Passing an index of zero returns "A", one returns "B" etc.

isMetronomeSuppressed

public final boolean isMetronomeSuppressed()

If true, then this score will NOT have a metronome track output to the Lilypond file. If false, and a metronome has been requested, then this score will get the metronome track. Defaults to 'false'.

setMetronomeSuppressed

public final void setMetronomeSuppressed(boolean suppressed)

If true, then this score will NOT have a metronome track output to the Lilypond file. If false, and a metronome has been requested, then this score will get the metronome track. Defaults to 'false'.

clone

public java.lang.Object clone()

Bit-wise implementation of the clone method.

Overrides:

clone in class java.lang.Object