abjad.tag

abjad.tag.activate(text, tag)

Activates tag in text.

abjad.tag.deactivate(text, tag[, ...])

Deactivates tag in text.

abjad.tag.double_tag(strings, tag_[, deactivate])

Double tags strings.

abjad.tag.left_shift_tags(text)

Left shifts tags in strings.

abjad.tag.remove_tags(string)

Removes all tags from string.

abjad.tag.Tag([string])

Tag.

abjad.tag.activate(text: str, tag: Tag | Callable) tuple[str, int, int][source]

Activates tag in text.

Tags can toggle indefinitely.

Returns (text, count, skipped) triple.

Count gives number of activated tags.

Skipped gives number of skipped tags.

Writes (deactivated) tag with "%@%" prefix into LilyPond input:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> markup = abjad.Markup(r"\markup { \with-color #red Allegro }")
>>> abjad.attach(
...     markup,
...     staff[0],
...     deactivate=True,
...     tag=abjad.Tag("RED_MARKUP"),
... )
>>> text = abjad.lilypond(staff, tags=True)
>>> text = abjad.tag.left_shift_tags(text)
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
    %@% - \markup { \with-color #red Allegro }
    d'4
    e'4
    f'4
}
>>> abjad.show(staff)  

Activates tag:

>>> text, count, skipped = abjad.activate(text, abjad.Tag("RED_MARKUP"))
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
    - \markup { \with-color #red Allegro } %@%
    d'4
    e'4
    f'4
}
>>> lines = [_.strip("\n") for _ in text.split("\n")]
>>> string = "\n".join(lines)
>>> lilypond_file = abjad.LilyPondFile([string])
>>> abjad.show(lilypond_file)  

Deactivates tag again:

>>> text, count, skipped = abjad.deactivate(text, abjad.Tag("RED_MARKUP"))
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
    %@% - \markup { \with-color #red Allegro }
    d'4
    e'4
    f'4
}
>>> lines = [_.strip("\n") for _ in text.split("\n")]
>>> string = "\n".join(lines)
>>> lilypond_file = abjad.LilyPondFile([string])
>>> abjad.show(lilypond_file)  

Activates tag again:

>>> text, count, skipped = abjad.activate(text, abjad.Tag("RED_MARKUP"))
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
    - \markup { \with-color #red Allegro } %@%
    d'4
    e'4
    f'4
}
>>> lines = [_.strip("\n") for _ in text.split("\n")]
>>> string = "\n".join(lines)
>>> lilypond_file = abjad.LilyPondFile([string])
>>> abjad.show(lilypond_file)  
abjad.tag.deactivate(text: str, tag: Tag | Callable, prepend_empty_chord: bool = False) tuple[str, int, int][source]

Deactivates tag in text.

Writes (active) tag into LilyPond input:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> string = r"\markup { \with-color #red Allegro }"
>>> markup = abjad.Markup(string)
>>> abjad.attach(
...     markup,
...     staff[0],
...     tag=abjad.Tag("RED_MARKUP"),
... )
>>> text = abjad.lilypond(staff, tags=True)
>>> text = abjad.tag.left_shift_tags(text)
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
    - \markup { \with-color #red Allegro }
    d'4
    e'4
    f'4
}
>>> abjad.show(staff)  

Deactivates tag:

>>> text = abjad.lilypond(staff, tags=True)
>>> text, count, skipped = abjad.deactivate(text, abjad.Tag("RED_MARKUP"))
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
%%% - \markup { \with-color #red Allegro }
    d'4
    e'4
    f'4
}
>>> lines = [_.strip("\n") for _ in text.split("\n")]
>>> string = "\n".join(lines)
>>> lilypond_file = abjad.LilyPondFile([string])
>>> abjad.show(lilypond_file)  

Activates tag again:

>>> text, count, skipped = abjad.activate(text, abjad.Tag("RED_MARKUP"))
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
    - \markup { \with-color #red Allegro }
    d'4
    e'4
    f'4
}
>>> lines = [_.strip("\n") for _ in text.split("\n")]
>>> string = "\n".join(lines)
>>> lilypond_file = abjad.LilyPondFile([string])
>>> abjad.show(lilypond_file)  

Deactivates tag again:

>>> text, count, skipped = abjad.deactivate(text, abjad.Tag("RED_MARKUP"))
>>> print(text)
\new Staff
{
    c'4
      %! RED_MARKUP
%%% - \markup { \with-color #red Allegro }
    d'4
    e'4
    f'4
}
>>> lines = [_.strip("\n") for _ in text.split("\n")]
>>> string = "\n".join(lines)
>>> lilypond_file = abjad.LilyPondFile([string])
>>> abjad.show(lilypond_file)  
abjad.tag.double_tag(strings: list[str], tag_: Tag, deactivate: bool = False) list[str][source]

Double tags strings.

abjad.tag.left_shift_tags(text: str) str[source]

Left shifts tags in strings.

abjad.tag.remove_tags(string: str) str[source]

Removes all tags from string.

class abjad.tag.Tag(string: str = '')[source]

Tag.

>>> abjad.Tag("YELLOW")
Tag(string='YELLOW')
>>> abjad.Tag("YELLOW:RED")
Tag(string='YELLOW:RED')

Raises exception on duplicate words in tag:

>>> abjad.Tag("YELLOW:RED:RED")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 4, in __init__
  File "/Users/trevor/Repositories/Projects/abjad/source/abjad/tag.py", line 54, in __post_init__
    self.words()
    ~~~~~~~~~~^^
  File "/Users/trevor/Repositories/Projects/abjad/source/abjad/tag.py", line 223, in words
    raise Exception(f"duplicate words in tag: {self.string!r}")
Exception: duplicate words in tag: 'YELLOW:RED:RED'

Raises exception on multiple only-edition tags:

>>> abjad.Tag("+SEGMENT:+PARTS")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 4, in __init__
  File "/Users/trevor/Repositories/Projects/abjad/source/abjad/tag.py", line 54, in __post_init__
    self.words()
    ~~~~~~~~~~^^
  File "/Users/trevor/Repositories/Projects/abjad/source/abjad/tag.py", line 232, in words
    raise Exception(f"at most one only-edition tag: {only_edition_tags!r}.")
Exception: at most one only-edition tag: ['+SEGMENT', '+PARTS'].

Raises exception on mixed only-edition / not-edition tags:

>>> abjad.Tag("+SEGMENT:-PARTS")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 4, in __init__
  File "/Users/trevor/Repositories/Projects/abjad/source/abjad/tag.py", line 54, in __post_init__
    self.words()
    ~~~~~~~~~~^^
  File "/Users/trevor/Repositories/Projects/abjad/source/abjad/tag.py", line 236, in words
    raise Exception(message)
Exception: only-edition and not-edition forbidden in same tag:

  ['+SEGMENT'] / ['-PARTS']

append(word)

Appends word to tag.

editions()

Gets edition tags in tag.

invert_edition_tags()

Inverts edition tags in tag.

not_editions()

Gets not-edition tags in tag.

only_edition()

Gets only-edition tag in tag.

retain_shoutcase()

Retains shoutcase.

words()

Gets words.

append(word: Tag) Tag[source]

Appends word to tag.

>>> abjad.Tag("-PARTS").append(abjad.Tag("DEFAULT_CLEF"))
Tag(string='-PARTS:DEFAULT_CLEF')
editions() list[Tag][source]

Gets edition tags in tag.

>>> abjad.Tag("FOO").editions()
[]
>>> abjad.Tag("+SEGMENT").only_edition()
Tag(string='+SEGMENT')
>>> abjad.Tag("+SEGMENT:FOO").only_edition()
Tag(string='+SEGMENT')
>>> abjad.Tag("-SEGMENT").editions()
[Tag(string='-SEGMENT')]
>>> abjad.Tag("-SEGMENT:FOO").editions()
[Tag(string='-SEGMENT')]
>>> abjad.Tag("-SEGMENT:-PARTS").editions()
[Tag(string='-SEGMENT'), Tag(string='-PARTS')]
invert_edition_tags() Tag[source]

Inverts edition tags in tag.

>>> abjad.Tag("FOO").invert_edition_tags()
Tag(string='FOO')
>>> abjad.Tag("FOO:-PARTS").invert_edition_tags()
Tag(string='FOO:+PARTS')
>>> abjad.Tag("FOO:+PARTS").invert_edition_tags()
Tag(string='FOO:-PARTS')
not_editions() list[Tag][source]

Gets not-edition tags in tag.

>>> abjad.Tag("FOO").not_editions()
[]
>>> abjad.Tag("-SEGMENT").not_editions()
[Tag(string='-SEGMENT')]
>>> abjad.Tag("-SEGMENT:FOO").not_editions()
[Tag(string='-SEGMENT')]
>>> abjad.Tag("-SEGMENT:-PARTS").not_editions()
[Tag(string='-SEGMENT'), Tag(string='-PARTS')]
only_edition() Tag | None[source]

Gets only-edition tag in tag.

>>> abjad.Tag("FOO").only_edition() is None
True
>>> abjad.Tag("+SEGMENT").only_edition()
Tag(string='+SEGMENT')
>>> abjad.Tag("+SEGMENT:FOO").only_edition()
Tag(string='+SEGMENT')
retain_shoutcase() Tag[source]

Retains shoutcase.

>>> tag = abjad.Tag("-PARTS:DEFAULT_CLEF:_apply_clef()")
>>> tag.retain_shoutcase()
Tag(string='-PARTS:DEFAULT_CLEF')
>>> tag = abjad.Tag("_debug_function()")
>>> tag.retain_shoutcase()
Tag(string='')
words() list[str][source]

Gets words.

>>> abjad.Tag("-PARTS:DEFAULT_CLEF").words()
['-PARTS', 'DEFAULT_CLEF']