LilyPond command marks
======================

LilyPond command marks allow you to attach arbitrary LilyPond commands
to Abjad score components.


Creating LilyPond command marks
-------------------------------

Use ``marktools`` to create LilyPond command marks:

<abjad>
command = marktools.LilyPondCommandMark('bar "||"', 'after')
</abjad>

<abjad>
command
</abjad>


Attaching LilyPond command marks to Abjad components
----------------------------------------------------

Use ``attach()`` to attach a LilyPond command mark to any Abjad component:

<abjad>
import copy
staff = Staff([])
key_signature = contexttools.KeySignatureMark('f', 'major')
key_signature.attach(staff)
staff.extend(p("{ d''16 ( c''16 fs''16 g''16 ) }"))
staff.extend(p("{ f''16 ( e''16 d''16 c''16 ) }"))
staff.extend(p("{ cs''16 ( d''16 f''16 d''16 ) }"))
staff.extend(p("{ a'8 b'8 }"))
staff.extend(p("{ d''16 ( c''16 fs''16 g''16 )} "))
staff.extend(p("{ f''16 ( e''16 d''16 c''16 ) }"))
staff.extend(p("{ cs''16 ( d''16 f''16 d''16 ) }"))
staff.extend(p("{ a'8 b'8 c''2 }"))
</abjad>

<abjad>
command.attach(staff[-2])
</abjad>

<abjad>
show(staff)
</abjad>


Inspecting the LilyPond command marks attached to an Abjad component
--------------------------------------------------------------------

Use the inspector to get the LilyPond command marks attached to a leaf:

<abjad>
inspect(staff[-2]).get_marks(marktools.LilyPondCommandMark)
</abjad>


Detaching LilyPond command marks from a component
-------------------------------------------------

Use ``detach()`` to detach LilyPond command marks from a component:

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

<abjad>
command
</abjad>

<abjad>
show(staff)
</abjad>


Inspecting the component to which a LilyPond command mark is attached
---------------------------------------------------------------------

Use ``start_component`` to inspect the component to which a LilyPond command
mark is attached:

<abjad>
command = marktools.LilyPondCommandMark('bar "||"', 'closing')
command.attach(staff[-2])
</abjad>

<abjad>
show(staff)
</abjad>

<abjad>
command.start_component
</abjad>


Getting and setting the command name of a LilyPond command mark
---------------------------------------------------------------

Set the ``command_name`` of a LilyPond command mark to change the
LilyPond command a LilyPond command mark prints:

<abjad>
command.command_name = 'bar "|."'
</abjad>

<abjad>
show(staff)
</abjad>


Copying LilyPond commands
-------------------------

Use ``copy.copy()`` to copy a LilyPond command mark:

<abjad>
import copy
</abjad>

<abjad>
command_copy_1 = copy.copy(command)
</abjad>

<abjad>
command_copy_1
</abjad>

<abjad>
command_copy_1.attach(staff[-1])
</abjad>

<abjad>
show(staff)
</abjad>

Or use ``copy.deepcopy()`` to do the same thing.


Comparing LilyPond command marks
--------------------------------

LilyPond command marks compare equal with equal command names:

<abjad>
command.command_name
</abjad>

<abjad>
command_copy_1.command_name
</abjad>

<abjad>
command == command_copy_1
</abjad>

Otherwise LilyPond command marks do not compare equal.
