File Masks - Nanook/NKit GitHub Wiki
NKit has bespoke file matching that is used across the following areas:-
- Input (
-in) source image scanning (Mask) - Dat file (
-dat) matching (Mask) - Key directory (
-keys) matching (Mask) - Extract Task (
-extract) file matching (Mask / Regex)
All file handling and matching is performed by the same code. There are four main abilities can be described as:
Wildcard Masks
- Wildcard match files using
*(any characters) and?(any single character) - e.g.*.isoor*.wbf?
Archive Masks
- Wildcard match files within archives.
//is the archive separator. - e.g.path/file.7z//*.txt
Multi File Masks
- Specify multiple masks within a directory or archive (including archive directories) - e.g.
path/*.rvz|*.wbf?or/path/*.txt|*.bin
Regular Expressions (Regex)
- Regular expressions. Performed on the full path and filename - e.g.
\.(txt|bin)$or^/GM[0-9|A-Z]+/content/
Usage
The following sections of this document give examples of the areas of the app that use file matching.
Linux and MacOS use forward slash directory separators (/), Windows traditionally uses backslash \, but will accept either, hence config files all use /.
Paths within archives and image filesystems all use / also.
Recursion / Matching files in subdirectories
When using masks throughout the app, it is important to note that directories do not support wildcards (*,?). They are for file use only. When using a wildcard in a filename NKit will recursively search subdirectories for matching candidates.
For example:
path/* # match all files within all subdirectories
path/*.iso # match all .iso files within all subdirectories
path/*.iso|*.rvz # match all .iso and rvz files within all subdirectories
path/file.iso # match that file exactly. Case insensitive
path/file.iso|file.rvz # match file.iso or file.rvz in the path directory. Case insensitive
It's a little non-standard, but adds more flexibility to file masks without having to use regular expressions (regex)
When using using regex, the expression applies to the full path. NKit will only test the expression against the current folder if recursion is not enabled
See the following sections for more information.
Input source image scanning (Mask)
When scanning for input files, recursion is controlled setting the -r parameter to y or n. Scanning archives is set using -arc with y or n. Recursion is always enabled for archives (when -arc is y). Regular expressions are not enabled here
* # all supported images - if arc is y then also Supported Archives (*r)
. # current working directory and subdirectories if -r is y (*r)
*.iso # all .iso files from the current working directory (*r)
path/*.iso # all .iso files in "path" relative to the current working directory (*r)
path\*.iso # windows only version of the above example (*r)
path/* # all supported images in the specified directory (*r)
path # same as above (*r)
Y:\path # same as above. Example with rooted Windows path (*r)
Y:\path\* # same as above (*r)
Y:\path\*.* # same as above. Example with extensions only (*r)
~/*.iso # all iso files in the user's home directory (*r)
/path/*.iso # linux rooted path, all iso files (*r)
filename.iso # specific filename.iso in the current working directory
*.wbf? # wbfs and wbf1 parts in the current working directory (*r)
*.zip # images in zip archives (*r,*a)
*.7z|*.rar # images in 7zip and rar archives (*r,*a)
path/file.7z//*.tmd # *.tmd anywhere in the archive (*r,*a)
path/file.7z//dir/title.tmd # specific file in a directory "dir" within archive (*a)
**r : includes subdirectories is `-r` is `y`*
**a : includes supported images and subdirectories in archives (including split and multi volume)*
Paths that start with ~ will point to the user's home directory (including Windows)
Dat file matching (Mask)
Dat masks point to a .dat file. The dat may be in a directory or an archive
Directory Examples:
path/file.dat # use exact specified file
path/*.dat # uses the first matched
Archive Examples:
path/file.zip//file.dat # use exact specified inside the zip
path/file.rar//*.dat # uses the first matched inside the zip
path/file.zip//arcDirectory/file.dat # use specified file with directory within archive
path/file.rar//arcDirectory/*.dat # use first matched file with directory within archive
Key directory matching (Mask)
Key masks point to a directory or archive containing .key (binary) and .dkey (ascii) files. Keys are looked up in the directory when processing images based on the source image name
Directory Examples:
path # use exact specified directory
Archive Examples:
path/file.zip # use archive
path/file.rar//arcDirectory # use directory within archive
Extract Task file matching (Mask / Regex)
Paths within archives all use the forward slash separator (/). Archive mode is not supported ('//'). Recursion is always on
Mask examples
Extract has slightly different behaviour to the rules used by Input source image scanning when using masks
* # all files including sub directories
*.txt # all .txt files within subdirectories
*.txt|*.bin # all .txt and .bin files within subdirectories
dirA/*.txt # all .txt files within a directory named dirA e.g. dir/dirA/a.txt and xxx/dirA/f.txt
/dirA/*.txt # all .txt files in the root dirA directory
/dirA/*.txt|*.bin # all .txt and .bin files in the root dirA directory
/dirA # all files in /dirA - not subdirectories
/dirA/* # all files in /dirA - and subdirectories
Regular Expression examples
Regex is the most powerful and flexible method of matching files. Regex gives you the freedom to match against the full path and filename of each item.
.* # all files including sub directories
\.txt$ # all .txt files within subdirectories
\.(txt|bin)$ # all .txt and .bin files within subdirectories
.*/dirA/[^/]*.txt$ # all .txt files within a directory named dirA e.g. dir/dirA/a.txt and xxx/dirA/f.txt
^/dir/ # all files within a root directory named /dir
/dir # all files in any directory (recursive) with a name like /dir*
^/[^/]+ # root files only
^/dir/[^/]+ # all files in root directory named dir (not recursive)
Plus anything else you can think of. See the Extract Files Cheat Sheet for more examples