FoscMutation

Returns a FoscMutation.


Description

Mutation agent.


Attributes Summary

Instance Properties

client Returns client of mutation agent.

Instance Methods

copy Copies client.
ejectContents Ejects contents from outside-of-score container.
extract Extracts mutation client from score. Leaves children of mutation client in score.
fuse Fuses mutation client.
fuseLeaves
replace Replaces mutation client (and contents of mutation client) with newContents.
respellWithFlats !!!TODO: Move to pitchtools package.
respellWithSharps !!!TODO: Move to pitchtools package.
rewriteMeter Rewrites the contents of logical ties in an expression to match meter.
rewritePitches
scale Scales mutation client by multiplier.
split Splits component or selection by durations.
swap Swaps mutation client for empty container.
transpose Transposes notes and chords in mutation client by interval.
wrap Wraps mutation client in empty container.


Instance Properties


client

Returns client of mutation agent.

Returns selection or component.


Instance Methods


copy

Copies client.

  1. Example

    a = FoscStaff(FoscLeafMaker().((60..67), [1/8]));
a.show;

  2. Example

    b = mutate(a[0..1]).copy;
a.addAll(b);
a.show;


ejectContents

Ejects contents from outside-of-score container.

Returns container contents as selection.

  1. Eject leaves from Container.

    a = FoscContainer(FoscLeafMaker().(#[60,60,62,62], [1/4]));
a.selectLeaves[0..1].tie;
a.selectLeaves[2..3].tie;
a.show;

  2. Example

    b = mutate(a).ejectContents;
c = FoscStaff(b, lilypondType: 'RhythmicStaff');
c.show;


extract

Extracts mutation client from score. Leaves children of mutation client in score.

Returns mutation client.

  1. Extract tuplets.

    m = FoscTuplet(#[3,2], [FoscNote(60, 1/4), FoscNote(64, 1/4)]);
n = FoscTuplet(#[3,2], [FoscNote(62, 1/4), FoscNote(65, 1/4)]);
a = FoscStaff([m, n]);
a.leafAt(0).attach(FoscTimeSignature(#[3,4]));
a.show;

    mutate(a[1]).extract;
mutate(a[0]).extract;
a.show;

  2. Scales tuplet contents and then extracts tuplet.

    m = FoscTuplet(#[3,2], [FoscNote(60, 1/4), FoscNote(64, 1/4)]);
n = FoscTuplet(#[3,2], [FoscNote(62, 1/4), FoscNote(65, 1/4)]);
a = FoscStaff([m, n]);
a.leafAt(0).attach(FoscTimeSignature(#[3,4]));
a.show;

    mutate(a[1]).extract(scaleContents: true);
mutate(a[0]).extract(scaleContents: true);
a.show;


fuse

Fuses mutation client.

Returns fused mutation client.

  1. Example

    a = FoscRhythmMaker();
b = a.(divisions: [1/4], ratios: #[[2,1],[3,2],[4,3]]);
a.show;

  2. TODO: BROKEN - removing tuplet leaves from parent

    a = FoscRhythmMaker();
b = a.(divisions: [1/4], ratios: #[1,1,1,1,1] ! 2);
c = FoscSelection(b).leaves.partitionBySizes(#[3,1,4,2]);
c.items;
    [ FoscSelection([ FoscNote(FoscPitch("C4"), FoscDuration(1, 16)), FoscNote(FoscPitch("C4"), FoscDuration(1, 16)), FoscNote(FoscPitch("C4"), FoscDuration(1, 16)) ]), FoscSelection([ FoscNote(FoscPitch("C4"), FoscDuration(1, 16)) ]), FoscSelection([ FoscNote(FoscPitch("C4"), FoscDuration(1, 16)), FoscNote(FoscPitch("C4"), FoscDuration(1, 16)), FoscNote(FoscPitch("C4"), FoscDuration(1, 16)), FoscNote(FoscPitch("C4"), FoscDuration(1, 16)) ]), FoscSelection([ FoscNote(FoscPitch("C4"), FoscDuration(1, 16)), FoscNote(FoscPitch("C4"), FoscDuration(1, 16)) ]) ]
    c.do { |each| mutate(each).fuseLeaves };
c.show;


fuseLeaves


replace

Replaces mutation client (and contents of mutation client) with newContents.

Returns nil.

  1. !!!TODO: does not copy wrappers when donors[0] is not a leaf (also broken in abjad)

    Replaces in-score tuplet (and children of tuplet) with notes.

    m = FoscTuplet(#[2,3], [FoscNote(60, 1/4), FoscNote(62, 1/4), FoscNote(64, 1/4)]);
n = FoscTuplet(#[2,3], [FoscNote(62, 1/4), FoscNote(64, 1/4), FoscNote(65, 1/4)]);
a = FoscStaff([m, n]);
a.selectLeaves.slur;
a.selectLeaves.hairpin('p < f');
a.show;

    b = FoscLeafMaker().(#[60,62,64,65,60,62,64,65], [1/16]);
mutate(m).replace(b, wrappers: true); // FIXME: ERROR: FoscMutation:replace: set wrappers only with single leaf: a FoscSelection.
b.show;

  2. Copies no wrappers when wrappers is false.

    a = FoscStaff(FoscLeafMaker().(#[60,65,67], [1/2,1/4,1/4]));
a.leafAt(0).attach(FoscClef('alto'));
a.show;

    mutate(a[0]).replace(FoscChord(#[62,64], 1/2)); // FIXME: MethodError
a.show;

  3. Set wrappers to true to copy all wrappers from one leaf to another leaf (and avoid full-score update). Only works from one leaf to another leaf.

    a = FoscStaff(FoscLeafMaker().(#[60,65,67], [1/2,1/4,1/4]));
a.show;

    a.leafAt(0).attach(FoscClef('alto'));
mutate(a[0]).replace(FoscRest(1/2), wrappers: true); // FIXME: MethodError
a.show;
    a = FoscRhythmMaker().([1/4], #[2,1,3] ! 4);
FoscMeterSpecifier(#[[1,4],[2,4],[1,4]], attachTimeSignatures: true).(a);
a = FoscSustainMask(FoscPattern.first(3) | FoscPattern.last(3)).(a); // FIXME Execution warning: Class 'FoscSegmentList' not found
a = FoscTupletSpecifier(extractTrivial: true, rewriteRestFilled: true).(a);
FoscStaff(a).show;


respellWithFlats

!!!TODO: Move to pitchtools package.

Respells named pitches in mutation client with flats.

Returns nil.

  1. Example

    n = #["C#4", "D4", "D#4", "E4", "F4", "F#4"];
a = FoscVoice(n.collect { |each| FoscNote(each, [1, 4]) });
a.format;
    \new Voice {
    cs'4
    d'4
    ds'4
    e'4
    f'4
    fs'4
}
    mutate(a).respellWithFlats;
a.format;
    \new Voice {
    df'4
    d'4
    ef'4
    e'4
    f'4
    gf'4
}
    a.show;


respellWithSharps

!!!TODO: Move to pitchtools package.

Respells named pitches in mutation client with sharps.

Returns nil.

  1. Example

    n = #["Db4", "D4", "Eb4", "E4", "F4", "Gb4"];
a = FoscVoice(n.collect { |each| FoscNote(each, [1, 4]) });
a.format;
    \new Voice {
    df'4
    d'4
    ef'4
    e'4
    f'4
    gf'4
}
    mutate(a).respellWithSharps;
a.format;
    \new Voice {
    cs'4
    d'4
    ds'4
    e'4
    f'4
    fs'4
}

  2. //!!! TODO

    FIXME: ERROR: Message __new__ not understood.

    n = #["Db4", "D4", "Eb4", "E4", "F4", "Gb4"];
a = FoscVoice(n.collect { |each| FoscNote(each, [1, 4]) });
p = [1, 3];
b = select(a).byLeaf(isPitched: true);
b.byLeaf(isPitched: true, condition: { |leaf| p.includes(leaf.pitch.pitchClassNumber) });
mutate(a).respellWithSharps;
a.format;


rewriteMeter

Rewrites the contents of logical ties in an expression to match meter.

!!! FIXME: rewriteMeter silently crashes docs build on interpret !!!

  1. !!! FIXME: This crashes docs build.

    a = FoscStaff(FoscLeafMaker().((60..67), [1/32,1/4,3/16,1/16,4/32,3/16,3/32,1/16]));
a.show;

    mutate(a[0..]).rewriteMeter(FoscMeter(#[4,4]));
a.show;

  2. FoscContainer used to specify measure boundaries.

    !!! FIXME: This crashes docs build.

    a = FoscStaff([
    FoscContainer([FoscNote(60, 2/4)]),
    FoscContainer([FoscLeafMaker().([60,62,62,64], [1/32,7/8,1/16,1/32])]),
    FoscContainer([FoscNote(64, 2/4)])
]);
a.leafAt(0).attach(FoscTimeSignature(#[2,4]));
a.leafAt(1).attach(FoscTimeSignature(#[4,4]));
a.leafAt(5).attach(FoscTimeSignature(#[2,4]));

m = a.selectLeaves;
m[0..1].tie;
m[2..3].tie;
m[4..5].tie;

a.show;

    mutate(a[1][0..]).rewriteMeter(FoscMeter(#[4,4]));
a.show;

  3. Use FoscRhythm to specify custom metrical hierarchy.

    !!! FIXME: This crashes docs build.

    a = FoscStaff([
    FoscContainer([FoscNote(60, 2/4)]),
    FoscContainer([FoscLeafMaker().([60,62,62,64], [1/32,7/8,1/16,1/32])]),
    FoscContainer([FoscNote(64, 2/4)])
]);
a.leafAt(0).attach(FoscTimeSignature(#[2,4]));
a.leafAt(1).attach(FoscTimeSignature(#[4,4]));
a.leafAt(5).attach(FoscTimeSignature(#[2,4]));
m = a.selectLeaves;
m[0..1].tie;
m[2..3].tie;
m[4..5].tie;

m = FoscRhythm(4/4, #[[2,[1,1]],[2,[1,1]]]);
mutate(a[1][0..]).rewriteMeter(m);
a.show;

  4. Limit the maximum number of dots per leaf using maximumDotCount.

    No constraint.

    t = FoscTimeSignature(#[3,4]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/32,1/8,1/8,15/32]));
a.leafAt(0).attach(t);
a.show;

  5. Constrain maximumDotCount to 2.

    !!! FIXME: This crashes docs build.

    t = FoscTimeSignature(#[3,4]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/32,1/8,1/8,15/32]));
a.leafAt(0).attach(t);
mutate(a[0..]).rewriteMeter(meter: t, maximumDotCount: 2);
a.show;

  6. Constrain maximumDotCount to 1.

    !!! FIXME: This crashes docs build.

    t = FoscTimeSignature(#[3,4]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/32,1/8,1/8,15/32]));
a.leafAt(0).attach(t);
mutate(a[0..]).rewriteMeter(meter: t, maximumDotCount: 1);
a.show;

  7. Constrain maximumDotCount to 0.

    !!! FIXME: This crashes docs build.

    t = FoscTimeSignature(#[3,4]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/32,1/8,1/8,15/32]));
a.leafAt(0).attach(t);
mutate(a[0..]).rewriteMeter(meter: t, maximumDotCount: 0);
a.show;

  8. Split logical ties at different depths of the Meter, if those logical ties

    cross any offsets at that depth, but do not also both begin and end at any of those offsets.

    t = FoscTimeSignature(#[9,8]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64], [2/4,2/4,1/8]));
a.leafAt(0).attach(FoscTimeSignature(t));
a.show;

  9. Establish meter without specifying boundaryDepth.

    t = FoscTimeSignature(#[9,8]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64], [2/4,2/4,1/8]));
a.leafAt(0).attach(FoscTimeSignature(t));
mutate(a[0..]).rewriteMeter(meter: t);
a.show;

  10. With a boundaryDepth of 1, logical ties which cross any offsets created by

    nodes with a depth of 1 in this Meter’s rhythm tree - 0/8, 3/8, 6/8 and 9/8

    !!! FIXME: This crashes docs build.

    t = FoscTimeSignature(#[9,8]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64], [2/4,2/4,1/8]));
a.leafAt(0).attach(FoscTimeSignature(t));
mutate(a[0..]).rewriteMeter(meter: t, boundaryDepth: 1);
a.show;

  11. Another way of doing this is by setting preferredBoundaryDepth on FoscMeter itself.

    !!! FIXME: This crashes docs build.

    t = FoscTimeSignature(#[9,8]);
a = FoscStaff(FoscLeafMaker().(#[60,62,64], [2/4,2/4,1/8]));
a.leafAt(0).attach(FoscTimeSignature(t));
m = FoscMeter(t, preferredBoundaryDepth: 1);
mutate(a[0..]).rewriteMeter(meter: m);
a.show;


rewritePitches

  1. Rewrite written pitches for first three notes.

    a = FoscStaff(FoscLeafMaker().(#[60], 1/16 ! 16));
mutate(a).rewritePitches(#[72,71,70]);
a.show;

  2. Rewrite written pitches using a pattern.

    a = FoscStaff(FoscLeafMaker().(#[60], 1/16 ! 16));
mutate(a).rewritePitches(Pseq((72,71..67), inf));
a.show;

  3. Rewrite written pitches for first three chords.

    a = FoscStaff(FoscLeafMaker().(#[[60,64]], 1/16 ! 16));
mutate(a).rewritePitches(#[[72,69],[71,68],[70,67]]);
a.show;

  4. Replaces chords with notes.

    a = FoscStaff(FoscLeafMaker().(#[[60,64]], 1/16 ! 16));
mutate(a).rewritePitches(#[72,71,70]);
a.show;

  5. Replaces notes with chords.

    a = FoscStaff(FoscLeafMaker().(#[60], 1/16 ! 16));
a.leafAt(0).attach(FoscArticulation('>'));
mutate(a).rewritePitches(#[[72,69],[71,68],[70,67]]);
a.show;

  6. !!!TODO: BROKEN!

    Rewrite written pitches for first three notes in a selection.

    a = FoscLeafMaker().(#[60], 1/16 ! 16);
mutate(a).rewritePitches(#[72,71,70]);
a.show;

  7. !!!TODO: selections must be added to a container for now, because of bug in FoscIteration:logicalTies.

    Rewrite written pitches for notes in an array of selections.

    a = FoscStaff(FoscRhythmMaker().(divisions: 1/4 ! 4, ratios: #[[1,1,1,1,1]]));
mutate(a).fuseBySizes(sizes: #[-2,4], isCyclic: true);
mutate(a).rewriteBeams(beamEachRun: true);
mutate(a).rewritePitches(#[60,62,64]);
a.show;


scale

Scales mutation client by multiplier.

  1. Scales note duration by dot-generating multiplier.

    a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/8]));
a.show;

    mutate(a.leafAt(1)).scale(3/2);
a.show;

  2. Scales nontrivial logical tie duration by dot-generating multiplier.

    a = FoscStaff(FoscLeafMaker().(#[60,60,62], [1/8]));
a[0..1].tie;
a.show;

    mutate(a.leafAt(0).prGetLogicalTie).scale(3/2);
a.show;

  3. Scales container duration by dot-generating multiplier.

    a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/8]));
a.show;

    mutate(a).scale(3/2);
a.show;

  4. Scales note by tie-generating multiplier.

    a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/8]));
a.show;

    mutate(a.leafAt(1)).scale(5/4);
a.show;

  5. Scales nontrivial logical tie duration by tie-generating multiplier.

    a = FoscStaff(FoscLeafMaker().(#[60,60,62], [1/8]));
a[0..1].tie;
a.show;

    mutate(a.leafAt(0).prGetLogicalTie).scale(5/4);
a.show;

  6. Scales container duration by tie-generating multiplier.

    a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/8]));
a.show;

    mutate(a).scale(5/4);
a.show;

  7. !!!TODO: NOT YET WORKING

    Scales note by tuplet-generating multiplier.

    a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/8]));
a.show;

    mutate(a.leafAt(1)).scale(2/3);
a.show;


split

Splits component or selection by durations.

Returns array of selections.

FIXME: these examples crash docs build when interpreted

  1. Splits leaves.

    d = [3/16, 7/32];
a = FoscStaff(FoscLeafMaker().(#[60,64,62,65,60,64,62,65], [1/8]));
m = a.selectLeaves;
m.hairpin('p < f');
mutate(m).split(d, tieSplitNotes: false);
a.show;

  2. Splits leaves cyclically.

    d = [3/16, 7/32];
a = FoscStaff(FoscLeafMaker().(#[60,64,62,65,60,64,62,65], [1/8]));
m = a.selectLeaves;
m.hairpin('p < f');
mutate(m).split(d, isCyclic: true, tieSplitNotes: false);
a.show;

  3. Splits tupletted leaves.

    t = FoscTuplet(2/3, FoscLeafMaker().(#[60,62,64], 1/4));
a = FoscStaff([t, mutate(t).copy]);
m = a.selectLeaves;
m.slur;
mutate(m).split([1/4], tieSplitNotes: false);
a.show;

  4. Splits leaves cyclically and tie split notes.

    a = FoscStaff(FoscLeafMaker().(#[60,62], [1]));
m = a.selectLeaves;
m.hairpin('p < f');
mutate(m).split([3/4], isCyclic: true, tieSplitNotes: true);
a.show;

  5. Splits leaves with articulations.

    a = FoscStaff(FoscLeafMaker().(#[60,62,64,65], [1/4]));
a.leafAt(0).attach(FoscArticulation('^'));
a.leafAt(1).attach(FoscLaissezVibrer());
a.leafAt(2).attach(FoscArticulation('^'));
a.leafAt(3).attach(FoscLaissezVibrer());
mutate(a.selectLeaves).split([1/8], isCyclic: true, tieSplitNotes: true);
a.show;


swap

Swaps mutation client for empty container.

Returns nil.


transpose

Transposes notes and chords in mutation client by interval.

Returns nil.

!!!TODO: Move to pitchtools package.

  1. Example

    n = #["Db4", "D4", "Eb4", "E4", "F4", "Gb4"];
a = FoscVoice(n.collect { |each| FoscNote(each, [1, 4]) });
a.format;
mutate(a).transpose(5);
a.format;
mutate(a).transpose(-5).respellWithFlats;
a.format;
    \new Voice {
    df'4
    d'4
    ef'4
    e'4
    f'4
    gf'4
}


wrap

Wraps mutation client in empty container.

  1. Wraps in-score notes in tuplet.

    a = FoscStaff(FoscLeafMaker().(#[60,62,64,60,62,64], [1/8]));
set(a).autoBeaming = false;
b = a.selectLeaves.partitionBySizes(#[3,3]);
b.do { |each|
    each.beam;
    each.slur;
};
a.show;

  2. !!!TODO: is Measure deprecated in abjad 3.0 ?

    Wraps leaves in measure.

    FIXME: ERROR: Class not defined.

    a = FoscVoice(FoscLeafMaker().((60..67), [1/8]));
m = FoscMeasure(#[4,8], []);
mutate(a[..3]).wrap(m);
a.show;