Advanced Find & Replace

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

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.

• Show Low ASCII Characters:  Makes visible all low ASCII characters such as Linefeed, Carriage Return and Tab characters.
• Open File: Open the current file in the default application (according to the windows file association).
• Open As Text: Open the current file in your text editor (as defined in FAR Preferences dialog).
• View As Hex Dump: View the current file in raw hexadecimal format.
• Copy: Copy the selected text to the Windows clipboard (top text control).

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:

• Save & continue
• Skip file save
• Reload file and search it again.

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.

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 changes are not saved beyond this dialog until either Save or Search are clicked.

Search Parameters group

Typically you would leave all setting checked for HTML work.

[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 Cartridge 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] 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 a special path.

[X] Search All Files

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

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

Save any changes made and close the dialog. No search is performed.

Cancel

Discard any changes made since the dialog was opened and close the dialog. If save was clicked then data will remain saved. Esc key will also cancel the dialog.

Help

Display this help. Alternatively press F1.

$$ 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	Substrings
$#nn$	Special Character command
$L$, $L+, $L*$	Lowercase commands
$F$, $F.$, $F*$	File name commands
$DT$, $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 string found during find and replace.

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*$

• Use $F$ in either the Find text or the Replace text.
  FAR replaces $F$ with the name of the current file being searched (file name only, no path). 
• $F.$ is replaced with the current file name (no path and no file extension).
• $F*$ is replaced with the current file name (full path and file name).

File date time $DT$, $D-$

• Use $DT$ or $D-$ in the Replace text.
• $DT$ is replaced with the current file date and time.
• $D-$ is replaced with the current file date only.
   
• $DT$[now] is replaced with todays date and time.
• $D-$[now] is replaced with todays date.
   
• $DT$[%format%] is replaced with the current file date and time using the supplied format.
  eg. $DT$[hh:nn ampm]  - Formats are the same as Batch date time formats.

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

• Use $O$ in the Replace text only. FAR replaces $O$ with the current match text found. This is particularly useful for inserting new text in files at a particular location.

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.

• $O-$ is replaced with the current match text but without the Start with and End with text.
• $O1$ is replaced with the current "Starting with" match text.
  This may not be the same as you entered in "Start with" entry field because you may have included ? or * wild chars.
• $O2$ is replaced with the current "Ending with" match text. Same comment applied to $O1$ applied here.

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$

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: $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. 

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 such as Netscape. 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.