Alpha prototype of foo_discogs 2.0.

Warning: this version is not complete or thoroughly tested. It is not meant to replace the existing public version of foo_discogs. This is a preview release so that "hardcore taggers" who are interested can provide feedback early on and get their request included before the public version.

Changes:
- New "edit tag mappings" dialog.
- Tag mappings are now defined by tag formatting strings that can be configured by the user. This allows you to add new tags and gives very fine control over how the tag values are written.
- Writing tags is now async.
- Network traffic can now occur in the "write tags" phase, when necessary to load data required by a tag formatting string. (In the past, all network loading was done in a separate step, but that is no longer possible.)
- Better error reporting.
- New fields such as series, barcode, master release year, etc have been added.
- Updating tags made more reliable, but not backwards compatible.
- Compilation checkmark has (tentatively) been removed. (I'd like to replace it with a better detection of compilations including a config option if necessary).
- Keyboard controls (Del, Cntl+Up, Cntl+Down) added to release dialog track lists.


*** New "edit tag mappings" dialog. ***

The new tag formatting strings are defined via this dialog.

Note: the default tags defined may changed. They are currently modeled after the tags available in traditional versions of foo_discogs.


*** Tag formatting strings ***

Tag formatting strings are an extension of foobar2000 titleformatting strings that support multiple-values. At the core of these strings are variables which contain information from Discogs. These variables are transformed via functions to form the final result(s) to be written to a tag. The final result can either be an array (for a multiple-value tag), or a single string value.

Some variables exposed from the Discogs database can have multiple values. For example, a release can have multiple artist names. These variables should be written as %<VARIABLE>% to use them as an array. If the triangular braces are omitted, they will be joined into a string separated by commas, giving the same result as $join(%<VARIABLE>%).

Using built-in titleformatting functions on arrays is not supported. It will likely result in corrupt strings or unexpected behavior because the built-in functions only work on strings. foo_discogs has to re-define any functions that we want to work on arrays (with a "multi_" prefix before their name). Only a couple have been done so far, but others will be added.


*** Tag formatting variables ***

The data variables at the core of tag formatting strings come from 5 roots:
RELEASE_*
DISC_*
TRACK_* (matched track from the Discogs tracklist)
ARTISTS_* (artist(s) for the track, if applicable, otherwise for the artist(s) for the release)
MASTER_RELEASE_* - (if applicable)

Each root exposes a list of fields that can be used.

RELEASE_:
ID
TITLE
COUNTRY
DATE
DATE_RAW
YEAR
MONTH
DAY
NOTES
BARCODE
WEIGHT
TOTAL_DISCS
TOTAL_TRACKS
DISCOGS_USERS_HAVE
DISCOGS_USERS_WANT
DISCOGS_AVG_RATING
DISCOGS_RATING_VOTES
DISCOGS_STATUS
DISCOGS_DATA_QUALITY
DISCOGS_SUBMITTED_BY
DISCOGS_TRACKLIST_COUNT
DISCOGS_TOTAL_DISCS
<GENRES>
<STYLES>
<VIDEOS>

DISC_:
NUMBER
TOTAL_TRACKS

TRACK_:
NUMBER
DISC_TRACK_NUMBER  (similar to NUMBER, but starts at 1 for each disc)
DISCOGS_TRACK_NUMBER  (original track position in Discogs tracklist. not necessarily a number)
DISCOGS_TRACKLIST_INDEX  (used internally for update tags)
TITLE
HEADING
INDEXTRACK_TITLE
SUBTRACK_TITLE
DISCOGS_DURATION_RAW
DISCOGS_DURATION_SECONDS

ARTIST_:  (ARTISTS_ wraps these an array)
ID
NAME
NAME_VARIATION  (name variation used in this track/release)
JOIN  ("join" field for multiple artists)
PROFILE
REAL_NAME
<URLS>
<ALIASES>
<ALL_NAME_VARIATIONS>
<MEMBERS>

MASTER_RELEASE_:
ID
TITLE
YEAR
MAIN_RELEASE_ID
MAIN_RELEASE_URL
MAIN_RELEASE_API_URL
DISCOGS_DATA_QUALITY
DISCOGS_TRACKLIST_COUNT  (used internally for update tags)
<GENRES>
<STYLES>
<VIDEOS>

Each of the 5 roots, excluding ARTISTS_*, also expose branches. Branches reference another object or, almost always, array of objects. (Therefore, branches usually return an array and sometimes a multi-dimensional array.) Here are the branches available:

RELEASE_:
<TRACKS_*>
<DISCS_*>
<ARTISTS_*>
<LABELS_*>
<SERIES_*>
<FORMATS_*>
<CREDITS_*>

DISC_:
<TRACKS_*>
<FORMAT_*>

TRACK_:
<ARTISTS_*>
<CREDITS_*>
<HIDDEN_TRACKS_*>

MASTER_RELEASE_:
<TRACKS_*>
<DISCS_*>
<ARTISTS_*>

Finally, here are the fields exposed from some of the objects that aren't root objects, but only available via branches:

LABEL_:
ID
NAME
CATALOG_NUMBER

SERIES_:
ID
NAME
CATALOG_NUMBER
NUMBER
API_URL

FORMAT_:
QUANTITY
NAME
<DESCRIPTIONS>

CREDIT:
ROLES_RAW
<ROLES>
<ARTISTS_*>


These field names aren't carved in stone and more may be added later. Most of this closely follows the information exposed via the Discogs API.


*** Tag formatting functions ***

The following custom functions defined and available for tag formatting strings:

$join(A) - Joins array A with depth N with ", " separator. Returns an array of depth N-1 where the highest dimension is joined into a string, or a string if N=1.
$join(A,B) - Joins array A of depth N with B array or string separator(s). If B is an array, it must have the same depth as A, but can be 1 shorter in width in its highest dimension. Returns an array of depth N-1 where the highest dimension is joined into a string, or a string if N=1.
$zip(A,B,...) - Zips arrays array A with any number of other arrays or strings. Other arrays must have the same dimensions as A. Returns an array with the same dimensions as A.
$split(s,x) - Splits string s into an array using delimiter x. Returns a 1-dimensional array.
$unique(A) - Filters non-unique values out of array A in the first dimension. Returns an array of the same depth as A, but possibly shorter in the first dimension.
//$append(A,B,...) - Appends any number of elements to array A with depth N. Elements must have depth N-1, where depth 0 is a string. Returns array of depth N, but wider than A in the first dimension.
//$extend(A,B,...) - Appends contents of any number of other arrays to array A with depth N. Other arrays must also have depth N. Returns array of depth N, but wider than A in the first dimension.
$multi_first(A) - Where A is an array with depth N, returns first item from A in the first dimension (depth N-1).
$multi_last(A) - Where A is an array with depth N, returns last item from A in the first dimension(depth N-1).
$multi_get(A,N) - Where A is an array with depth N, returns Nth item from A in the first dimension(depth N-1).
//$multi_length(A) - Where A is an array with depth N, returns an array of depth N-1 composed of the widths of elements in the last dimension. For a 1-dimensional array, this is a simple string with the length.
$multi_create(X,N) - Returns a 1-dimensional array composed of value X repeated N times.
$multi_replace(A,B,C) - Replaces all occurrences of B in A with C, where each of B and C are either a string or an array of the same dimensions as A. Returns an array of the same dimensions as A.
$multi_strcmp(A,B) - Compares B with A, where B is either a string or an array of the same dimensions as A. Returns a boolean array of the same dimensions as A.
$multi_strstr(A,B) - Finds B in A, where B is either a string or an array of the same dimensions as A. Returns a boolean array of the same dimensions as A.
$multi_trim(A) - Trims whitespace from elements in array A. Returns an array of the same dimensions as A.
$multi_pad(A,B) - Pads elements in array A with B on both sides, where B is either a string or an array of the same dimensions as A. Returns an array of the same dimensions as A.
$multi_any(A) - Where A is an array with depth N, returns a boolean array with depth N-1 indicating whether "any" values exist in the top dimension of A.
$multi_if(A,B,C) - Returns an array of the same dimensions as A, composed of values B where A was true and C where A was false.
$multi_or(A, B) - Returns a boolean array of the same dimensions as A, where either A or B is true.
$multi_not(A) - Returns a boolean array of the same dimensions as A, with value false where A was true and vice versa.

Note: You will get an error popup if these functions are used incorrectly (or, perhaps, if you discover a bug).


*** Special default tags ***

Some of the default tags are greyed out and can't be disabled or edited. These are tags that have a special purpose within foo_discogs. If these tags are disabled or missing, some extra features provided by foo_discogs may not work.

DISCOGS_RELEASE_ID - Used to streamline the "find release" dialog when writing tags. Used to update tags. Used to open the release page in browser.
DISCOGS_MASTER_RELEASE_ID - Used to open the master release page in browser.
DISCOGS_ARTIST_ID - Used to update artist art. Used to open the artist page in browser.
DISCOGS_LABEL_ID - Used to open the label page in browser.
DISCOGS_TRACKLIST_INDEX - New! Used when updating tags to match tracks to the Discogs release with greater accuracy.