Understanding time signature marks
==================================

In this tutorial we take a deeper look at what happens
when we attach time signature marks to staves and other score components.

At the end of the tutorial you'll understand how time signature marks are
created.

You'll also understand how the states of different objects change when
you attach and detach time signature marks.


Getting started
---------------

We start by creating a staff full of notes:

<abjad>
staff = Staff("c'4 d'4 e'4 f'4 g'2")
</abjad>

The interpreter representation of our staff looks like this:

<abjad>
staff
</abjad>

The ``5`` in ``Staff{5}`` shows that the staff contains five top-level
components.  The curly braces in ``Staff{5}`` show that the contents of the
staff are to be read sequentially through time rather than simultaneously.

Before we get to time signature marks let's take a moment and examine the state
of the staff we've created. We can motivate this a bit by asking two questions:

1. what time signature is currently in effect for the staff we have just
created?

2. what is the time signature currently in effect for the five notes contained
within the staff we have just created?

The answer to both questions is the same: there is no time signature currently
in effect for either our staff or for the five notes it contains.

We can use the inspector to see that this is the case:

<abjad>
print inspect(staff).get_effective_context_mark(contexttools.TimeSignatureMark)
</abjad>

And:

<abjad>
for leaf in staff.select_leaves():
    print inspect(leaf).get_effective_context_mark(
        contexttools.TimeSignatureMark)
</abjad>

And we can iterate both the staff and its leaves at one and the same time like
this:

<abjad>
for component in iterationtools.iterate_components_in_expr(staff):
    effective_time_signature = inspect(component).get_effective_context_mark(
        contexttools.TimeSignatureMark)
    print component, effective_time_signature
</abjad>

This confirms the answers to our questions. There is not yet any time
signature in effect for any component in our staff because we have not yet
attached a time signature mark to any component in our staff.


LilyPond's implicit ``4/4``
---------------------------

So what happens if we format our staff and send it off to LilyPond to render as
a PDF? Will LilyPond render the staff with a time signature? Without a time
signature? Will LilyPond refuse to render the example at all?

We find out like this:

<abjad>
show(staff)
</abjad>

It turns out LilyPond defaults to a time signature of ``4/4``.

What's important to note here is that because we have not yet attached a time
signature mark any component in our staff Abjad says "no effective time
signature here" while LilyPond says "OK, I'll default to ``4/4`` so we can get
on with rendering your music."

We can further confirm that this is the case by asking Abjad for the LilyPond
format of our staff:

<abjad>
f(staff)
</abjad>

The LilyPond format of our staff contains no LilyPond ``\time`` command.
This is, again, because we have not yet attached a time signature mark
to any component in our staff.


Using time signature marks
--------------------------

We can now practice attaching and detaching time signature marks
to different components in our staff and study what happens as we do.

We'll start with ``3/4``.

The easiest thing to do is to attach a time signature mark to the staff itself.

We'll do this in two separate steps and study each step to understand exactly
what's going on.

First, we create a ``3/4`` time signature mark:

<abjad>
time_signature_mark = contexttools.TimeSignatureMark((3, 4))
</abjad>

The interpreter representation of our time signature looks like this:

<abjad>
time_signature_mark
</abjad>

All this tells us is that we have in fact created a ``3/4`` time signature
mark. Nothing too exciting yet. At this point our ``3/4`` time signature is
not yet attached to anything. We could say that the "state" of our time
signature mark is "unattached." And we can see this like so:

<abjad>
time_signature_mark.start_component is None
</abjad>

What does it mean for a time signature mark to have ``'start_component'`` equal
to none? It means that the time signature isn't yet attached to any score
component anywhere.

So now we attach our time signature mark to our staff:

<abjad>
time_signature_mark.attach(staff)
</abjad>

Abjad responds immediately by returning the time signature mark we have just
attached.

Notice that the interpreter representation of our time signature mark has
changed. The interpreter representation of our ``3/4`` time signature mark now
includes the staff to which we have just attached the time signature mark. That
is to say that the interpreter representation of our time signature mark is
statal.

Our time signature mark has transitioned from an "unattached" state to an
"attached" state. We can see this like so:

<abjad>
time_signature_mark.start_component
</abjad>

And our staff has likewise transitioned from a state of having no effective
time signature to a state of having an effective time signature:

<abjad>
inspect(staff).get_effective_context_mark(contexttools.TimeSignatureMark)
</abjad>

And what about the leaves inside our staff?
Do the leaves now "know" that they are governed by a ``3/4`` time signature?

Indeed they do:

<abjad>
for leaf in staff.select_leaves():
    effective_time_signature = inspect(leaf).get_effective_context_mark(
        contexttools.TimeSignatureMark)
    print leaf, effective_time_signature
</abjad>

Briefly to resume:

What we just did was to:

1. create a time signature mark
2. attach the time signature to a score component

This 2-step pattern is always the same when dealing with context marks: create
then attach.

Before moving on let's look at the PDF corresponding to our staff:

<abjad>
show(staff)
</abjad>

And let's confirm what we see in the PDF in the staff's format:

<abjad>
f(staff)
</abjad>

The staff's format now contains a LilyPond ``\time`` command because we have
attached an Abjad time signature mark to the staff.

What we've just been through above will cover over 80% of what you'll ever wind
up doing with time signature marks: creating them and attaching them directly
to staves. But what if we wan to get rid of a time signature mark? Or what if
the time signature will be changing all over the place? We cover those cases
next.

Detaching a time signature mark is easy:

<abjad>
time_signature_mark.detach()
</abjad>

Abjad returns the mark we have just detached. And the interpreter
representation of the time signature mark has again changed state:
the time signature mark has transitioned from attached to unattached.
We confirm this like so:

<abjad>
time_signature_mark.start_component is None
</abjad>

And also like so:

<abjad>
print inspect(staff).get_effective_context_mark(contexttools.TimeSignatureMark)
</abjad>

Our time signature mark now knows nothing about our staff. And vice versa.

So now what if we want to set up a time signature of ``2/4``?

We have a couple of options.

We can simply create and attach a new time signature mark:

<abjad>
duple_time_signature_mark = contexttools.TimeSignatureMark((2, 4))
duple_time_signature_mark.attach(staff)
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
</abjad>

Yup. That works.

On the other hand, we could simply reuse our previous ``3/4`` time signature
mark.

To do this we'll first detach our ``2/4`` time signature mark ...

<abjad>
duple_time_signature_mark.detach()
</abjad>

... confirm that our staff is now time signatureless ...

<abjad>
print inspect(staff).get_effective_context_mark(contexttools.TimeSignatureMark)
</abjad>

<abjad>
f(staff)
</abjad>

... reattach our previous ``3/4`` time signature ...

<abjad>
time_signature_mark.attach(staff)
</abjad>

... change the numerator of our time signature mark ...

<abjad>
time_signature_mark.numerator = 2
</abjad>

... and check to make sure that everything is as it should be:

<abjad>
inspect(staff).get_effective_context_mark(contexttools.TimeSignatureMark)
time_signature_mark.start_component
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
</abjad>

And everything works as it should.

To change to ``4/4`` we change just change the time signature mark's numerator
again:

<abjad>
time_signature_mark.numerator = 4
</abjad>

<abjad>
show(staff)
</abjad>

<abjad>
f(staff)
</abjad>


First-measure pick-ups
----------------------

But what if our time signature has a ``2/4`` pick-up?

The LilyPond command for pick-ups is ``\partial``.
Abjad time signature marks implement this as a read / write attribute:

<abjad>
time_signature_mark.partial = Duration(2, 4)
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
</abjad>

And what if time signature changes all over the place?

We'll use the trivial example of a measure in ``4/4`` followed by a measure in
``2/4``.

To do this we will need two time signature marks.

We've already got a ``4/4`` time signature mark attached to our staff:

<abjad>
f(staff)
</abjad>

Let's get rid of the pick-up:

<abjad>
time_signature_mark.partial = None
</abjad>

<abjad>
f(staff)
</abjad>

Now what about the ``2/4`` time signature mark?

We create it in the usual way:

<abjad>
duple_time_signature_mark = contexttools.TimeSignatureMark((2, 4))
duple_time_signature_mark
</abjad>

But should we attach it? We can't attach our ``2/4`` time signature to our
staff because we've already attached our ``4/4`` time signature to our staff.
And it only makes sense to attach one time signature to any given score
component.

Observe that we've built our score in a very straightforward way: we have a
single staff that contains a (flat) sequence of notes. This means that we have
only one choice for where to attach the new ``2/4`` time signature mark. And
that is one the ``g'2`` that comes on the downbeat of the second measure. We
do that like this:

<abjad>
duple_time_signature_mark.attach(staff[4])
</abjad>

<abjad>
f(staff)
</abjad>

<abjad>
show(staff)
</abjad>

And everything works as we would like.

Incidentally, ``staff[4]`` means the component sitting at index ``4`` inside
our staff. Using the interpreter we can verify that this is ``g'2``:

<abjad>
staff[4]
</abjad>

Depending on how we had chosen to build our staff we would have had more
options for where to attach our ``2/4`` time signature mark. If, for example,
we had chosen to populate our staff with a series of measures then it's
possible we could have attached our ``2/4`` time signature to a measure instead
of a note.
