Repeater

class auxjad.Repeater(contents: Container, *, omit_time_signatures: bool = False, force_identical_time_signatures: bool = False, reposition_clefs: bool = True, reposition_dynamics: bool = True, reposition_slurs: bool = True, repeat_type: str = 'unfold', include_2x_volta_text: bool = True)

Takes an abjad.Container (or child class) as input and outputs an abjad.Selection with n repetitions. It can be of type unfold or volta.

Basic usage:

Calling the object will return an abjad.Selection generated by the repeating process, which is of type unfold by default (more on this below). The argument of __call__() defines the number of repetitions.

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

>>> repeater = auxjad.Repeater(container)
>>> notes = repeater(2)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

The property current_window can be used to access the last results.

>>> notes = repeater.current_window()
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

repeat_type:

Use the repeat_type property to set the type of the repeater. It takes a single string, which should be either 'unfold' or 'volta'. Unfold is the default mode i.e. the repeater outputs a selection of n identical consecutive measures. In volta mode, repeat bars are added as well as a written indication of the number of repeats. Compare:

>>> container = abjad.Container(r"c'2 d'2")
>>> repeater = auxjad.Repeater(container,
...                            repeat_type='unfold',
...                            )
>>> notes = repeater(5)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

>>> container = abjad.Container(r"c'2 d'2")
>>> repeater = auxjad.Repeater(container,
...                            repeat_type='volta',
...                            )
>>> notes = repeater(5)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

Typical usage of volta mode:

The volta mode can be used to construct containers in the following way:

>>> container = abjad.Container(r"c'4 d'4 e'4 f'4")
>>> repeater = auxjad.Repeater(container,
...                            repeat_type='volta',
...                            )
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> repeater.contents = abjad.Container(r"g'2 a'2")
>>> notes = repeater(2)
>>> staff.append(notes)
>>> repeater.contents = abjad.Container(r"b'16 c''16 d''16 e''16 r2.")
>>> notes = repeater(5)
>>> staff.append(notes)
>>> abjad.show(staff)

include_2x_volta_text:

By default, the written indication nx is added to all repeats in volta mode. To omit it when n is 2, set include_2x_volta_text to False:

>>> container = abjad.Container(r"c'4 d'4 e'4 f'4")
>>> repeater = auxjad.Repeater(container,
...                            repeat_type='volta',
...                            include_2x_volta_text=False,
...                            )
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> repeater.contents = abjad.Container(r"g'2 a'2")
>>> notes = repeater(2)
>>> staff.append(notes)
>>> repeater.contents = abjad.Container(r"b'16 c''16 d''16 e''16 r2.")
>>> notes = repeater(5)
>>> staff.append(notes)
>>> abjad.show(staff)

Time signatures:

This class handles different time signatures.

>>> container = abjad.Container(r"\time 3/4 c'2. \time 2/4 r2 g'2")
>>> repeater = auxjad.Repeater(container)
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

Underfull containers:

Containers that are not fully filled in are automatically closed by this class in its output. Containers without a time signature are assumed to be in 4/4 (which is LilyPond’s default).

>>> container = abjad.Container(r"c'4 d'4 e'4")
>>> repeater = auxjad.Repeater(container)
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

>>> container = abjad.Container(r"\time 3/4 c'4 d'4 e'4 f'2")
>>> repeater = auxjad.Repeater(container)
>>> notes = repeater(2)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

Using as iterator:

The instances of this class can also be used as an iterator, which can then be used in a for loop. Note that unlike the methods __call__() and output_n(), time signatures are added to each window returned by the shuffler. Use the function auxjad.mutate.remove_repeated_time_signatures() to clean the output when using this class in this way. It is also important to note that a break statement is needed when using this class as an iterator. The reason is that repeating is a process that can happen indefinitely (unlike some of the other classes in this library).

>>> container = abjad.Container(r"\time 3/4 c'4 d'4 e'4")
>>> repeater = auxjad.Repeater(container)
>>> staff = abjad.Staff()
>>> for window in repeater:
...     staff.append(window)
...     if abjad.get.duration(staff) == abjad.Duration((9, 4)):
...         break
>>> auxjad.mutate.remove_repeated_time_signatures(staff[:])
>>> abjad.show(staff)

Arguments and properties:

This class can take many optional keyword arguments during its creation, besides attr:repeat_type and attr:include_2x_volta_text. attr:omit_time_signatures will remove all time signatures from the output while force_identical_time_signatures will force all time signatures (including repeated ones) to be added to the output (both are False by default). When set to True, the properties reposition_clefs, reposition_dynamics, and reposition_slurs will invoke the mutations auxjad.mutate.reposition_clefs(), auxjad.mutate.reposition_dynamics(), and auxjad.mutate.reposition_slurs() (default values are True). Check their documentation for more information on how they operate.

>>> container = abjad.Container(r"\time 3/4 c'4 d'4 e'4")
>>> repeater = auxjad.Repeater(container,
...                            repeat_type='volta',
...                            include_2x_volta_text=False,
...                            omit_time_signatures=False,
...                            force_identical_time_signatures=False,
...                            reposition_clefs=True,
...                            reposition_dynamics=True,
...                            reposition_slurs=True,
...                            )
>>> repeater.repeat_type
'volta'
>>> repeater.include_2x_volta_text
False
>>> repeater.omit_time_signatures
False
>>> repeater.force_identical_time_signatures
False
>>> repeater.reposition_clefs
True
>>> repeater.reposition_dynamics
True
>>> repeater.reposition_slurs
True

Use the properties below to change these values after initialisation.

>>> repeater.repeat_type = 'unfold'
>>> repeater.include_2x_volta_text = True
>>> repeater.omit_time_signatures = True
>>> repeater.force_identical_time_signatures = True
>>> repeater.reposition_clefs = False
>>> repeater.reposition_dynamics = False
>>> repeater.reposition_slurs = False
>>> repeater.repeat_type
'unfold'
>>> repeater.include_2x_volta_text
True
>>> repeater.omit_time_signatures
True
>>> repeater.force_identical_time_signatures
True
>>> repeater.reposition_clefs
False
>>> repeater.reposition_dynamics
False
>>> repeater.reposition_slurs
False

contents:

Use the contents property to read as well as overwrite the contents of the repeater.

>>> container = abjad.Container(r"c'4 d'4 e'4 f'4")
>>> repeater = auxjad.Repeater(container)
>>> notes = repeater(2)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

>>> repeater.contents = abjad.Container(r"c'16 d'16 e'16 f'16 g'2.")
>>> notes = repeater(2)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

output_n():

This is an alias of __call__(). Takes an argument n for the number of repetitions.

>>> container = abjad.Container(r"c'4 d'4 e'4 f'4")
>>> repeater = auxjad.Repeater(container)
>>> notes = repeater.output_n(2)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

omit_time_signatures:

To disable time signatures altogether, initialise this class with the keyword argument omit_time_signatures set to True (default is False), or use the omit_time_signatures property after initialisation.

>>> container = abjad.Container(r"c'4 d'4 e'4")
>>> repeater = auxjad.Repeater(container,
...                            omit_time_signatures=True,
...                            )
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

force_identical_time_signatures:

To force time signatures in all iterations of the output, initialise this class with the keyword argument force_identical_time_signatures set to True (default is False), or use the force_identical_time_signatures property after initialisation.

>>> container = abjad.Container(r"\time 5/4 c'2. d'4 e'4")
>>> repeater = auxjad.Repeater(container,
...                            force_identical_time_signatures=True,
...                            )
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

Dynamics, slurs, and clefs:

By default, this class automatically handles dynamics, slurs, and clefs, optimising their position and omitting repetitions.

>>> container = abjad.Container(r"\clef bass f4\pp( e4) d4(")
>>> abjad.show(staff)

This is done by invoking auxjad.mutate.reposition_clefs(), auxjad.mutate.reposition_dynamics(), and auxjad.mutate.reposition_slurs(). Check their documentation for more information on how they operate.

>>> repeater = auxjad.Repeater(container)
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

Set theproperties reposition_clefs, reposition_dynamics, and reposition_slurs to False to not invoke these mutations.

>>> repeater = auxjad.Repeater(container,
...                            reposition_clefs=False,
...                            reposition_dynamics=False,
...                            reposition_slurs=False,
...                            )
>>> notes = repeater(3)
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

Error

If a container is malformed, i.e. it has an underfilled measure before a time signature change, this class will raise a ValueError exception.

>>> container = abjad.Container(r"\time 5/4 g''1 \time 4/4 f'1")
>>> repeater = auxjad.Repeater(container)
ValueError: 'contents' is malformed, with an underfull measure
preceding a time signature change

Methods

__call__([n])	Calls the repeater process for n iterations, returning an abjad.Selection.
__init__(contents, *[, ...])	Initialises self.
__iter__()	Returns an iterator, allowing instances to be used as iterators.
__next__()	Calls the shuffling process for one iteration, returning an abjad.Selection.
__repr__()	Returns interpreter representation of contents.
output_n([n])	Calls the repeater process for n iterations, returning an abjad.Selection.

Attributes

contents	The abjad.Container to be shuffled.
current_window	Read-only property, returns the previously output selection.
force_identical_time_signatures	When True, all time signatures will be printed in the output, including repeated ones .
include_2x_volta_text	When True, a written indication for the number of repeats will be included for n=2.
omit_time_signatures	When True, all time signatures will be omitted from the output.
repeat_type	Defines the type of repeat, either 'unfold' or 'volta'.
reposition_clefs	When True, auxjad.mutate.reposition_clefs() is invoked.
reposition_dynamics	When True, auxjad.mutate.reposition_dynamics() is invoked.
reposition_slurs	When True, auxjad.mutate.reposition_slurs() is invoked.

__call__(n: int = 1) → Selection

Calls the repeater process for n iterations, returning an abjad.Selection. Default n is 1.

__init__(contents: Container, *, omit_time_signatures: bool = False, force_identical_time_signatures: bool = False, reposition_clefs: bool = True, reposition_dynamics: bool = True, reposition_slurs: bool = True, repeat_type: str = 'unfold', include_2x_volta_text: bool = True) → None

Initialises self.

__iter__() → None

Returns an iterator, allowing instances to be used as iterators.

__next__() → Selection

Calls the shuffling process for one iteration, returning an abjad.Selection.

__repr__() → str

Returns interpreter representation of contents.

property contents: Container

The abjad.Container to be shuffled.

property current_window: Selection

Read-only property, returns the previously output selection.

property force_identical_time_signatures: bool

When True, all time signatures will be printed in the output, including repeated ones .

property include_2x_volta_text: bool

When True, a written indication for the number of repeats will be included for n=2. Otherwise, it is included only when repeated more than two times.

property omit_time_signatures: bool

When True, all time signatures will be omitted from the output.

output_n(n: int = 1) → Selection

Calls the repeater process for n iterations, returning an abjad.Selection. Default n is 1.

property repeat_type: bool

Defines the type of repeat, either 'unfold' or 'volta'.

property reposition_clefs: bool

When True, auxjad.mutate.reposition_clefs() is invoked.

property reposition_dynamics: bool

When True, auxjad.mutate.reposition_dynamics() is invoked.

property reposition_slurs: bool

When True, auxjad.mutate.reposition_slurs() is invoked.