Karya, built on 2023-08-29T07:47:28 (patch 7a412d5d6ba4968ca4155ef276a062ccdeb9109a)
Safe HaskellSafe-Inferred

Derive.Scale.TheoryFormat

Description

This is the part of Derive.Scale.Theory that's concerned with converting Pitch.Pitches to and from Pitch.Notes.

It's split off to avoid cluttering Theory, but also because the Derive.Scale import would make it a circular dependency.

This is basically just a bunch of functions that take a million arguments to configure octave format, accidental format, key parsing, etc. To avoid annoyingly long argument lists, they are mostly packaged up into records, such as Config, KeyConfig, and RelativeFormat.

It's basically all just an attempt to parameterize scale creation, so I can reuse the shared parts but still be able to configure them. It winds up being complicated, probably due to how it's evolved in reaction to increasingly varied scales, rather than according to an overarching design.

Synopsis

types

type ParseOctave = A.Parser (Pitch.PitchClass, Maybe Pitch.Accidentals) -> A.Parser RelativePitch Source #

This can't just be A.Parser Pitch.Octave because I don't know where the octave is in the pitch text.

data KeyConfig key Source #

Key config is only necessary for formatting that depends on the key, e.g. RelativeFormat.

Constructors

KeyConfig 

Fields

data RelativePitch Source #

This is a just-parsed pitch. It hasn't yet been adjusted according to the key, so it's not yet an absolute Pitch.Pitch. It also represents a natural explicitly, via Just 0.

fmt_to_absolute is responsible for converting this to a Pitch.Pitch, likely via rel_to_absolute.

absolute

letters :: Pitch.PitchClass -> Format Source #

Make an absolute scale starting at a.

absolute_c :: Format Source #

The usual 7 note scale, which wraps around at c instead of a.

relative

data RelativeFormat key Source #

Args for a relative scale format.

The Pitch.Pitches handled by a relative scale are still absolute, the same as the Pitches of an absolute scale. The difference is that the read_pitch and show_pitch functions adjust based on the key to display the absolute Pitch relative to the tonic of the key.

type ToAbsolute key = key -> Degrees -> RelativePitch -> Pitch.Pitch Source #

Given a RelativePitch relative to the default key, adjust it to be absolute. This is so I can figure out if a relative pitch is valid without knowing the key, as described in fmt_to_absolute.

type ShowDegree key = key -> ShowOctave -> Degrees -> AccidentalFormat -> Either Pitch.Degree Pitch.Pitch -> Pitch.Note Source #

This is a specialization of ShowPitch for show functions that need a key.

Format

data Format Source #

This is the central data structure for this module. It has the set of functions needed to parse and generate symbolic pitches. Making one of these gives you access to the set of functions in here, such as show_pitch and read_pitch, which in turn can be used to implement a Scale.

Constructors

Format 

Fields

type ShowPitch = Maybe Pitch.Key -> Either Pitch.Degree Pitch.Pitch -> Pitch.Note Source #

This is used to show both a Pitch with an octave, and a Degree without one (used for key names). This is because the code is presumably mostly the same.

show keys

show_key_signature :: Format -> Theory.Key -> Text Source #

Show a key along with its key signature.

show_signature :: Format -> Theory.Key -> [Text] Source #

Show the signature of the given key by showing each scale degree with the the accidentals implied by the key signature.

key_degrees :: Theory.Key -> Format -> [Text] Source #

Get the degree names of a chromatic scale in this key.

show pitches

read_relative_pitch :: Format -> Pitch.Note -> Either DeriveT.PitchError RelativePitch Source #

Parse a Note, but don't adjust it for the key. This means that relative pitches will likely be incorrect. ToAbsolute documents why this needs to be separate.

make

absolute

relative

diatonic_to_absolute :: ToAbsolute Tonic Source #

Convert a relative pitch using a simple diatonic key system, where the key is just a note in the scale.

keyed relative

show_pitch_keyed_absolute :: Config -> KeyConfig Theory.Key -> Degrees -> ShowPitch Source #

Like show_degree_chromatic, but format the accidentals as staff notation does, in that accidentals implicit in the key signature are omitted, and a natural that differs from the key signature is emitted. TODO tons of args, can I package some up?

parse

octave

show_octave :: ShowOctave Source #

Most scales display the octave as a leading number.

parse_octave1 :: ParseOctave Source #

Require a single digit octave.

accidentals

data AccidentalFormat Source #

natural, sharp1, sharp2, flat1, flat2

Constructors

AccidentalFormat !Text !Text !Text !Text !Text 

Instances

Instances details
Show AccidentalFormat Source # 
Instance details

Defined in Derive.Scale.TheoryFormat

show_accidentals_keyed :: AccidentalFormat -> Pitch.Accidentals -> Pitch.Accidentals -> Text Source #

Show accidentals relative to the key signature.