obgc

Containers

OnBeatGraceContainer

On-beat grace container.

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''"
>>> obgc = abjad.on_beat_grace_container(
...     string, music_voice[1:3], grace_leaf_duration=(1, 24)
... )
>>> abjad.attach(abjad.Articulation(">"), obgc[0])
>>> staff = abjad.Staff([music_voice])
>>> lilypond_file = abjad.LilyPondFile([r'\include "abjad.ily"', staff])
>>> abjad.show(lilypond_file)  

Attributes Summary

`attach_lilypond_one_voice`	Attaches LilyPond `\oneVoice` command.
`get_first_nongrace_leaf`	Gets first nongrace leaf.
`get_nongrace_voice`	Gets nongrace voice.
`get_polyphony_container`	Gets polyphony container.
`grace_leaf_duration`	Gets grace leaf duration.
`match_first_nongrace_leaf`	Matches first nongrace leaf.
`set_grace_leaf_multipliers`	Sets grace leaf multipliers.

Special methods

(Container).__contains__(argument) → bool: Is true when argument appears in container.

(Component).__copy__(*arguments)

Shallow copies component.

Copies indicators.

Does not copy spanners.

Does not copy children.

Returns new component.

(Container).__delitem__(i) → None

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

(Container).__getitem__(argument: SupportsIndex | str | slice) → Component | list[Component]: Gets top-level item or slice identified by argument.

(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__() → int: Gets number of components in container.

(Container).__repr__() → str: Gets repr.

(Container).__setitem__(i, argument) → None: Sets container i equal to argument.

Methods

(Container).append(component: Component, *, language: str = 'english') → None

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)  

attach_lilypond_one_voice() → None[source]: Attaches LilyPond \oneVoice command.

(Container).extend(argument, *, language: str = 'english') → None

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)  

get_first_nongrace_leaf() → Leaf[source]: Gets first nongrace leaf.

get_nongrace_voice() → Voice[source]: Gets nongrace voice.

get_polyphony_container() → Container[source]: Gets polyphony container.

(Container).index(component) → int

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

(Container).insert(i: int, component: str | Component, *, language: str = 'english') → None

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)  

match_first_nongrace_leaf() → None[source]: Matches first nongrace leaf.

(Container).pop(i: int = -1) → Component

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)  

(Container).remove(component: Component) → None

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)  

set_grace_leaf_multipliers() → None[source]: Sets grace leaf multipliers.

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)  

(Component).tag: Gets component tag.

Read-only properties

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

grace_leaf_duration: Gets grace leaf duration.

Functions

on_beat_grace_container

Wraps grace_leaves in on-beat grace container; wraps nongrace_leaves in voice ("nongrace voice"); wraps on-beat grace container and nongrace voice in container ("polyphony container").

abjad.obgc.on_beat_grace_container(grace_leaves: str | Sequence[Leaf], nongrace_leaves: Sequence[Leaf], *, do_not_attach_one_voice_command: bool = False, do_not_beam: bool = False, do_not_slash: bool = False, do_not_slur: bool = False, grace_font_size: int = -3, grace_leaf_duration: Duration | tuple[int, int] | None = None, grace_polyphony_command: VoiceNumber = VoiceNumber(n=1, leak=False), nongrace_polyphony_command: VoiceNumber = VoiceNumber(n=2, leak=False), tag: Tag = Tag(string='')) → OnBeatGraceContainer[source]

Wraps grace_leaves in on-beat grace container; wraps nongrace_leaves in voice (“nongrace voice”); wraps on-beat grace container and nongrace voice in container (“polyphony container”).

>>> def make_lilypond_file(nongrace_leaves_string, obgc_string, *, below=False):
...     music_voice = abjad.Voice(nongrace_leaves_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)
...     obgc = 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 two examples, above.