Bucket Plugin
*************

The "bucket" plugin groups your files into buckets folders
representing *ranges*. This kind of organization can classify your
music by periods of time (e.g,. *1960s*, *1970s*, etc.), or divide
overwhelmingly large folders into smaller subfolders by grouping
albums or artists alphabetically (e.g. *A-F*, *G-M*, *N-Z*).

To use the "bucket" plugin, first enable it in your configuration (see
Using Plugins). The plugin provides a template function called
"%bucket" for use in path format expressions:

   paths:
       default: /%bucket{$year}/%bucket{$artist}/$albumartist-$album-$year

Then, define your ranges in the "bucket:" section of the config file:

   bucket:
       bucket_alpha: ['A-F', 'G-M', 'N-Z']
       bucket_year:  ['1980s', '1990s', '2000s']

The "bucket_year" parameter is used for all substitutions occurring on
the "$year" field, while "bucket_alpha" takes care of textual fields.

The definition of a range is somewhat loose, and multiple formats are
allowed:

* For alpha ranges: the range is defined by the lowest and highest
  (ASCII-wise) alphanumeric characters in the string you provide. For
  example, "ABCD", "A-D", "A->D", and "[AD]" are all equivalent.

* For year ranges: digits characters are extracted and the two extreme
  years define the range. For example, "1975-77", "1975,76,77" and
  "1975-1977" are equivalent. If no upper bound is given, the range is
  extended to current year (unless a later range is defined). For
  example, "1975" encompasses all years from 1975 until now.

The "%bucket" template function guesses whether to use alpha- or year-
style buckets depending on the text it receives. It can guess wrong
if, for example, an artist or album happens to begin with four digits.
Provide "alpha" as the second argument to the template to avoid this
automatic detection: for example, use "%bucket{$artist,alpha}".


Configuration
=============

To configure the plugin, make a "bucket:" section in your
configuration file. The available options are:

* **bucket_alpha**: Ranges to use for all substitutions occurring on
  textual fields. Default: none.

* **bucket_alpha_regex**: A "range: regex" mapping (one per line)
  where "range" is one of the *bucket_alpha* ranges and "value" is  a
  regex that overrides original range definition. Default: none.

* **bucket_year**: Ranges to use for all substitutions occurring on
  the "$year" field. Default: none.

* **extrapolate**: Enable this if you want to group your files into
  multiple year ranges without enumerating them all. This option will
  generate year bucket names by reproducing characteristics of
  declared buckets. Default: "no"

Here's an example:

   bucket:
      bucket_year: ['2000-05']
      extrapolate: true
      bucket_alpha: ['A - D', 'E - L', 'M - R', 'S - Z']
      bucket_alpha_regex:
        'A - D': ^[0-9a-dA-D…äÄ]

This configuration creates five-year ranges for any input year. The *A
- D* bucket now matches also all artists starting with ä or Ä and 0 to
9 and … (ellipsis). The other alpha buckets work as ranges.
