Advanced Find & Replace

General Search Tips
Preview Dialog
Main Menu
Search File | Search Definition | Search Options
Find Text | Replace Text | Advanced Settings | Buttons
$$ Commands

The Advanced Find & Replace dialog is available from the main window. Select "Advanced Find & Replace" from the Command menu or click the find icon on the Find & Replace panel (See the View menu).

Advanced find and replace does everything the regular find and replace does and more. The search button will be disabled when there are no files in the FAR file list.

General Search Tips
  • Press ESC at anytime to terminate a find and replace run.
  • Auto-scroll: If the FAR File List has the focus (click on it) then the list will auto-scroll during a search.
  • Far Find & Replace can also be operated in batch mode from the command line.
  • MS FrontPage HTML tab does not always show you the true document source code. So when you are swearing at FAR remember you may have copied FP text not the true source.
  • Normally for HTML file searching we leave all option checkboxes (right) checked. The exception is if we are searching for CR & LF characters (see below),  then "Ignore CR LF" and "Ignore Multiple Spaces" should be Unchecked.
  • Speed Up Tip: If you have thousands of files to process, use Windows Find to get a short list then drop the short list onto FAR. Windows Find is exceptionally fast (Although don't trust Win XP search).
  • Click the icon on the Find and Replace panel (main window) to access the Advanced Search dialog.
  • If the special character string "$F$" is found in a find or replace entry field then during Find and Replace $F$ will be replaced by the name of the current file being searched (file name only, no directory).
  • If the special character string "$#nn$" is found in a find or replace entry field then during Find and Replace $#nnn$ will be replaced by the char representation of nnn.
    EG. Find or Replace a CR char by using the string "$#13$"
    EG. Find or Replace a LF char by using the string "$#10$"
    EG. Find or Replace a Tab char by using the string "$#09$"
  • FAR supports the wild character "?" and "*". The "?" will match any single character, while "*" will match any string of chars. To search for a real "?" or "*" prefix with the "^" char.
    Note1: The "*" wild char can not be the first or last character of the search text.
    Note2: Wild chars only work in the Starting, Ending, Containing, Not Containing text fields.

    EG. Find: "abc?" will match text "abcd" and "abcx" etc.
    EG. Find: "abc^?" will match text "abc?".
    EG. Find "<h*>" will match the text <html> and <head>  etc.
    EG. Find "<x^*>" will match the text "<x*>".
The preview dialog (Top to bottom):

When Prompt Mode is checked you will see a Find & Replace confirmation / preview window as each match is found.


The Preview dialog (Replace mode)

File: Name of current file being searched. This field is readonly and can be copied (select and press Ctrl+C).

Options: Click "Options" (or press Alt+O or Ctrl+O) to access the options popup.

Note: If you modify the current file using an external application, when you switching back to FAR, click "Next". If you have unsaved changes in FAR, then at the time of FAR saving the file, you will be given the options of:

Text found - Line#: Displays the line number where the match text was found. 

Text found: This text window display a slab of text from the current file with the match text selected, and underlined in the middle. If the current file size is very big then you will see the text <snip> at top and/or bottom of the text. Note that removing the highlight will not upset the replacement. This found text can not be edited.

Replace with: In Replace mode this displays the text that will replace the highlighted /underlined text above. This text can be edited.

When you edit the replacement text, the background color will change to a bright yellow. Right click the text control and select "Revert", to return to the original replacement text. Take care with dynamic replacements (containing $A$ etc) as once you change the text the dynamic changes are disabled until you "Revert" to the original text again.

The preview dialog has the following buttons in replace mode:

Yes Perform the replacement.
No Skip the replacement.
Cancel Terminate multi-file find and replace. The current file in memory will not be saved. This means any other changes made to the current file will be lost. Changes made to other files have already been saved to disk.
Replace All Turns prompting off for the rest of this session of multi-file find and replace.
Next file Skip the current replacement, save all changes to the current file and move to the next file in the file list.

The preview dialog has the following buttons in find only mode (Replace Text checkbox is deselected):

Next Go and search for another match.
Cancel Terminate multi-file search.
Find All Turns prompting off for the rest of this find session. This is useful to quickly see how many matches are in the file list. Each match is recorded in the main file list.
Next file Stop searching the current file and move onto the next file in the FAR file list.
Main Menu

Search definitions are stored in .FarRun files (a format usually used by FAR batch script files). The file format is the same as batch script, so this file will help those who create FAR batch files.

When saving, search definitions are merged with the target file. So extra file content such as comments or non-search commands will remain after performing a save. Note however the Save As dialog allows you to fully overwrite the target file, as well as save just the current definition. When a .FarRun file is loaded, only definitions containing search item (FindStart=) are loaded.
 
The .FarRun files are just text files. We encourage you to edit this directly. The [DEFAULT] section defines the order (as you see it in the search definition dropdown). If you delete the [DEFAULT] section, or any of its items, then the items will be found as the section names and the [DEFAULT] section will be fully recreated next time you save. Because the name DEFAULT has special meaning, you will see that if you create a definition called DEFAULT then it's saved in a file section called [_DEFAULT].
 
File > New Create a new search definition file. Each search definition file can store hundreds of search definitions.
File > Open Load a previously saved search definition file.
File > Reopen Load a previously saved search definition file. A list the most recently used files is available. Click a file name to reload that file. This same list is available by clicking the file link.
File > Save Save all definitions (all definitions in the Search Definition dropdown) to the current file. If definitions were removed you will be asked to confirm the deletion of these files. FAR basically finds those definitions that exist only in the target file and gives you the opportunity to keep them or discard them. Clicking the Save buttons performs the same action.
File > Save As Save to the file name and location of your choice.

Checkbox: Save All (default setting is checked). Uncheck this box to save only the current search definition. Remember that definitions are appended to the target file by default, so don't be surprised if the resultant file contains more than one item (even though you unchecked this box). If you only want the current definition in the target file, then make sure you save to a new file name, or check the Replace File checkbox below.

Checkbox: Replace File - Check this to delete the target file before saving. The default is NOT to delete first, and to try and merge with the target file settings.
Edit as Text Opens the search definition file in a text editor. The preferred text editor for FAR can be set in the FAR Preferences dialog.
Options These settings are menu checkboxes. They are additional advanced options that effect search. You can also check/uncheck these settings by clicking their icons in the options group box.

DOS "\" = UNIX "/"

File paths in MS HTML can contain a mixture of both DOS and UNIX file separators. When this setting is checked DOS paths will match UNIX paths and visa-versa. Leave this setting checked unless searching for string containing slashes.

Find first Occurrence Only

Normally FAR finds every occurrence in a file. Check this if you only want to find just the first occurrence in each file.

Match Start of File Only

Causes search to match only the very start of each file. So a match, if found, will begin at character 1 of each file.
Search File

The file link displays the current search definition file. All the search definitions loaded in the Search Definition dropdown were read from this file. When you save, they will be saved back to this file.

Double click the link to open the file in your text editor. See "File > Edit as Text" above. Click the link to access the most recently used file list and other file commands.

Search Definition

To store a definition, press the Add button and enter a unique name for the definition.
To recall a previously stored definition, select a name from the dropdown.
To remove a definition, first select the definition from the dropdown, then press the Remove button.

Note that these settings and changes are stored in memory until Save or Search are clicked. Then they are saved permanently to file.

Search Options group

Typically you would leave all setting checked for HTML work. These are the same checkboxes as you see in the Find Panel on the FAR main window.

[X] Prompt Mode

In prompt mode you get to preview each match found. No replacement is done until you click the Yes or All button. Always start a search with this setting enabled, you can always click the Replace All button to skip further prompting. See Preview Dialog below.

[X] Ignore Case

When checked, a search for say Boy will match BOY and boy.

[X] Ignore CR LF

HTML documents often breaks lines at unpredictable places.  Check this option to search right through all line breaks. A line break is seen as a single space. Leave this setting checked unless specifically searching for line breaks characters.
EG. To search for Carriage Return, Linefeed characters enter the code $#13$$#10$

[X] Ignore Multi-Spaces

Multiple spaces have no meaning in HTML and can make text difficult to find. Check this option to treat all multiple spaces as a single space. Normally you would leave this setting checked. Just make sure your Find text contains only single spaces, otherwise you will never match.

[X] Search All Files

Uncheck this option to search only the selected files in the FAR file list.

The other iconic settings represent advanced search settings found in the options menu. They are linked to the options menu items. Click them to check/uncheck the equivalent options menu items.

Find Text

Start with:

Enter the text you want to find. To find text spanning between some start and end text check the "Ending with" checkbox and enter end text. The match will include the start and end text.
Example: 

Start with: <body
End with: >

Will match <body> as well as <body Onload='myfunc()'>

Ending with:

Check this box and enter end text to find a block of text with known start and end text. See Start with above.

Containing:

Check this box and enter some text to add a further constraint to the search. When checked, only text containing this text will match.

Example:

Start with: <body
End with: >
Contains: Onload

Will not match <body>, but will match <body Onload='myfunc()'>

Not Containing:

Check this box and enter some text to add a further constraint to the search. When checked, only text that does not contain this text will match.
Example:

Start with: <body
End with: >
Not Contains: Onload

Will match <body>, but will not match <body Onload='myfunc()'>


12/05/2007 - FAR build 667 - Change in the way Containing and Not Containing works.

In this version of FAR if you use a Containing or Not Containing text that matches the beginning the Start with text, we now ignore the hit (which is mostly useless), and move the search file pointer on just past the 'Start with' match text.

Note: there is a setting in Settings.ini that can switch off this new behavior.
Example:

Start with: xxx
End with: yyy
Not Contains: xxx

If the file contain xxx xxx yyy FAR will now match xxx yyy only, ignoring the first xxx hit. Previous versions would never generate a hit at all.

Example:

Start with: xxx
End with: yyy
Contains: xxx

FAR will match text xxx xxx yyy but not text xxx yyy. For previous versions the Contains text does nothing since it always matched the Start with text.

Replace Text

Uncheck the "Replace Text" box to find text only. When checked the replace text entry field. Enter single or multiple lines of text. Any line breaks entered will be used.

For special advanced command codes see Advanced Settings Pane below.

"V" Button

Displays a list of advanced commands that can be inserted into the replace text entry field (you should first set the insert point in the replace text entry field). Note that some commands such as $L$, $M$ open an intermediate dialog to allow you to select a file.
$$ commands are described below.

">>" Button

Hide and show the advanced settings pane.

Advanced Settings Pane

Displays some info and extra fields for a number of advanced $$ replacement commands. See below.

Sub-Strings page

Provides easy access to the $A$, $B$, $C$ Substring definition dialogs.

Relative Path page

Click the browse button [...] and select a file to insert into your files. The file name is wrapped in $R$[...] command script and inserted into the edit field. You can then copy this command text into your replace text. More on the $R$ command below.

Move Link page

More on the $M$ command below.

Notes page

Enter any notes you want to store with the current definition (plain text only).

Buttons

Search 

Save any changes, close the dialog and start searching. The button is disabled if there are no files are in the FAR file list (main window).

Save

Saves any changes made. Same as the "File > Save (ctrl+S)" command.

Cancel

Discard any unsaved changes made since the dialog was opened and close the dialog. Esc key will also cancel the dialog. You will be prompted to save any unsaved changes.

$$ Commands

Special codes of the form $x$ can be inserted into the Replacement text (and Find text where specified). When a find and replace is performed any codes found will be expanded. These commands can also be inserted into the replace text (adv dialog) using the [v] button.

$A$,$B,$C$  $A*$,$B*$,$C*$ Substrings
$#nn$ Special Character command
$L$, $L+, $L*$ Lowercase commands
$F$, $F.$, $F*$ File name commands
$DT$, $DT$[format], $D-$ File date time commands
$I$ Insert text from file command
$O$, $O-$, $O1$, $O2$ Original Match Text commands
$R$ Relative Path command
$T$ Set HTML Title command
$M$ Move Link command
$X*$, $X+$, $X-$, $X@$ XML Data Island commands (separate topic)

Easy access to the $$ commands can be gained from the [V] button and drop down list.

Sub Strings $A$, $B$, $C$
$A$,$B$ & $C$ represent substrings extracted from the match text found during find and replace.

See Define Substring dialog help.

$A*$, $B*$, $C*$
[New for FAR HTML 5]

$A*$,$B*$ & $C*$ are similar to $A$..$C$ and use the same $A$..$C$ definitions you setup using the Define Substring dialog.

So $A$ is recalculated every time FAR finds a search hit. And $A*$ is calculated whenever a file is loaded for search.

See Define Substring dialog help.

$#nn$

If the special character string $#nn$ is found in a find or replace entry field then during Find and Replace $#nnn$ will be replaced by the char representation of nnn.

Example:

$#13$ is replaced by the CR  char
$#10$ is replaced by the LF  char
$#09$ is replaced by the Tab char

Note: If you try and search for CR/LF characters, search will probably fail until you turn off the search option "Ignore CR LF Chars".

Lowercase $L$, $L+$, $L*$
Use $L$ to set all HTML tag strings to lowercase. Use separately from all other commands. This special command requires the following settings:

Set Start with: <
Set End with: >
Set Replace: $L$    (any other text entered around $L$ is ignored)

Click the search button. All tags containing upper case chars will be changed to lowercase. Test this with prompt mode on.

This command was written to assist those moving from HTML to XHTML or XML.

Note: The search command finds the first '<' character and begins changes from there.

Example: <A HREF="SOMEFILE"> would be converted to <a HREF="SOMEFILE">.


$L+$ is the same but includes the Tag Attributes.

Example: <A HREF="SOMEFILE"> would be converted to <a href="SOMEFILE">.


$L*$ makes everything lowercase.

Set Start with: href="
Set End with: "
Set Replace: $L*$    (any other text entered around $L$ is ignored)

This will force everything in the match string to lowercase.

Example: <A HREF="SOMEFILE">Click me</A>
would be converted to <a href="somefile">click me</a>.

File name $F$, $F.$, $F*$
File date time $DT$, $DT$[format], $D-$

%format% codes are the same as Batch date time formats.

Original Match Text $O$, $O-$, $O1$, $O2$

Example: 

Start with: <body
End with: >
Replace with: $O$ 
                   <script...

Will match <body ???> in each HTML file and replace <body ???> with itself followed by <script...  on the next line. 

Tip:    How would I add text to only those files that don't already have the text? For example add a Style Sheet include statement to HTML files that do not already have the include text.

  1. Add all your HTML files to the FAR file list.
  2. Perform a Find to locate the files that already contain the new text.
  3. From the main window sort your list by clicking on the "Matches" column heading.
  4. Now you have all the up to date files in a bunch. Select these and remove them from the list.
  5. Perform the required text insert on the remaining files.

Another option is to first strip all existing text and the add the new text to every file.

Include Text From File $I$
This command can insert text from an external file. This command can be used in the Replace text only.

Syntax: $I$[c:\path\file.ext]

The file name must be an absolute path surrounded by square brackets as shown above. When the replacement is performed, FAR will replace "$I$[xxx]" with the text found in the supplied ASCII file.

Relative Path $R$[filename], $R$[int:n], $R$[str:ss]
This command is very useful for inserting Style Sheet or Script file names (relative paths) into files scatted though different folders.  The different folders mean that the relative path would need to be constantly adjusted.

Syntax 1: $R$[c:\path\file.ext]

The file name must be an absolute path surrounded by square brackets as shown above. When the replacement is performed, FAR will replace "$R$[xxx]" with the calculated relative path. 

Syntax 2: $R$[int:n] where n is an integer offset usually 0

This inserts the folder depth as a number string (depth relative to the root of the FAR file list).

$R$[int:0] would be replaced with '0' if the current file is in the root folder, '1' if file is 1 folder below the root folder, '2' if 2 folders below etc.

$R$[int:10] - 10 is an offset. This would be replaced with '10' if the file is in the root folder, '11' if file is 1 folder down from the root folder etc.

Syntax 3: $R$[str:ss] where ss is a string

This inserts string 'ss' repeated n times where n is the folder depth relative to the root FAR file list).

$R$[str:..\] would be replaced with '' if the file is in the root folder, '..\' if file is 1 folder down from the root folder, '..\..\' if file is 2 folders down from the root folder etc.

So this is yet another another way to insert a relative file path.

EG.  $R$[..\]SomeFile.JS  -- If SomeFile.JS lived in the root folder (of the FAR file list) then FAR inserts the correct number of '..\' strings before the 'SomFile.JS' text.

Advanced Example

On Adv Find and Replace dialog, in the [V] drop down insert menu you will see "$R$[..] -- Insert NavScript.js web help script".

This uses the above commands to insert the following text.

<script src="$R$[str:..\]NavScript.js" language="JavaScript1.2" type="text/javascript"></script>
<script language="JavaScript1.2" type="text/javascript">WriteNavLink($R$[int:0]);</script>

Basically it's for Web Uncompressed Help where you want to insert a link into every to reopen the navigation pane. You can read  more here about the script.


More on Syntax 1 - $R$[c:\path\file.ext]

How to do it:

  1. In the Relative Path page click the [...] browse button and select a file to insert. 
  2. The edit field will now show: $R$[x:\path\file.ext]
  3. Insert this text into the required position in the Replace text using Copy (Ctrl+C) and Paste (Ctrl+V).

Alternatively you can insert the "$R$[xxx]" statement using the [V] button popup list. The [V] button list also contains complete Style Sheet, JavaScript and VBScript commands that will prompt you for a file name then insert the entire HTML code into the Replacement text for you.

Example: 

Start with: <header>
Replace with: $O$ 
    <link
rel="stylesheet" type="text/css"
     
href="$R$[c:\site\html\farstyles.css]">

This will find the start of the header block "<header>" and replace it with itself closely followed by a CSS include statement. The "$R$[c:\site\html\farstyles.css]" will be replaced with the appropriate relative path for that file. EG. "farstyles.css" or "../farstyles.css" or "../html/farstyles.css" etc.

UNIX Paths: 

The resultant relative path will contain UNIX separators "/" since DOS separators "\" don't work in some HTML environments. If you want to force DOS separators then temporarily uncheck the "DOS "\" = UNIX "/"" check box.

Set Title $T$

This command is useful when you have to set the HTML document title <title>xxx</title>, of many documents to say the first <h1> string found in each document.

Syntax: $T$NewTitle

This command can only be used in the replacement text block.
NewTitle
can be anything from plain text to a combination of text and other tags.

Example: 

Lets say our HTML file titles have been set incorrectly and we want to set each title to the first H1 text found in each document. I.E. <h1>ThisText</h1>   -->  <title>ThisText</title>.
Set up the search params as follows:

Start with: <h1
End with: </h1>

This will find the string <h1 ??>text</h1>.
To extract the actual text in the middle we will need to define a $A$ substring.

$A$.Find Sub Str No = 1
$A$.Start Text = ">"
$A$.End Text = "<"
$A$.Include Start End Text=No

So now every search hit will contain the H1 text in our $A$ variable.
All we need now is the replace text:

Replace with: $T$$A$

When you perform a search everything after $T$, in this case the H1 text stored inside $A$, is inserted between the documents <Title> and </title> tags. Experiment and get a feel for its scope.

Move Links $M$
We made this command so we could move certain binary files  (.pdf, .doc. zip etc) to a separate folder system. To be precise we move the binary downloads outside the Help web, convert the links to absolute links dynamically at run-time using script then convert the entire help web to a CHM. Without the binary files the CHM is quite small and we can ship the entire web + binary files (the ones that fit) on CDROM to our support staff. So anyway, we have included this code into FAR in case others find it handy.

Warning: Great care must be taken. When experimenting with this command, make sure you experiment on a copy of the help web first. The command can save a lot of time but also cause a lot of damage if your rules are not setup correctly. It is not simple to use, but maybe we can improve it in the future.

Old location base dir:

Base folder used by all the items in column 1 of the Relocation Rules list.

New location base dir:

Base folder used by all the items in column 2 of the Relocation Rules list.

Note: The "New Location Base Folder" must be on the same disk as the Help Web. This is because FAR performs a file rename, not do a copy and delete.

File Types to move:

A list of all file types you want to move with the $M$ command. Each file extension should start with a dot and be separated from each other by a space. Example: ".zip .exe .pdf"
Note: HTML files cannot be moved. Any HTML files added here will be ignored.

Relocation Rules:

During the $M$ move command each link we find is expanded to a full path. It is then tested to see if the file type matches one of the file types list above. Next we search download the list, testing if "Old location base dir"/OldLocation(n) is part of the current links path. If it is, we then change the links path to "New location base dir"/NewLocation(n) + Link file name. We then make the link path relative again and if the "Link is Unix" is checked, we change all file separators from DOS (\) to Unix (/). After every matching link has been changed in all files in FAR file list, we finally move all binary files effected to their new location.

Note: You can optionally make the last item in the list an empty string (Old Location = '') which means that if all tests fail then the final rule will be used.

See "The $M$ Procedure" below for instructions on how to auto fill this list. The list also has a right-click menu.

Link is Unix:

Check this if all links changed should be Unix links (/). Normally you would leave this checked.

The $M$ Procedure:

  1. Set up relocation rules. Which files to move where?

    Turn off all drop filters and drop your help web  onto the FAR main window. Sort by File Ext and then remove all content files from the list (HTML, GIF, JPG, CSS, TXT, JS etc). This leaves just the required ZIP, DOC, PDF etc files you want to move.

  2. Click the Define $M$ button (Move Link Page, Adv Search dialog).
    The Move Link Setup dialog will appear.

  3. Right-Click the list and Select the Auto-Fill command. This fills the "File Types to move" Field with all File Extensions you want to move. It also files the "Old Location Base Folder" and the Relocation Rules list. At move time this list is searched from top to bottom and the first match is used.
     
    Blue List Items
    Some list items may be highlighted in blue.  Care must be taken with these items since they represent items that point to files with the same file name (EG. files.zip and HTML\files.zip). Removing a blue item may mean that you move and link to the incorrect duplicate file name. 

    The List shows a list of rules of how files will be moved and links renamed. As each link is found FAR checks 
    1. Does the link point to a valid local file.
    2. Find the first folder in the list that is part of the current link path ("Old Location Base Folder" + "\" + OldLocation(N)). Once a match is found the "New Location Base Folder" + "\" +  NewLocation(n) folder is used as the new file location. The new link will of course be given the appropriate relative path.

    Important: Check the List
    Take some time to examine the file list. Move items to the bottom of the list that might mask other items.

    Example: ("Old Location" column)
    item1: "downloads"
    item2: "downloads\tools"

    Old Location Base Dir: "c:\fred\downloads"

    Note that "downloads" masks the item "downloads\tools". For a link = "c:\fred\downloads\tools\delete.exe", "downloads" would match before "downloads\tools". Normally the Auto-Fill command will sort the items correctly, still to be safe always check your list before moving files. In the above case we need to move the "downloads" item lower down in the list.

     

  4. Once you have entered  a "New Location Base Folder" and have your rules setup click OK to save and return to the FAR File list.

  5. Performing the Move

    Now we have rules to find and move files stored away, drop onto FAR only your HTML files (use a drop filter or remove all non-HTML files). We are going to change all the links to the specified binary files.

  6. Set up the Adv Search as follows.
    Start with: <a
    End with: >
    Replace with:  $M$
    and press the Search Button. The rules you set up before are used to relocate all specified files/links. After all HTML files have been scanned and links renamed, the binary files effected are moved.

    Note1: Cancelling the search half way through can cause problems since several links can point to a single file. If this happens, get a fresh copy of the web.
    Note2: During the process, links containing the "New Location Base Folder" are ignored. I.E. Links already moved will not be moved again.
    Note3: If a link points to a non-existent file then no change or move is performed. Thus file links such as ftp:, http:, mailto: and broken links will all be ignored.
    Note4: The files are not moved until every link has been found and changed.
    Note5: Links to other HTML files are ignored. HTML files cannot be relocated.

  7. Finally, once finished you should search the main folder for any stray ZIP, PDF etc files that were not moved. If files are found, then they are probably:

        a) orphan files that are not linked to, Or
        b) maybe linked to via script (if you link via script), Or
        c) file paths that may contain HTML unfriendly chars like #, %.

    Orphan files should be deleted if not used as they take up disk space.

That's it for the $M$ command. There is still more work to do if you plan to convert the binary file links into scripted links and the web files into a CHM.


http://www.HelpwareGroup.com/