Home | Ruby | SearchReplaceGlobal |     Share This Page

Find it, change it, save it.

All content Copyright © 2007, P. Lutus

Version 1.4, 02/18/2007

Introduction | In the Context of Linux/Unix | Doing it in Stages | Some Details | Revision History

(double-click any word to see its definition)

Source package: searchreplaceglobal.zip (18.2 KB)

I've been rewriting my entire Web site recently, replacing all HTML page content with XHTML, as well as finding and correcting decade-old syntax errors by using various kinds of code validators. At times during this project I encountered cases where each and every one of my nearly 500 Web pages had the same error, or needed the same change.

What it is: A powerful file maintenence utility.
Written in: Ruby 1.8.4.
Requires: The Qt library, version >= 3.3,
and Ruby, version >= 1.8.
Both Qt and Ruby are free, cross-platform and open-source.
Purpose: Intended to be a superset of "grep" and "find", plus the ability to replace file contents.
Source: Ruby interpreter and related files: searchreplaceglobal.zip (18 KB).
Primary Source Listing: searchreplaceglobal.rb Pretty-printed (this one file isn't enough to run the program).
License: GPL.
(Those of my readers who have used the various incarnations of my program Arachnophilia will recognize this ability right away — I have always wanted to be able to apply a successful regular expression to a lot of files at once.)

Over time I wrote and modified a Ruby command-line utility to perform these changes, and that worked out well. Then, after successfully making certain structural changes to 500 Web pages in one fell swoop on a number of occasions, I decided this might be a more useful program if it were given a better interface. So I added a GUI and produced more internal structure to support this kind of file maintenance activity. And SearchReplaceGlobal is the result.

So here it is. SearchReplaceGlobal is a tool for programmers and Web site maintainers. It's written in Ruby, so it should be easy to understand and change if necessary.

In the Context of Linux/Unix
There are any number of cool file manipulation utilities in Linux and other Unices. I can use "grep" to find patterns in files, and I can use "find" to search a directory tree for specific files.

But "grep" is not very good at searching a directory tree, and "find" is not very good at searching the contents of files (although one can make these things happen). Finally, neither "grep" nor "find" can replace file contents (many will regard this as a Good Thing™).

Be warned. If you tell it to, SearchReplaceGlobal will replace all file contents based on a user-entered regular expression. This means you can empty an entire hierarchy of files of all their content because of a mistaken entry. Be very careful when using the search/replace feature, and create a complete backup of the files to be operated on.

SearchReplaceGlobal tries to address this gap in the panoply of utilities, also it has a nice graphic interface with drop-down lists of prior entries.

Also it saves its entire state between uses, a property I try to build into all my programs. If you have moved the SearchReplaceGlobal window to the lower left of the display and selected a particular search string and particular options, and you decide to exit the application, all these choices will be restored when you run the program again.

Doing it in Stages
A typical SearchReplaceGlobal operational sequence runs from the least risky operation (scanning a directory tree for files whose names match a provided regular expression) to the downright dangerous (reading, editing, and saving an entire tree of files based on a user-entered regular expression). And I want to emphasize the risk in the search/replace option — if applied imprudently, it really can reduce your entire file system to a spirit world of files with names but no contents.

Please run SearchReplaceGlobal to familiarize yourself with its layout and operation, or refer to the graphic on this page to get some context for the following steps.

Typically, one would use SearchReplaceGlobal according to this sequence:

  • Scan (quite safe)
    • Choose a search path
      Use the "Search Path" drop-down list or the associated "Browse" button to select a directory for search.
    • Enter a filename match argument
      Enter a regular expression into the window marked "File Filter" for the desired filename match.
    • Press "Scan"
      The program carries out the search, and a list of matching files is displayed under the "Found" tab.
  • Search (still safe, but not so quick)
    • Provide a content search argument
      Enter into the window marked "Search For".
    • Press "Search"
      Each of the files that meets the file selection regular expression are read and compared to the content search regular expression. A list of matching files is displayed under the "Found" tab.
  • Replace (very dangerous if not used carefully)
    • Provide a replacement argument
      Enter a replacement regular expression in the window marked "Replace With".
    • Press "Replace ..."
      After asking for confirmation, the program will read each matching file and perform the specified search and replacement. If the result is different than the original file contents, a backup file is created named "filename~", and the original file contents are replaced.
  • Undo (only really feasible immediately after a search & replace operation)
    • Press "Undo ..."
      After asking for confirmation, the program will replace each changed file with its backup.
  • Erase (for those possessed by great confidence in the outcome)
    • Press "Erase ..."
      After confirmation, the program will erase all the filenames with a "~" final character in the current search directory tree. This feature is for those suffering from OCD, and/or those who believe there is no need for backups to files that appear to be all right after five minutes of testing.
Some Details
There are some additional features in SearchReplaceGlobal that make its primary task easier to carry out. One of these is the fact that the files listed under the "Found" tab can be edited by clicking on their names. An editor is specified at the top of the "searchrplaceglobal.rb" Ruby source file, the user can change this to suit his own preference. Also, if the listed file appears to be a graphic image, an image viewer is launched instead of a text editor.

SearchReplaceGlobal has a group of option selectors at the center right of the main display. Here is a listing of their functions:

  • "Search Subdirs" — search the subdirectories of the chosen search directory.
  • "Global" — perform the specified replacement on all matching cases in the file, not just one.
  • "Multiline" — Interpret "." as matching any character, not excluding linefeeds, the default. This is a feature commonly stated as "dot = all".
  • "Case" — Make content searches case sensitive. This option only applies to content searches, not file name searches.
  • "Reverse" — This option creates a list of files whose contents don't match the content search string. This option only applies to content searches, not file name searches.

The Ruby capture-group selector is entered into the replace window as, for example, "\1". Entries of "\n","\r", and "\t" and a number of others are translated into the respective control characters. SearchReplaceGlobal will process one case not normally handled in Ruby: the sequence "\cx" will produce the control character corresponding to "x".

Revision History
  • Version 1.4 02/18/2007. Modified interface code to accommodate newer Qt libraries.
  • Version 1.3 11/21/2006. Improved how embedded escaped control characters are handled.
  • Version 1.2 10/24/2006. Cleaned up some small errors, changed the sort order in the display windows.
  • Version 1.1 10/22/2006. Changed layout to allow longer search & replace strings.
  • Version 1.0 10/22/2006. Initial public release.

Home | Ruby | SearchReplaceGlobal |     Share This Page