Feature: prefer-game-regex, prefer-rom-regex options

docs/roms/filtering-preferences.md

@@ -8,13 +8,13 @@ ROM filters cut down the list of games desired for a set, and any games filtered
 
 Multiple filter options can be specified at once.
 
-### Game name regex filter
+### Game name filter
 
 ```text
 --filter-regex <regex|filename>, --filter-regex-exclude <regex|filename>
 ```
 
-Only include, or exclude games based on their DAT name (or filename if not using DATs).
+Only include, or exclude games based if their DAT name (or filename if not using DATs) matches a regular expression.
 
 Regex flags can be optionally provided in the form `/<pattern>/<flags>`, for example:
 
@@ -363,7 +363,37 @@ Micro Machines Military - It's a Blast! (E) [x]
 
 The `--single` option is required for all `--prefer-*` options, otherwise there would be no effect.
 
-Multiple `--prefer-*` options can be specified at once, and they will be applied in the following order of importance (most to least).
+Multiple `--prefer-*` options can be specified at once, and they will be applied in the following order of importance (most important to least important).
+
+### Prefer game names
+
+```text
+--prefer-game-regex <regex|filename>
+```
+
+Prefer games if their DAT name (or filename if not using DATs) matches a regular expression.
+
+Regex flags can be optionally provided in the form `/<pattern>/<flags>`, for example:
+
+```text
+.*Mario.*
+/.*mario.*/i
+```
+
+### Prefer ROM filenames
+
+```text
+--prefer-rom-regex <regex|filename>
+```
+
+Prefer games if any of their ROM filenames matches a regular expression.
+
+Regex flags can be optionally provided in the form `/<pattern>/<flags>`, for example:
+
+```text
+Mario.*\\.gb$
+/mario.*\\.gb$/i
+```
 
 ### Prefer verified
 

src/modules/argumentsParser.ts

@@ -575,6 +575,22 @@ export default class ArgumentsParser {
         description: 'Output only a single game per parent (1G1R) (required for all options below, requires DATs with parent/clone information)',
         type: 'boolean',
       })
+      .option('prefer-game-regex', {
+        group: groupRomPriority,
+        description: 'Regular expression of game names to prefer',
+        type: 'string',
+        coerce: ArgumentsParser.readRegexFile,
+        requiresArg: true,
+        implies: 'single',
+      })
+      .option('prefer-rom-regex', {
+        group: groupRomPriority,
+        description: 'Regular expression of ROM filenames to prefer',
+        type: 'string',
+        coerce: ArgumentsParser.readRegexFile,
+        requiresArg: true,
+        implies: 'single',
+      })
       .option('prefer-verified', {
         group: groupRomPriority,
         description: 'Prefer verified ROM dumps over unverified',

src/modules/candidatePreferer.ts

@@ -103,7 +103,9 @@ export default class CandidatePreferer extends Module {
    */
 
   private sort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    return this.preferVerifiedSort(a, b)
+    return this.preferGameRegexSort(a, b)
+        || this.preferRomRegexSort(a, b)
+        || this.preferVerifiedSort(a, b)
         || this.preferGoodSort(a, b)
         || this.preferLanguagesSort(a, b)
         || this.preferRegionsSort(a, b)
@@ -114,18 +116,42 @@ export default class CandidatePreferer extends Module {
         || this.preferParentSort(a, b);
   }
 
+  private preferGameRegexSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
+    const gameRegex = this.options.getPreferGameRegex();
+    if (gameRegex === undefined || gameRegex.length === 0) {
+      return 0;
+    }
+
+    const aMatched = gameRegex.some((regex) => regex.test(a.getGame().getName())) ? 0 : 1;
+    const bMatched = gameRegex.some((regex) => regex.test(b.getGame().getName())) ? 0 : 1;
+    return aMatched - bMatched;
+  }
+
+  private preferRomRegexSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
+    const romRegex = this.options.getPreferRomRegex();
+    if (romRegex === undefined || romRegex.length === 0) {
+      return 0;
+    }
+
+    const aMatched = romRegex
+      .some((regex) => a.getGame().getRoms().some((rom) => regex.test(rom.getName()))) ? 0 : 1;
+    const bMatched = romRegex
+      .some((regex) => b.getGame().getRoms().some((rom) => regex.test(rom.getName()))) ? 0 : 1;
+    return aMatched - bMatched;
+  }
+
   private preferVerifiedSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    if (this.options.getPreferVerified()) {
-      return (a.getGame().isVerified() ? 0 : 1) - (b.getGame().isVerified() ? 0 : 1);
+    if (!this.options.getPreferVerified()) {
+      return 0;
     }
-    return 0;
+    return (a.getGame().isVerified() ? 0 : 1) - (b.getGame().isVerified() ? 0 : 1);
   }
 
   private preferGoodSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    if (this.options.getPreferGood()) {
-      return (b.getGame().isBad() ? 0 : 1) - (a.getGame().isBad() ? 0 : 1);
+    if (!this.options.getPreferGood()) {
+      return 0;
     }
-    return 0;
+    return (b.getGame().isBad() ? 0 : 1) - (a.getGame().isBad() ? 0 : 1);
   }
 
   private preferLanguagesSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
@@ -149,10 +175,10 @@ export default class CandidatePreferer extends Module {
   }
 
   private preferRegionsSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    if (this.options.getPreferRegions().length > 0) {
-      return this.preferRegionSortValue(a) - this.preferRegionSortValue(b);
+    if (this.options.getPreferRegions().length === 0) {
+      return 0;
     }
-    return 0;
+    return this.preferRegionSortValue(a) - this.preferRegionSortValue(b);
   }
 
   private preferRegionSortValue(releaseCandidate: ReleaseCandidate): number {
@@ -175,30 +201,30 @@ export default class CandidatePreferer extends Module {
   }
 
   private preferRetailSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    if (this.options.getPreferRetail()) {
-      return (a.getGame().isRetail() ? 0 : 1) - (b.getGame().isRetail() ? 0 : 1);
+    if (!this.options.getPreferRetail()) {
+      return 0;
     }
-    return 0;
+    return (a.getGame().isRetail() ? 0 : 1) - (b.getGame().isRetail() ? 0 : 1);
   }
 
   private preferNTSCSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    if (this.options.getPreferNTSC()) {
-      return (a.getGame().isNTSC() ? 0 : 1) - (b.getGame().isNTSC() ? 0 : 1);
+    if (!this.options.getPreferNTSC()) {
+      return 0;
     }
-    return 0;
+    return (a.getGame().isNTSC() ? 0 : 1) - (b.getGame().isNTSC() ? 0 : 1);
   }
 
   private preferPALSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    if (this.options.getPreferPAL()) {
-      return (a.getGame().isPAL() ? 0 : 1) - (b.getGame().isPAL() ? 0 : 1);
+    if (!this.options.getPreferPAL()) {
+      return 0;
     }
-    return 0;
+    return (a.getGame().isPAL() ? 0 : 1) - (b.getGame().isPAL() ? 0 : 1);
   }
 
   private preferParentSort(a: ReleaseCandidate, b: ReleaseCandidate): number {
-    if (this.options.getPreferParent()) {
-      return (a.getGame().isParent() ? 0 : 1) - (b.getGame().isParent() ? 0 : 1);
+    if (!this.options.getPreferParent()) {
+      return 0;
     }
-    return 0;
+    return (a.getGame().isParent() ? 0 : 1) - (b.getGame().isParent() ? 0 : 1);
   }
 }

src/types/options.ts

@@ -122,6 +122,8 @@ export interface OptionsProps {
   readonly onlyBad?: boolean,
 
   readonly single?: boolean,
+  readonly preferGameRegex?: string,
+  readonly preferRomRegex?: string,
   readonly preferVerified?: boolean,
   readonly preferGood?: boolean,
   readonly preferLanguage?: string[],
@@ -283,7 +285,11 @@ export default class Options implements OptionsProps {
 
   readonly onlyBad: boolean;
 
-  readonly single: boolean = false;
+  readonly single: boolean;
+
+  readonly preferGameRegex: string;
+
+  readonly preferRomRegex: string;
 
   readonly preferVerified: boolean;
 
@@ -401,6 +407,8 @@ export default class Options implements OptionsProps {
     this.onlyBad = options?.onlyBad ?? false;
 
     this.single = options?.single ?? false;
+    this.preferGameRegex = options?.preferGameRegex ?? '';
+    this.preferRomRegex = options?.preferRomRegex ?? '';
     this.preferVerified = options?.preferVerified ?? false;
     this.preferGood = options?.preferGood ?? false;
     this.preferLanguage = options?.preferLanguage ?? [];
@@ -1046,6 +1054,14 @@ export default class Options implements OptionsProps {
     return this.single;
   }
 
+  getPreferGameRegex(): RegExp[] | undefined {
+    return Options.getRegex(this.preferGameRegex);
+  }
+
+  getPreferRomRegex(): RegExp[] | undefined {
+    return Options.getRegex(this.preferRomRegex);
+  }
+
   getPreferVerified(): boolean {
     return this.preferVerified;
   }

test/modules/argumentsParser.test.ts

@@ -162,6 +162,8 @@ describe('options', () => {
     expect(options.getOnlyBad()).toEqual(false);
 
     expect(options.getSingle()).toEqual(false);
+    expect(options.getPreferGameRegex()).toBeUndefined();
+    expect(options.getPreferRomRegex()).toBeUndefined();
     expect(options.getPreferVerified()).toEqual(false);
     expect(options.getPreferGood()).toEqual(false);
     expect(options.getPreferLanguages()).toHaveLength(0);
@@ -554,6 +556,46 @@ describe('options', () => {
     expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, 'zip', '--remove-headers', 'lnx,.LNX']).canRemoveHeader(dat, '.LnX')).toEqual(true);
   });
 
+  it('should parse "prefer-game-regex"', async () => {
+    expect(() => argumentsParser.parse([...dummyCommandAndRequiredArgs, '--prefer-game-regex', '[a-z]'])).toThrow(/dependent|implication/i);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', '[a-z]']).getPreferGameRegex()?.some((regex) => regex.test('lower'))).toEqual(true);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', '[a-z]']).getPreferGameRegex()?.some((regex) => regex.test('UPPER'))).toEqual(false);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', '/[a-z]/i']).getPreferGameRegex()?.some((regex) => regex.test('UPPER'))).toEqual(true);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', '/[a-z]/i', '--prefer-game-regex', '[0-9]']).getPreferGameRegex()?.some((regex) => regex.test('UPPER'))).toEqual(false);
+
+    const tempFile = await FsPoly.mktemp(path.join(Constants.GLOBAL_TEMP_DIR, 'temp'));
+    try {
+      await util.promisify(fs.writeFile)(tempFile, '\n/[a-z]/i\r\n[0-9]\n\n');
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', tempFile]).getPreferGameRegex()?.some((regex) => regex.test(''))).toEqual(false);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', tempFile]).getPreferGameRegex()?.some((regex) => regex.test('lower'))).toEqual(true);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', tempFile]).getPreferGameRegex()?.some((regex) => regex.test('UPPER'))).toEqual(true);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', tempFile]).getPreferGameRegex()?.some((regex) => regex.test('007'))).toEqual(true);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-game-regex', tempFile]).getPreferGameRegex()?.some((regex) => regex.test('@!#?@!'))).toEqual(false);
+    } finally {
+      await FsPoly.rm(tempFile);
+    }
+  });
+
+  it('should parse "prefer-rom-regex"', async () => {
+    expect(() => argumentsParser.parse([...dummyCommandAndRequiredArgs, '--prefer-rom-regex', '[a-z]'])).toThrow(/dependent|implication/i);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', '[a-z]']).getPreferRomRegex()?.some((regex) => regex.test('lower'))).toEqual(true);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', '[a-z]']).getPreferRomRegex()?.some((regex) => regex.test('UPPER'))).toEqual(false);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', '/[a-z]/i']).getPreferRomRegex()?.some((regex) => regex.test('UPPER'))).toEqual(true);
+    expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', '/[a-z]/i', '--prefer-rom-regex', '[0-9]']).getPreferRomRegex()?.some((regex) => regex.test('UPPER'))).toEqual(false);
+
+    const tempFile = await FsPoly.mktemp(path.join(Constants.GLOBAL_TEMP_DIR, 'temp'));
+    try {
+      await util.promisify(fs.writeFile)(tempFile, '\n/[a-z]/i\r\n[0-9]\n\n');
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', tempFile]).getPreferRomRegex()?.some((regex) => regex.test(''))).toEqual(false);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', tempFile]).getPreferRomRegex()?.some((regex) => regex.test('lower'))).toEqual(true);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', tempFile]).getPreferRomRegex()?.some((regex) => regex.test('UPPER'))).toEqual(true);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', tempFile]).getPreferRomRegex()?.some((regex) => regex.test('007'))).toEqual(true);
+      expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--single', '--prefer-rom-regex', tempFile]).getPreferRomRegex()?.some((regex) => regex.test('@!#?@!'))).toEqual(false);
+    } finally {
+      await FsPoly.rm(tempFile);
+    }
+  });
+
   it('should parse "prefer-verified"', () => {
     expect(() => argumentsParser.parse([...dummyCommandAndRequiredArgs, '--prefer-verified'])).toThrow(/dependent|implication/i);
     expect(argumentsParser.parse([...dummyCommandAndRequiredArgs, '--prefer-verified', '--single']).getPreferVerified()).toEqual(true);