				*** SearchReplaceGlobalPy Help ***

Welcome to SearchReplaceGlobalPy, a global search/replace utility written in Python.

SearchReplaceGlobalPy [version] is Copyright 2011, P. Lutus.

SearchReplaceGlobalPy [version] is released under the GPL:

http://www.fsf.org/licensing/licenses/gpl.txt

This file contains general information for using SearchReplaceGlobal. Be sure to visit the SearchReplaceGlobalPy Home Page at:

http://www.arachnoid.com/python/searchreplaceglobal 

* What is SearchReplaceGlobalPy?

SearchReplaceGlobalPy is my solution for a problem I have noticed over years of maintaining large sets of data files -- I needed a way to search for particular files, then search for particular patterns within those files, and finally to replace one pattern with another, using regular expressions.

SearchReplaceGlobalPy is primarily intended for use with Linux, but I don't see any particular reason it wouldn't work under Windows just as well -- but I want to emphasize that I haven't tried using it there.

There are a number of command-line utilities in Linux to meet some of the needs met by SearchReplaceGlobalPy, but they are rather cumbersome to use. "grep" is good at searching files, but won't replace file contents and isn't particularly good at scanning an entire directory tree. "find" will scan a directory tree, but it is not particularly suited for scanning file contents.

"grep" allows you to specify the file contents to search for, but not the files to be sought if a tree search is undertaken. "find" allows you to specify a file filter, but then has a rather baroque syntax for examining the contents of files.

Neither "grep" nor "find" allow you to replace file contents. SearchReplaceGlobalPy will search a specified directory tree for a specified filename pattern, then it will search the matched files for a particular regular expression, then it will replace one expression with another if you tell it to.

If SearchReplaceGlobalPy edits a file, it automatically creates a backup file in the same directory by appending a tilde "~" to the file name. It does this for each matching file:

1. Read "filename".
2. Apply user-entered regular expression.
3. If the file is changed, it is written out, but only after a backup of the original is created, named "filename~".

* System Requirements

SearchReplaceGlobalPy is written in Python and GTk, so both Python and the GTk libraries must be present on your system (they are both free).

The deep thinkers among my readers will wonder what is the point of my listing these essential prerequisites in the help file for a program that must be running for the help file to be read ... well, the plain-text help file is available in the download package, readable before installation.

* More Detail

SearchReplaceGlobalPy maintains its state between uses, and when it is exited, it places its state in this file on your system:

[ini_file]

If something happens to disable SearchReplaceGlobalPy, or simply if its present state annoys you, simply exit the program, delete this program data file and start again.

The primary display of SearchReplaceGlobalPy includes a set of entry windows, one each for:

1. Current search path.
2. File filter, a regular expression filter used to select files.
3. A search regular expression to examine the file contents.
4. A replacement pattern.

Plus a number of option checkboxes and command buttons.

The buttons are ordered left to right in increasing order of ... well, frankly ... danger:

* If you press the "Scan" button, the entered "File Filter" string will be applied to files in the selected directory tree and a list of matching files will be created (readable by pressing the "found" tab at the bottom of the display).

* If you press the "Search" button, each of the files will be read and scanned for matches for the entered "Search for" string, and a list of matches (along with the number of occurrences per file) will be placed in the "Found" window.

* If you press the "Replace ..." button, which you should seriously think about before doing, all the files that met the "File Filter" criterion, and that contain the "Search For" string, will have the "Replace With" string applied to matching patterns (all cases, if "Global" is selected). In this case, as explained above, a backup file will be created for each changed file (and the program won't save unchanged files).

For the "Replace ..." command, since this will actually change file contents, a warning dialog appears for confirmation.

The next button, marked "Undo ...", will try to restore each changed file from its backup. This will obviously only work for the action immediately conducted, so if you expect to undo an action, you must do so immediately, before conducting another search. Another way of putting this is there is only one level of undo, and that level is volatile.

The next button, marked "Erase ...", can be used to remove the clutter of backup files once you are satisfied that you have done more good than harm.

* More and Better

SearchReplaceGlobalPy has some additional features. Once you have created a list of matching files in the "Files Found" window, you can click a file name in that window and an editor will be launched to allow manual editing. This is for those cases where a regular expression can find the target files but can't make the needed changes. If the clicked file is a graphic, a graphic viewer will be launched instead of an editor.

Because I am thinking of SearchReplaceGlobalPy as a cross-platform program, I should add that the editor and graphic viewer choices appear at the top of the SearchReplaceGlobalPy class definition in "searchreplaceglobal.py", so the user can change them to suit what is available as well as personal taste.

* Regular Expression Notes

First, the "File Filter" entry is a regular expression. This is not the norm for file scanning programs, which ordinarily use a simplified globbing expression syntax for this particular task. If you type "*" to accept all files, this will produce an error instead of a list.

Second, in the regular expression entries, entered sequences of "\t", "\r" and "\n" will be translated into tab, return and newline respectively (see below in "Escape Handling" for more detail on this).

Here is a pattern one can use to find all typical Web pages in a directory tree (for these examples, make sure the "case" checkbox is not selected):

\.html?$

Meaning ".", followed by "htm", followed by a single, optional "l", at the end of the path.

To find all HTML and PHP files that use common suffixes:

\.(html?|php)$

The "Search For" entry is a regular expression as well. In "Replace With", the syntax follows the Python convention that "\1" matches the first capture group, "\2" matches the second, and so forth.

Next example:

"Search For": (\w+)\s+(\w+)

"Replace With": \2 \1

If the "global" option were selected, this example would switch the order of all the words in all the files.

Here is an example that will strip all HTML tags from the target files:

"Search For": <.*?>

"Replace With": (nothing)

This simple approach will fail is there are nested "<" or ">" symbols, or if these symbols are used as ordinary characters (shouldn't be true in good HTML, but it does happen).

* Checkboxes and their meanings

* "Subdirs" Checkbox

This checkbox enables a full-depth search, through all subdirectories below the search directory.

* "Global" Checkbox

This selector causes all matches to be replaced, not just the first.

* "Case" Checkbox

Makes the content search case sensitive. This has no effect on the file filter search.

* "DotAll" Checkbox

This checkbox makes the '.' metacharacter match linefeeds in regular expressions. By default this metacharacter matches everyting except linefeeds.

* "Multiline" Checkbox

This selector causes "^" and "$" to refer to the beginning and ending of each file line (split by linefeeds), rather than the beginning and ending of the entire file.

* "Reverse" Checkbox

This feature may cause some confusion. The "Reverse" checkbox selects and lists those files that don't match the search string. It doesn't work during search & replace, it only works on search-only actions (it's only used while finding files having certain contents). Also, it doesn't reverse the sense of the file filter search, only the content search.

* "Update" Checkbox

This checkbox causes overwritten files to be given the current date and time (the default filesysem behavior). If disabled, overwritten files retain their original dates and times. But be careful -- in some cases, if you have an automatic backup system and if you disable updating, the backup system may not recognize the file as changed and may not back it up.

* Control and special characters

Most control characters may be submitted to the regular expression entry panes as escaped letters (\n = linefeed, \r = carriage return, \t = tab etc.) and the usual regular expression metacharacters (\w for wordlike character, etc.) may be entered as well.

* Caveats

Many of my readers will be seasoned computer professionals, but just in case this isn't true, I add this advice. Before using SearchReplaceGlobalPy to scramble your files, make a full backup in a separate location. Because SearchReplaceGlobalPy does exactly what its name implies, it is entirely possible for a single ill-considered regular expression to empty all your files of their content.

It would be a mistake to rely solely on the backup files that SearchReplaceGlobalPy creates. They might be deleted, be the wrong files, or go out of date as you proceed with operations on the file tree. Backing up is the only reliable way to avoid data loss.

* Further

For more information about SearchReplaceGlobalPy, including to check for the latest version, visit:

http://www.arachnoid.com/python/searchreplaceglobal

Or click the "Online" button to automatically visit the SearchReplaceGlobalPy Home Page.





