******************************************************************************* SRENAME 2.540 USERS MANUAL Copyright (C) 1996-1998 Constantinos Nicolakakis ******************************************************************************* INTRODUCTION : The philosophy behind SRename is to give you a CLI command with relatively few, but versatile functions that can be combined in many ways to provide whatever renaming operation is needed by the user, rather than providing dozens of specialised renaming options that limit the renaming operations that can be performed, to what the programmer had in mind when he was designing the command and are difficult to remember by the user. SRename can easily replace the original Rename command but I wouldn't recommend that because SRename's behaviour is not identical to the original command. You will probably find SRename most useful at renaming a lot of filenames at once, as it supports wildcards, multiple filenames and recursion. Some of SRename's advantages: * Selector-Action keyword separation that allows building specialized functions easily. * Total control over recursion. * Wildcard and multiple filename support. * Optional wildcard for directory selection in recursion. * Can isolate selected parts of the filename for modification with the use of the selector keywords. * Executes multiple actions in one go. * Performs intelligent renumbering with automatic checking for filename clashes. * Uses the ReadArgs OS function for argument parsing. * Can be made resident. PROGRAM STATUS : ******************************************************************************** * * * SRename is shareware but is not crippled in any way, and I don't charge any * * amount of money for it's use. If you find it useful I only ask to let me * * know that you are using it by sending me an email at: cnicol@compulink.gr * * * ******************************************************************************** Permission is granted to distribute free of charge, in unchanged form, provided this documentation file is accompanied with the program. Permission is granted to include on freely distributable software libraries such as Aminet CD-ROMs. Although I'm quite confident that SRename contains no major bugs, I can't guarantee that it is completely bug-free, and do not accept any responsibility of any damage this program could cause directly or indirectly. REQUIREMENTS : Amiga with kickstart 2 or higher. TECHNICAL : SRename is written in optimized C++ and was compiled with SAS C 6.58. It uses C++ features like object classes to achieve code reusability, memory management reliability and good program design. Memory is allocated dynamically in pages, to avoid high memory usage. It only uses moderate amounts of memory (around 100 KB or more) when it recurses through very complex disks/partitions that have wide directory trees and directories with many entries. It always uses buffers when renaming more than one filename as the Ram-Disk's filesystem has a bug that makes unbuffered renaming with pattern matching problematic. SRename has been tested with Enforcer and MungWall successfully on the following systems: A4000 060/50 - PPC 604e/200, kickstart 3.0, 42 MB RAM UAE 0.7.0 PPC, kickstart 2.04, 4 MB RAM INSTALLATION : Just copy SRename to your C: directory. INTERFACE CHANGES/ADDITIONS : The command interface of SRename is not 100% backwards compatible with previous versions, as some functions have been replaced by others along the way, and some improvements have been made to the command interface itself to make it more consistent and easier to use. I could have included code to maintain complete backward interface compatibility, but chose not to, because SRename is a new program and probably not many of you have been used to a certain way of using it already, and the changes that cause the incompatibilities are relatively few, and because adding such code would obviously make it increase in size. To make it easier to upgrade to newer versions, I include a button bank for use with Directory Opus 5 or higher, that is set up to work with the latest version of SRename. Since 2.540: MATCH additions: multiple match string support, single character mode, and character code mode. DELCHARS was removed as it can be replaced by MATCH : DELETE. SWAP now takes into account the PREFIX/MAIN/SUFFIX selectors, so that parts other than just the extremest can be swapped. Since 2.520: The TO keyword is no longer needed to perform simple renaming, so you can now type 'SRename oldname newname' to rename 'oldname' as 'newname'. The FILENAME keyword was renamed as FROM (same as the original rename command). Since 2.510: ICONS option was added to automatically rename .info files in single or multiple filename mode (not in wildcard mode). Since 2.500: New keywords: - DO - SKIP - BEFORE - AFTER - REVMATCH - AT - APPEND - UPDATE - UPTO Removed keywords: - DELBASE (is replaced by BASENAME "") Additional parameters were removed from keywords: - MATCH (moved to DO, SKIP, BEFORE, AFTER, REVMATCH) - INSERT (moved to AT, APPEND) - RENUMBER (moved to UPTO) Other changes: LEFT-RIGHT is not used anymore to set the position of the number within the basename in renumbering mode. Instead the AT and APPEND keywords are used for that purpose. The following keywords now have different full names: - PRE is PREFIX - SUF is SUFFIX - LEN is LENGTH The following keywords now have abbreviations: - PREFIX (PR) - MAIN (MA) - SUFFIX (SU) - LEFT (L) - MID (M) - RIGHT (R) - QUIET (Q) Read each function's description for details about it's syntax. USAGE : SRename FROM/A/M,TO=AS/K,RLEVEL=RL/N,SLEVEL=SL/N,DIRPAT=DP/K,ALLDIRS=AD/S, RECURSE=RC/S,NODIRS=ND/S,NOFILES=NF/S,ICONS=IC/S,DOT/K,PREFIX=PR/S,MAIN=MA/S, SUFFIX=SU/S,LEFT=L/K,MID=M/K,RIGHT=R/K,MATCH=MT/K,DO/N,SKIP=SK/N,BEFORE=BF/S, AFTER=AF/S,REVMATCH=RM/S,EXCLUDE=XC/S,EXIST=XS/S,CASESENS=CS/S,UPPER=UP/S, LOWER=LW/S,UPAFTERSPC=US/S,LENGTH=LN/N,INSERT=IN/K,AT/N,APPEND=AP/S,UPDATE=UD /S,DELETE=DL/S,SWAP=SW/S,LSHIFT=LS/S,RSHIFT=RS/S,UNIFY=UN/S,CONV8+3=8+3/S, RENUMBER=RN/K,UPTO=UT/N,STEP=ST/N,PLACES=PL/N,INVERT=IV/S,BASENAME=BN/K, PREFIRST=PF/S,NODIROUT=NDO/S,QUIET=Q/S: Short description of keywords : FROM : filenames to rename, multiple can be accepted. TO : new string that replaces the selected characters, and/or destination path. RLEVEL : maximum level of recursion. SLEVEL : starting level of recursion. DIRPAT : match pattern for entering directories. ALLDIRS : make the DIRPAT pattern be used and beyond the starting level of recursion. RECURSE : sets full recursion. NODIRS : no directories are renamed. NOFILES : no files are renamed. ICONS : rename .info files automatically. DOT : change the separator character. PREFIX : operate on prefix. MAIN : operate on main. SUFFIX : operate on suffix. LEFT [,] : operate on characters from the left. MID [],[] : operate on characters in the middle. RIGHT ,[] : operate on characters from the right. MATCH : operate on part that matches the string. DO : number of matches to perform. SKIP : number of matches to skip before starting. BEFORE : select the characters before the matched string. AFTER : select the characters after the matched string. REVMATCH : look for matches from the end of the filename. EXCLUDE : invert the selection process. EXIST : operate on a filename component only if it exists. CASESENS : enable case-sensitive matching. UPPER : make selected characters uppercase. LOWER : make selected characters lowercase. UPAFTERSPC : make uppercase the character after a space. LENGTH : maximum length of selected part. INSERT : insert string into the filename. AT : position from the start to insert. APPEND : measure insert position from the end. UPDATE : insert/append a string only if it does not exist in the specified position. DELETE : delete the selected characters. SWAP : swap the selected segments. LSHIFT : shift filename segments to the left. RSHIFT : shift filename segments to the right. UNIFY : unify the selected segments. CONV8+3 : convert to MS-DOS filename format. RENUMBER : renumber a filename sequence to start with the given number. UPTO : renumber up to that number. STEP : set the renumber step value. PLACES : set the renumber number-format. INVERT : perform inverted renumbering. BASENAME : set the renumber basename. PREFIRST : set the prefix segment first. NODIROUT : no directory name output. QUIET : no output at all. A detailed description of the above keywords can be found below. Most keywords have an abbreviation which is the one in parentheses after their full name. ******************************************************************************* FILE/DIR SELECTORS: ******************************************************************************* The following keywords define which files or directories will be renamed, according to their name, file or dir type, directory tree level, and the directory name that are in. FROM : The given file(s) or dir(s) are renamed. If just a directory or volume is supplied, all its files are renamed. If instead of a filename, a pattern (wild-card) is given, only files or dirs that match this pattern will be renamed. Multiple patterns can be supplied. Note that you don't actually have to type 'FROM' in the command line. Examples: > SRename C LW : Make C lowercase regardless of type (file or dir) > SRename C/ LW : Make all files and dirs in C lowercase > SRename C:d* UP : Make all files and dirs in C that begin with 'd' uppercase ------------------------------------------------------------------------------- RLEVEL (RL) : Sets the level of recursion. If this is 1, only subdirectories in the current directory will be entered. The default recursion level is 0 (no recursion). Example: > SRename SYS:Games/a* LW RL 3 : Make all files in SYS:Games that begin with 'a' and in subdirectories up to 3 levels deep lowercase. ------------------------------------------------------------------------------- SLEVEL (SL) : Sets the starting level of recursion Files and directories in a tree level lower than the specified will not be entered. Also sets full recursion if a RLEVEL parameter is not given. The default starting level is 1. Note that the value of SLEVEL can not be greater than the value of RLEVEL. Example: > SRename SYS: UP SL 2 : Make all filenames in SYS: uppercase, except for the filenames in the root directory. ------------------------------------------------------------------------------- RECURSE (RC) : Sets full recursion. All directories in the directory tree will be entered. It is overridden by RLEVEL and can also be set by ALLDIRS. Example: > SRename SYS:Games/a* LW RC : Make all files in SYS:Games that begin with 'a' lowercase in all subdirectories. ------------------------------------------------------------------------------- DIRPAT (DP) : Determines which directories in a given path are to be entered to rename their contents, according to the specified pattern. This parameter implies that recursion is active, if not it sets the level of recursion to 1. Note that the DIRPAT pattern, is used only once, for the directories that exist in the directory that renaming begins. If you want the DIRPAT pattern to be used all the way when recursing, you must give the ALLDIRS keyword. Examples: > SRename SYS:Data/*z DP project* DL SU : Remove the suffix from all the filenames in SYS:Data that end with 'z' and from the filenames in the subdirectories of SYS:Data that begin with 'project'. > SRename SYS:Data/*z DP project* DL SU RC : Same as the previous example but acts on filenames in all subdirectories that are contained in directories that begin with 'project'. ------------------------------------------------------------------------------- ALLDIRS (AD) : Makes the DIRPAT pattern be used with all directories that are encountered, not just with those in the starting level. A directory is entered for renaming to take place, only if it matches the DIRPAT pattern. ALLDIRS sets full recursion if a RLEVEL parameter is not given. Examples: > SRename SYS:Data/*z DP project* DL SU AD : Remove the suffix from all the filenames in SYS:Data that end with 'z' and in all subdirectories of SYS:Data that begin with 'project'. > SRename SYS:Data/*z DP project* DL SU RL 2 : same as the previous example but only acts on subdirectories of SYS:Data that begin with 'project' in a depth of up to 2 levels. ------------------------------------------------------------------------------- NODIRS (ND) : Do not rename any directories. Only files are renamed. Example: > SRename Work/Data/ UP ND : Make all the filenames in Work/Data uppercase. Directory names are not renamed. ------------------------------------------------------------------------------- NOFILES (NF) : Do not rename any files. Only directories are renamed. Example: > SRename Work/Data LW NF : Make all the dirnames in Work/Data lowercase. Filenames are not renamed. Note: if both NODIRS and NOFILES are given, only NODIRS will remain active. ------------------------------------------------------------------------------- ICONS (IC) : When in single or multiple filename mode, or in renumbering mode, the icon files (.info files) are renamed automatically even if they weren't specified in the filename list. Note that the way this option works is that the icon gets exactly the same filename that was given to the file that the icon accompanies (the icon's filename itself is not taken into account). If the new name of the file (not the icon) is longer than 25 characters, then the icon's filename is not changed simply because there is not enough room for the '.info' extension. This keyword can not be used with wildcards. Examples: > SRename tools/lacer tools/prepcard UP IC : Make 'lacer' and 'prepcard' uppercase including their icons' filenames. output: lacer renamed as LACER lacer.info renamed as LACER.info prepcard renamed as PREPCARD prepcard.info renamed as PREPCARD.info >SRename picture1 RN 10 IC : Renumber files from picture1 and up, including their icons. output: picture1 renamed as picture10 picture1.info renamed as picture10.info picture2 renamed as picture11 picture2.info renamed as picture11.info picture3 renamed as picture12 picture3.info renamed as picture12.info .... ******************************************************************************* CHARACTER SELECTORS: ******************************************************************************* The following keywords define which parts of the filename will be affected by the action keywords that will follow. The selection can be done according to the position of the characters or the characters themselves. PREFIX (PR) : Select the prefix (leftmost part) for modification. MAIN (MA) : Select the main part (middle part) for modification. SUFFIX (SU) : Select the suffix (rightmost part) for modification. Specifying one of the above selectors does not cancel the others. Note that if SRename receives a filename with only two components it regards that the filename has no prefix. The prefix component is filled only if the filename has 3 or more components, or with 2 components if PREFIRST is specified, which forces prefix-main to be filled instead of main-suffix. Here are some examples on how different filenames fill the PREFIX-MAIN-SUFFIX components: Filename PREFIX MAIN SUFFIX ---------------- -------- -------- -------- test : -empty- test -empty- 001.test.pic.gif : 001 test.pic gif test.pic.gif : test pic gif 001.test : -empty- 001 test 001.test PF : 001 test -empty- Examples: > SRename Work:#? SU ilbm XS : Replaces the contents of the suffix of every filename in Work: with 'ilbm', if they have a suffix. > SRename files/backup.lzx MA UP : Makes the main component uppercase. output: backup.lzx renamed as BACKUP.lzx > SRename mod.techno PR UP PF : Forces PREFIX to be filled before 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 ------------------------------------------------------------------------------- LEFT (L) [,] : Select characters from the left of the filename (start). MID (M) [] [,] : Select characters using the distance from the left and right edge of the filename. RIGHT (R) [,] : Select characters from the right of the filename (end). Left/right offset specifies the number of characters from left/right to skip before selecting the number of characters given in the first parameter. Note that PREFIX/MAIN/SUFFIX are evaluated before LEFT/MID/RIGHT. This means that you cannot for example select the 8 rightmost characters of a file/dirname and then select the main component in them (if there is one). For example: SRename newfilename.suf R 8 MA UP would not select the characters 'name' but would rather select the characters 'filename' as MAIN is evaluated before RIGHT. Also if more than one component of a filename is selected, any specified actions will take place on the selected components separately. For example: SRename 001.testpic.jpeg MA SU L 1 UP would make uppercase the leftmost character in MAIN, and then in SUFFIX (001.Testpic.Jpeg) and not the leftmost character of MAIN and SUFFIX combined (001.Testpic.jpeg). 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 Volume output: DataPartition_backup renamed as DataVolume_backup ------------------------------------------------------------------------------- MATCH (MT) [:][/] : Selects the characters that match the supplied string(s). If the string to match is preceded by a colon ':' then single character mode is activated and the supplied string is treated as individual characters. This mode is now used to replace the DELCHARS action. Example: > SRename Pics/ MT :[]{}()<>#@ DELETE : Remove all []{}()<>#? characters from the filenames in Pics. If the match string begins with a slash '/' then character code mode is activated, and single or multiple comma separated ASCII codes or single characters should follow. Example: > SRename Data/ MT /42,> DELETE : Remove all '*' and '>' characters from the filenames in Data. In this 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 ('0' gives ASCII code 48). Examples: > SRename Data/ MT /160-,48-57 DELETE : Remove all characters with ASCII codes same as or greater than 160, and ASCII codes 48 to 57 (digit characters). > SRename Data/ MT /-.,0-9,~- TO _ : Replace with '_' all characters before '.' including it, from '0' to '9', and after '~' including it. Note that BEFORE and AFTER have no effect in single character and character code modes, and CASESENS has no effect in character code mode. If none of the above modes are active then normal string matches are performed. Multiple strings to match can be supplied by using '|' as a separator. The matching is case-insensitive by default unless CASESENS is also given, and the supplied string cannot be a wild-card. The MATCH selector is very powerful and in conjunction with the DO, SKIP, BEFORE, AFTER and REVMATCH keywords which are used only with MATCH and are described below, and with the LEFT-MID-RIGHT selectors, it can select any part of the filename relative to the matched string. Using BEFORE or AFTER complicates things a bit for MATCH because selected character ranges can overlap, and changes in one selected range can affect the next selected range in the way that it will be selected and in the way it will be modified. To ensure that the intended characters by the user are selected, the MATCH selector corrects both the selected character range length and position. For example if two selected character ranges overlap, and new characters were inserted within the overlapping range, then the length of the second character range is adjusted so that all the intended characters are selected. Examples: > SRename SYS: MT pic TO picture : Replace all occurrences of 'pic' with 'picture' in all the filenames in the root dir of SYS: > SRename Work: MT exe|lib UP : Make every occurrence of 'exe' and 'lib' uppercase in all the filenames in the root dir of Work: ------------------------------------------------------------------------------- DO : Determines 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 will not result in making no matches. Example: > SRename -new-text-file MT - TO _ DO 2: Only the first 2 occurrences of '-' will be replaced with '_'. output: -new-text-file renamed as _new_text-file ------------------------------------------------------------------------------- SKIP (SK) : Determines the number of matches that will be skipped before any matches can be performed. Example: > SRename -new-text-file MT - TO _ SK 1: Only the occurrences of '-' after the first will be replaced. output: -new-text-file renamed as -new_text_file ------------------------------------------------------------------------------- REVMATCH (RM) : Makes the matching process to start from the end of the filename, instead of the start. Example: > SRename -new-text-file MT - DO 1 RM : Only the last occurrence of '-' will be replaced. output: -new-text-file renamed as -new-text_file ------------------------------------------------------------------------------- BEFORE (BF) : Selects the characters before the matched string. If you want to select a limited amount of characters before a string, you should use the RIGHT selector. Note that if you use BEFORE without RIGHT to select all characters before the matched string, and start the match from the right with REVMATCH, only one match will be performed, even if more than one strings to match exist. Examples: > SRename lastletter MT letter BF UP : Makes uppercase all characters before 'letter'. output: lastletter renamed as LASTletter > SRename gamescreengrab MT grab BF R 6 UP : Makes uppercase 6 characters before 'grab'. output: gamescreengrab renamed as gameSCREENgrab ------------------------------------------------------------------------------- AFTER (AF) : Selects the characters after the matched string. If you want to select a limited amount of characters after a string, you should use the LEFT selector. Note that if you use AFTER without LEFT and without REVMATCH to select all characters after the matched string, only one match will be performed, even if more than one strings to match exist. Examples: > SRename lastletter MT last AF UP : The characters after 'last' will be made uppercase. output: lastletter renamed as lastLETTER > SRename "the last ballad" MT " " AF L 1 UP : This is equivalent to uppercase after space, with the exception that it does not uppercase the first character. output: the last ballad renamed as the Last Ballad > SRename readmenow MT read AF L 3,2 UP : Makes uppercase 3 characters after the end of 'read' plus 2 characters. output: readmenow renamed as readmeNOW ******************************************************************************* OTHER KEYWORDS THAT AFFECT COMPONENT SELECTION: ******************************************************************************* EXCLUDE (XC) : Exclude selected chars (inverse selection). Note that it does not invert the PREFIX/MAIN/SUFFIX selectors. Examples: > SRename asmallfile MT small UP XC output: asmallfile renamed as AsmallFILE > SRename editorprefs L 6 UP XC output: editorprefs renamed as editorPREFS ------------------------------------------------------------------------------- CASESENS (CS) : Make string matching case-sensitive. The default is case insensitive. This keyword can be used in conjunction with the MATCH selector, the UPDATE action, and any of the renumbering actions. Refer to these keywords for a detailed description. Example: > SRename FileNamewithname MT name TO Comment CS output: FileNamewithname renamed as FileNamewithComment Note that only the second occurrence of 'name' is replaced with 'Comment' because the string matching is case-sensitive. ------------------------------------------------------------------------------- EXIST (XS) : Modify the specified component (PREFIX-MAIN-SUFFIX) only if it exists. Example: > SRename SoundSample SU TO 8SVX XS output: SoundSample not changed A new suffix is not appended to the filename because it didn't have one in the first place. ------------------------------------------------------------------------------- DOT : Redefine the separator character (default separator: '.') The separator character determines the PREFIX-MAIN-SUFFIX components. Example: > SRename archive_tar_gz MA SU UP DOT _ output: archive_tar_gz renamed as archive_TAR_GZ ******************************************************************************* ACTION KEYWORDS: ******************************************************************************* The following keywords define how the characters that have been selected with the component selector keywords, will be modified. TO (AS) <[path/]filename> : Replaces the selected portion of the filename with the given string. It can also be used to move files to other directories in the same volume (AmigaOS Rename function limitation) if a path is supplied. The 'TO' keyword need not be given if no other action keywords are supplied, because in such a case the last given filename activates the 'TO' action. That means that now SRename can perform simple renaming in the same manner as the original Rename command: > SRename oldfilename newfilename : 'oldfilename' is renamed as 'newfilename'. If however you want for example to move a file to another directory and make it uppercase, then you will have to use 'TO' as: > SRename anyfile TO dirx/ UP : 'anyfile' is moved to 'dirx' and is made uppercase. If you omit 'TO' as: 'SRename anyfile dirx/ UP' ,that will tell SRename to make uppercase 'anyfile' and all the filenames in the directory 'dirx'. Note that the destination path is inherited from the source path (if it was given) so that it (the destination path) doesn't have to be supplied with the new filename. For example if the current dir is not 'SYS:Data', to rename 'letter.txt' with the original Rename command you would type: > Rename SYS:Data/letter.txt SYS:Data/NewFileName With SRename you just type: > SRename SYS:Data/letter.txt NewFileName. Examples: > SRename SYS:OldFileName L 3 New output: OldFileName renamed as NewFileName > SRename SYS:OldFileName SYS:C/ : Moves OldFileName to C: maintaining its filename. > SRename SYS:OldFileName SYS:C/NewName : Moves OldFileName to C: and renames it as 'NewName'. ------------------------------------------------------------------------------- UPPER (UP) : Makes the selected characters uppercase. It is Keymap sensitive so that it will function correctly with any keymap-font setup. Example: > SRename Data/ L 1 UP : Makes uppercase the first character of every filename in 'Data'. > SRename Data/ SU UP : Makes uppercase only the suffix of every filename in 'Data'. ------------------------------------------------------------------------------- LOWER (LW) : Makes the selected characters lowercase. It is Keymap sensitive so that it will function correctly with any keymap-font setup. Example: > SRename Data/TEXTFILE LW output: TEXTFILE renamed as textfile ------------------------------------------------------------------------------- UPAFTERSPC (US) : Makes characters after spaces uppercase. It also makes uppercase the first character in the selected range. Example: > SRename "Data/text file" US output: text file renamed as Text File ------------------------------------------------------------------------------- LENGTH (LN) : Determines the maximum length in characters a filename can be. Exceeding characters are deleted from the end. Example: > SRename Data/program.preferences LN 12 output: program.preferences renamed as program.pref ------------------------------------------------------------------------------- INSERT (IN) : Inserts the given string at the beginning of the selected characters. You can make the insertion anywhere within the filename by using the AT keyword, or at the end of the filename by using the APPEND keyword. Example: > SRename Letter.txt IN First output: Letter.txt renamed as FirstLetter.txt ------------------------------------------------------------------------------- AT : Determines the position within the filename at which the string that was given with INSERT, is to be placed. Note that in INSERT mode there always has to be at least one character after the string to be inserted, and in APPEND mode at least one character before the string to be appended. You can't for example insert string 'ABC' at the end of filename 'somefile' with : > SRename somefile IN ABC AT 8 output: somefile not changed To do the former you must use the APPEND action together with INSERT and AT. If the position you have specified is invalid for INSERT or APPEND, the operation will be aborted. Note that the AT keyword can also be used in renumbering mode to set the position of the number within the basename. Example: > SRename AnyFilename IN XYZ AT 3 output : AnyFilename renamed as AnyXYZFilename ------------------------------------------------------------------------------- APPEND (AP) : Makes INSERT place the supplied string at the end of the selected characters, so make sure you supply the INSERT action too. Can also be used in conjunction with AT to determine the position of the inserted string not from the left but from the right of the selected characters. Note that the APPEND keyword can also be used in renumbering mode to set the position of the number within the basename. Examples: > SRename Sound IN Sample AP output : Sound renamed as SoundSample > SRename Sound.iff IN Sample AT 4 AP output : Sound.iff renamed as SoundSample.iff ------------------------------------------------------------------------------- UPDATE (UD) : Allows the INSERT action to proceed only if the string to insert does not exist in the specified position. The characters that are compared with the string to insert, are after the specified position in insert mode and before the specified position in append mode. The comparison is case-insensitive unless CASESENS is given. Examples: > SRename old_letter.txt IN Old UD : Because 'old' already exists in the beginning of the filename it is not inserted. output : old_letter.txt not changed > SRename old_letter.txt IN Old UD CS : Now 'Old' is inserted because the comparison is case-sensitive. output : old_letter.txt renamed as Oldold_letter.txt > SRename pic_last.iff IN Last AT 4 AP UD : Trying to insert 'last' 4 chars from the end fails because it already exists. output : pic_last.iff not changed ------------------------------------------------------------------------------- DELETE (DL) : Removes the selected characters from the filename. Examples: > SRename SYS: L 3 DL : deletes the first 3 characters from filenames in SYS: > SRename SYS: SU DL : deletes the suffix from filenames in SYS: > SRename SYS: MT :#@ DL : deletes every '#' and '@' character from filenames in SYS: ------------------------------------------------------------------------------- SWAP (SW) : Swaps the selected filename components. If 2 of the PREFIX,MAIN,SUFFIX selectors are given, then the parts specified by these selectors will be swapped. Otherwise if none of the above selectors are given, or just one, or all of them, then just the 2 extremest components are swapped. SWAP has an effect only on filenames with at least 2 components, like prefix- main, main-suffix, or all (prefix-main-suffix). Examples: > SRename picture.iff SW output: picture.iff renamed as iff.picture > SRename 001.picture.iff SW output: 001.picture.iff renamed as iff.picture.001 > SRename 001.picture.iff PR MA SW output: 001.picture.iff renamed as picture.001.iff ------------------------------------------------------------------------------- LSHIFT (LS) : Shifts the filename components to the left, the leftmost becomes the rightmost. Like SWAP it has an effect only on filenames with at least 2 components. This keyword operates on the whole filename, so the component selectors have no effect with it. Example: > SRename SYS:001.picture.iff LS output: 001.picture.iff renamed as picture.iff.001 ------------------------------------------------------------------------------- RSHIFT (RS) : The opposite of LSHIFT. The rightmost component becomes the leftmost. Example: > SRename SYS:001.picture.iff RS output: 001.picture.iff renamed as iff.001.picture ------------------------------------------------------------------------------- UNIFY (UN) : Unifies the filename components specified by PREFIX/MAIN/SUFFIX by deleting the separator character. If no component is specified it unifies the whole filename. Examples: > SRename SYS:picture.001 UN output: picture.001 renamed as picture001 > SRename SYS:001.picture.iff UN PR output: 001.picture.iff renamed as 001picture.iff > SRename SYS:001.some.complex.name.iff UN MA output: 001.some.complex.name.iff renamed as 001.somecomplexname.iff ------------------------------------------------------------------------------- CONV8+3 (8+3) : Converts filenames to the MS DOS format of 8+3 characters. The filename will be made uppercase, if it has a suffix this will be cut to 3 characters in length, and if it has a prefix it will only be maintained if there is room left from the main component. Note that none of the selector keywords have any effect with this keyword, because it always operates on the whole filename. It is possible when converting whole directories that some filenames will fail to be converted because they may get the same name with other files. For example picture-1.iff and picture-2.iff will both receive the name: PICTURE-.IFF Examples: > SRename SYS:User.prefs 8+3 output: User.prefs renamed as USER.PRE > SRename SYS:sound.sample.iff 8+3 output: sound.sample.iff renamed as S_SAMPLE.IFF ******************************************************************************* RENUMBERING: ******************************************************************************* SRename can perform intelligent renumbering of filename sequences in one go. It is not limited in the formats it can support, as it scans the filenames for numbers of up to 9 digits long, which can have leading zeros, and can be in any position in the filename, or on their own. You don't have to specify the order of renaming, normal or reverse, as with other renumbering utilities, because it scans the filenames in the directory and decides which way to go. Furthermore you don't have to worry for filename clashes during renumbering, as any clashes will be found before the actual renaming begins, and the clashing filenames will be given temporary names, before are finally renamed. Inverting of numbers in a sequence can also be performed, a feature that would be useful in compiling ping-pong animations. The following keywords are relevant to renumbering and can be given all at once, or on their own : RENUMBER (RN) : specifies the new starting number of a filename sequence. All matching filenames will be renumbered unless an ending number is specified with UPTO. Examples: > SRename Data:picture001 RN 50 : will renumber all filenames that begin with 'picture' and have a number attached at the end, to values starting with 50. The leading zeroes will be preserved. output: picture001 renamed as picture050 picture002 renamed as picture051 picture003 renamed as picture052 picture004 renamed as picture053 picture005 renamed as picture054 .... > SRename Data:picture001 RN 50 UT 4 : as above but will renumber up to filename 'picture004'. output: picture001 renamed as picture050 picture002 renamed as picture051 picture003 renamed as picture052 picture004 renamed as picture053 > SRename Data:10.frame RN 020 : will renumber all filenames that end in '.frame' and are preceded with a value of 10 or greater, to values starting with 020. output: 10.frame renamed as 020.frame 11.frame renamed as 021.frame 12.frame renamed as 022.frame 13.frame renamed as 023.frame 14.frame renamed as 024.frame .... Note that when you supply a new starting number with leading zeroes, the old number format is overridden. ------------------------------------------------------------------------------- UPTO (UT) : specifies the existing number in a filename up to which SRename will perform any of the renumbering actions. If you give this keyword you must specify at least one renumber-type action (RENUMBER,STEP,PLACES,BASENAME,AT,INVERT) with it, otherwise a 'Required argument missing' error will occur. Examples: > SRename Data:picture001 RN 50 UT 6 : will renumber from 'picture001' up to 'picture006'. > SRename Data:frame100 UT 110 BN AnimFrame : will change the basename to 'AnimFrame' from 'frame100' up to 'frame110'. > SRename Pics/datafile0010 UT 20 PL 2 : will make 2-digit the numbers from 'datafile0010' up to 'datafile0020'. ------------------------------------------------------------------------------- STEP (ST) : defines the increment value of renumbering. The default increment is 1. It can also take negative values. Examples: > SRename Data:picture001 RN 30 ST 2 : increases the new starting value by 2. output: picture001 renamed as picture030 picture002 renamed as picture032 picture003 renamed as picture034 picture004 renamed as picture036 .... > SRename Data:picture001 ST 3 : will keep the original starting value, but will increase the destination numbers in steps of 3 : output: picture004 renamed as picture010 picture003 renamed as picture007 picture002 renamed as picture004 picture001 not changed .... Note that the renumbering is executed in reverse order in order to avoid a clash when renaming picture002 to picture004 (picture004 already exists). ------------------------------------------------------------------------------- PLACES (PL) : Sets the number format of the destination filenames. This affects the number of leading zeroes the numbers will have. If you specify a places value that is smaller than the digits a number already has, that number will be unaffected. Any numbers will less digits than the places value will be padded with leading zeroes. Examples: > SRename Data:picture001 RN 30 PL 4 : makes the numbers 4-digit. output: picture001 renamed as picture0030 picture002 renamed as picture0031 picture003 renamed as picture0032 picture004 renamed as picture0033 .... > SRename Data:picture001 PL 1 : strips all leading zeroes from the numbers. output: picture001 renamed as picture1 picture002 renamed as picture2 picture003 renamed as picture3 picture004 renamed as picture4 .... > SRename Data:picture001 UT 3 PL 2 : will renumber from number 001 to 003, and make the numbers 2-digit. output: picture001 renamed as picture01 picture002 renamed as picture02 picture003 renamed as picture03 ------------------------------------------------------------------------------- INVERT (IV) : tells SRename to invert the numbers in a filename sequence. This is exactly how inverting works: original filenames new filenames ------------------ ------------- file.10 -> becomes -> file.14 file.11 -> becomes -> file.13 file.12 - not changed - file.13 -> becomes -> file.11 file.14 -> becomes -> file.10 You may have noticed that executing this sequence of rename commands has a problem: how can 'file.10' become 'file.14' when 'file.14' already exists. SRename sees that and when destination filenames already exist, the files to be renumbered are given temporary filenames until the existing filenames themselves have been renumbered, so after this is done the temporary filenames are given their normal destination filenames. An unresolvable error occurs (New number exists) if these existing filenames that cause clashes are not scheduled to be renumbered because they are outside the range of files to be renumbered. Examples: > SRename Data:file100 IV : inverts the whole filename sequence. output: file100 renamed as 109_srtemp861A5BC file101 renamed as 108_srtemp861A5BC file102 renamed as 107_srtemp861A5BC file103 renamed as 106_srtemp861A5BC file104 renamed as 105_srtemp861A5BC file105 renamed as file104 file106 renamed as file103 file107 renamed as file102 file108 renamed as file101 file109 renamed as file100 109_srtemp861A5BC renamed as file109 108_srtemp861A5BC renamed as file108 107_srtemp861A5BC renamed as file107 106_srtemp861A5BC renamed as file106 105_srtemp861A5BC renamed as file105 Notice how numbers 100 to 104 are given temporary filenames before been finally renumbered, because of clashes that would occur during the renaming process. > SRename Data:file100 RN 50 IV : inverts the filename sequence and gives it a starting number of 50. output: file100 renamed as file59 file101 renamed as file58 file102 renamed as file57 file103 renamed as file56 file104 renamed as file55 file105 renamed as file54 file106 renamed as file53 file107 renamed as file52 file108 renamed as file51 file109 renamed as file50 ------------------------------------------------------------------------------- BASENAME (BN) : replaces the non-numeric parts of the filename sequence, if they exist, with the given string. From this version BASENAME also replaces the DELBASE function. To delete the basename of a filename sequence, thus leaving only the numbers you should simply give: BASENAME "". Examples: > SRename Data:file100 BN picture : replaces 'file' with 'picture' in every filename. Note that the number continues to be at the end of the new basename. output: file100 renamed as picture100 file101 renamed as picture101 file102 renamed as picture102 file103 renamed as picture103 .... > SRename Data:sound001.iff BN snd : will replace 'sound' with 'snd'. output: sound001.iff renamed as snd001 sound002.iff renamed as snd002 sound003.iff renamed as snd003 sound004.iff renamed as snd004 .... > SRename Data:file001pic RN 50 BN filepicture : will renumber starting at 50, and replace 'filepic' with 'filepicture'. Note that the old number position is preserved. output: file001pic renamed as file50picture file002pic renamed as file51picture file003pic renamed as file52picture file004pic renamed as file53picture .... > SRename Data:file001pic BN "" : will delete the basename. output: file001pic renamed as 001 file002pic renamed as 002 file003pic renamed as 003 file004pic renamed as 004 .... Note that when the number is surrounded by the basename, (the number is not at the beginning or at the end) the position of the number within the basename is preserved when a new basename is given. This position can be changed with the use of the AT and/or APPEND keywords as we will see later. ------------------------------------------------------------------------------- AT : Sets the position of the number within the basename. Examples: > SRename frame100.iff AT 0 : will move all numbers in the filename sequence 0 characters from the left. output: frame100.iff renamed as 100frame.iff frame101.iff renamed as 101frame.iff frame102.iff renamed as 102frame.iff frame103.iff renamed as 103frame.iff .... > SRename 100frame.iff AT 5 : will move all numbers 5 characters from the left. output: 100frame.iff renamed as frame100.iff 101frame.iff renamed as frame101.iff 102frame.iff renamed as frame102.iff 103frame.iff renamed as frame103.iff .... ------------------------------------------------------------------------------- APPEND (AP) : Sets alone or in conjunction with AT the position of the number within the basename. When used alone the numbers go at the end of the basename, and when used with AT, the position is measured from the end of the basename. Examples: >SRename frame100.iff AP : all numbers will be moved at the end of the basename. output: frame100.iff renamed as frame.iff100 frame101.iff renamed as frame.iff101 frame102.iff renamed as frame.iff102 frame103.iff renamed as frame.iff103 .... >SRename 100frame.iff AT 4 AP : all numbers will be moved 4 characters from the end of the basename. output: 100frame.iff renamed as frame100.iff 101frame.iff renamed as frame101.iff 102frame.iff renamed as frame102.iff 103frame.iff renamed as frame103.iff .... ------------------------------------------------------------------------------- CASESENS (CS) : when in renumbering mode, preserves each basename's casing. If CASESENS is not given, all basenames will get their content from the first basename that is to be renumbered. Example: >SRename frame01 RN 20 CS output: frame01 renamed as frame20 FRAME02 renamed as FRAME21 frame03 renamed as frame22 FRAME04 renamed as FRAME23 frame05 renamed as frame24 As you see the second and fourth basename remain in upper case. ******************************************************************************* OTHER KEYWORDS: ******************************************************************************* NODIROUT (NDO) : suppresses directory name output during recursion. QUIET (Q) : suppresses all output including error messages. ------------------------------------------------------------------------------- EMULATED FUNCTIONS : You may think that SRename has some functions missing, like uppercase first character, delete spaces, spaces to underscores, replace string1 with string2, etc. Such specialised functions can be built with other functions, for example: Uppercase first can be performed with: LEFT 1 UP, delete spaces with: MATCH " " DELETE, spaces to underscores with MATCH " " TO _ , and replace str1 with str2 with MATCH string1 TO string2. Even uppercase after space can be emulated with MATCH " " AFTER LEFT 1 UP, but as the emulated function does not uppercase the first character too, I have left the specialised function in. PRIORITIES : Not all keyword combinations make sense, that's why some keywords have priority or cancel others. The following priorities exist: LEFT has priority over MID which has priority over RIGHT MATCH is executed before LEFT/MID/RIGHT NODIRS cancels NOFILES BEFORE cancels AFTER RLEVEL has priority over RECURSE DELETE cancels every other action TO cancels every other action except DELETE CONV8+3 cancels UPPER, LOWER and UPAFTERSPC UPPER cancels LOWER and UPAFTERSPC LSHIFT cancels RSHIFT Any renumbering related action is cancelled by any other non-renumbering action. TIPS: When you use SRename with a filemanager like Directory Opus, and you have set it up to receive multiple filenames ({O} option in DOpus), place that option at the end of the command line, because if the filename sequence is too big the arguments after it will be omitted. For example don't give DOpus the command SRename {O} UP QUIET, but SRename UP QUIET {O}. Although SRename has been updated to work with filenames that contain wildcard characters (i.e. parentheses) and thus are recognised by the OS as file- matching patterns, it will only rename such filenames if it can find them immediately in the supplied path. It is not possible for example to specify such a filename and tell SRename to recurse through the directory tree, renaming every occurrence of this filename, if it does not find it in the starting directory, because once it can't find it it will decide that it's a file-matching pattern, which is not what it was intended for by you. I advise you not to use any such filenames that confuse the OS and other applications. Even if the command interface is now 100% compatible with the original rename command (version 37.2), SRename still differs in the way that it inherits the destination path from the supplied source path. For that reason I don't recommend that you replace the original Rename with SRename. LIMITATIONS : -Because of the way that the ReadArgs OS function works, you can not assign different actions to different parts of the filename in one go, like for example SRename anyfilename.suffix LEFT 3 UP SUFFIX DELETE. The previous command will just delete the 3 leftmost characters from the suffix (DELETE cancels UP). This will change in the future. -SRename can handle directories that contain up to 32768 filenames and up to 4096 directory names, more will result in a buffer overflow error. -When recursing, it can go up to 127 directory levels deep (it's difficult to encounter even 10 levels of depth). -Recursing is cancelled if a destination path is given. -Any supplied path can be up to 512 characters long. -The length of all filenames is limited by AmigaOS to 30 characters. Limitations in Renumbering: -Numbers in filenames from 0 to 999999999 can be handled. -No wildcards can be used, and when a destination path is supplied no clash- checking takes place (it is assumed that the destination directory contains no filenames that can clash with the filenames that will be moved there). -No filenames that contain wildcard characters can be used, because pattern- matching is used to collect the filenames of the sequence. -Any numbers that have a different format to that of the first number scanned will not be renumbered: if the first number is 001 and 02,03 follow, these will not be renumbered because SRename will try to find 002 and 003. -The PREFIX-MAIN-SUFFIX, LEFT-MID-RIGHT selectors and EXCLUDE have no effect in renumbering mode. -A filename clash can not be resolved if the clashing filename is outside the range of filenames to be renumbered (New number exists error). KNOWN BUGS : Although the MATCH selector performs length and position correction for the selected character range, in case of overlapping ranges, actions that accept position parameters are not corrected yet. HISTORY : Version Changes ------- ----------------------------------------------------------------------- 0.xxx : First working version. Compiled with Storm C 1.1 1.xxx : Recursion added, switched to SAS-C because of problems with the Storm C executables. 2.xxx : Renumbering added. 2.393 : First public release. 2.396 : Recompiling with option Parms=REGISTER results in code size decrease. Averted possible crash when recursion level exceeded 128. Made a derived class separate and specialized. 2.400 : Serious bug fixed when repositioning a number within a filename, in renumbering mode with LEFT/RIGHT. Now the utility.library uppercase/lowercase routines are used so that filenames like 'Boulderdäsh' are processed correctly. Unnecessary clash-checking and subsequent temporary renaming has been removed. 2.410 : In renumbering now SRename does not pick the first number it finds, but the number that appears at least 2 times in a filename position with different values, so that filenames like pic2.10, pic2.11, pic2.12, ... can be renumbered normally. Doubled the amount of file and dir names that can be renamed in one go, as well as the amount of filenames that can be renumbered in one go. Added separate error message when trying to renumber a filename that does not contain a number. 2.420 : Fixed various bugs that prevented multiple filename sequences from being renumbered properly. Improved the structure of argument checking routines. Several code optimizations. Only one 68k generic executable supplied as processor-specific executables are now very similar. 2.430 : Now SRename avoids renaming unchanged filenames and reports not renaming unchanged filenames in renumbering mode. As a result a bug in renumbering mode that left unchanged filenames in the same directory even though a new destination dir was given was fixed. 2.500 : Added BEFORE,AFTER,REVMATCH options for MATCH selector. Added UPDATE option for INSERT action. Major interface changes: removed additional parameters from MATCH, INSERT and RENUMBER and made them separate, also changed the full names of LEN,PRE,SUF and gave abbreviations to PREFIX,MAIN,SUFFIX,LEFT,MID, RIGHT and QUIET. AT is now used for number positioning in renumbering instead of LEFT and RIGHT. Removed the DELBASE action. Fixed bug in TO action. Can now rename filenames that are recognised by the OS as wildcards if these filenames are found in the given path. Fixed bugs introduced in 2.430 that caused misrecognition of same source and destination filenames. 2.510 : Added ICONS option for automatic icon renaming. Fixed a bug in routine that detects same source-destination filename. 2.520 : The TO keyword is now optional for some rename actions. The FILENAME keyword was renamed as FROM. Fixed serious bug that hampered multiple filepattern renaming when different directories were given. Improved the error and other message output. Errors: 'source path not found', 'no number in filename' and 'invalid number in filename' do not abort the processing of other filepatterns anymore. Some code optimizations. 2.530 : Changed the way that temporary filenames are named when resolving clashes, to eliminate the possibility that another SRename task could use the same temporary filenames when trying to resolve a clash. Now all temporary filenames receive an address that is different for each SRename task. As a result the limit for numbers contained in filenames has gone up to just under a billion (999999999). Failure to perform a temporary rename in renumbering mode now results in an error message and termination of further processing. Fixed small bug that caused the casing of the basename in renumbering to be determined from the given starting filename. Made a few code optimizations. 2.540 : MATCH selector enhancements: * Added single character mode, as a result the DELCHARS action was removed, as it can be replaced by MATCH : DELETE. * Added character code mode supporting ranges. * MATCH can now accept multiple strings to match. The SWAP action can now swap the filename parts determined by the PREFIX/MAIN/SUFFIX selectors, instead of always swapping the two extreme parts. Increased the limit for maximum number of filenames in each directory to 32768 and of directory names to 4096. Some more optimizations for speed. ------------------------------------------------------------------------------- If you would like SRename to continue to be developed, or you have some suggestion, request, or bug report, email me at: cnicol@compulink.gr or for snail-mail: Constantinos Nicolakakis Olympion 7 Patissia 11143 Athens, Greece