phreplace Documentation

Introduction

phreplace is a multi-line search and replace add on for PSPad. It allows multiple lines for search and replace terms, as well as supporting other standard search features such as:

Search, replace or replace all functions
Search only within selected text, the active document or all open documents.
Search from current cursor position or from start of document
Search in reverse direction
Search for whole words only
Search as case sensitive or ignore case
Seach using regular expressions
Save search history

Installation

Install File Structure

The zip file should contain the following files:

phreplace.dll
This is the phreplace application, containing all the processing and user interface. As it is a dll (dynamic link library) this file needs to be registered so PSPad can use it. See note for Windows Vista users in Support and Development. This file should be saved to the PSPad root directory e.g. C:\Program Files\PSPad\phreplace.dll.
phreplace.vbs
This is the script file which PSPad calls to start phreplace, it trys to register the phreplace.dll file if it's not already registered. This file should be saved under the PSPad VBScript directory e.g. C:\Program Files\PSPad\Scripts\VBScript\phreplace.vbs
phreplace.chm
This help file. Contains instructions to install and run phreplace as well as it's version history. This file should be located in the same folder as the phreplace.dll file.
phreplace.ini
The settings file, if this doesn't exist then phreplace will use the registry to save it's settings, this can be changed in the settings menu if necessary.

Portability of phreplace

Phreplace stores settings in an ini file by default (this can be changed to use the registry, see the settings menu) therefore once it has been extracted the PSPad folder can be moved without having to reinstall phreplace. This means it can be used with a portable copy of PSPad e.g. a copy of PSPad on a portable media device. Please note that phreplace will need to register the phreplace.dll file on each computer in order to run, the startup script does this automatically.

Starting phreplace

To start phreplace, click on the Scripts menu in PSPad and select Multiline Search / Replace . A shortcut key can be assigned to phreplace, by default this is Ctrl-Alt-F. This can be changed in the phreplace startup script (phreplace.vbs).

Using phreplace

Search

Enter a search term in the Search For text box and press search.

Replace

Enter a search term in the Search For text box and the text to replace in the Replace With text box. Press replace.

If the highlighted text is the next search match, the text is replaced.

Otherwise the next search term is highlighted.

The replace function alternates between highlighting the next search match, and replacing the highlighted match.

Replace All

Enter a search term in the Search For text box and the text to replace in the Replace With text box. Press the replace all button, the number of replacments is shown after the replace all has completed.

Search Options

Start From Beginning

Starts the search from the beginning of the document rather than from the current cursor position.

Search Backwards

Find the first match to the left of the cursor (or the end of the document if Start From Beginning is selected)

All Open Documents

Searches all the open documents in PSPad rather than just the active document. When combined with Start From Beginning, starts
searching from the first document, when combined with search backwards, searches the next document to the left.

Selected Text Only

Searches for matches only within the currently selected text.

Whole Word Only

Finds the next match where the search term is surrounded by non-word characters, e.g. Space, tab, comma etc.

Case Sensitive Search

Find the next match ignoring the case of characters, e.g. A is the same as a.

Use Regular Expression

Interpret search term as a regular expression, replace term can use backreferences (see Regular Expressions).

Regular Expressions

phreplace uses the vbscript regular expression engine, for more information on pattern matching, see the following Microsoft reference:
Microsoft Beefs Up VBScript with Regular Expressions

Note that the full stop (.) matches any character except \n. This means it also matches \r which can cause issues with Windows encoding which uses \r\n as the line break.

Backreferences

To use search matches in a replace term, surround the match you wish to use in parenthesis (brackets) and use $1, $2, $3 etc... in the replace term. e.g.

Text:	The quick brown fox jumps over the lazy dog
Search:	The quick brown (\w) jumps over the lazy (\w)
Replace:	The $1 $2
Result:	The fox dog

Use $& to match the entire search match.

Use $1, $2, etc. To match backreferences (parenthesis) in the search match.

Examples

Search: ^([^\n\r]+)$
Description: Matches a whole line.

Search History

When save search history is selected in the settings, each search or replace term used is stored in the search history, up to the last 10 searches. The search history is recorded in the settings and is saved between instances of phreplace.
The search and replace history is available by using the history button beside the search and replace text fields.

Settings

Settings for phreplace can be changed in the settings drop down menu. Settings that are turned on have a check mark (tick) beside them, click on a setting to toggle it on or off.

Use Ini File

If set, phreplace uses an ini file to store all history and setting information. If off phreplace uses the registry to store all history and settings. Toggling this open on and off copies all history and settings to the new location and deletes all records in the old location (i.e. turning on creates an ini file, copies all history and settings, then deletes all registry keys associated with phreplace). To decide whether phreplace is using an ini file or the registry, it checks for the existance of a phreplace.ini file in the same folder as the phreplace.dll file. If it exists it assumes it should use an ini file, if it does not exist then it uses the registry. This means if you delete the phreplace.ini file (or rename it), phreplace will not create a new file, it will use the registry. To restore the ini file, either select the Use Ini File option in the settings menu, or close phreplace, create an empty file called phreplace.ini in the same folder as phreplace.dll and restart phreplace.

Save Layout

If set, phreplace records the size and position of the phreplace window on the screen so that it appears at the same position the next time phreplace is started. If not set phreplace uses the default size and window position each time it starts.

Save Search History

If set, records the last 10 search and replace terms for reuse. When this option is turned off it deletes all currently saved search history (so don't toggle it on and off if you don't want to lose your search history). When this setting is off, search history is still recorded for as long as phreplace is kept open, but as soon as phreplace is closed the histroy is lost. See Search History for more information.

Always On Top

If set, the phreplace windows is always kept on top of other windows, including PSPad.

Tab Inserts Tab

If set, pressing tab when in the Search For or Replace With field inserts a tab character into the field. If off pressing tab changes the keyboard focus to the next control on the phreplace window.

Reset to Defaults

Selecting this menu item resets all options back to their original defaults (all options set on) including resetting the saved size and position of the phreplace window.

Support and Development

Settings for phreplace can be changed in the settings drop down menu. Settings that are turned on have a check mark (tick) beside them, click on a setting to toggle it on or off.

Use Ini File

Save Layout

Save Search History

Always On Top

If set, the phreplace windows is always kept on top of other windows, including PSPad.

Tab Inserts Tab

If set, pressing tab when in the Search For or Replace With field inserts a tab character into the field. If off pressing tab changes the keyboard focus to the next control on the phreplace window.

Reset to Defaults

Selecting this menu item resets all options back to their original defaults (all options set on) including resetting the saved size and position of the phreplace window.

Version History

2.0

Major redesign of code base.
Created file menu to turn settings on and off as well as access help files.
Created .chm help files.
Added search history buttons to recall last 10 search / replace terms.
Fixed the insert tabs functionality. When set on, pressing tab key inserts a tab character.
If off, pressing tabs moves to the next control on the window.
Configured keyboard shortcuts so they work properly now.
Improved handling large files. Doesn't crash when doing search / replace on a huge file,
although performance could still be improved.
Handled an error being thrown by the vbscript Regex object when passing in some badly formed regular expressions.
Added Write to Log setting (which defaults to off) to write some debugging log events to a ‘phreplace.log’ file in the same folder as the ‘phreplace.dll’ library.

1.4

Released new stable version, only know bug is when word wrap is on.
Stop phreplace defaulting to 'Start from Begining' everytime it is opened.
Display the search match in the middle of the screen.

1.3

Changed the way phreplace handles open files in PSPad, you can now
change the active file or open and close files while phreplace is
running without phreplace crashing.
After completing a replace all, you can now undo all changes with just
one undo step.
Replace All runs much faster.
Regular Expressions now run in Multiline mode.
When matching a new line with Regular Expressions, the first character
on the new line was highlighted, this should be fixed.
Fixed bug when using replace all on selected text, phreplace truncates
some of the following text.
Added ability to use $1 in Regular Expression replaces.
Fixed bug when resizing phreplace, the Close button does not update
it's position.
Previously using $1, $2 substitutions in phreplace only worked when
using replace all, it now works for a single replace as well.
Fixed bug when doing a search in selection, the length of the selection
didn't take into account line feeds.
Fixed bug when performing a reverse search, phreplace kept finding the
same match (didn't move past it).
Fixed bug when doing a Replace All on All Open Docs, the last document
isn't searched.
Fixed bug when doing a Replace All on All Open Docs, the last document
isn't searched.

1.2

Fixed Buffer Overflow error when searching through large files.
Save Settings in INI file rather than registry.
Added support for regular expressions.
When opening phreplace, if text is selected and is longer than 200 chars
or is more than one line, 'Search in Selection' is checked, otherwise if
a small amount of text is selected this text is used as the search.
Added Modeless support for phreplace. You can now have phreplace open
and still be able to use PSPad.
phreplace window is always on top.
Added ability to set the options of save layout, modeless form and
always on top in the ini file.
Fixed bug, shouldn't allow search / replace / replace all when search
field is empty.
When doing a Regular Expression search, unless the highlighted text is
exactly the same as the search text, you can't replace it.
Show error message if user tries to search on an editor which is closed.

1.1

Used better hack for getting the starting point of the current
selection, previously when searching in a selection it would add a redo
step to PSPad, this no longer happens.
When pressing tab in textbox the tab character is inserted rather than
focus moving to the next control on the screen.
phreplace now utilises the PSPad icon.
Fixed Bug: When starting phreplace with no editors open, phreplace
throws an error.
Esc key closes phreplace.
Keyboard shortcuts setup on buttons.
Default text in Search field is highlighted when phreplace starts.
Set Ctrl+Alt+F as shortcut key to start phreplace.
Removed Minimise and Maximise buttons.
Saves window position and size when closing.
If user has selected text when starting phreplace the 'Search in
Selection' option is ticked.

1.0

Inital application release.

Troubleshooting

Below are details on phreplace error message and possible fixes.
If these do not help you can comment out the line "On Error Resume Next" in
the phreplace.vbs script to get a more detailed error message.

Error 1: Unable to register library XXXXXXXX.dll
If the phreplace.dll library is not already registered or seems to be an old
version, the script will try to load the library, if this fails you will see
this error message. If the library seems to be an old version it will try to run
the old version after you click ok, if this fails of the library is not
registered you will see Error 2.
FIX: Copy phreplace.dll to the PSPad program folder
(e.g. C:\Program Files\PSPad\) or copy phreplace.dll to your Windows system
folder and type at a command prompt: regsvr32 "phreplace.dll"

Error 2: Unable to start phreplace add-on
The phreplace object could not be started, most likely because the library is
not loaded.
FIX: Copy phreplace.dll to the PSPad program folder
(e.g. C:\Program Files\PSPad\) or copy phreplace.dll to your Windows system
folder and type at a command prompt: regsvr32 "phreplace.dll"

Error 3: There was an error running the phreplace add-on
The phreplace object loaded ok but failed when performing an operation. This
could either be a bug or you may have an old version of phreplace.dll
FIX: Download and install latest version of phreplace

Known Bugs

Need to improve performace when searching large files.
Would like to have the search controller run in a seperate thread so user can cancel a long running replace all.
When searching / replacing / undoing operations in PSPad with wrod wrap on, errors sometimes occur. This seems to be a problem with PSPad as it happens with the default search dialog as well.
Need to create a Vista compatible version - how can we register a dll using vbscript?