SELECTORS


These commands determine which parts of the filename will be affected by the action commands. The selectors are listed below in the order that they are evaluated which is fixed for the time being.

COMMENT
PREFIX
MAIN
SUFFIX
WORD
MATCH
LEFT
MID
RIGHT


Selector options:

These are additional options that affect the selection process.

INVERTSEL
COMPSEP
PREFIRST

COMMENT (CO) :


This selector doesn't select characters in the filename but instead forces the comment of the file or directory to be selected for modification. Any other selectors that are given after it will also target the comment.
COMMENT can't be used in renumbering to renumber comments, it can however be used in numbering to add numbers to comments.
If multiple actions are to be performed to a comment then COMMENT like other selectors should be given repeatedly before those actions.

Examples:

> SRename pic.iff CO UP : Make the comment of "pic.iff" uppercase.
output:
Comment of "pic.iff" changed from "created with lightwave" to "CREATED WITH LIGHTWAVE"

> SRename #? CO DL : Delete all the filename comments in the current dir.

> SRename #? CO MT "MAME" TO "M.A.M.E." : Replace all occurences of "MAME" in the comments of the filenames with "M.A.M.E."

> SRename #? CO NS *01* AT -1 : Place an incremental number at the end of each comment starting at 1.

> SRename #? CO LW CO L 1 UP : Makes comments lowercase and the first character uppercase. Notice that COMMENT (CO) has to be given again after the first action (LW) for the first character to be made uppercase.

PREFIX (PR) :

Secondary arguments:

ADD (AD)

Selects the prefix component for modification.




MAIN (MA) :

Secondary arguments:

ADD (AD)

Selects the main component for modification.




SUFFIX (SU) :

Secondary arguments:

ADD (AD)

Selects the suffix component for modification.

The above selectors can be given each one alone or all together.

The default component separator is a period (.) and can be changed with the COMPSEP (CP) option which accepts a single character as a parameter.
When each filename is scanned for prefix/main/suffix components the default behaviour is to first fill the main component then the suffix and finally the prefix. So that filenames with 2 components are taken to have a main and a suffix component, but no prefix. This can be overriden with the PREFIRST (PF) option that forces the prefix to be filled before the suffix in 2-component filenames. 
The COMPSEP and PREFIRST selector options should be placed before the selectors of each action.
New prefix, main or suffix components are not created by default if they don't already exist but this can be overridden with the ADD secondary argument.

Here are some examples on how different filenames fill the PREFIX, MAIN, SUFFIX components:

Examples:

> SRename archive_tar_gz CP _ MA SU UP : Redefines the component separator to '_' and makes the main and suffix components uppercase.
output:
"archive_tar_gz" renamed as "archive_TAR_GZ"

> SRename #? SU TO ilbm : Replaces the suffix of every filename with "ilbm", if they have a suffix.

> SRename backup.lzx MA UP : Makes the main component uppercase.
output:
"backup.lzx" renamed as "BACKUP.lzx"

> SRename mod.techno PF PR UP : Forces the prefix to be filled before the suffix and makes the prefix uppercase.
output:
"mod.techno" renamed as "MOD.techno"

> SRename TheLastBallad.s3m SU UP : Makes the suffix uppercase.
output:
"TheLastBallad.s3m" renamed as "TheLastBallad.S3M"

> SRename SoundSample SU TO 8SVX
output:
"SoundSample" not changed
Here an attempt is made to modify a suffix that doesn't exist, which fails because ADD is not given.

> SRename SoundSample SU AD TO 8SVX
output:
"SoundSample" renamed as "SoundSample.8SVX"
Now a new suffix is created as ADD was given.

WORD (WD) <starting word number>,[number of words to select] :

Secondary arguments:

INCLSEP (IS) <value>
WORDSEP (WS) <char(s)>

Selects a word in the filename. A word is surrounded by spaces by default unless the word separator is changed with the WORDSEP secondary argument. Words are selected from the start of the filename unless the starting word number is negative. For example WORD -1 selects the last word of the filename.
If the second parameter is also given then consecutive words can be selected. If this second parameter is -1 then all the words in the filename will be selected.

Examples:

> SRename "screen grab of game" WD 1 UP
output:
"screen grab of game" renamed as "SCREEN grab of game"
The first word is made uppercase.

> SRename Letter_to_john WD 3 WS _ UP
output:
"Letter_to_john" renamed as "Letter_to_JOHN"
The third word is made uppercase and the word separator is redefined to '_'.

> SRename "Letter to john" WD -1 UP
output:
"Letter to john" renamed as "Letter to JOHN"
The last word is made uppercase.

> SRename "screen grab of game" WD 1,2 UP
output:
"screen grab of game" renamed as "SCREEN GRAB of game"
Two words are made uppercase starting from the first.

> SRename Data:Pics/ MA WD 1 UP : Makes uppercase the first word in the main part of the filename.

> SRename Data:Pics/ MA WD 1 L 1 UP : Makes uppercase the first character of the first word in the main part of the filename.


If the INCLSEP secondary argument is given then the separating characters that are left or right of the word to select are also selected. The parameter value can be 1 or 2 and determines what separating characters should be included.
If the value is 1 the separating characters of only one side of the word will be included: the right side. If there aren't any on the right side then the characters on the left side will be included.
If the value is 2 the separating characters on both sides will be included if they exist.
If INCLSEP is not used the WORD selector will select the exact word that is told to and in case that word is to be deleted the spaces next to that word will remain.

For example:

> SRename "Picture of a ship" WD 3 DL
output:
"Picture of a ship" renamed as "Picture of  ship"

As you see there are two spaces between "of" and "ship" instead of one that would be normal.
If you use INCLSEP 1 you will get:

> SRename "Bin:Picture of a ship" WD 3 IS 1 DL
output:
"Picture of a ship" renamed as "Picture of ship"

Now 'a ' (including the right space) is deleted instead of 'a'.

If you use INCLSEP 2 you will get:

> SRename "Picture of a ship" WD 3 IS 2 DL
output:
"Picture of a ship" renamed as "Picture ofship"

Now ' a ' (including left and right spaces) is deleted.

MATCH (MT) <string> :

Secondary arguments:

DO <value>
SKIP (SK) <value>
REVMATCH (RM)
CASESENS (CS)

Selects the characters that match the given string, characters, character codes or pattern. Some of MATCH's features are controlled by giving with the string to match some special characters or small keywords. These characters and keywords are distinguished from normal characters to match by enclosing them in slashes (/).

These are:

 ':' : Activates single character mode. Must be placed at the beginning of the match arguments. 

 '%' : Activates character code mode. Must be placed at the beginning of the match arguments.

The following are allowed only in string mode (the default mode):

 '|' : Indicates that the string to match must be at the start or end of the filename segment that is searched for matches, depending on whether '|' is on the start or end of the string to match.

 '[' : Selection start designator. Indicates the start of characters to select in the match string. It also substitutes the AFTER match option of previous versions.

 ']' : Selection end designator. Indicates the end of characters to select in the match string. It also substitutes the BEFORE match option of previous versions.

 '?' : Wildcard character that matches any character. Can be followed by a number to indicate how many characters to match.

 'DEC' : Matches any decimal characters up to 10 digits long. Can be followed by a number to indicate how many characters to match.

 'HEX' : Matches any hexadecimal characters up to 8 digits long. Can be followed by a number to indicate how many characters to match.

There are some limitations: For now you can't use the '?', 'DEC' and 'HEX' keywords together in a match string.
Also you can't use any of them more than once in a match string.
Also only one set of the '[' and ']' selection designators can be given for each match string.

Each one of the above characters and keywords doesn't have to be enclosed in slashes on their own. It is possible and much easier to use for example /HEX2[/ instead of /HEX2//[/.

  
MATCH can work in 3 modes: string mode (default), single character mode and character code mode. In string mode it simply matches the given string(s) or pattern(s). In single character mode it matches each character in the given string separately, and in character code mode it matches characters according to their ASCII codes.

Multiple match strings can be given in string match mode and they should be separated by colons (:).
In character code mode different codes should be separated by commas (,).

In character code mode you can also select character ranges by supplying two characters or their ASCII codes which should be separated by a minus sign '-', or just the starting or ending character or ASCII code.
Note that if you want to specify a range that starts lower than 10 whatever reason should you have to do that, then you must supply a leading zero before the number so that it won't be a single character, as single characters supply
their ASCII value even if they are numeric.
Those 3 modes can't be used together in the same MATCH selector.

Examples:

MATCH text:doc:picture:sample : String mode, matches every occurence of 'text', 'doc', 'picture', and 'sample'.

MATCH /:/[]()<>#! : Single character mode, matches every []()<>#! character.

MATCH /%/65-68,70,Q-S,W- : Character code mode, matches characters 'A' to 'D', 'F', 'Q' to 'S' and 'W' and every other character after it.


Examples of string mode matches:

MATCH abcd/|/ : matches the string "abcd" that must be at the end of the filename part that is searched.

MATCH /|/abcd : as above but the string must be at the start.

MATCH ab/[/cd/]/ef : matches the string "abcdef" but only the characters "cd" are selected for modification.

MATCH abcd/[/ : selects for modification the characters after "abcd".

MATCH /]/abcd : selects for modification the characters before "abcd".

MATCH /]/abcd/[/ " selects for modification the characters before and after "abcd".

MATCH /?/ : matches everything.

MATCH /?5/ : matches the first 5 characters it finds.

MATCH /?5|/ : matches the first 5 characters it finds from the end.

MATCH abcd/?/ : matches any string that begins with "abcd".

MATCH /?/abcd : matches any string that ends with "abcd".

MATCH abcd/?3/ : matches any string that starts with "abcd" and is followed by another any 3 characters.

MATCH /dec/ : matches any decimal number of up to 10 digits.

MATCH /dec3/ : matches any 3-digit decimal number.

MATCH +/dec3/ : matches any 3-digit decimal number that starts with '+'.

MATCH +/dec3/d : matches any 3-digit decimal number that starts with '+' and ends with 'd'.

MATCH /hex/ : matches any hexadecimal number of up to 8 digits.

MATCH /hex2/ : matches any hexadecimal byte number.

MATCH %/hex2/ : matches any hexadecimal byte number that starts with '%'.

MATCH %/hex4/ : matches any hexadecimal word number that starts with '%'.

MATCH %/hex8/ : matches any hexadecimal long word number that starts with '%'.

MATCH %/[hex2]/ : matches any hexadecimal byte number that starts with '%' but only selects the byte number. The '%' is left untouched.

MATCH %/hex2/:+/[dec]/ : 2 match strings given here. Matches hex bytes starting with '%' and decimal numbers that start with '+' without selecting the plus sign.


Usage of secondary arguments:

DO <value> :

Sets the maximum number of matches that will be attempted by the MATCH selector. The supplied numeric value should be at least 1, as a value of 0 makes DO to be ignored.

Example:

MATCH - TO _ DO 2: Match only the first 2 occurrences of '-'.


SKIP (SK) <value> :

Sets the number of matches that will be skipped before any matches will be performed.

Example:

MATCH - SK 1: Only the occurrences of '-' after the first will be matched.


REVMATCH (RM) :

Makes the matching process to start from the end of the filename instead of the start.

Example:

MATCH - DO 1 RM : Only the last occurrence of '-' will be matched.


CASESENS (CS) :

Makes string matching case sensitive. The default is case insensitive.

Example:

MATCH letter CS : Only lowercase occurrences of 'letter' will be matched.

LEFT (L) <number of chars>,[<left offset>] :


Selects characters from the left side of the filename.




MID (M) [<left offset>],[<right offset>] :


Selects characters using the distance from the left and right edge of the filename.




RIGHT (R) <number of chars>,[<right offset>] :


Selects characters from the right side of the filename.


Only one of the LEFT, MID, RIGHT selectors can be given for a specific action in contrast to PREFIX, MAIN, SUFFIX that can be given together. Left/right offset specifies the number of characters from left/right to skip before selecting the number of characters given in the first parameter.

Examples:

> SRename Libs:datatypes.library L 1 UP
output:
"datatypes.library" renamed as "Datatypes.library"

> SRename Work:001picture R 1,6 UP
output:
"001picture" renamed as "001Picture"

> SRename DataPartition_backup M 4,7 TO Volume
output:
"DataPartition_backup" renamed as "DataVolume_backup"

INVERTSEL (IN) :


This option causes the entire selection process to be inverted so that the selected characters are finally those that haven't been selected by whatever selectors have been given. Note that it does not invert the PREFIX, MAIN and SUFFIX selectors, and that it doesn't act selectively but on all the selectors that have been used.
If for example you have given the WORD and MATCH selectors and INVERTSEL, then you can't invert what WORD has selected and then try to select something else in that inverted selection with MATCH, because INVERTSEL will do the inverting after both WORD and MATCH have been evaluated.
Also note that when INVERTSEL is given with MATCH in single character or in character code mode then the parts that are excluded are modified as single characters and not as strings.
The position that INVERTSEL is put among the selectors is not important yet because it performs the inverting after all selectors have been evaluated. However this may change in the future so to ensure compatibility with future versions it's better to give INVERTSEL after the selectors of each action.

Examples:

> SRename temptextdocument MT text IN UP
output:
"temptextdocument" renamed as "TEMPtextDOCUMENT"

> SRename editorprefs L 6 IN UP
output:
"editorprefs" renamed as "editorPREFS"