obgc¶

Containers

OnBeatGraceContainer

On-beat grace container.

class abjad.obgc.OnBeatGraceContainer(components=(), *, grace_leaf_duration=None, identifier=None, name=None, tag=None)[source]¶

On-beat grace container.

Note

On-beat grace containers must be included in a named voice.

On-beat grace containers implement custom formatting not available in LilyPond:

>>> music_voice = abjad.Voice("c'4 d'4 e'4 f'4", name="MusicVoice")
>>> string = "<d' g'>8 a' b' c'' d'' c'' b' a' b' c'' d''"
>>> container = abjad.on_beat_grace_container(
...     string, music_voice[1:3], grace_leaf_duration=(1, 24)
... )
>>> abjad.attach(abjad.Articulation(">"), container[0])
>>> staff = abjad.Staff([music_voice])
>>> lilypond_file = abjad.LilyPondFile([r'\include "abjad.ily"', staff])
>>> abjad.show(lilypond_file)  

Attributes Summary

`get_anchor_leaf`	Gets anchor leaf.
`grace_leaf_duration`	Gets grace leaf duration.

Special methods

(Container).__contains__(argument)¶

Is true when argument appears in container.

Return type:: bool

(Component).__copy__(*arguments)¶

Shallow copies component.

Copies indicators.

Does not copy spanners.

Does not copy children.

Returns new component.

(Container).__delitem__(i)¶

Deletes components(s) at index i in container.

Deletes first tuplet in voice:

>>> voice = abjad.Voice()
>>> voice.append(abjad.Tuplet((4, 6), "c'4 d'4 e'4"))
>>> voice.append(abjad.Tuplet((2, 3), "e'4 d'4 c'4"))
>>> leaves = abjad.select.leaves(voice)
>>> abjad.slur(leaves)
>>> abjad.show(voice)  

>>> tuplet_1 = voice[0]
>>> del voice[0]
>>> start_slur = abjad.StartSlur()
>>> leaf = abjad.select.leaf(voice, 0)
>>> abjad.attach(start_slur, leaf)

First tuplet no longer appears in voice:

>>> abjad.show(voice)  

>>> abjad.wf.wellformed(voice)
True

First tuplet must have start slur removed:

>>> abjad.detach(abjad.StartSlur, tuplet_1[0])
(StartSlur(),)

>>> abjad.show(tuplet_1)  

>>> abjad.wf.wellformed(tuplet_1)
True

Returns none.

(Container).__getitem__(argument)¶

Gets top-level item or slice identified by argument.

Return type:: Component | list[Component]

(Container).__iter__()¶

Iterates container.

Abjad containers are iterables:

>>> import collections
>>> container = abjad.Container()
>>> isinstance(container, collections.abc.Iterable)
True

Abjad containers are not sequences:

>>> import collections
>>> container = abjad.Container()
>>> isinstance(container, collections.abc.Sequence)
False

Yields container elements.

Returns generator.

(Container).__len__()¶

Gets number of components in container.

Return type:: int

(Container).__repr__()¶

Gets repr.

Return type:: str

(Container).__setitem__(i, argument)¶

Sets container i equal to argument.

Return type:: None

Methods

(Container).append(component, *, language='english')¶

Appends component to container.

Appends note to container:

>>> container = abjad.Container("c'4 ( d'4 f'4 )")
>>> abjad.show(container)  

>>> container.append(abjad.Note("e'4"))
>>> abjad.show(container)  

Return type:: None

(Container).extend(argument, *, language='english')¶

Extends container with argument.

Extends container with three notes:

>>> container = abjad.Container("c'4 ( d'4 f'4 )")
>>> abjad.show(container)  

>>> notes = [abjad.Note("e'32"), abjad.Note("d'32"), abjad.Note("e'16")]
>>> container.extend(notes)
>>> abjad.show(container)  

Return type:: None

get_anchor_leaf()[source]¶: Gets anchor leaf.

(Container).index(component)¶

Returns index of component in container.

Gets index of last element in container:

>>> container = abjad.Container("c'4 d'4 f'4 e'4")
>>> abjad.show(container)  

>>> note = container[-1]
>>> note
Note("e'4")

>>> container.index(note)
3

Return type:: int

(Container).insert(i, component, *, language='english')¶

Inserts component at index i in container.

Inserts note.

>>> container = abjad.Container([])
>>> container.extend("fs16 cs' e' a'")
>>> container.extend("cs''16 e'' cs'' a'")
>>> container.extend("fs'16 e' cs' fs")
>>> abjad.show(container)  

>>> container.insert(-4, abjad.Note("e'4"))
>>> abjad.show(container)  

Return type:: None

(Container).pop(i=-1)¶

Pops component from container at index i.

Pops last element from container:

>>> container = abjad.Container("c'4 ( d'4 f'4 ) e'4")
>>> abjad.show(container)  

>>> container.pop()
Note("e'4")

>>> abjad.show(container)  

Return type:: Component

(Container).remove(component)¶

Removes component from container.

Removes note from container:

>>> container = abjad.Container("c'4 d'4 f'4 e'4")
>>> abjad.show(container)  

>>> note = container[2]
>>> note
Note("f'4")

>>> container.remove(note)
>>> abjad.show(container)  

Return type:: None

Read/write properties

(Container).identifier¶

Gets and sets bracket comment.

>>> container = abjad.Container(
...     "c'4 d'4 e'4 f'4",
...     identifier="%*% AB",
... )
>>> abjad.show(container)  

>>> string = abjad.lilypond(container)
>>> print(string)
{   %*% AB
    c'4
    d'4
    e'4
    f'4
}   %*% AB

(Container).name¶

Gets and sets name of container.

Gets container name:

>>> container = abjad.Container("c'4 d'4 e'4 f'4")
>>> abjad.show(container)  

>>> container.name is None
True

Sets container name:

>>> container = abjad.Container(
...     "c'4 d'4 e'4 f'4",
...     name="Special",
... )
>>> abjad.show(container)  

>>> container.name
'Special'

Container name does not appear in LilyPond output:

>>> string = abjad.lilypond(container)
>>> print(string)
{
    c'4
    d'4
    e'4
    f'4
}

(Container).simultaneous¶

Is true when container is simultaneous.

Gets simultaneity status of container:

>>> container = abjad.Container()
>>> container.append(abjad.Voice("c'8 d'8 e'8"))
>>> container.append(abjad.Voice("g4."))
>>> abjad.show(container)  

>>> container.simultaneous
False

Sets simultaneity status of container:

>>> container = abjad.Container()
>>> container.append(abjad.Voice("c'8 d'8 e'8"))
>>> container.append(abjad.Voice("g4."))
>>> abjad.show(container)  

>>> container.simultaneous = True
>>> abjad.show(container)  

Read-only properties

(Container).components¶: Gets components in container.

grace_leaf_duration¶: Gets grace leaf duration.

(Component).tag¶: Gets component tag.

Functions

on_beat_grace_container

Makes on-beat grace container (with grace_leaves) and attaches to nongrace_leaves.

abjad.obgc.on_beat_grace_container(grace_leaves, nongrace_leaves, *, do_not_attach_one_voice_command=False, do_not_beam=False, do_not_slash=False, do_not_slur=False, grace_font_size=-3, grace_leaf_duration=None, grace_polyphony_command=VoiceNumber(n=1, leak=False), nongrace_polyphony_command=VoiceNumber(n=2, leak=False), tag=Tag(string=''))[source]¶

Makes on-beat grace container (with grace_leaves) and attaches to nongrace_leaves.

>>> def make_lilypond_file(anchor_voice_string, obgc_string, *, below=False):
...     music_voice = abjad.Voice(anchor_voice_string, name="MusicVoice")
...     if below is False:
...         nongrace_polyphony_command = abjad.VoiceNumber(2)
...         grace_polyphony_command = abjad.VoiceNumber(1)
...     else:
...         nongrace_polyphony_command = abjad.VoiceNumber(1)
...         grace_polyphony_command = abjad.VoiceNumber(2)
...     result = abjad.on_beat_grace_container(
...         obgc_string,
...         music_voice[1:3],
...         grace_leaf_duration=abjad.Duration(1, 30),
...         grace_polyphony_command=grace_polyphony_command,
...         nongrace_polyphony_command=nongrace_polyphony_command,
...     )
...     staff = abjad.Staff([music_voice])
...     lilypond_file = abjad.LilyPondFile([r'\include "abjad.ily"', staff])
...     return lilypond_file
... 

GRACE NOTES ABOVE.

Note-to-note anchor:

>>> lilypond_file = make_lilypond_file(
...     "c'4 d' e' f'",
...     "g'8 a' b' c'' d'' c'' b' a' b' c'' d''",
... )
>>> abjad.show(lilypond_file)  

Note-to-chord anchor:

>>> lilypond_file = make_lilypond_file(
...     "<a c'>4 <b d'> <c' e'> <d' f'>",
...     "g'8 a' b' c'' d'' c'' b' a' b' c'' d''",
... )
>>> abjad.show(lilypond_file)  

Chord-to-note anchor:

>>> lilypond_file = make_lilypond_file(
...     "c'4 d' e' f'",
...     "<g' b'>8 a' b' c'' d'' c'' b' a' b' c'' d''",
... )
>>> abjad.show(lilypond_file)  

Chord-to-chord anchor:

>>> lilypond_file = make_lilypond_file(
...     "<a c'>4 <b d'> <c' e'> <d' f'>",
...     "<g' b'>8 a' b' c'' d'' c'' b' a' b' c'' d''",
... )
>>> abjad.show(lilypond_file)  

GRACE NOTES BELOW.

Note-to-note anchor:

>>> lilypond_file = make_lilypond_file(
...     "c'4 d' e' f'",
...     "g8 a b c' d' c' b a b c' d'",
...     below=True,
... )
>>> abjad.show(lilypond_file)  

Note-to-chord anchor:

>>> lilypond_file = make_lilypond_file(
...     "<c' e'>4 <d' f'> <e' g'> <f' a'>",
...     "g8 a b c' d' c' b a b c' d'",
...     below=True,
... )
>>> abjad.show(lilypond_file)  

Chord-to-note anchor:

>>> lilypond_file = make_lilypond_file(
...     "c'4 d' e' f'",
...     "<e g>8 a b c' d' c' b a b c' d'",
...     below=True,
... )
>>> abjad.show(lilypond_file)  

Chord-to-chord anchor:

>>> lilypond_file = make_lilypond_file(
...     "<c' e'>4 <d' f'> <e' g'> <f' a'>",
...     "<e g>8 a b c' d' c' b a b c' d'",
...     below=True,
... )
>>> abjad.show(lilypond_file)  

Todo

Fix stem-alignment in final example.

Return type:: OnBeatGraceContainer