feat(modifications): Implement "when" conditions

[FoxxMD]

• Enable using multiple "when" conditions of regex matching to determine if a hook or individual part-rules should run
  • Use updated regex buddy lib to enable caching parsed rule regexes for performance
• Refactor hooks so they can be an array of parts rather than a single object
  • Enables a user to have multiple if-then scenarios per hook
  • Refactor hook parts so they can be parsed from external files

[github-actions]

📦 A new release has been made for this pull request.

To play around with this PR, pull an image:

• foxxmd/multi-scrobbler:pr-186

Images are available for x86_64 and ARM64.

Latest commit: 9b808c8

[FoxxMD]

when (if-then logic)

Top-level hooks and individual rules now support a when key for testing if they should be run.

The when key is similar to a normal modification except:

• the keys accept a single string instead of an array
• the when key data is an array instead of a single object

All parts of an individual when clause must test true to "pass" but if any when clauses pass the hook/rule is processed. Example when data:

{
  "when": [
    {
      "artist": "Elephant Gym", // both of these must match the Play object (AND)
      "album": "Dreams" // both of these must match the Play object (AND)
    },
    // OR
    {
      "title": "/(Remastered)$/", // both of these must match the Play object (AND)
      "album": "Various Artists" // both of these must match the Play object (AND)
    }
  ]
}

More succinctly:

• All parts (artist album title) of a when are AND conditions
• All part-objects in the when array are OR conditions

(I need to come up with better terminology)

Example for top-level hook:

{
  // IF the artist is Elephant Gym 
  // THEN Run preCompare hook ELSE skip this hook
  //
  //    Run search-replace on album
  //    Run regex title remove
  "sourceDefaults": {
    "playTransform": {
      "preCompare": {
        "when": [
          {
            "artist": "/Elephant Gym/"
          }
        ],
        "album": [
          {
            "search": "Dreams",
            "replace": "夢境"
          }
        ],
        "title": ["/\s\-\s滾石40\s滾石撞樂隊\s40團拚經典(.+)$/i"]
      },
    }
  }
}

Example of individual rules:

{
  // Always run preCompare
  //
  //   On search-replace in title...
  //     IF artist matches "Elephant Gym"
  //     THEN Run regex search-replace ELSE skip this rule
  //
  //   Run live|remastered regex remove
  "sourceDefaults": {
    "playTransform": {
      "preCompare": {
        "title": [
          {
            "search": "/\\s\\-\\s滾石40\\s滾石撞樂隊\\s40團拚經典(.+)$/i",
            "replace": "",
            "when": [
              {
                "artist": "/Elephant Gym/"
              }
            ]
          },
          "/(\\s\\-\\s|\\s)(feat\\.(.+)|live|remastered(.+))$/i"
        ],
      }
    }
  }
}

Top-level hook array

Top-level hooks can now also be an array of hooks. This makes creating multiple scenarios for top-level when-gated hooks easier. All hooks in the array will be run (assuming their when's pass, if they exist) and their input will be the Play object output of the previous hook in the array.

{
  "sourceDefaults": {
    "playTransform": {
      "preCompare": [
        {
          "title": [
            {
              "search": "something",
              "replace": "else unique"
            }
          ]
        },
        {
          "title": [
            {
              "search": "else unique",
              "replace": "very demure"
            }
          ]
        },
      ]
    }
  }
}

Example using the above two preCompare hooks:

• Input => Some Artist - A Song About Something
• First Hook => Some Artist - A Song About else unique
• Second Hook => Some Artist - A Song About very demure

Logging

MS can log the output of hook transformations if/when they occur. In the playTransform object use log:

• "log": true => Output original play + final transformed output of last hook in the array
• "log": "all" => Output original play + final transformed output of each hook in the array

{
  "name": "myThing",
  "data": {/*...*/},
  "options": {
    "playTransform": {
      "preCompare": {/*...*/},
      "log": true
    }
  }
}