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']