SSREPLACE

SSREPLACE reads a control file, a replacement file, where each line consists of pairs of old-string and new-string. SSREPLACE then searches the files in one more SourceSafe projects for the old-strings and if there is a match in a file, SSREPLACE checks out the file and substitutes any old-string with the corresponding new-string and leaves the file checked out. SSREPLACE can also work in a read-only mode, listing the changes that would occur without checking out the files; in fact this is the default behaviour. Like SSGREP, SSREPLACE ignores comments in files of known types, unless told otherwise.

Contents:
    Command-Line Syntax
    How the Matching Files are Handled
    Format of the Replacement File
    A Crash-Course in Perl Regexps

Command-Line Syntax

   ssreplace -config config-file | -VSS SS-path [-comments] [-HTML]
             [-lang VB|SQL|C ...] [-type filetype ... ]
             [-nolist] [-edit] [-rename] repl-file

`-config`	Config-file that determines which SourceSafe projects that SSREPLACE is to search in. With SSREPLACE, the version-designator column in the config-file has no signficance, as SSREPLACE always searches the most recently checked-in version of each file.
`-VSS`	Specifies an SS-path for a singular SourceSafe project for SSREPLACE to search. SSREPLACE will search the most recently checked-in version of each file.
`-comments`	Whether SSREPLACE is to search and replace also within comments, or only in text outside comments. See the page for SSGREP, for which file types AbaPerls knows how to strip comments from the code. If you do not specify `-comments`, SSREPLACE will only search and replace text outside comments.
`-HTML`	Instructs SSREPLACE to produce the list of changes in HTML format, with underlining the performed replacements. This greatly enhances readability. As you will need a web browser to read the output, it is adviceable to use > to redirect the output to a file.
`-type`	Specifies that SSREPLACE is to search only files of the specified type(s). You can specify multiple `-type` on the command line. You can specify the file type with a leading period, but this is not required. Example: to search only stored procedures and triggers you could specify: `-type .sp -type TRI`. As the example indicates the type names are case-insenstive.
`-lang`	This is a shortcut to `-type` that permits you to specify all types for a certain programming language in one go. The following values are recognized: SQL – The SQL files according to the AbaPerls SQL directory structure. VB – Files of the types .BAS, .CLS, .FRM and .VB. C – Files of the types .C, .CPP, .H and .HPP. As with `-type` you can specify multiple `-lang` on the command line. You can mix `-lang` and `-type`.
`-nolist`	Normally, SSPREPLACE prints all replacements it performs (or is about to perform if you do not specify `-edit`), and also prints the Perl code it creates to perform the replacements with statistics over the number of matches. If you specify `-nolist`, SSREPLACE prints only the number of changes in each affected file. The output is printed to the command-line window. Use > to redirect output to a file.
`-edit`	You need to specify `-edit`, to compel SSREPLACE to actually perform the changes in the files. Without `-edit`, SSREPLACE only searches the files and prints the available replacements.
`-rename`	With `-rename`, SSREPLACE also applies the changes on the file names, and renames files that matches any old-string. This is handy if you want to rename a couple of stored procedures, and they reside in files with the same name as the procedures. Note that you need to be extra careful when you use `-rename`. If a file is shared between several SourceSafe projects, the file is renamed in all those projects, which is probably not what you want. Thus, first run SSREPLACE without `-edit` and review the output and branch all files that will be renamed. If you do not specify `-rename`, SSREPLACE will anyway list the file names that matches the old-strings in the replacement file.
repl-file	File with the replacements to perform. Each line consists of old-string, new-string and repl-options. The fields are separated by white space. The three fields are used as input to the `s///` operator in Perl with a few twists. See further below for more details on the format.

How the Matching Files are Handled

When SSREPLACE finds a file where one or more of old-string in repl-file matches, there are three different possibilities:

The file is currently not checked out. In this case SSREPLACE checks out the file. Just like all other AbaPerls tools SSREPLACE does not honour your SourceSafe settings. If you specify a single project with -VSS, SSREPLACE sets the working directory for SS-path to the current directory, and thus all files will be checked out to the current directory or a subdirectory thereof, depending on where there file is in relation to SS-path. If you specify a config-file, SSREPLACE sets the working directory for each subsystem to a sub-directory with the same name as the subsystem in the current directory.
You already have the file checked out. In this case SSREPLACE updates the local copy, no matter where it is located. SSREPLACE searches the local copy, and does not read the file from SourceSafe.
Someone else has the file checked out. In this case, SSREPLACE reads the file from SourceSafe and prints the changes incurred by the replacement file together with a note that the file is checked out, but SSREPLACE leaves the file unchanged.

SSREPLACE ignores files that are binary according to SourceSafe. SSREPLACE also ignores projects with a path ending in SQL/SCRIPTS (since these typically are conversion scripts etc, that you have no interest to change.)

The default for SSREPLACE is to search and replace only outside comments. SSREPLACE first strips the code of comments, performs the replacements and then puts the comments back. (This is the same procedure as the AbaPerls file-loading process employs). In most cases you are not likely to notice this, but since AbaPerls does not really keep track on where on the line the comment is (most comments are at the end...), you may see changes if you put your comments in "odd" places.

Format of the Replacement File

Each line in the file consists of three fields, separated by blanks. The fields are old-string, new-string and repl-options. The latter field may be empty. Text that follows -- (two hyphens) are comments and ignored. Unless they appear in the beginning of the line, the hyphens must be preceded by space to work as a comment delimiter. (That is, two hyphens in the middle of old-string or new-string does not start a comment.) A line may be empty, or consist of comments only.

For each line that SSREPLACES traverses, SSREPLACES applies the replacements in repl-file in the order they appear in the file. That is, the second replacement is applied on the result of the first replacement. Thus, some carefulness may be in order.

A short description for the reader who already knows Perl regexps: the replacements are carried out with the operator s///. You need to observe the following differences with regards to how you use s/// in a Perl script:

To specify space in old-string or new-string, specify \_ (backslash followed by underscore).
If old-string or new-string begins with -- (two hyphens), you must be prepend it with a backslash, or else the string will be taken for a comment.
Multi-line replacements are not available, as SSREPLACE carries out the replacements line-by-line.
By default SSREPLACE, specifies the options igo to s///, that is replacements are case-insensitive, and carried out for all matches on the line.

A Crash-Course in Perl Regexps

Here follows a brief summary of the three fields – old-string, new-string and options – for the Perl illiterate. For a complete description, refer to the file \LIB\POD\HTML\POD\PERLRE.HTML in your local Perl installation, or a suitable Perl book. (And if you think that isn't enough... About every new version of Perl appears to add new functionaility to the world of regexps.)

old-string

What is said here, also applies to the search strings you pass to SSGREP and the patterns you can use in GRANT.TEMPLATE, except for the operator \_ which is specific to SSREPLACE.

All alphanumeric characters (letters, digits and underscore) representes themselves. (Note: I'm here only considering the letters of the English alphabet. What happens if you specify characters outside ASCII is up to Perl, and not defined by AbaPerls.) An alphanumeric character preceded by a backslash, represents in many cases some special function. A non-alphanumeric character preceded by a backslash always match that character and nothing else. If the character does not have any special meaning, the backslash is optional. The following non-alphanumeric characters are operators in regexps, and must be preceded by backslash to match the character itself:

   $ @ / ( ) [ { + ? \ * . ^ |

Also keep in mind, that if old-string starts with two hyphens, you need to use a backslash to prevent AbaPerls to intepret them as a comment delimiter.

The follow table lists the most commonly used components to build regular expressions.

`.`	Matches any character.
*``**	Previous regular expression 0 or more times. *`hej` matches "he", "hej", "hejj", but not "hejhej". The expreission `(hej)`* matches "hejhej".
`+`	Previous regular expression 1 or more times.
`?`	Previous regular expression 0 or 1 time. E.g. `EXEC(UTE)?` matches "EXEC" and "EXECUTE".
`()`	Grouping to control in which order the expressions are evaluated, but also to get a back reference to use in new-string, more below.
`^`	Matches beginning of line.
`$`	Matches end of line.
`[]`	A group of possible characters. Works like in SQL. For instance, `[^0-9]` matches all non-digit characters.
`\|`	Separates alternatives. E.g. `(nisse\|pelle)` matches both "nisse" and "pelle".
`\_`	Matches a space character. (Applies to SSREPLACE only; this is not a Perl operator.)
`\b`	Matches word boundary. If you wish to search for "insid", but not want a match for "insidnew" or "newinsid", specify `\binsid\b` as your search string.
`\s \S`	`\s` matches a white-space character, i.e. space or tab. `\S` matches all characters that `\s` does not match.
`\w \W`	`\w` matches a word charcater, that is, a-z, A-Z, 0-9 and underscore. Whether it will match letters like ÅÄÖ is up to Perl. `\W` matches everything that `\w` does not match.
`\d \D`	`\d` matches a digit, 0-9. `\D` matches everything else.

new-string

Also for new-string the rule is that letters, digits and underscore represent themselves, but may carry a special meaning if they are preceded by backslash. You must precede the following non-alphanumeric characters with backslash to prevent Perl from apply any special meaning to them:

   @ $ / \

If new-string begins with two hyphens, you must precede them with backslash to prevent SSREPLACE to interpret the hyphens as a comment delimiter.

The following special characters are of interest:

\U Change the case of the letters following \U to uppercase.

\L Change the case of the letters following \L to lowercase.

\E Closes \U or \L.

\_ Inserts a space. This is not a Perl operator, but added by SSREPLACE.

$1 $2 ... Refers back to parenthesized grous in old-string. $1 refers to the first parenthesis etc. You can also write ${1}. See example below.

Say that we are change the datatype for all columns and variables that has "curcode" in the name from "ab_code" to "aba_curcode". We write this in the replacement file as:

   (curcode\s+)ab_code  ${1}aba_curcode

${1} here refers back to "curcode" and all white-space that follows it. "aba_curcode" will then appear in the same column as "ab_code" did.

repl-options

The search option which you are most likely to use is I, which instructs SSREPLACE to use a case-sensitive search.

You could also use G or O to prevent SSREPLACE to use s/// with the g and o options, but it is questionable whether this is a good idea.

The option x enables extednded regular expressions in Perl. These are beyond the scope of this crash-course.

An advanced option is e which means that new-string is a Perl-expression. If you use e, you still need to use \_ to specify a space.

You cannot use the options s and m with SSREPLACE.

For detailed information about these options, please refer to the Perl documentation.

`\U`	Change the case of the letters following `\U` to uppercase.
`\L`	Change the case of the letters following `\L` to lowercase.
`\E`	Closes `\U` or `\L`.
`\_`	Inserts a space. This is not a Perl operator, but added by SSREPLACE.
`$1 $2 ...`	Refers back to parenthesized grous in old-string. `$1` refers to the first parenthesis etc. You can also write `${1}`. See example below.