Conversion of libtrackerboy data types to textual format.
Types
EffectString = FixedString[3]
-
Fixed string type that contains the textual version of an Effect. This string will always contain 3 characters.
The format of this string is one of the following:
- ...: no effect is set
- EPP: a set effect where E is a character the determines the effect type, and PP is the effect's parameter in hexadecimal.
Examples:
- "..." represents effectNone
- "V03" represents initEffect(etSetTimbre, 3)
- "C00" represents initEffect(etPatternHalt, 0)
FixedString[N] = array[N, char]
- Type for a fixed-length string implemented as an array of characters. Since most of the strings in this module are a fixed length, this type is used instead of string for optimization purposes. If a string is needed, use the $ overload. Source Edit
InstrumentString = FixedString[2]
-
Fixed string type that contains the textual version of an instrument column. This string will always contain 2 characters.
The format of this string is one of the following:
- ..: no instrument set
- XX: a set instrument where XX is the instrument id in hexadecimal.
Examples:
- ".." represents instrumentNone
- "00" represents instrumentColumn(0)
- "12" represents instrumentColumn(18)
NoteString = FixedString[3]
-
Fixed string type that contains the textual version of a note column. This string will always contain 3 characters.
The format of this string is one of the following:
- ... : an unset column or no note.
- NSO : a set note where N is the note letter from A to G. S is a separator that indicates if the note is a natural, sharp or a flat. '-' is used for naturals, '#' is used for sharps and 'b' is used for flats. O is the octave from 2 to 8.
- --- : a set note containing a note cut.
Examples:
- "..." represents noteNone
- "E-3" represents noteColumn(5, 3)
- "D#3" or "Eb3" represents noteColumn(4, 3)
- "---" represents noteColumn(noteCut)
OrderRowString = FixedString[11]
-
Fixed string type that contains the textual version of an OrderRow. This string will always contain 11 characters.
The format of this string is T1 T2 T3 T4 where
- T1 is the track id for channel 1, in hexadecimal
- T2 is the track id for channel 2, in hexadecimal
- T3 is the track id for channel 3, in hexadecimal
- T4 is the track id for channel 4, in hexadecimal
TrackRowString = FixedString[18]
-
Fixed string type that contains the textual version of a TrackRow. This string will always contain 18 characters.
The format of this string is "NNN II EEE EEE EEE" where
- NNN is a NoteString of the row's note field
- II is an InstrumentString of the row's instrument field
- EEE is an EffectString for each effect in the row's effects array.
Effects are ordered from left to right, so the first effect is located after II and before the second EEE.
Source Edit WaveDataString = FixedString[32]
-
Fixed string type that contains the textual version of a WaveData. This string will always contain 32 characters.
The format of this string is 32 hexadecimal literals, where each literal is a single sample of the wave data.
Examples:
- "00000000000000000000000000000000" is an empty waveform
- "0123456789ABCDEFFEDCBA9876543210" is a triangular waveform
Consts
noValueChar = '.'
- A repeating character that is used to represent a column not having a value. Source Edit
Procs
func `$`[N](str: FixedString[N]): string {....raises: [].}
- Convert a fixed string to a regular string. Source Edit
func effectText(effect: Effect): EffectString {....raises: [], tags: [], forbids: [].}
- Converts an Effect to textual representation. See EffectString for details on the format of the text. Source Edit
func instrumentText(instrument: InstrumentColumn): InstrumentString {. ...raises: [], tags: [], forbids: [].}
- Converts an instrument column to textual representation. See InstrumentString for details on the format of the text. Source Edit
func litInstrument(str: string): InstrumentColumn {.compileTime, ...raises: [], tags: [], forbids: [].}
- Construct an instrument column from its textual representation at compile time. An AssertError will be raised if str could not be parsed. Source Edit
func litNote(str: string): NoteColumn {.compileTime, ...raises: [], tags: [], forbids: [].}
- Construct a note column from its textual representation at compile time. An AssertError will be raised if str could not be parsed. Source Edit
func litOrderRow(str: string): OrderRow {.compileTime, ...raises: [], tags: [], forbids: [].}
- Construct an order row from its textual representation at compile time. An AssertError will be raised if str could not be parsed. Source Edit
func litSequence(str: string; minVal = low(int8); maxVal = high(int8)): Sequence {. compileTime, ...raises: [], tags: [], forbids: [].}
- Construct a sequence from its textual representation at compile time. An AssertError will be raised if str could not be parsed. Source Edit
func litTrackRow(str: string): TrackRow {.compileTime, ...raises: [], tags: [], forbids: [].}
- Construct a track row from its textual representation at compile time. An AssertError will be raised if str could not be parsed. Source Edit
func noteText(note: NoteColumn; useFlats = false): NoteString {....raises: [], tags: [], forbids: [].}
-
Converts a note column to textual representation. See NoteString for details on the format of the text.
Sharps are used by default, set useFlats to true if flats are desired.
Source Edit func orderRowText(row: OrderRow): OrderRowString {....raises: [], tags: [], forbids: [].}
- Converts an OrderRow to textual representation. See OrderRowString for details on the format of the text. Source Edit
func parseEffect(str: openArray[char]): Option[Effect] {....raises: [], tags: [], forbids: [].}
-
Parse the character buffer containing the textual representation of an Effect, and return it on success. See EffectString for details on the format that is expected.
Parsing will fail for any of the following:
- str.len does not match the expected amount
- The effect type was not recognized
- The effect parameter was not a valid hexadecimal number
func parseEffect(str: string): Option[Effect] {.inline, ...raises: [], tags: [], forbids: [].}
- Convenience overload that takes a string. See parseEffect(openArray[char]). Source Edit
func parseEffectCmd(ch: char): EffectCmd {....raises: [], tags: [], forbids: [].}
- Converts a character to the EffectType it represents. For any unrecognized character, ecNoEffect is returned. Source Edit
func parseInstrument(str: openArray[char]): Option[InstrumentColumn] {. ...raises: [], tags: [], forbids: [].}
-
Parse the character buffer containing the textual representation of an InstrumentColumn, and return it on success. See InstrumentString for details on the format that is expected.
Parsing will fail for any of the following:
- str.len does not match the expected amount
- an invalid hexadecimal number was given
- the instrument id was outside the range of TableId (id >= 64)
func parseInstrument(str: string): Option[InstrumentColumn] {.inline, ...raises: [], tags: [], forbids: [].}
- Convenience overload that takes a string. See parseInstrument(openArray[char]). Source Edit
func parseNote(str: openArray[char]): Option[NoteColumn] {....raises: [], tags: [], forbids: [].}
-
Parse the character buffer containing the textual representation of a NoteColumn, and return it on success. See NoteString for details on the format that is expected.
Parsing will fail for any of the following:
- str.len does not match the expected amount
- the note letter was not a valid note
- the separator was not a sharp #, flat b or natural -
- the octave was not a valid digit
- the octave was not in TrackerBoy's octave range
func parseNote(str: string): Option[NoteColumn] {.inline, ...raises: [], tags: [], forbids: [].}
- Convenience overload that takes a string. See parseNote(openArray[char]). Source Edit
func parseOrderRow(str: openArray[char]): Option[OrderRow] {....raises: [], tags: [], forbids: [].}
-
Parse the character buffer containing the textual representation of an OrderRow, and return it on success. See OrderRowString for details on the format that is expected.
Parsing will fail for any of the following:
- str.len does not match the expected amount
- The string contained an invalid hexadecimal character
- The string did not contain the required space separators
func parseOrderRow(str: string): Option[OrderRow] {.inline, ...raises: [], tags: [], forbids: [].}
- Convenience overload that takes a string. See parseOrderRow(openArray[char]). Source Edit
func parseSequence(str: string; minVal = low(int8); maxVal = high(int8)): Option[ Sequence] {....raises: [], tags: [], forbids: [].}
-
Parse the string containing the textual representation of a Sequence, and return it on success. minVal and maxVal can be used to clamp the parsed values.
Parsing will fail for any of the following:
- more than one loop index, '|', was encountered
- the number of values parsed exceeded 256
- a number could not be parsed as a decimal integer
func parseTrackRow(str: openArray[char]): Option[TrackRow] {....raises: [], tags: [], forbids: [].}
-
Parse the character buffer containing the textual representation of a TrackRow, and return it on success. See TrackRowString for details on the format that is expected.
Parsing will fail for any of the following:
- str.len does not match the expected amount
- The string did not contain the required space separators
- The note column could not be parsed
- The instrument column could not be parsed
- One of the effect columns could not be parsed
func parseTrackRow(str: string): Option[TrackRow] {.inline, ...raises: [], tags: [], forbids: [].}
- Convenience overload that takes a string. See parseTrackRow(openArray[char]). Source Edit
func parseWave(str: openArray[char]): Option[WaveData] {....raises: [], tags: [], forbids: [].}
-
Parse the character buffer containing the textual representation of a WaveData, and return it on success. See WaveDataString for details on the format that is expected.
Parsing will fail for any of the following:
- str.len does not match the expected amount
- The string contained an invalid hexadecimal character
func parseWave(str: string): Option[WaveData] {.inline, ...raises: [], tags: [], forbids: [].}
- Convenience overload that takes a string. See parseWave(openArray[char]). Source Edit
func sequenceText(s: Sequence): string {....raises: [], tags: [], forbids: [].}
-
Converts a Sequence to textual representation. Since sequences vary in length, a regular string is returned.
The format of the string returned is each element in the sequence as an integer separated by spaces. A | is used to indicate the location of the loop index, if present, and is placed before the element it refers to.
Examples:
- 1 2 3 is a sequence with no loop index and has values 1, 2 and 3.
- -1 | 3 is a sequence with a loop index of 1 and has values -1 and 3.
func trackRowText(row: TrackRow; useFlats = false): TrackRowString {....raises: [], tags: [], forbids: [].}
- Converts a TrackRow to textual representation. See TrackRowString for details on the format of the text. Source Edit
func waveText(wave: WaveData): WaveDataString {....raises: [], tags: [], forbids: [].}
- Converts a WaveData to textual representation. See WaveDataString for details on the format of the text. Source Edit