SELECTORS


The selector instructions determine which parts of the filename will be modified by actions.
They are listed below in the order that they are evaluated. The selectors below that are in the same line have the same priority and only one of them can be used in each rename operation.

COMMENT / BASENAME
PREFIX / MAIN / SUFFIX
WORD
MATCH
LEFT / MID / RIGHT


Selector options:

Selector options should be placed before the selectors of each rename operation.

INVERTSEL
COMPSEP
PREFIRST

COMMENT (CO) :


COMMENT selects the comment of files or directories for modification.
It can't be used in renumbering to renumber comments, it can however be used in numbering to add numbers to comments.

Examples:

> SRename "pic.iff" COMMENT UPPER
Comment of "pic.iff" changed from "created with lightwave" to "CREATED WITH LIGHTWAVE"


> SRename #? COMMENT DELETE

Deletes all the filename comments in the current dir.


> SRename #? COMMENT INSERT *01* AT -1

Places an incremental number at the end of each comment starting at 1.


> SRename #? COMMENT LOWER : COMMENT LEFT 1 UPPER

Makes comments lowercase and the first character uppercase.

PREFIX (PR) :

Secondary arguments:

ADD (AD)
ADDONLY (AO)

Selects the prefix component for modification. For example in filename "abc.foo.xyz" the prefix would be "abc".




MAIN (MA) :

Secondary arguments:

ADD (AD)
ADDONLY (AO)

Selects the main component for modification. For example in filename "abc.foo.xyz" the main component would be "foo".




SUFFIX (SU) :

Secondary arguments:

ADD (AD)
ADDONLY (AO)

Selects the suffix component for modification. For example in filename "abc.foo.xyz" the suffix would be "xyz".


The default component separator is a period (.) and can be changed with the COMPSEP (CP) option which accepts a single character as a parameter.

By default the suffix has a higher priority than the prefix when filename components are defined. So when filenames have 2 components the default mode of operation is to define the main and suffix components.
This can be changed by using the PREFIRST (PF) option that makes the prefix get a higher priority than the suffix when components are defined, so in a 2-component filename the main and prefix components would be defined.


This table shows how the components of filename "abc.xyz" would be defined with and without PREFIRST.

Examples:

> SRename "archive_tar_gz" COMPSEP "_" MAIN UPPER : SUFFIX UPPER
"archive_tar_gz" renamed as "archive_TAR_GZ"

Redefines the component separator to '_' and makes the main and suffix components uppercase.


> SRename #? SUFFIX TO "ilbm"

Replaces the suffix of every filename with "ilbm" if they already have a suffix.


> SRename "backup.lzx" MAIN UPPER
"backup.lzx" renamed as "BACKUP.lzx"

Makes the main component uppercase.


> SRename "mod.techno" PREFIRST PREFIX UPPER
"mod.techno" renamed as "MOD.techno"

Makes the prefix be defined before the suffix and then makes it uppercase.



Usage of secondary arguments:


ADD (AD) :

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 option.

Examples:

> SRename "SoundSample" SUFFIX TO 8SVX
"SoundSample" not changed

Here it is attempted to modify a non-existent suffix, which fails because ADD is not used.


> SRename "SoundSample" SUFFIX ADD TO 8SVX
"SoundSample" renamed as "SoundSample.8SVX"

Now a new suffix is created as ADD was used.


ADDONLY (AO) :

When the ADDONLY option is used existing components are not modified but are only added if they don't already exist.

Examples:

> SRename "test.pic" SUFFIX ADDONLY TO "iff"
"test.pic" not changed

Here the suffix isn't changed because it already exists.


> SRename "test" SUFFIX ADDONLY TO "iff"
"test" renamed as "test.iff"

Now the new suffix is added because it didn't exist.



 

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" WORD 1 UPPER
"screen grab of game" renamed as "SCREEN grab of game"


> SRename "Letter_to_john" WORD 3 WORDSEP "_" UPPER
"Letter_to_john" renamed as "Letter_to_JOHN"


> SRename "Letter to john" WORD -1 UPPER
"Letter to john" renamed as "Letter to JOHN"


> SRename "screen grab of game" WORD 1,2 UPPER
"screen grab of game" renamed as "SCREEN GRAB of game"


> SRename "Data:Pics/" MAIN WORD 1 UPPER

Makes uppercase the first word of the main component.


> SRename "Data:Pics/" MAIN WORD 1 LEFT 1 UPPER

Makes uppercase the first character of the first word of the main component.


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 only the word characters are selected and if they are deleted then the spaces next to that word will remain.

For example:

> SRename "Picture of a ship" WORD 3 DELETE
"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" WORD 3 INCLSEP 1 DELETE
"Picture of a ship" renamed as "Picture of ship"

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


If you use INCLSEP 2 you will get:

> SRename "Picture of a ship" WORD 3 INCLSEP 2 DELETE
"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 used by giving some special characters or keywords together with the string to match. These characters and keywords are enclosed in slashes (/).

These are:

 ":" or "SCHR" : Activate single character mode. Must be placed at the beginning of the match arguments. 

 "%" or "CODE" : Activate 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.

 "]" : Selection end designator. Indicates the end of characters to select in the match string.

 "?" : 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: 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 occurrence of "text", "doc", "picture", and "sample".


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


MATCH /code/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 the characters after "abcd".


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


MATCH /]/abcd/[/ " selects 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 it.



Usage of secondary arguments:


DO <value> :

Sets the maximum number of matches that will be attempted by the MATCH selector. The parameter value should be at least 1.

Example:

MATCH "-" DO 2 TO "_"

Matches and replaces 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 "-" SKIP 1

Only the occurrences of "-" after the first will be matched.



REVMATCH (RM) :

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

Example:

MATCH "-" DO 1 REVMATCH

Only the last occurrence of "-" will be matched.



CASESENS (CS) :

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

Example:

MATCH "letter" CASESENS

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 used in a rename operation. 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" LEFT 1 UPPER
"datatypes.library" renamed as "Datatypes.library"


> SRename "Work:001picture" RIGHT 1,6 UPPER
"001picture" renamed as "001Picture"


> SRename "DataPartition_backup" MID 4,7 TO "Volume"
"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.


Examples:

> SRename "temptextdocument" MATCH "text" INVERTSEL UPPER
"temptextdocument" renamed as "TEMPtextDOCUMENT"


> SRename "editorprefs" LEFT 6 INVERTSEL UPPER
"editorprefs" renamed as "editorPREFS"