*******************************************************************************
*******ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ Selecting files with --files=rulesÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ*******
*******************************************************************************
Some wit commands (DUMP, ILIST, EXTRACT) will operate with the files contained
by ISO images. The option --files=rule_list defines which files are processed.
Option syntax:
ÂÂÂÂ-FÂÂÂÂÂÂrule_list
ÂÂÂÂ--files rule_list
ÂÂÂÂ--files=rule_list
ÂÂÂÂÂÂÂÂ
'rule_list' is a semicolon separated list of rules. Each rules begin with a
plus sign fpr a allow rule or a minus sign for a deny rule. The options can
be used multiple times to define more and more rules.
Rule Syntax:
ÂÂÂÂrule_listÂÂ:= rule [ ';' rule_list ]
ÂÂÂÂruleÂÂÂÂÂÂ := skip_rule | std_rule | macro_call
ÂÂÂÂskip_ruleÂÂ:= number prefix pattern
ÂÂÂÂstd_ruleÂÂ := prefix pattern
ÂÂÂÂmacro_call := ':' pattern
ÂÂÂÂprefixÂÂÂÂ := '+' | '-'
ÂÂÂÂpatternÂÂÂÂ:= [char]...
ÂÂÂÂnumberÂÂÂÂ := '1'..'9' ['0'..'9']...
'pattern' is a file pattern including wildcards. The design is like 'rsync'.
The rule patterns are compared with the source path inside the ISO. A source
path looks like "DIRECTORY/FILE.EXT" without the partition prefix (example:
sys/boot.bin). The '/' at the beginning of the pattern is like a '^' in regular
expressions. If the pattern starts with a '/' then it is matched against the
beginning of the source path. Otherwise it is matched against the end of the
source path. To force matching against the end use a '$' as last character in
the pattern.
--------------------------------------------------------------------------------
This is a short description of the special characters:
ÂÂ /ÂÂ: At the beginning of pattern
ÂÂÂÂÂÂÂÂ => Match against the beginning of the source path
ÂÂ $ÂÂ: At the end of pattern
ÂÂÂÂÂÂÂÂ => Match against the end of the source path. This is the default if
ÂÂÂÂÂÂÂÂÂÂÂÂno '/' is at the beginning or the end of the pattern.
ÂÂ *ÂÂ: Match any number (zero or more) of characters but not '/'.
ÂÂ ** : Match any number (zero or more) of characters includingÂÂ'/'.
ÂÂ
ÂÂ #ÂÂ: Match any number (one or more) of digit ('0'..'9').
ÂÂ ?ÂÂ: match exact 1 character but not '/'.
ÂÂ' ' : (SPACE) Match space and any control characters (ASCII 1..32).
[..] : Match 1 character of the list within the brackets. The list is
ÂÂÂÂÂÂÂÂanalyzed in the following way:
ÂÂÂÂÂÂÂÂ - If the first character is a '^' then characters not in the
ÂÂÂÂÂÂÂÂÂÂ list are matched.
ÂÂÂÂÂÂÂÂ - If the next character (behind optional '^') is a '+' or a '*'
ÂÂÂÂÂÂÂÂÂÂ then it is matched against the maximum possible characters.
ÂÂÂÂÂÂÂÂÂÂ A '+' means that at least one character must match.
ÂÂÂÂÂÂÂÂ - The list contains single characters 'c' or ranges 'x-y'.
ÂÂÂÂÂÂÂÂÂÂ To use a ']' it must be the first character. To use a '-' it
ÂÂÂÂÂÂÂÂÂÂ must be the first or last character.
{..} : This is a comma separated list of alternatives. It matches if
ÂÂÂÂÂÂÂÂat least one alternative match. {..} can be used recursively.
ÂÂ \c : Any character preceded by '\' looses its special meaning and
ÂÂÂÂÂÂÂÂis handled as normal character.
Pattern examples:
ÂÂÂÂÂÂ.wad : all files ending with '.wad'
ÂÂÂÂÂÂ*/ÂÂ : all directories but no files
ÂÂÂÂdir/ÂÂ : all directories which name ends with 'dir'.
ÂÂÂÂdir/*ÂÂ: all files in directories which name ends with 'dir'.
ÂÂÂÂdir/** : all files in (sub-)directories which name ends with 'dir'.
**/dir/** : all files in (sub-)directories which name is 'dir'.
/dir/
/dir/*
/dir/**ÂÂ : All files in the first level directory 'dir'
ÂÂÂÂÂÂÂÂÂÂÂÂ including sub directories.
/dir/*$ÂÂ : All files in in the first level directory 'dir'
ÂÂÂÂÂÂÂÂÂÂÂÂ excluding sub directories.
/dir/*.wad
ÂÂÂÂÂÂÂÂÂÂ : All '*.wad' files in the first level directory 'dir' excluding
ÂÂÂÂÂÂÂÂÂÂÂÂ sub directories and all files in directories named *.wad.
ÂÂÂÂÂÂÂÂÂÂÂÂ
/DATA/dir/**.wad
ÂÂÂÂÂÂÂÂÂÂ : All '*.wad' files in in the first level directory 'dir'
ÂÂÂÂÂÂÂÂÂÂÂÂ including sub directories.
--------------------------------------------------------------------------------
Processing the Rule list:
Each option --filter= define a list of rules. Each file is checked against the
every rule on the list until a pattern matches the file name. If the rule
match the file name the rule prefix decide what to do. A '+' means include
the file and a '-' means exclude the file. A ':' (and the obsolete '=') calls
an internal macro to define a set of rules.
If a '+' or '-' is preceded by a decimal number the rule has a special
meaning. If '+' and the pattern does match then the following NUMBER rules are
skipped. If '-' and the pattern does not match then the following NUMBER rules
are skipped.
If no rule match the prefix, the last rule in the list decide what to do.
If the last rule is a '+' rule than the file is excluded (opposite handling).
If the last rule is a '-' rule than the file is included.
A empty list means: include all files.
--------------------------------------------------------------------------------
Rule macros:
Rule macros are predefined rules to make live easier. Some of them exists
as positive (without prefix 'no') and as negative (with prefix 'no') rule.
:baseÂÂÂÂÂÂÂÂ:= +/*$
:nobaseÂÂÂÂ:= -/*$
ÂÂÂÂAllow or deny files of the base directory
ÂÂÂÂ(ticket.bin, tmd.bin, cert.bin, h3.bin),
:discÂÂÂÂÂÂÂÂ:= +/disc/
:nodiscÂÂÂÂ:= -/disc/
ÂÂÂÂAllow or deny files from the 'disc' directory.
ÂÂÂÂ(disc/header.bin, disc/region.bin)
:sysÂÂÂÂÂÂÂÂ:= +/sys/
:nosysÂÂÂÂÂÂÂÂ:= -/sys/
ÂÂÂÂAllow or deny files from the 'sys' directory.
ÂÂÂÂ(sys/boot.bin, sys/bi2.bin, sys/apploader.img, sys/main.dol, sys/fst.bin)
:filesÂÂÂÂÂÂÂÂ:= +/files/
:nofilesÂÂÂÂ:= -/files/
ÂÂÂÂAllow or deny files from the 'file' directory.
ÂÂÂÂThis are the real files of the ISO image.
:witÂÂÂÂÂÂÂÂ:= 2+/h3.bin; 1+/sys/fst.bin; +
:wwtÂÂÂÂÂÂÂÂ:= :wit
ÂÂÂÂAllow files that are used from wit and wwt to compose an ISO image.
:composeÂÂÂÂ:= 3+/disc/;2+/h3.bin;1+/sys/fst.bin;+
ÂÂÂÂAllow files that are needed from wit and wwt to compose an ISO image. This
ÂÂÂÂis like ':wit' expect that the optional files '/disc/*' are not included.
:sneekÂÂÂÂÂÂÂÂ:= 2+/h3.bin; 1+/disc/; +
ÂÂÂÂAllow files that SNEEK needs.
--------------------------------------------------------------------------------
Examples:
ÂÂ--filter +
ÂÂÂÂinclude all files
ÂÂ--filter -
ÂÂÂÂexclude all files
ÂÂ--filter +.wad
ÂÂÂÂinclude all '*.wad' files
ÂÂ--filter -.wad
ÂÂÂÂexclude all '*.wad' files
ÂÂ--filter '+.wad;-d'
ÂÂÂÂexclude all '*d' files but not '*.wad'
ÂÂ--filter '+.h3.bin;:sneek'
ÂÂÂÂsuppress for SNEEK unneeded files, but add 'h3.bin'.
