Copyright: Copyright © 1997 to Bill Klein


Getting Started With BK ReplaceEm

Hello, and welcome to BK ReplaceEm, your premiere quality string-replacing utility. The following sections should be enough to get you going with BK ReplaceEm. I have tried to make the program as intuitive as possible while not stripping out powerful functionality, but at the very least, I recommend you read the section, How Things Are Structured, as a quick crash course on how things are setup and related to each other in the program. Context-sensitive help is available everywhere in the program, so when in doubt, simply right-click and choose “What’s This.” Enjoy the program!

•	What Is it?

•	What Can It Do?

•	How Things Are Structured

The following sections are provided for those that want to get more in-depth information about certain parts of the program:

•	What Does This Do?

•	Advanced Edit & Keys Codes

Please do not hesitate to get in contact with the author for questions, comments, or suggestions:

    E-Mail:	Bill Klein <bklein@total.net>
    Web:	http://bk.base.org/replace/


What Is It?

At its core, BK ReplaceEm is essentially a text search-and-replace program. However, unlike the search-replace functionality of a standard text editor, BK ReplaceEm is designed to operate on multiple text files at a time. And you need not only perform one search-replace operation per file – you can setup a list of operations to perform. If different groups of files need to have different operations performed on them, this is no problem either. You can also specify a backup file for each file processed just incase the replace operation didn’t do exactly what you wanted.

When specifying which files to be included in a particular replace operation, you can add one file at a time, or you can tell BK ReplaceEm to use all the files from a particular folder – or the files from that folder that match a given file filter (such as *.txt or *.html). You can also decide to include the files from all subfolders of that folder.

One very powerful feature of BK ReplaceEm is that you can specify that the destination of the altered file be some other location than where it originally came from. This is handy if, for instance, you want to have some search-replace operations performed on a particular file and have it saved to a destination file, and then want to have different search-replace operations performed on the same file, and have it saved to a different location.

When the replace operations are performed, a log file is generated to let you know if everything went ok; Information about which files were processed, where they were saved to, where they were backed up to, and how many replace operations were performed on them are provided.


What Can It Do?

There are a great many things you can do with BK ReplaceEm to improve your productivity. Personally, I wrote the program because although there were many search-replace programs available, they were either too much of a hassle to use (requiring one to learn an entire scripting language just to do some search-replace operations), or weren’t powerful or flexible enough to do what I wanted. Here I present an example of one of the ways in which I use BK ReplaceEm nearly every day.

I maintain a set of web pages at http://bk.base.org/. I also have a mirror for these pages – for simplicity let’s say that my pages on the mirror have their root in http://www.mymirror.com/bk/. There are multiple pages located on these sites. Some equivalent pages on the main site and the mirror are located as follows:

http://bk.base.org/	—»	http://www.mymirror.com/bk/

http://bk.base.org/programs/	—»	http://www.mymirror.com/bk/programs/

http://optima.base.org/	—»	http://www.mymirror.com/bk/optima/

Now let’s say that at the bottom of each of my pages I wanted to keep a link to each of the other pages on that same site. From the root pages (http://bk.base.org/ and http://www.mymirror.com/bk/) if I wanted to make a link to the programs page, I could make the link to “programs/” and things would be fine for both the mirror and the main site. A problem arises with the optima page though – there is no one link which would work for both the mirror and the main site. Also, linking from the programs page to the root page could only work with both sets of pages using a link to “../”, but this does not work with all web browsers. Clearly the only possible solution is to maintain to entirely different sets of web pages for the main site and the mirror site, and this was precisely what I was forced to do before I developed BK ReplaceEm.

Aside from being a disaster to update, the two sets of pages will inevitably get out of sync sooner or later. Luckily, using BK ReplaceEm solves the problem nicely. Now I have one main set of pages on my hard-drive, which are the only pages I update, located in C:\BK Pages\Generic\. Anywhere in these pages where I wish to place a URL to the root page, I have the text %%%_bk_url_%%%. Likewise, I have %%%_programs_url_%%% for the programs page, and %%%_optima_url_%%% for the optima page.

I have two replace groups setup in BK ReplaceEm – one called “Main Site,” and the other called “Mirror Site.” In the “Main Site” group, each of the above %%% strings are set to be replaced by the appropriate URLs for the main site. Similarly, in the “Mirror Site” group, the same %%% strings are set to be replaced by the appropriate URLs for the mirror site. When I perform the replace operation using BK ReplaceEm and this setup, the “Main Site” pages are all saved, with the correct URLs, to the folder C:\BK Pages\Main Site\, while the “Mirror Site” pages are saved, also with the correct URLs, to the folder C:\BK Pages\Mirror Site\. In this way I need only ever modify the generic version of the pages and run BK ReplaceEm on them before I upload the generated and updated site-specific pages to their appropriate locations.

As an added bonus, if I were to ever get another mirror site for my pages, I would only need to add a new replace group for the mirror in BK ReplaceEm, and I would never have to worry about changing my source pages to work properly with the new mirror’s setup.


How Things Are Structured

The structure of BK ReplaceEm is fairly simple, but it would be advantageous for you to understand it fully before you start working with the program. Read this section to get familiar with how things are setup.

The basis for everything you do will be the replace groups. Each replace group can have associated with it a set of search-replace strings. To add a new group, you can click on the Add Group button in the main window. Now that your new replace group is created, you can add strings of Original Text and corresponding Replacement Text by double-clicking in the appropriate cell of the grid at the bottom of the main program window. Alternatively, you can right-click on the desired cell and choose Advanced Edit.

Also associated with each replace group are multiple files. To add a file (or a folder) to a group, right-click on the group and chose Add File(s). You can add as many files as you desire to each replace group, and you can have as many replace groups as you wish. When you start the replacing process, BK ReplaceEm will go to the first replace group and process each of the files associated with it using the search-replace strings associated with that group. Then the next replace group will be handled, and each file in there will be processed according to the rows of Original Text and Replacement Text in that group… And so on until all the groups and all the files have been handled.

Remember:	The rows of Original Text and Replacement text are associated with a particular group and therefore all its associated files – the rows of search-replace text are not associated with individual files.

By default, the replace groups you setup are stored globally. What this means is that if you create some replace groups with associated search-replace text for each one, when you exit and come back into the program, the same groups will still be there.

On the other hand, files associated with the groups are not stored globally. Instead, you can save a file set (by choosing Save File Set from the File menu) of all the files currently associated with replace groups. You can then, at a later time, reload this file set (by choosing Open File Set from the File menu), which will load in the files that were associated with particular replace groups when you saved the file set. If, between the time of saving and loading the file set, you had modified the replace groups, say, by adding a new line of Original and Replacement Text to one of the groups, the new modified group will continue to be used even after you load the file set since, as was just mentioned, the replace groups are stored globally, and are not specific to individual file sets. (This behaviour can be changed in the program options, but it is only recommended if you have a good reason to do so).


What Does This Do?

BK ReplaceEm’s menu is structured as follows. Click on any item of the items below for an explanation of what it does:

File New File Set Open File Set… Save File Set Save As… Save Replace Groups Restore Replace Groups Exit View Toolbar Status Bar Replace Log Options…	Replace Add Group Remove Group » Rename Group Remove Row… Advanced Edit… Insert File(s) To » Remove File / Folder… File / Folder Properties Start Replacing Help Help Topics What’s This… About BK ReplaceEm
Note:	Context help is available everywhere in BK ReplaceEm, so when in doubt, simply right-click and choose “What’s This?”


Advanced Edit

Your can bring up the advanced edit dialog box by right-clicking on the desired cell of Original Text or Replacement text and choosing Advanced Edit. There you can edit the text as you would in any text editor – pressing the Enter key for carriage returns and the TAB key for tabs and so on. When you click the OK button, the text you entered will be converted into text usable by the program and placed into the cell you had originally selected to edit.

If you wish to edit text directly in their cells rather than using the advanced edit dialog box, you can simply double-click on the desired cell. If you wish to use any of the special keys however, you will need to enter the key codes manually. The codes available are as follows:

Key	Code
Enter (CR+LF)	{}e
TAB	{}t
{}	{}}
Carriage Return	{}r
Line Feed	{}n

In addition to these, search strings which begin with the code “{}s” (without the quotes) will be searched for in a case sensitive manner (matching case), while search strings beginning with the code “{}i” (without the quotes) will be searched for in a case intensive manner (ignoring case). If neither of these codes are specified, the Default Search Case specified in the program options will be used for the search. Of course these two codes apply only to the Original Text, as opposed to the Replacement Text.


The first level of this tree view displays the list of replace groups available to you. Any files associated with a particular group are displayed as children of that group. Right-click on any item for a popup-menu of actions which you can perform on it.


This is a list containing all of the replace groups you have defined. You can choose one to display its contents below, or you can click the “Add Group” button to add a new group to this list.


Click this button to add a new replace group to those already available. You will be able to edit its contents below.


Double-click on a cell to edit its contents. When a replace procedure is performed on a file that is associated with this group, all occurrences of Original Text are replaced by corresponding Replace Text located beside it. For advanced editing, right-click on a cell, and choose Advanced Edit.


In the about box you find information about the program and its author. Contact information is also displayed here.


This is the Internet e-mail address of the author of the program. You can use this e-mail address if you have any questions, suggestions, or comments about the program.


This is the web page URL of BK ReplaceEm. The latest version of BK ReplaceEm is available for download there, as well as information about the program.


Click here to close this dialog box and return to the program.


In the advanced edit dialog box, you do not type in special codes for tabs and enters - instead, you use the Tab key and the Enter key respectively, as you would in any text editor. Similarly, you need not worry about how you use the control keys: {}. You may use them freely as part of your text.


Here is where you enter (or edit) the text of the cell which was selected when you chose advanced edit. Note that if you had entered any character codes (such as {}e for enter) manually into the cell, they are converted to their corresponding characters and displayed here as such. Likewise, if you wish to enter characters like tab and enter here, do so as you would regularly, rather than typing in their {} counterparts.


Click here to close this dialog box and apply the new text to the selected cell.


Click here to close this dialog box and ignore any changes you have made to the selected cell’s text.


Chose from the list of options to decide how this string will be searched for in the source file. If a case sensitive search is selected, only strings which mach the search string exactly, including case, will be replaced with the replacement text. If a case intensive search is selected, only the string’s content need mach, and case is ignored in the search. If you chose to use case from options, the type of searching will be determined by what you have selected on the Replace page of the Options dialog.


Click this tool button to start the replace procedure. All files in the different replace groups will be processed, and the file names and paths will be added to the replace log according to the program options you have set.


Click this tool button to bring up the replace log. There, information about the last replace procedure is displayed. In the program options, you can specify which file names and paths processed you would like to be included in the log.


Click this tool button to add a replace group. When you do so, the group will be given a default name, which will be ready for editing to something more appropriate. You can then add files to the group, and add sets of original text and replacement text by editing the grid.


Click this tool button to delete the currently selected replace group. If a file is selected, the group to which it belongs will be deleted. Note that when you remove a replace group, all the files associated with it (and their settings, such as target and backup) are removed with it, so you might want to move the files to a different group before your remove it. You can do this by dragging the desired files from one group, and dropping them onto another.


Click this tool button to rename the currently selected replace group. If a file is currently selected, the group to which it belongs will be renamed.


Click this tool button to remove the currently selected row of original text and accompanying replacement text.


Click this tool button to bring up the advanced edit dialog box with the currently selected cell of original text or replacement text available for edit there. In the advanced edit dialog box, you do not type in special codes for tabs and enters - instead, you use the Tab key and the Enter key respectively, as you would in any text editor. Similarly, you need not worry about how you use the control keys: {}. You may use them freely as part of your text.


Click this tool button to add a file (or multiple files from a folder) to the currently selected replace group. If a file is currently selected, the new file(s) will be added to the group that the selected file belongs to. Note that you can choose the default file options (for newly added files) in the program options.


Click this tool button to remove the currently selected file from its replace group.


Click this tool button to bring up the file properties of the currently selected file (or folder). In the file properties dialog you can choose the source, target, and backup paths.


Click this tool button to bring up the What’s This? help pointer. The next control, toolbar button, or menu item which you click on will display a small help popup with a brief description of what it does, and how to use it (like what you see here).


Click the appropriate option button to specify whether you want to perform the replace operation on a specific file, or multiple files in a folder. If you choose the latter, you can specify a filter (such as *.txt), so that the replace operation is only performed on certain files in that folder.


If you have specified a folder as your source, you can specify a file filter (such as *.txt), so that the replace operation is only performed on certain files in that folder.


Here you should specify the path of your source file or folder (depending on the source type you have chosen). You can click on the ‘…’ button to the right of this text box to browse for a particular file or folder.


If you have chosen a folder as your source type, you can check this option button to specify that you wish to include all files in all subfolders of the folder you have entered into the ‘File / Folder Path’ text box (as well as include all files from the folder specified). Files from subfolders are subject to the same filtering as files from the main folder, as specified in the ‘File Filter’ text box.


If this option is specified, any changes made to a file in a replace operation will be saved back to the original file. Otherwise, you specify the location that the modified file is saved to.


The modified versions of files to which replace operations have been performed will be saved to the path specified here. If your source is a folder, this path must also be a folder. Likewise, if your source is a file, this path must also be a file. Click the ‘…’ button to the right to browse for the desired path.


If this option is checked, then the folder structure under the main folder chosen as source path will be maintained under the destination path folder. For example, suppose your source folder is C:\Files\, and C:\Files\Text\info.txt is processed. If this option is checked, and your destination path is D:\Dest\, the file will be saved to D:\Dest\Text\info.txt. If this option is not checked, it will be saved to D:\Dest\info.txt. This can lead to problems if more than one file of the same name exists in your source (in different folders). When the second file is processed it will overwrite the first (or prompt you, depending on the options you have set). Of course, this option only applies if your source is a folder, and if you have enabled the “Include files in all subfolders” option.


Check this checkbox to specify that you wish to make backups of the files processed.


Here, specify the extension to be used for the files backed up. The extension will be added on according to the specified extension type.


Here you choose how the specified file extension should be added to the backed up files. Append Extension will add the specified extension to the file. For example, if the file being backed up is info.txt, and the specified extension is backup, the backed up file will be called info.txt.backup. If Replace Extension was chosen, the file would have become info.backup. Choose No Extension Change to use the original file names in the backup. You are responsible for making sure that the backup path will not include files that will have the same name. If such a conflict exists, old files will be overwritten, or you will be prompted (depending on the options you have set).


Check this option to save backed up files to the same paths that their original counterparts came from. Note that you are responsible for making sure that an appropriate file extension is added so that no file conflicts exist. If such a conflict exists, old files will be overwritten, or you will be prompted (depending on the options you have set).


The backed up versions of files to which replace operations have been performed will be saved to the path specified here. If your source is a folder, this path must also be a folder. Likewise, if your source is a file, this path must also be a file. Click the ‘…’ button to the right to browse for the desired path.


If this option is checked, then the folder structure under the main folder chosen as source path will be maintained under the backup path folder. For example, suppose your source folder is C:\Files\, and C:\Files\Text\info.txt is processed. If this option is checked, and your backup path is D:\Dest\, the file will be saved to D:\Dest\Text\info.txt. If this option is not checked, it will be saved to D:\Dest\info.txt. This can lead to problems if more than one file of the same name exists in your source (in different folders). When the second file is processed it will overwrite the first (or prompt you, depending on the options you have set). Of course, this option only applies if your source is a folder, and if you have enabled the “Include files in all subfolders” option.


Click this button to close the dialog box and apply the changes you have made.


Click this button to close the dialog box and ignore any changes you have made.


Normally, Replace Groups are stored independent of individual File Sets, and all File Sets share a common set of Replace Groups. Check this checkbox if you want to use a local set of Replace Groups with each File Set. When you open a File Set, its associated Replace Groups will also be opened, and are independent of another File Set's Replace Groups.


If this option is checked, when you exit the program the Replace Groups loaded at that time will be saved to the program’s global Replace Groups file.


When you click this button, the File / Folder Properties dialog box will be displayed. In it, choose the options which you would like to use as default when you add new files to your Replace Groups.


You can manipulate these Log options to decide whether a log of a replace operation is kept, and if so, whether it is displayed immediately after the replace operation is completed. You can also specify which file names and paths processed in the replace operation should be included in the log. If you choose not to include the file names and paths, only the number of files processed is used.

Note: When a log is generated, it deletes the previous log generated, so you should probably examine the log after each replace operation, and save it to a file if you wish.


Use these options to decide if and how files should be overwritten in case of a conflict during a replace operation. In the case of target files, the last two options (Prompt before overwrite of files which already exist and Do not overwrite files which already exist) will only apply if the “Save processed file(s) to original location” options is not checked. A log entry is added for files which are not written so as to indicate this.


This option allows you to start BK ReplaceEm simply by double-clicking on a saved File Set in explorer - BK ReplaceEm will open with the File Set loaded. Disable this feature if you have another application which uses the BKR file extension, and you want to keep your files associated with that application instead of this one.


BK ReplaceEm makes several entries in the system registry. If you wish to remove BK ReplaceEm from your system, you should first run the program, and click this button. This will remove all the entries which BK ReplaceEm has added to the registry, and then exit the program. This function will not delete the files associated with the program. You must manually remove the files yourself which are all contained in the directory in which BK ReplaceEm was originally placed.


Chose from these two options to decide how strings will be searched for in source files by default. If a case sensitive search is selected, only strings which mach the search string exactly, including case, will be replaced with the replacement text. If a case intensive search is selected, only the string’s content need mach, and case is ignored in the search. You can override the search method you chose here on a string by string basis by choosing the desired search method in the advanced edit dialog box. You can access the advanced edit dialog box by right-clicking on the desired cell text and choosing Advanced Edit.


When you perform a replace operation, a log is generated according to the options you have set, and is kept here. Note: When a log is generated, it deletes the previous log generated, so you should probably examine the log after each replace operation, and save it to a file if you wish. You can use the Log menu to save or clear the log, or close the log window.


Choose this menu item to remove all the files currently associated with the different replace groups and start a new file set.


Chose this menu item to remove all the files currently associated with the different replace groups and open a previously saved file set.


Choose this menu item to save all the current associations of files with replace groups to a file set. The file set will be saved to the file last saved to or opened. If there was no file set saved or opened in the past session (or you have chosen New File Set since), you will be prompted to specify where the file set should be saved to.


Choose this menu item to save all the current associations of files with replace groups to a file set. You will be prompted to specify where the file set should be saved to.


Choose this menu item to immediately save all replace groups, with their associated rows of Original Text and Replacement Text, to the global replace group file. Normally this file is saved when you exit BK ReplaceEm and loaded when execute it.


Choose this menu item to restore the replace groups to their state when you last saved/loaded them. Normally the replace groups are saved when you exit BK ReplaceEm and loaded when execute it, although you can force an immediate save by choosing Save Replace Groups from the File menu.


Choose this menu item to exit BK ReplaceEm.


Choose this menu item to toggle the toolbar between being visible and hidden.


Choose this menu item to toggle the status bar between being visible and hidden.


Choose this menu item to display the replace log window.


Choose this menu item to display the program options dialog box.


Choose this menu item to add a new replace group to those already available.


Choose one of these menu items to remove that particular replace group.


Choose this menu item to rename the currently selected replace group.


Choose this menu item to remove the currently selected row of Original Text and corresponding Replacement Text.


Choose this menu item to bring up the advanced edit dialog box with the currently selected cell’s text available for edit.


Choose one of these menu items to associate a file (or a folder of files) with that particular replace group.


Choose this menu item to remove the currently selected file from its replace group.


Choose this menu item to bring up the properties for the currently selected file or folder.


Choose this menu item to start the replacing process. All the files in all the different replace groups will be processed.


Choose this menu item to bring up a list of the available help topics for BK ReplaceEm.


Choose this menu item to bring up the What’s This? help pointer. The next control, toolbar button, or menu item which you click on will display a small help popup with a brief description of what it does, and how to use it (like what you see here).


Choose this menu item to display the about box. There you will find information about the program and author, as well as contact information.


Choose this menu item to remove the currently selected replace group.


Choose this menu item to associate a file (or a folder of files) with the currently selected replace group.