Spanner — Abjad v1.1.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Project Abjad »
- Abjad v1.1.1 documentation »
- Abjad API »

# Spanner

class `abjad.` `Spanner`(music=None)

  Bases: `abjad.core.abjadcore._Abjad`

  Any type of notation object that stretches horizontally and encompasses some number of notes, rest, chords, tuplets, measures, voices or other Abjad components.

  Beams, slurs, hairpins, trills, glissandi and piano pedal brackets all stretch horizontally on the page to encompass multiple notes and all implement as Abjad spanners. That is, these spanner all have an obvious graphic reality with definite start-, stop- and midpoints.

  Abjad also implements a number of spanners of a different type, such as tempo and instrument spanners, which mark a group of notes, rests, chords or measues as carrying a certain tempo or being played by a certain instrument.

  The `Spanner` class described here abstracts the functionality that all such spanners, both graphic and nongraphics, share. This shared functionality includes methods to add, remove, inspect and test components governed by the spanner, as well as basic formatting properties. The other spanner classes, such as `Beam` and `Glissando`, all inherit from this class and receive the functionality implemented here.

  `append`(component)

    Add component to right of spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[:2])
        abjad> spanner
        Spanner(c'8, d'8)

        abjad> spanner.append(voice[2])
        abjad> spanner
        Spanner(c'8, d'8, e'8)

  `append_left`(component)

    Add component to left of spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[2:])
        abjad> spanner
        Spanner(e'8, f'8)

        abjad> spanner.append_left(voice[1])
        abjad> spanner
        Spanner(d'8, e'8, f'8)

  `clear`()

    Remove all components from spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[:])
        abjad> spanner
        Spanner(c'8, d'8, e'8, f'8)

        abjad> spanner.clear( )
        abjad> spanner
        Spanner( )

  `components`

    Return read-only tuple of components in spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[:2])
        abjad> spanner.components
        (Note(c', 8), Note(d', 8))

    Changed in version 1.1.1: Now returns an (immutable) tuple instead of a (mutable) list.

  `duration`

    Return read-only reference to spanner duration interface.

    Spanner duration interface implements `written`, `preprolated` and `prolated` attributes.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[:2])
        abjad> spanner
        Spanner(c'8, d'8, e'8, f'8)

        abjad> spanner.duration.written
        Rational(1, 2)

        abjad> spanner.duration.preprolated
        Rational(1, 2)

        abjad> spanner.duration.prolated
        Rational(1, 2)

    Spanner duration interface also implements `seconds` attribute.

        abjad> Tempo(voice[:], TempoIndication(Rational(1, 8), 48))
        abjad> spanner.duration.seconds
        Rational(5, 1)

  `extend`(components)

    Add iterable components to right of spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice([:2])
        abjad> spanner
        Spanner(c'8, d'8)

        abjad> spanner.extend(voice[2:])
        abjad> spanner
        Spanner(c'8, d'8, e'8, f'8)

  `extend_left`(components)

    Add iterable components to left of spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice([2:])
        abjad> spanner
        Spanner(e'8, f'8)

        abjad> spanner.extend_left(voice[:2])
        abjad> spanner
        Spanner(c'8, d'8, e'8, f'8)

  `fracture`(i, direction='both')

    Fracture spanner at direction of component at index i.

    Valid values for direction are `'left'`, `'right'` and `'both'`.

    Return original, left and right spanners.

        abjad> voice = Voice(construct.scale(4))
        abjad> beam = Beam(voice[:])
        abjad> beam
        Beam(c'8, d'8, e'8, f'8)

        abjad> beam.fracture(1, direction = 'left')
        (Beam(c'8, d'8, e'8, f'8), Beam(c'8), Beam(d'8, e'8, f'8))

        abjad> print voice.format
        \new Voice {
                c'8 [ ]
                d'8 [
                e'8
                f'8 ]
        }

  `fuse`(spanner)

    Fuse contiguous spanners.

    Return new spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> left_beam = Beam(t[:2])
        abjad> right_beam = Beam(t[2:])

        abjad> print voice.format
        \new Voice {
                c'8 [
                d'8 ]
                e'8 [
                f'8 ]
        }

        abjad> left_beam.fuse(right_beam)
        [(Beam(c'8, d'8), Beam(e'8, f'8), Beam(c'8, d'8, e'8, f'8))]

        abjad> print voice.format
        \new Voice {
                c'8 [
                d'8
                e'8
                f'8 ]
        }

    Todo

    Return (immutable) tuple instead of (mutable) list.

  `index`(component)

    Return nonnegative integer index of component in spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[2:])
        abjad> spanner
        Spanner(e'8, f'8)

        abjad> spanner.index(t[-2])
        0

  `leaves`

    Return read-only tuple of leaves in spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[:2])
        abjad> spanner.leaves
        (Note(c', 8), Note(d', 8))

    Changed in version 1.1.1: Now returns an (immutable) tuple instead of a (mutable) list.

  `offset`

    New in version 1.1.1.

    Return read-only reference to spanner offset interface.

    Spanner offset interface implements `start` and `stop` attributes.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[2:])
        abjad> spanner
        Spanner(e'8, f'8)

        abjad> spanner.offset.start
        Rational(1, 4)

        abjad> spanner.offset.stop
        Rational(1, 2)

  `pop`()

    Remove and return rightmost component in spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[:])
        abjad> spanner
        Spanner(c'8, d'8, e'8, f'8)

        abjad> spanner.pop( )
        f'8

        abjad> spanner
        Spanner(c'8, d'8, e'8)

  `pop_left`()

    Remove and return leftmost component in spanner.

        abjad> voice = Voice(construct.scale(4))
        abjad> spanner = Spanner(voice[:])
        abjad> spanner
        Spanner(c'8, d'8, e'8, f'8)

        abjad> spanner.pop_left( )
        c'8

        abjad> spanner
        Spanner(d'8, e'8, f'8)

### Navigation

- index
- modules |
- next |
- previous |
- Project Abjad »
- Abjad v1.1.1 documentation »
- Abjad API »