spannertools.Spanner

class abjad.tools.spannertools.Spanner.Spanner.Spanner(components=None)

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.

Read-only Properties

Spanner.components

Return read-only tuple of components in spanner.

abjad> voice = Voice("c'8 d'8 e'8 f'8")
abjad> spanner = spannertools.Spanner(voice[:2])
abjad> spanner.components
(Note("c'8"), Note("d'8"))

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

Spanner.duration_in_seconds

Sum of duration of all leaves in spanner, in seconds.

Spanner.leaves

Return read-only tuple of leaves in spanner.

abjad> voice = Voice("c'8 d'8 e'8 f'8")
abjad> spanner = spannertools.Spanner(voice[:2])
abjad> spanner.leaves
(Note("c'8"), Note("d'8"))

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

Note

When dealing with large, complex scores accessing this attribute can take some time. Best to make a local copy with leaves = spanner.leaves first. Or use spanner- specific iteration tools.

Spanner.offset

New in version 1.1.

Return read-only reference to spanner offset interface.

Spanner offset interface implements start and stop attributes.

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

abjad> spanner._offset.start
Offset(1, 4)

abjad> spanner._offset.stop
Offset(1, 2)

Return duration.

Spanner.override

LilyPond grob override component plug-in.

Spanner.preprolated_duration

Sum of preprolated duration of all components in spanner.

Spanner.prolated_duration

Sum of prolated duration of all components in spanner.

Spanner.set

LilyPond context setting component plug-in.

Spanner.written_duration

Sum of written duration of all components in spanner.

Methods

Spanner.append(component)

Add component to right of spanner.

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

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

Return none.

Spanner.append_left(component)

Add component to left of spanner.

abjad> voice = Voice("c'8 d'8 e'8 f'8")
abjad> spanner = spannertools.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)

Return none.

Spanner.clear()

Remove all components from spanner:

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

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

Return none.

Spanner.extend(components)

Add iterable components to right of spanner:

abjad> voice = Voice("c'8 d'8 e'8 f'8")
abjad> spanner = spannertools.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)

Return none.

Spanner.extend_left(components)

Add iterable components to left of spanner:

abjad> voice = Voice("c'8 d'8 e'8 f'8")
abjad> spanner = spannertools.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)

Return none.

Spanner.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("c'8 d'8 e'8 f'8")
abjad> beam = spannertools.BeamSpanner(voice[:])
abjad> beam
BeamSpanner(c'8, d'8, e'8, f'8)

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

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

Return tuple.

Spanner.fuse(spanner)

Fuse contiguous spanners.

Return new spanner.

abjad> voice = Voice("c'8 d'8 e'8 f'8")
abjad> left_beam = spannertools.BeamSpanner(voice[:2])
abjad> right_beam = spannertools.BeamSpanner(voice[2:])

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

abjad> left_beam.fuse(right_beam)
[(BeamSpanner(c'8, d'8), BeamSpanner(e'8, f'8), BeamSpanner(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.

Spanner.index(component)

Return nonnegative integer index of component in spanner.

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

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

Return nonnegative integer.

Spanner.pop()

Remove and return rightmost component in spanner.

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

abjad> spanner.pop()
Note("f'8")

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

Return component.

Spanner.pop_left()

Remove and return leftmost component in spanner.

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

abjad> spanner.pop_left()
Note("c'8")

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

Return component.

Special Methods

Spanner.__contains__(expr)

Spanner.__delattr__()

x.__delattr__(‘name’) <==> del x.name

Note

Inherited from __builtin__.object

Spanner.__eq__(arg)

True when id(self) equals id(arg).

Return boolean.

Note

Inherited from abctools.AbjadObject

Spanner.__ge__(arg)

Abjad objects by default do not implement this method.

Raise exception.

Note

Inherited from abctools.AbjadObject

Spanner.__getitem__(expr)

Spanner.__gt__(arg)

Abjad objects by default do not implement this method.

Raise exception

Note

Inherited from abctools.AbjadObject

Spanner.__hash__() <==> hash(x)

Note

Inherited from __builtin__.object

Spanner.__le__(arg)

Abjad objects by default do not implement this method.

Raise exception.

Note

Inherited from abctools.AbjadObject

Spanner.__len__()

Spanner.__lt__(other)

Trivial comparison to allow doctests to work.

Spanner.__ne__(arg)

True when id(self) does not equal id(arg).

Return boolean.

Note

Inherited from abctools.AbjadObject

Spanner.__repr__()

Spanner.__setattr__()

x.__setattr__(‘name’, value) <==> x.name = value

Note

Inherited from __builtin__.object

Spanner.__str__() <==> str(x)

Note

Inherited from __builtin__.object