<commit_before># naklo

... is batch music tagger. You use it by specifying tags for a given
album in one or more files and applying them in one shot with a naklo
invocation. Through `mutagen`, naklo supports tagging FLAC, MP3 (to a
limited extent), and Opus files.

> **NOTE**: This project is free software, a personal project by j39m.
> However, Google LLC owns the copyright on commits
> `d7144ae933c48733abf818308e8153786b4d23a6` and newer. This does not
> impact your ability to use and to hack at this free software; I
> provide this notice only for attribution purposes.

## Control file format

A naklo control file contains up to two types of blocks. In general,
the format goes:

```
# A map of spans to tags to values. Useful when the tag-value pairs are
# strongly grouped together in the same span.
#
# Note that the leaf node need not be a single string value; it can be a
# list, enabling you to lay down several values at once for a given tag
# in a given span.
classic-tag-block:
    <span>:
        <tag>: <value>
        <tag>:
            - <value>
            - <value>
    <span>:
        ...

# A map of tags to spans to values. Useful when tag values are not
# strongly grouped together in the same span.
#
# As with the classic-tag-block, note that the leaf node need not be a
# string value.
inverted-tag-block:
    <tag>:
        <span>: <value>
        <span>:
            - <value>
            - <value>
    <tag>:
        ...
```

You can find further reading

1.  in [the controls module](libnaklo3/controls.pyx) and
1.  in [the reference-examples/ directory](reference-examples/).
<commit_msg>README.md: update with caveats<commit_after># naklo

... is batch music tagger. You use it by specifying tags for a given
album in one or more files and applying them in one shot with a naklo
invocation. Through `mutagen`, naklo supports tagging FLAC, MP3 (to a
limited extent), and Opus files.

> **NOTE**: This project is free software, a personal project by j39m.
> However, Google LLC owns the copyright on commits
> `d7144ae933c48733abf818308e8153786b4d23a6` and newer. This does not
> impact your ability to use and to hack at this free software; I
> provide this notice only for attribution purposes.

## Control files: format

I encourage the gentle reader to browse
[the reference-examples/ directory](reference-examples/) to get a feel
for how control files work; the formal definition is a little stuffy.

A naklo control file contains up to two types of blocks. In general,
the format goes:

```
# A map of spans to tags to values. Useful when the tag-value pairs are
# strongly grouped together in the same span.
#
# Note that the leaf node need not be a single string value; it can be a
# list, enabling you to lay down several values at once for a given tag
# in a given span.
classic-tag-block:
    <span>:
        <tag>: <value>
        <tag>:
            - <value>
            - <value>
    <span>:
        ...

# A map of tags to spans to values. Useful when tag values are not
# strongly grouped together in the same span.
#
# As with the classic-tag-block, note that the leaf node need not be a
# string value.
inverted-tag-block:
    <tag>:
        <span>: <value>
        <span>:
            - <value>
            - <value>
    <tag>:
        ...
```

A *span* is a numerical specification consisting of any of

*   a single numerical token,
*   a set of tracks denoted by `<lower>-<upper>` (inclusive), or
*   the wildcard token, denoted by a literal star `*`.

## Control files: known caveats

1.  Wildcard spans (`*`) must be quoted, lest the YAML fail to parse.
1.  While most leaf values need not be enclosed in quotes, you will need
    to do something about leaf values containing colon characters (`:`).
    If quote enclosure is not feasible, I prefer to use YAML's `>-`
    notation.

{'fraction_non_alphanumeric': 0.083008066614624, 'fraction_numerical': 0.01795472287275566, 'mean_word_length': 2.9466119096509242, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 44, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3414573', 'n_tokens_mistral': 1174, 'n_tokens_neox': 1105, 'n_words': 559}