Karya, built on Mon Jul 24 11:39:07 PDT 2017 (patch 33511aca01257b76b88de7c7a2763b7a965c084e)

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

data Config Source #

General purpose config.

Constructors

 Config

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 Fieldskey_parse :: ParseKey key key_default :: keyDefault key if there is none, or it's not parseable. Otherwise, a bad or missing key would mean you couldn't even display notes.

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.

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

Constructors

 RelativePitch !Pitch.Octave !Pitch.PitchClass !(Maybe Pitch.Accidentals)

Instances

 # MethodsshowList :: [RelativePitch] -> ShowS # # Methods

# absolute

Make an absolute scale starting at a.

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, exactly 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.

Constructors

 RelativeFormat Fieldsrel_config :: Config rel_key_config :: KeyConfig key rel_show_degree :: ShowDegree key rel_to_absolute :: ToAbsolute key

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

Given a relative pitch 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 Fieldsfmt_show :: ShowPitch fmt_read :: A.Parser RelativePitchThis doesn't need the key because that work is split off to fmt_to_absolute.fmt_to_absolute :: Maybe Pitch.Key -> RelativePitch -> Either BaseTypes.PitchError Pitch.PitchI need the key to parse the pitch, but that can't happen unless I want to give all pattern_lookup calls access to the env in scope. But I don't need the env to recognize if it's a valid call or not.fmt_pattern :: !Text fmt_pc_per_octave :: Pitch.PitchClass fmt_relative :: !BoolTrue if this scale is relative to the key.

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 a key along with its key signature.

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

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

## show pitches

show_pitch adapted to scale_show.

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

A configurable version of make_absolute_format.

make_relative_format :: Show key => Text -> Degrees -> RelativeFormat key -> Format Source #

Make a Format from a RelativeFormat.

### relative

Convert a relative pitch using the key signature key system defined by Theory.Key.

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

### keyed relative

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

Most scales display the octave as a leading number.

## accidentals

natural, sharp1, sharp2, flat1, flat2

Constructors

 AccidentalFormat !Text !Text !Text !Text !Text

Instances

 # MethodsshowList :: [AccidentalFormat] -> ShowS #

Show accidentals relative to the key signature.