# -*- coding: utf-8 -*-


def iterate(client=None):
    r'''Makes iteration agent.

    ..  container:: example

        Example staff:

        ::

            >>> staff = Staff("c'4 e'4 d'4 f'4")
            >>> show(staff) # doctest: +SKIP

        ..  doctest::

            >>> f(staff)
            \new Staff {
                c'4
                e'4
                d'4
                f'4
            }

    ..  container:: example

        Iterates staff by leaf pair:

            >>> for pair in iterate(staff).by_leaf_pair():
            ...     pair
            Selection([Note("c'4"), Note("e'4")])
            Selection([Note("e'4"), Note("d'4")])
            Selection([Note("d'4"), Note("f'4")])

    ..  container:: example

        Iterates staff by pitch:

            >>> for pitch in iterate(staff).by_pitch():
            ...     pitch
            NamedPitch("c'")
            NamedPitch("e'")
            NamedPitch("d'")
            NamedPitch("f'")

    ..  container:: example

        Returns iteration agent:

        ::

            >>> iterate(staff)
            IterationAgent(client=Staff("c'4 e'4 d'4 f'4"))

    '''
    from abjad.tools import agenttools
    from abjad.tools import expressiontools
    if client is not None:
        return agenttools.IterationAgent(client=client)
    expression = expressiontools.Expression()
    expression = expression.iterate()
    return expression
