Containers
==========

Creating containers
-------------------

Create a container with components:

<abjad>
container = Container([Note("ds'16"), Note("cs'16"), Note("e'16"), Note("c'16")])
</abjad>

<abjad>
show(container)
container.override.staff.time_signature.transparent = True <hide
iotools.write_expr_to_ly(container, 'containers-1') <hide
</abjad>

Or with a note-entry string:

.. Xenakis: Jalons (1986): Contrabass: m58

<abjad>
container = Container("ds'16 cs'16 e'16 c'16 d'2 ~ d'8")
</abjad>

<abjad>
show(container)
container.override.staff.time_signature.transparent = True <hide
iotools.write_expr_to_ly(container, 'containers-2') <hide
</abjad>

Inspecting music
----------------

Return the components in a container with ``music``:

<abjad>
container.music
print repr(container.music) <hide
</abjad>

Or with a special call to ``__getslice__``:

<abjad>
container[:]
print container[:] <hide
</abjad>

Inspecting length
-----------------

Get the length of a container with ``len()``:

<abjad>
len(container)
print repr(len(container)) <hide
</abjad>

Inspecting duration
-------------------

Contents duration equals the sum of the duration of everything inside the container:

<abjad>
container.contents_duration
print repr(container.contents_duration) <hide
</abjad>

Adding one component to the end of a container
----------------------------------------------

Add one component to the end of a container with ``append``:

<abjad>
container.append(Note("af'32"))
</abjad>

<abjad>
show(container)
iotools.write_expr_to_ly(container, 'containers-3') <hide
</abjad>

Adding many components to the end of a container
------------------------------------------------

Add many components to the end of a container with ``extend``:

<abjad>
container.extend([Note("c''32"), Note("a'32")])
</abjad>

<abjad>
show(container)
iotools.write_expr_to_ly(container, 'containers-4') <hide
</abjad>

Finding the index of a component
--------------------------------

Find the index of a component with ``index``:

<abjad>
note = container[7]
</abjad>

<abjad>
container.index(note)
print repr(container.index(note)) <hide
</abjad>

Inserting a component by index
------------------------------

Insert a component by index with ``insert``:

<abjad>
container.insert(-3, Note("g'32"))
</abjad>

<abjad>
show(container)
iotools.write_expr_to_ly(container, 'containers-5') <hide
</abjad>

Removing a component by index
-----------------------------

Remove a component by index with ``pop``:

<abjad>
container.pop(-1)
</abjad>

<abjad>
show(container)
iotools.write_expr_to_ly(container, 'containers-6') <hide
</abjad>

Removing a component by reference
---------------------------------

Remove a component by reference with ``remove``:

<abjad>
container.remove(container[-1])
</abjad>

<abjad>
show(container)
iotools.write_expr_to_ly(container, 'containers-7') <hide
</abjad>

.. note::

    ``__getslice__``, ``__setslice__`` and ``__delslice__`` remain to be documented.

Naming containers
-----------------

You can name Abjad containers:

<abjad>
flute_staff = Staff("c'8 d'8 e'8 f'8")
flute_staff.name = 'Flute'
violin_staff = Staff("c'8 d'8 e'8 f'8")
violin_staff.name = 'Violin'
staff_group = scoretools.StaffGroup([flute_staff, violin_staff])
score = Score([staff_group])
</abjad>

Container names appear in LilyPond input:

<abjad>
f(score)
</abjad>

And make it easy to retrieve containers later:

<abjad>
componenttools.get_first_component_in_expr_with_name(score, 'Flute')
print repr(componenttools.get_first_component_in_expr_with_name(score, 'Flute')) <hide
</abjad>

But container names do not appear in notational output:

<abjad>
show(score)
iotools.write_expr_to_ly(score, 'containers-8') <hide
</abjad>

Understanding ``{ }`` and ``<< >>`` in LilyPond
-----------------------------------------------

LilyPond uses curly ``{ }`` braces to wrap a stream of musical events
that are to be engraved one after the other::

    \new Voice {
        e''4
        f''4
        g''4
        g''4
        f''4
        e''4
        d''4
        d''4 \fermata
    }

<abjad>
staff = Staff(r"e''4 f''4 g''4 g''4 f''4 e''4 d''4 d''4 \fermata") <hide
iotools.write_expr_to_ly(staff, 'containers-9') <hide
</abjad>

LilyPond uses skeleton ``<< >>`` braces to wrap two or more musical
expressions that are to be played at the same time::

    \new Staff <<
        \new Voice {
            \voiceOne
            e''4
            f''4
            g''4
            g''4
            f''4
            e''4
            d''4
            d''4 \fermata
        }
        \new Voice {
            \voiceTwo
            c''4
            c''4
            b'4
            c''4
            c''8
            b'8
            c''4
            b'4
            b'4 \fermata
        }
    >>

<abjad>
voice_1 = Voice(r"e''4 f''4 g''4 g''4 f''4 e''4 d''4 d''4 \fermata") <hide
voice_2 = Voice(r"c''4 c''4 b'4 c''4 c''8 b'8 c''4 b'4 b'4 \fermata") <hide
staff = Staff([voice_1, voice_2]) <hide
staff.is_parallel = True <hide
marktools.LilyPondCommandMark('voiceOne')(voice_1) <hide
marktools.LilyPondCommandMark('voiceTwo')(voice_2) <hide
iotools.write_expr_to_ly(staff, 'containers-10') <hide
</abjad>

The examples above are both LilyPond input.

The most common use of LilyPond ``{ }`` is to group a potentially long stream of notes
and rests into a single expression.

The most common use of LilyPond ``<< >>`` is to group a relatively smaller
number of note lists together polyphonically.

Understanding sequential and parallel containers
------------------------------------------------

Abjad implements LilyPond ``{ }`` and ``<< >>`` in the container ``is_parallel`` attribute.

Some containers set ``is_parallel`` to false at initialization::

    staff = Staff([])
    staff.is_parallel
    False

Other containers set ``is_parallel`` to true::

    score = Score([])
    score.is_parallel
    True

Changing sequential and parallel containers
-------------------------------------------

Set ``is_parallel`` by hand as necessary:

<abjad>
voice_1 = Voice(r"e''4 f''4 g''4 g''4 f''4 e''4 d''4 d''4 \fermata")
voice_2 = Voice(r"c''4 c''4 b'4 c''4 c''8 b'8 c''4 b'4 b'4 \fermata")
staff = Staff([voice_1, voice_2])
staff.is_parallel = True
marktools.LilyPondCommandMark('voiceOne')(voice_1)
marktools.LilyPondCommandMark('voiceTwo')(voice_2)
show(staff)
iotools.write_expr_to_ly(staff, 'containers-11') <hide
</abjad>

The staff in the example above is set to parallel after initialization to create
a type of polyphonic staff:

<abjad>
f(staff)
</abjad>

Overriding containers
---------------------

The symbols below are black with fixed thickness and predetermined spacing:

<abjad>
staff = Staff("c'4 d'4 e'4 f'4 g'4 a'4 g'2")
slur_1 = spannertools.SlurSpanner(staff[:2])
slur_2 = spannertools.SlurSpanner(staff[2:4])
slur_3 = spannertools.SlurSpanner(staff[4:6])
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'containers-12') <hide
</abjad>

But you can override LilyPond grobs to change the look of Abjad containers:

<abjad>
staff.override.staff_symbol.color = 'blue'
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'containers-13') <hide
</abjad>

Overriding containers' contents
-------------------------------

You can override LilyPond grobs to change the look of containers' contents, too:

<abjad>
staff.override.note_head.color = 'red'
staff.override.stem.color = 'red'
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'containers-14') <hide
</abjad>

Removing container overrides
----------------------------

Delete grob overrides you no longer want:

<abjad>
del(staff.override.staff_symbol)
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'containers-15') <hide
</abjad>
