Tools en Utilities

home *** CD-ROM | disk | FTP | other *** search

/ Tools en Utilities / CDASS_5.ISO / shell / file / tsnr21.arj / SNR.DOC < prev next >

Wrap

Text File | 1992-11-16 | 119.0 KB | 3,362 lines

TTuurrbboo SSeeaarrcchh AAnndd RReeppllaaccee(tm) Copyright (c)1990 By Curtis Little All Rights Reserved "Software Solutions That Make Sense"(tm) TTaabbllee ooff CCoonntteennttss LLiicceennssee . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 WWaarrrraannttyy . . . . . . . . . . . . . . . . . . . . . . . . . . 5 GGeettttiinngg SSttaarrtteedd . . . . . . . . . . . . . . . . . . . . . . . 6 Acknowledgments . . . . . . . . . . . . . . . . . . . . 6 How to Contact the Support Board . . . . . . . . . . . . 6 Required Equipment . . . . . . . . . . . . . . . . . . . 6 Typefaces Used in this Manual . . . . . . . . . . . . . 6 IInnttrroodduuccttiioonn . . . . . . . . . . . . . . . . . . . . . . . . 8 Overview of Turbo SNR . . . . . . . . . . . . . . . . . 8 Calling Turbo SNR . . . . . . . . . . . . . . . . . . . 8 Turbo SNR Command Line Options . . . . . . . . . . . . . 9 Overview of the Command Line Options . . . . . . . . . . 9 Specifying Options . . . . . . . . . . . . . . . . . . 10 CCoommmmaanndd LLiinnee OOppttiioonn DDeessccrriippttiioonnss . . . . . . . . . . . . . 12 List Line Numbers (#) . . . . . . . . . . . . . . . . 12 Strip 8th Bit (8) . . . . . . . . . . . . . . . . . . 12 ASCII mode (a) . . . . . . . . . . . . . . . . . . . . 12 Backup Changed Files (b) . . . . . . . . . . . . . . . 13 Count matches (c) . . . . . . . . . . . . . . . . . . 14 Search Child Subdirs (d) . . . . . . . . . . . . . . . 14 Ignore Case (i) . . . . . . . . . . . . . . . . . . . 15 Keep Old Case (k) . . . . . . . . . . . . . . . . . . 15 List Matching Lines (l) . . . . . . . . . . . . . . . 17 One-One Table (o) . . . . . . . . . . . . . . . . . . 17 Programmer Words (p) . . . . . . . . . . . . . . . . . 19 Regular Expressions (r) . . . . . . . . . . . . . . . 20 Replacement Using Regular Expressions . . . . . . 23 How Regular Expressions are Evaluated . . . . . . 25 Verbose (v) . . . . . . . . . . . . . . . . . . . . . 28 Word Search (w) . . . . . . . . . . . . . . . . . . . 28 Interactive Mode (z) . . . . . . . . . . . . . . . . . 29 SSuubbssttiittuuttiioonn SSttrriinnggss . . . . . . . . . . . . . . . . . . . 31 Substitution String Syntax . . . . . . . . . . . . . . 31 Using Context Modes . . . . . . . . . . . . . . . . . 31 Using String Specifiers . . . . . . . . . . . . . . . 34 Using White Space in Strings . . . . . . . . . . . . . 35 Special Characters In Strings . . . . . . . . . . . . 36 UUssiinngg CCoommmmaanndd FFiilleess . . . . . . . . . . . . . . . . . . . . 40 AAddvvaanncceedd TTooppiiccss . . . . . . . . . . . . . . . . . . . . . . 42 AAppppeennddiixx AA -- TTuurrbboo SSNNRR MMeessssaaggeess . . . . . . . . . . . . . . 44 Informational Messages . . . . . . . . . . . . . . . . 45 Warning Messages . . . . . . . . . . . . . . . . . . . 48 Error Messages . . . . . . . . . . . . . . . . . . . . 49 AAppppeennddiixx BB -- SSppeeeedd CCoonnssiiddeerraattiioonnss . . . . . . . . . . . . . 54 AAppppeennddiixx CC -- TTeecchhnniiccaall SSppeecciiffiiccaattiioonnss . . . . . . . . . . . 56 IInnddeexx . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 LLiicceennssee You are granted a nonexclusive personal right to use this Software under the terms stated in this Agreement. Unregistered users are allowed to evaluate this software for a period NOT TO EXCEED FIFTEEN (15) DAYS. If, on or before this time expires, you wish to continue using this software, you must register by sending the registration fee to the author "Curtis Little" for EACH COPY to be used. You may not modify or alter the Software or any of the accompanying files and/or documentation. This license is effective until terminated. You may terminate it at any time by destroying your copies of the Software. It will also terminate if you fail to comply with any term or condition of this Agreement. You agree upon such termination to destroy your copies of the Software. The shareware version of this software may be freely distributed as long as the following conditions are met: 1) All files are distributed as is and in unmodified form. 2) No more than a $5.00 handling fee can be charged without the express written consent of the author "Curtis Little". 3) This Software may not be distributed with or as a part of any other product or software package without the express written consent of the author "Curtis Little". Registered users may not transfer or assign ownership of this license to any other person without the express written consent of the author (Curtis Little). Attempts to sublicense, assign, or transfer any of the rights, duties, or obligations hereunder is void. You may not copy, modify, alter, electronically transfer, or lease the registered version of this Software. Registered owners may use this software on more than one computer providing there is no possibility it will be used on more than one computer at any one time. Business and government users of the Software are not allowed the evaluation period. Use in a business or government institution without first paying the required registration fee is in violation of this license agreement. BByy uussiinngg tthhee SSooffttwwaarree yyoouu aacckknnoowwlleeddggee tthhaatt yyoouu hhaavvee rreeaadd tthhiiss aaggrreeeemmeenntt,, uunnddeerrssttaanndd iitt aanndd aaggrreeee ttoo bbee bboouunndd bbyy iitt''ss tteerrmmss aanndd ccoonnddiittiioonnss.. 4 Turbo SNR - License Agreement WWaarrrraannttyy With respect to the physical diskette sent to registered owners, the author warrants the same to be free from defects in materials and workmanship for a period of 60 days from the date of registration. In the event of notification within the warranty period of defects in material or workmanship the author will replace the defective diskette. The remedy for breach of this warranty shall be limited to replacement and shall not encompass any other damages, including but not limited to loss of profit, and special, incidental, consequential, or other similar claims. The author specifically disclaims all other warranties, expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose and the program license granted herein in particular, and without limiting operation of the program license with respect to any particular application, use, or purpose. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY LOSS OF PROFIT, LOST SAVINGS, COMMERCIAL DAMAGE, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THIS SOFTWARE EVEN IF THE AUTHOR (Curtis Little) OR AN AUTHORIZED REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. This agreement shall be governed by the laws of the state of California. Turbo SNR - Users Guide 5 GGeettttiinngg SSttaarrtteedd AAcckknnoowwlleeddggmmeennttss In this manual several products are referred to: MS-DOS is a registered trademark of Microsoft Corporation. Brief is a registered trademark of Underware, Inc. IBM PC, XT, AT, and PS/2 are trademarks of International Business Machines, Inc. Turbo C is a registered trademark of Borland, Inc. Turbo Search & Replace and Turbo SNR are trademarks of Curtis Little HHooww ttoo CCoonnttaacctt tthhee SSuuppppoorrtt BBooaarrdd An electronic bulletin board is used to support Turbo Search & Replace (herein referred to as Turbo SNR). You may contact the support board 24 hours a day. The support board is: Lost At C BBS (303) 280-1007 In addition you may contact the author (Curtis Little) on (303) 280-1076 Be aware that if I need to call you back I will do so as a collect call. If you have any questions/suggestions regarding Turbo SNR feel free to call. The support board is open to the public, however, registered users will receive priority service. RReeqquuiirreedd EEqquuiippmmeenntt IBM PC, XT, AT, PS/2 or MS-DOS Compatible MS-DOS 2.0 or above At least 128K memory available to application programs TTyyppeeffaacceess UUsseedd iinn tthhiiss MMaannuuaall [] Square brackets are used to enclose optional parameters. Text of this sort should not be typed verbatim. Note that at times it is necessary to type 6 Turbo SNR - Getting Started the square brackets - in these cases it will be noted in the text that the square brackets are meant verbatim. Turbo SNR - Users Guide 7 IInnttrroodduuccttiioonn OOvveerrvviieeww ooff TTuurrbboo SSNNRR Turbo SNR (Search & Replace) is a highly sophisticated program designed to provide you the best search and replace capabilities available. Turbo SNR was designed as a command line utility to allow unattended operation in addition to batch file operation. This section of the manual briefly talks about the calling syntax for Turbo SNR and the various parameter types that are available. Later sections of the manual explain each of the options in detail. CCaalllliinngg TTuurrbboo SSNNRR When you call Turbo SNR you specify what it should do using parameters on the command line. With Turbo SNR you are not restricted to using different types of parameters in a predefined order; Turbo SNR can handle parameters in any order you specify them. The types of parameters that Turbo SNR accepts are: o Options o Substitution strings o Command files o File names Options configure the way Turbo SNR operates. Any parameter that starts with a '-' or '/' is considered to be an option. There are two categories of options that you should be aware of. The first category of option can be changed multiple times on the command line. Using this type of option you can cause Turbo SNR to act one way for the part of the command line following the option, and then differently when the same option is changed later on the command line. The second type of option is one that will not cause Turbo SNR to act differently if it's value is changed multiple times on the command line. In the discussion on options it will be noted anytime an option can be used multiple times for different effects. Substitution strings specify what Turbo SNR should search for and replace with. You can specify as many substitution strings as you desire. The only limitation on the number of substitution strings is the amount of memory available and the maximum length allowed for a command line (which is a bit more restrictive than 8 Turbo SNR - Introduction memory limitations!). Note that using command files (described next) you can overcome the command line length limitation. Command files specify a file that Turbo SNR should read to get a list of substitution strings. Turbo SNR can handle as many command files as you want to specify providing there's enough memory to store all the substitution strings read from the files. File names specify the file(s) that Turbo SNR should operate on. Turbo SNR allows you to specify as many filespecs as you like - any of the specified file names can contain wildcards. TTuurrbboo SSNNRR CCoommmmaanndd LLiinnee OOppttiioonnss There are quite a few options available that allow you to control how Turbo SNR operates. This chapter will describe each of the options, any limitations, and special considerations you need to know about. Before getting into the details of each option a brief overview will be listed. OOvveerrvviieeww ooff tthhee CCoommmmaanndd LLiinnee OOppttiioonnss As previously mentioned, Turbo SNR considers something to be an option if it is preceded with a '-' or a '/' (the only exception to this rule is the use of an option to specify a substitution string - the s option). The following lists the options that are currently supported by Turbo SNR. With Turbo SNR each option is either ON or OFF. If an option is ON it is considered to be a 'default' option by Turbo SNR and will be noted in the table below: (Note that options are not case sensitive) 8 Strip the high bit from every character in the input files. ? Displays a brief help screen listing all the available options in Turbo SNR. # List line numbers that contained a match to at least one of the substitution strings. a Use ASCII mode. b Backup files that are changed. **DEFAULT** c Display a count on the number of strings replaced for each input file. Turbo SNR - Users Guide 9 d Search child subdirs for input files. h Displays a brief help screen listing all the available options in Turbo SNR. i Ignore case when searching. k Keep the case of the string found when replacing. l List each of the lines that contained a match to at least one of the substitution strings. o Use the one to one table when possible. p Search for "programmer" words (i.e. strings that would be considered identifiers or tokens in a typical programming language). r Allow use of regular expressions in substitution strings. s Specify a substitution string v Verbose mode. **DEFAULT** w Search for words (i.e. strings that would be considered words in a language). z Interactive mode - prompt user before replacing each match. SSppeecciiffyyiinngg OOppttiioonnss When Turbo SNR scans the command line it looks for options by looking for a leading '-' or '/'. Once a '-' or '/' is found Turbo SNR considers the next block of text (until a white space character is hit) to be options specified by the caller. On the command line you can turn options on and turn options off. The syntax for specifying an option is as follows: -option[-|+][option 2[-|+]][option n...] Immediately after each option an optional "sign" can be used to specify whether you want to turn the flag on (+) or off (-). If the sign isn't specified the option is turned on. To look at an example let's say you want to use Turbo SNR to strip the high bit of a Word Star file using ASCII mode, and don't want a backup 10 Turbo SNR - Introduction file created. The following lists several different ways to specify these options (all examples do the same thing): -a -b- -8 -a+b-8 -ab-8 -a+ -b- -8+ As you can see there is a great deal of flexibility in how you specify options to Turbo SNR. Choose the method that you feel most comfortable with. In the following Chapter each of the options will be explained in detail. Turbo SNR - Users Guide 11 CCoommmmaanndd LLiinnee OOppttiioonn DDeessccrriippttiioonnss LLiisstt LLiinnee NNuummbbeerrss ((##)) S_ y_ n_ o_ p_ s_ i_ s_ The # option tells Turbo SNR whether or not it should list the line numbers for each line that contains at least one match. Line numbers containing multiple matches will only be listed once. At default this option is off. L_ i_ m_ i_ t_ a_ t_ i_ o_ n_ s_ This option is only available when you use ASCII mode. ASCII mode will automatically be set when the line number option is used. SSttrriipp 88tthh BBiitt ((88)) S_ y_ n_ o_ p_ s_ i_ s_ The 8 option tells Turbo SNR whether or not it should strip the high bit of the input file(s). This option is handy for converting the old Word Star format files to ASCII. At default this option is off. AASSCCIIII mmooddee ((aa)) S_ y_ n_ o_ p_ s_ i_ s_ The a option tells Turbo SNR whether or not it should operate in ASCII mode. When Turbo SNR operates in ASCII mode it expects each line in the file to be terminated with either a CR, LF, or CRLF. At default this option is off. L_ i_ m_ i_ t_ a_ t_ i_ o_ n_ s_ ASCII mode will always create files that have standard MS-DOS line terminators (a carriage return followed by a line feed). S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ 12 Turbo SNR - Command Line Options Using ASCII mode simplifies the way you have to specify the end of line character. You can specify the end of line by using either the linefeed (ascii character #10 or '\n') or the carriage return (ascii character #13 or '\r'). In ASCII mode these characters are treated as being the same (the carriage return specifier is translated to a linefeed by Turbo SNR), and are translated internally by SNR to match whatever type of line terminator the input file really uses. Although this end of line translation makes things easier for you, it may be confusing for those in touch with how MS-DOS stores files. In DOS an ASCII file is typically stored with a trailing CR LF. In SNR if you use ASCII mode and specify to search for the CR followed by an LF you won't match the end of every line (only the end of lines followed by a blank line) since Turbo SNR translates the CR and LF search specifiers for you. If you use either \r or \n in your replace value Turbo SNR will substitute a CR LF combination when it replaces (since CR LF is the DOS standard). BBaacckkuupp CChhaannggeedd FFiilleess ((bb)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should backup the files that it changes. When Turbo SNR creates a backup file it does so by creating a file with the same name as the original with the exception of a $ appended to the input file extension. If the input file has a three character extension the last character will be replaced with a $. For example the following are the names of some input files and the names of the backup files that would be created: I_ n_ p_ u_ t_ f_ i_ l_ e_ B_ a_ c_ k_ u_ p_ N_ a_ m_ e_ TEST.C TEST.C$ TEST.ASM TEST.AS$ TEST TEST.$ At default this option is on. Turbo SNR - Users Guide 13 S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ If you're not sure the substitution strings you specified will have the exact results you want it is suggested that you leave the backup option turned on. It is easy to get results you didn't think about if you're not careful when using Turbo SNR (especially when you use regular expressions). A good backup file never hurt anyone! CCoouunntt mmaattcchheess ((cc)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should display a count of the number of matches (i.e. strings replaced) for each input file. At default this option is off. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ If this option is used in combination with interactive mode (z option), line numbers (# option), or list lines (l option) the count will be displayed at the end of a file. Otherwise a running total will be displayed on the screen showing how many matches occurred in a file. SSeeaarrcchh CChhiilldd SSuubbddiirrss ((dd)) S_ y_ n_ o_ p_ s_ i_ s_ This option is used to tell Turbo SNR if it should search the child directories of the file specifiers for matching input files. When this option is on Turbo SNR searches the child directories of each specified input file for other files that match the file specs. As an example assume the following files are specified on the command line: *.txt c:\turboc\readme.* \lib\*.txt Turbo SNR would search: Starting with the current drive and directory Turbo SNR would search for all files with an extension of .TXT. Any 14 Turbo SNR - Command Line Options child directories from the current would be traversed as well. Starting in the C:\TURBOC directory Turbo SNR would search for all files with a name of README. Any child directories from Turbo C would also be traversed. Starting on the current drive in the \LIB directory Turbo SNR would search for files with an extension of .TXT. Child directories of \LIB would also be traversed. To get Turbo SNR to search an entire drive for a specific file spec you'd simply use the search subdir option and specify the filespec to search for as: DRIVE:\FILESPEC As mentioned before, Turbo SNR fully supports the DOS wildcards in file specifications. At default this option is off. L_ i_ m_ i_ t_ a_ t_ i_ o_ n_ s_ The total number of files that can be processed by Turbo SNR is only limited by memory. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ Note that it is possible to accidently specify the same file name twice using the search subdir option (as could also be done manually by specifying the same input file twice on the command line). If you don't want Turbo SNR to process the same file(s) more than once you should be careful not to specify file specs that will cause multiple processing to occur. IIggnnoorree CCaassee ((ii)) S_ y_ n_ o_ p_ s_ i_ s_ This option tells Turbo SNR whether it should ignore case when looking for a match. At default this option is off. KKeeeepp OOlldd CCaassee ((kk)) Turbo SNR - Users Guide 15 S_ y_ n_ o_ p_ s_ i_ s_ This option tells Turbo SNR whether it should use the case for the value that was matched. For example, the following lists the values found and the value that would be used to replace with (in this example ignore case is set to true): Substitution string: "you=thou" V_ a_ l_ u_ e_ M_ a_ t_ c_ h_ e_ d_ R_ e_ p_ l_ a_ c_ e_ d_ W_ i_ t_ h_ you thou You Thou YOU THOu As you can see from the examples above, when the replacement value is longer than the search value the trailing characters will remain in the original case you specified. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ To use this option you must also specify the ignore case option. Turbo SNR won't let you keep existing case if case isn't being ignored in the search string (after all, if you know the specific case you're searching for you should know the case you want to replace with!). As was shown in the examples above, Turbo SNR doesn't change the case for positions in the replacement string that don't exist in the search string. However, special consideration needs to be given when you use regular expressions since variable length strings can be matched. As an example the following lists several strings in the order they were processed in a selected document: Substitution string: "t*e=this" V_ a_ l_ u_ e_ M_ a_ t_ c_ h_ e_ d_ R_ e_ p_ l_ a_ c_ e_ d_ W_ i_ t_ h_ the this The This THESE THIS the thiS Note in particular the last entry - the last character has the case that was last used since the search value is shorter than the value being replaced with. 16 Turbo SNR - Command Line Options LLiisstt MMaattcchhiinngg LLiinneess ((ll)) S_ y_ n_ o_ p_ s_ i_ s_ This option tells Turbo SNR whether or not it should list the lines that contain at least one match. At default this option is off. L_ i_ m_ i_ t_ a_ t_ i_ o_ n_ s_ ASCII mode is automatically set when you specify you want matching lines to be listed. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ Note that matching lines will only be listed once no matter how many additional matches they may contain. OOnnee--OOnnee TTaabbllee ((oo)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should use the one-one table when possible. To understand what this option does you need to be aware how Turbo SNR stores substitution strings. A detailed description on the substitution tables is saved for the advanced topics chapter (see page 42 for details), however, I'll briefly describe the tables here as well. In Turbo SNR there are two distinct tables used to store substitution strings as follows: One-One Table This table can only contain entries that replace a single character with another single character. Replacement using the one-one table is done at the i/o level while the input file is being read. This means that entries in the one-one table will not obey the word flags available with Turbo SNR. The one-one table provides a way to quickly replace single characters - the speed of using the one-one table is hundreds of times faster than using the other type of table Turbo SNR has. Standard Table The standard table used by Turbo SNR allows you to replace any length string with another string of any length. This table can also store character Turbo SNR - Users Guide 17 for character replacements that the one-one table is capable of storing. The following table goes over some of the advantages and disadvantages of the one-one table: Advantages: *VERY* fast. Using the one-one table you can replace character for character almost as fast as your PC can read and write the file. There is very little processing overhead needed to replace with the one-one table. Allows you to ignore the setting of the word flags for specified characters (the one-one table usage can be toggled on and off to accommodate this). Since replacement is done at the I/O level it is convenient and fast to create a table that can upper case or lower case a file. Disadvantages: Can only be used to do character to character substitution. You can't delete characters or replace/search for strings of multiple characters using the one-one table. Since the word flags are not honored by the one- one table you can't use it to locate one letter words - the standard table must be used to locate words. Context modes are not supported in the one-one table. Only entries with both a search and replace context of 0 qualify for the one-one table. At default this flag is off. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ The one-one table can be toggled on and off during the course of the command line allowing you to specify certain values to put in the one to one table (when possible) while putting other character-character replacements in the standard table. For example: SNR -o @ONE2ONE.TAB -o- @STANDARD.TAB -o @ONE.TAB The example above would cause the entries in the ONE2ONE.TAB and ONE.TAB command files to be placed in the one-one table when 18 Turbo SNR - Command Line Options possible, and the entries in the STANDARD.TAB would be placed in the standard table. Note that once a character in the one-one table has been redefined to another character the one-one entry can not be changed again (instead the new definition will be placed in the standard table). For instance if the following lines were in a command file read by Turbo SNR (Assuming one-one usage is turned on): a=z ;This entry will be placed in the one-one table ;redefining the letter 'a' z=a ;This entry will be placed in the one-one table ;redefining the letter 'z' a=b ;This entry will *NOT* be placed in the one-one ;table since 'a' has already been redefined in ;the one-one table. Instead this entry will be ;placed in the standard table. Again, you should refer to the advanced topics chapter for a detailed discussion of the tables used by Turbo SNR. Note that if you specify a search or replace context other than 0 an entry will not be qualified to go in the one-one table. (See the discussion on substitution strings on page 31 for details about the context options). PPrrooggrraammmmeerr WWoorrddss ((pp)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should search for strings that would be considered words in a typical programming language. This is useful when you have source code and want to change a variable name or function name in your program. When this option is set the search strings will only be replaced if Turbo SNR considers the matching text to be a "programmer" word. At default this option is turned off. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ Turbo SNR considers a string to be a programmer word under the following conditions: Turbo SNR - Users Guide 19 1) The matching string in the input file must be preceded by one of the following: whitespace (' ' or \t), a newline (\r or \n), open parenthesis, quote character (' or " or `), a plus sign (+), a minus sign (-), an asterisk (*), a forward slash (/), a period (.), a caret (^), a percent sign (%), a dollar sign ($), an at sign (@), an exclamation point (!), an equal sign (=), a vertical bar (|), an ampersand (&), a curly brace ({ or }), a square bracket ([ or ]), a tilde (~), a question mark (?), a greater than sign (>), a less than sign (<), a colon (:), a semicolon (;), or a comma (,). If the string found in the input file is preceded by a character not specified above it is not considered to be a programmer word. 2) The matching string in the input file must be followed by one of the following: whitespace (' ' or \t), a newline (\r or \n), closing parenthesis, quote character (' or "), a colon (:), a semicolon (;), a plus sign (+), a minus sign (-), an asterisk (*), a forward slash (/), a period (.), a caret (^), a percent sign (%), a dollar sign ($), an at sign (@), an exclamation point (!), an equal sign (=), a vertical bar (|), an ampersand (&), a curly brace ({ or }), a square bracket ([ or ]), a tilde (~), a question mark (?), a greater than sign (>), a less than sign (<), or a comma (,). You should take special care since by the above definition of a programmer word Turbo SNR will consider matches in quotes to be just as valid as matches outside of quotes. RReegguullaarr EExxpprreessssiioonnss ((rr)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should allow use of regular expressions in the substitution strings. The use of regular expressions is a very powerful feature that allows you to do many things with Turbo SNR that aren't possible with other Search & Replace type programs. At default regular expression usage is off. Note that in ASCII mode, regular expressions may not be used to go past the end of a line unless you specifically include the line terminator in the search expression. In ASCII mode, none of 20 Turbo SNR - Command Line Options the wildcard/meta characters can be used to match the newline character. You must use the \n in the search expression to match a newline character. In binary mode, wildcard/meta characters can match and search through new lines without problems. The regular expressions supported by Turbo SNR are similar to those supported by Brief. The following lists the meta- characters and their meanings. @ Match zero or more repeats of the preceding character or expression. This meta character matches the most possible occurrences of a pattern that satisfy the match (it does a maximal closure). Ex: a@t Matches any of the following: t at aat aaat ...and so on. + This meta character does the same thing as @, except it matches 1 or more occurrences of the preceding character or expression. The most possible occurrences of a pattern that satisfy the match will be found. Ex: a+t Matches any of the following: at aat aaat ...and so on. * Matches anything. This wildcard does a minimal match if you specify something after it (i.e. a*b), otherwise it matches all the way to (but not including) the end of line. Ex: t*e Matches any of the following: the that was what he today's time Turbo SNR - Users Guide 21 ? Matches any single character (except the newline). < or ^ Matches the start of a line. Note that this is good to insure the next part of the search is at the start of a line. Ex: <How Matches the word 'How' when it is the first thing in a line. The word 'How' embedded in a line would not be matched. > or $ Matches the end of a line (not the newline character). This is good to insure the previous search expression was the last thing contained on a line. Ex: \t> Matches every line that has a tab character immediately before the newline character. [xyz] Set: Matches if the character for the position is included in the set. Ex: [abc]xyz Matches any of the following: axyz bxyz cxyz [~a] Matches anything that isn't in the set. [^b] [a-z] Matches anything between the two specifications. Ex: [0-9] Matches anything that is a digit. | Specifies a logical OR condition. This matches either the preceding or following character or expression. Ex 1: a|b Matches the letter a or the letter b Ex 2: mine|yours Matches the words: mineours and minyours (not mine or yours like you might have expected). To see how to 22 Turbo SNR - Command Line Options match the words mine or yours read through the next section about grouping. {} Group characters and expressions together for searching. Note that group numbers (for the purpose of replacing) start with zero. The use of groups allows you to: Group text together so you can refer to it in the replacement string by group number (see discussion below for how replacement using regular expressions works). Control the way a search pattern is evaluated (see the discussion below on how regular expressions are evaluated). Ex 1: {abc}xyz Matches occurrences of abcxyz (sets up one group - in the event of a match group 0 contains the text abc). Ex 2: {mine}|{yours} Matches occurrences of the words mine or yours (sets up two groups - in the event of a match the group that matched contains the matching text, the other group contains nothing). Ex 3: {{zortech}|{borland}} Matches occurrences of the words zortech or borland (sets up three groups as follows): Group 0 contains {zortech}|{borland}, which contains either zortech or borland (whichever matched). Group 1 contains zortech (or nothing if zortech wasn't matched). Group 2 contains borland (or nothing if borland wasn't matched). RReeppllaacceemmeenntt UUssiinngg RReegguullaarr EExxpprreessssiioonnss When you replace a string in Turbo SNR you generally would tell SNR exactly what string to insert as the replacement. The use of Turbo SNR - Users Guide 23 regular expressions allows you to replace using part of whatever matched by making use of the groups. When you use regular expressions you can specify group numbers in the replacement string by using the following syntax: \g9 Where 9 is the number of the group you wish to insert in the replacement string. As mentioned before groups are numbered starting with zero. Group numbering is based on the position of the opening curly brace ({). Going from the left to right the first { starts group 0, the next is group 1, etc. The following examples demonstrate how to use this powerful feature of Turbo SNR. Ex 1: If you specify the following pattern as the search pattern: {[Tt]he} program And use the following pattern as the replacement: \g0 best program The \g0 will be replaced with the string that matched group 0: {[Tt]he}. The pattern for group 0 will match all occurrences of the words The and the. In this example every occurrence of the pattern (The program or the program) will be replaced with The best program or the best program. Ex 2: If you specify the following pattern as the search pattern: {his}|{her} And use the following pattern as the replacement: \g1 The \g1 will be replaced with the string that matched group 1. Group 1 will contain the word her when matched, or NULL if the expression matched his. This replacement would cause all occurrences of his to be removed from the file. 24 Turbo SNR - Command Line Options HHooww RReegguullaarr EExxpprreessssiioonnss aarree EEvvaalluuaatteedd The meta characters used by Turbo SNR for regular expressions have a set precedence just as operators in other languages do. The following table lists the precedence for regular expression meta characters: {} [] Grouping has the highest precedence. If you enclose one or more characters within braces or brackets it is considered to be a single grouped expression. Ex: If you search for: {his}|{her} You are searching for his or her. If you search for: his|her You are searching for hiser or hiher. @ | + These characters have the next highest precedence and are matched from the left to right. Ex: The following patterns show simple examples of how these operators are treated when used alone: 1@2 (Searches for 0 or more 1's followed by a 2). 1|2 (Searches for either a 1 or a 2). 1+2 (Searches for 1 or more 1's followed by a 2). The following pattern shows an example that may not be clear when it comes to how the operators interact together. This demonstrates the idea that you must keep in mind these operators with equal precedence are read from the left to the right: 1|2@3 (Searches for 0 or more 1's or 2's followed by a 3). Since the OR operator is the leftmost it is evaluated first followed by the @. Turbo SNR - Users Guide 25 This expression could also be expressed as: {1|2}@3 After processing the characters listed in the precedence table above the remaining characters are concatenated. L_ i_ m_ i_ t_ a_ t_ i_ o_ n_ s_ There can be a maximum of 10 groups defined in the search pattern. In ASCII mode meta characters (i.e. *) won't go beyond the end of a line. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ Note that the use of regular expressions will slow Turbo SNR quite a bit. SSppeecciiffyy aa SSuubbssttiittuuttiioonn SSttrriinngg ((ss)) S_ y_ n_ o_ p_ s_ i_ s_ This option allows you to specify a substitution string from the command line. Note that substitution strings can also be specified using command files (see the chapter on command files on page 40 for details). You may freely intermix the use of the s option and command files. A detailed description of substitution strings will be presented in the chapter on substitution strings (see page 31). In this section I will only briefly cover how substitution strings are specified. A substitution string can have up to 4 different fields as follows: o Search context o Search value o Replace context o Replace value 26 Turbo SNR - Command Line Options Of these fields only the search value is required. All other fields are optional and have defaults if not specified. The context fields default to 0 when not specified, and the replace value defaults to NULL when not specified (i.e. causes the matching string to be deleted). The syntax for specifying a search string using the s option is: -s "[search_context:]search_value=[replace_context:][replace_val]" If specified the context fields should be a decimal integer from 0 to 9 followed immediately by a colon. The context is used when searching for a match - Turbo SNR will only look for strings with a search context that match the current context (or have the global context of 9). When a match occurs Turbo SNR replaces the match and then sets the current context to the replace context for the matching substitution string. The search value is whatever text you want to search for immediately followed by an equal sign. Lastly, the replace value is the string that you wish to replace the matched search string with. For example, to replace all occurrences of the word "all" with the word "most" you could specify the following: -s "all=most" L_ i_ m_ i_ t_ a_ t_ i_ o_ n_ s_ The number of strings you specify using the command line is only limited by the maximum command line length allowed by DOS. There are several characters that Turbo SNR considers command characters and won't allow you to place direct in the search or replace strings. These special characters must be preceded with a backslash to be used in the search or replace strings. The characters are: " ' \ : ; = S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ If you have many substitution strings you may wish to use a command file to specify them instead of manually doing it at the command line. Turbo SNR - Users Guide 27 VVeerrbboossee ((vv)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should output the file names as they're processed. At default this option is on. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ Several of the other options automatically turn verbose mode on. These options include: count matches, list line numbers, list matching lines, and interactive mode. WWoorrdd SSeeaarrcchh ((ww)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should search for strings that would be considered words in English text. This is useful when you have a text file and want to change all occurrences of selected words to something else. When this option is set the search strings will only be replaced if Turbo SNR considers the matching text to be a word. At default this option is turned off. S_ p_ e_ c_ i_ a_ l_ C_ o_ n_ s_ i_ d_ e_ r_ a_ t_ i_ o_ n_ s_ Turbo SNR considers a string to be a word under the following conditions: 1) The matching string in the input file must be preceded by one of the following: whitespace (' ' or \t), a newline (\r or \n), open parenthesis, quote character (' or " or `), or a forward slash (/). If the string found in the input file is preceded by a character not specified above it is not considered to be a word. 2) The matching string in the input file must be followed by one of the following: whitespace (' ' or \t), a newline (\r or \n), closing parenthesis, quote character (' or "), a colon (:), a semicolon (;), a forward slash (/), a period (.), an exclamation point (!), a question mark (?), or a comma (,). 28 Turbo SNR - Command Line Options IInntteerraaccttiivvee MMooddee ((zz)) S_ y_ n_ o_ p_ s_ i_ s_ This option specifies whether or not Turbo SNR should allow you to interactively specify which matches to replace. If you set this option Turbo SNR will prompt for each match to get your input as to what should be done. When a match occurs Turbo SNR will display the matching text in reverse video (the text is shown in context when possible, so the reverse video helps the matched value to stand out for you). After the matching text is displayed Turbo SNR displays the value that it will be replaced with (if the match is to be deleted from the file Turbo SNR displays: <<NULL>> as the replacement value). Finally, Turbo SNR prompts you for the action to take. Messages that are blinking during interactive mode are displayed by Turbo SNR to advise you of special conditions. The following is a list of possible blinking messages and the reasons they would be displayed: M_ e_ s_ s_ a_ g_ e_ R_ e_ a_ s_ o_ n_ T_ u_ r_ b_ o_ S_ N_ R_ d_ i_ s_ p_ l_ a_ y_ s_ <<START OF MATCH NOT SHOWN>> This message is displayed if Turbo SNR is unable to show you the match that occurred from the beginning. An example of how this can happen is when something matches around a newline in ASCII mode (in ASCII mode Turbo SNR will only display the line that contains the ending portion of the match). <<MORE>> This message is displayed when the replace value is longer than Turbo SNR is showing. Turbo SNR limits the amount of the replacement value shown to one screen line. The following is the prompt Turbo SNR displays at each match: Replace? <Y>es, <N>o, <A>nd the rest, <I>gnore the rest, <ESC> to Quit Turbo SNR - Users Guide 29 You specify the option you desire by pressing the appropriate key (the valid keys are displayed between the <>). The actions taken by Turbo SNR for the various keys are: Y (Yes) This tells Turbo SNR to replace the current match and continue searching. N (No) This tells Turbo SNR to skip replacing the current match and continue searching. A (And the rest) This tells Turbo SNR to replace the current match as well as all remaining matches - without prompting for the additional matches. (I.E. turns interactive mode off and automatically replaces all remaining matches). I (Ignore the rest) This tells Turbo SNR to skip the current match as well as all remaining matches - without prompting further (interactive mode is turned off and all remaining matches are automatically skipped). ESC (ESC to quit) Causes Turbo SNR to abort returning you to the DOS prompt (or shell/menu that called Turbo SNR). L_ i_ m_ i_ t_ a_ t_ i_ o_ n_ s_ Interactive mode currently only works on 100% Compatible IBM PCs. The method used for screen output is direct video writes - you should not use this method if your PC is not completely IBM compatible. 30 Turbo SNR - Command Line Options SSuubbssttiittuuttiioonn SSttrriinnggss One of the most important types of input you specify to Turbo SNR is in the form of substitution strings. Substitution strings specify what strings should be searched for and the replacement values to use when a match is found. In addition, Turbo SNR supports the idea of contexts allowing you to replace certain strings with one value the first time, another value the second time, etc. The following sections describe each aspect of a substitution string. S_ u_ b_ s_ t_ i_ t_ u_ t_ i_ o_ n_ S_ t_ r_ i_ n_ g_ S_ y_ n_ t_ a_ x_ Substitution strings used by Turbo SNR have a defined syntax. The following lists the syntax for specifying a substitution string: ["][search_context:]search_val=[replace_context:][replace_val]["] As mentioned at the start of this documentation the [] are used to signify optional parameters. You should note that the only required data for a substitution string is the search value immediately followed by an equal sign. There are two categories of fields possible in a substitution string. They are: o Context Specifier o String Specifier The context specifier is a decimal number followed immediately by a colon (the context specification is optional). The string specifier category includes both the search value and the replace value (the replace value is optional - if not specified Turbo SNR defaults to deletion of the search value from the input files). Each of the field categories will be explained in detail in the following sections. U_ s_ i_ n_ g_ C_ o_ n_ t_ e_ x_ t_ M_ o_ d_ e_ s_ Turbo SNR supports context sensitive searching and replacing through the use of two optional "context" fields in the substitution string. If you don't manually specify the context fields for a substitution string Turbo SNR will search for and replace every match in the input file(s). There may be times Turbo SNR - Users Guide 31 when you want to replace a certain string with one value the first time it occurs, another value the second time, etc... This is where the context fields come in. Turbo SNR supports a total of 10 different context settings numbered 0 through 9. When Turbo SNR first opens an input file it is working in context number 0. The first nine contexts will be referred to as "user definable contexts"; these are the contexts you assign to substitution strings you want Turbo SNR to search for only when the current context matches the user defined context. The last context (number 9) is a "global" context. This context is for strings that you want searched for no matter what the current context really is. Using the global context you can intermix strings that need to be searched for no matter what with other strings that you only want searched for under certain circumstances. In the substitution string the optional context fields let you specify the context Turbo SNR should be in before searching for the string as well as the context to switch to after replacing the string. The search context field indicates the context Turbo SNR should be in before trying to look for the search value. If you don't specify the search context a default of 0 is used by Turbo SNR. Turbo SNR will not search for values if the search context for the search string doesn't match the current context (with the exception of those strings using the global context of 9). When Turbo SNR replaces a matching string it will set the context to the value specified as the replace context. If you don't specify the replace context for a string a default of 0 is used. When you specify one or both of the context fields you use the number of the context and follow it immediately with a colon. For example, to specify a search context of 1 and a replace context of 5 the format would be: 1:search_value=5:replace_value Let's take a look at a few examples that show how this would work. Example: There are times when you may want to send a message or file to another person and insure that only the intended recipient will be able to read what you sent. To accomplish this you must come up with some sort of cipher that can be used to scramble the message. By 32 Turbo SNR - Substitution Strings using a cipher you can create a message that can only be read by those who know how to decipher the message. At a simple level of ciphering messages (or encrypting them as it's sometimes referred to) a translation table for each character of the alphabet is created so that one letter is always used in place of another. For example, every occurrence of the letter 'a' might be replaced with the letter 'w'. Using substitution the intended message would be translated to have words that look unreadable without knowing what letters were substituted for other letters. For example you might develop a cipher that would translate: Meet me at noon behind the gate To: Ztta zt ha dssd rtxbdq axt ihat The bad part about this type of cipher is that it is fairly easy for an outsider to decipher using trial and error. With just a little effort it is easy to figure out most of the message above. The longer a message is the easier it is to figure out the cipher that was used. Knowing just a little about the expected frequency of letters in the English language makes it even easier to decipher a message of this type since the letters were changed but the frequency of each was not (i.e. by figuring out that t stands for e the message above begins to unravel). To make things more secure it is desirable to replace a certain letter with one thing and then another thing the next time. You may be wondering (or may have already figured out) how Turbo SNR can help do something like file encryption. The answer is simple: By using context sensitive replacements you can make a message nearly impossible to decipher by persons not knowing the exact cipher you used. In the above example the cipher used was as follows: m = z e = t t = a a = h n = d o = s b = r h = x i = b d = q g = i Using Turbo SNR we can spice things up a bit by making the whole message one big word as well as using context to replace a character with different things at different times. Included with Turbo SNR are two Turbo SNR - Users Guide 33 sample command files called CIPHER.TAB and DECIPHER.TAB (see the discussion on command files on page 40 for details about using command files). Feel free to work with these (if you're familiar with C take a look at CIPHER.C which is also included!). When you use SNR and one of the command files on a text file it's contents will become scrambled until SNR is used with the other command file. Using the CIPHER.TAB file on the original message changed: Meet me at noon behind the gate To: A](gUaPUtgUqmdqk{(B}qVU:B]AG':P As you can see this version of the encrypted text is a bit more difficult to figure out than the simple example presented before. Example: To provide a simpler example of how multiple contexts work assume the following substitution strings were specified: "0:abc=1:xyz" "1:abc=0:abc" The example above would cause the text 'abc' to be replaced with 'xyz' every other occurrence. If a file contained the following line: abcabcabcabcabc And the substitution strings listed above were used it would be converted to: xyzabcxyzabcxyz The examples listed above are just an introduction of what can be accomplished using the context support of Turbo SNR. U_ s_ i_ n_ g_ S_ t_ r_ i_ n_ g_ S_ p_ e_ c_ i_ f_ i_ e_ r_ s_ The strings you want to search for and replace with are considered string specifiers. Turbo SNR provides some powerful features that help you specify any possible mixture of data (including non-ascii data). This section of the manual describes in detail how strings can be specified. You can specify any 34 Turbo SNR - Substitution Strings possible string value using the features available for specifying strings to Turbo SNR. As mentioned before there are two ways you can specify substitution strings: o On the command line using the -s option o In a command file U_ s_ i_ n_ g_ W_ h_ i_ t_ e_ S_ p_ a_ c_ e_ i_ n_ S_ t_ r_ i_ n_ g_ s_ It is important to note that Turbo SNR will ignore any white space (i.e. spaces or tabs) in a substitution string unless they are in quotes. This convention is necessary to allow free form comments in the command files (see the discussion on command files on page 40 for details) as well as prevent possible syntax errors when reading the command line. For simplicity I strongly suggest you enclose all substitution strings in quotes, however, for those that desire to know the details I will describe the rules Turbo SNR uses for white space treatment in the following examples. If you're not interested in the details presented feel free to skip to the next section. Let's look at a couple of examples that will illustrate the point about white space being ignored when it's not quoted: Ex: If you were to type the following at the command line: SNR -s Copyright = Copyr *.c Turbo SNR would have no way of knowing what you were trying to do. The above command line would cause the following messages: (CMD Line) Line (0): = required to specify replace value. Warning: no files matching (=) Warning: no files matching (Copyr) *** 1 Errors Found *** These errors were all caused because of the white space embedded in the substitution string. When scanning the command line a white space character not in quotes is considered to be the end of the option that was being defined. Turbo SNR - Users Guide 35 To clear the error messages you could specify the above command line as follows: SNR -s "Copyright=Copyr" *.c Ex: Now let's look at the same replacement string used in a command file called MY.TAB. Assuming the command file contained the following line (the left margin is marked below for clarity): Copyright = Copyr ;This is a comment ^ | Left margin of command file This would cause all occurrences of "Copyright" to be replaced with "Copyr". Note that the leading, trailing and embedded spaces are ignored by Turbo SNR since they aren't in quotes. If we were to specify the line above as: "Copyright = Copyr" ;This is a comment ^ | Left margin of command file This would cause all occurrences of "Copyright " to be replaced with " Copyr". Note that the leading and trailing spaces are ignored (since they aren't in quotes), but as shown the embedded spaces that are inside quotes are inserted in the strings. Note that this specification does the same thing as: "Copyright " = " Copyr" ;This is a comment That should give you a general feel for how spaces and tabs are handled by Turbo SNR. Again, I suggest you enclose the entire substitution string in quotes for simplicity. S_ p_ e_ c_ i_ a_ l_ C_ h_ a_ r_ a_ c_ t_ e_ r_ s_ I_ n_ S_ t_ r_ i_ n_ g_ s_ There are certain characters that Turbo SNR considers to be "special" and won't allow you to simply insert in a string. To overcome this limitation Turbo SNR supports the idea of using an "escape character" to insert special characters. Those familiar with a programming language like C are likely to already understand how this works. Anytime you want to specify a special character in a string you precede it with the backslash character 36 Turbo SNR - Substitution Strings (\). When Turbo SNR finds a \ in a string it treats the next character in a special way as defined in the following table (note that Turbo SNR considers the special characters to be the same no matter what the actual case is - upper case is treated like lower case for the purposes of the special characters): Turbo SNR - Users Guide 37 Char Description \b This causes a backspace to be inserted in the string. \n This causes a linefeed to be inserted in the string. \r This causes a carriage return to be inserted in the string. \t This causes a tab to be inserted in the string. \x9 This causes a hex byte to be inserted in the string. Note that you may specify multiple values with one escape code as in the following: \xff101d00 ;Inserts 4 hex bytes in a string. \xff\x10\x1d\x0 ;Does the same as above using ;multiple escape codes. Turbo SNR considers the hex specification to be over when it encounters a non-hex character in the string. Each two hex digits in the string are interpreted as a single character (byte) value. In the above example the character values ff, 10, 1d, and 0 would be inserted in the string. \99 This causes a decimal byte to be inserted in the string. Note that you may only specify one byte value using decimal (i.e. a value from 0 - 255) per escape code. For example: \999 ;This causes an error message \10 ;Causes a linefeed (character 10) to be ;inserted in the string. \g If you're using regular expressions a 'g' following a backslash in the replace value causes group substitution. See the discussion on replacement using regular expressions on page 23 for details. AAnnyy cchhaarraacctteerr nnoott lliisstteedd aabboovvee iiss iinnsseerrtteedd aass aa lliitteerraall cchhaarraacctteerr iiff iitt iiss pprreecceeddeedd wwiitthh aa \\.. If you are using regular expressions and wish to insert a literal character in the search value that is the same as a regular expression meta character (i.e. * @ | + < > $ ~ [ ] ^) you must 38 Turbo SNR - Substitution Strings precede the character with a \ to keep it from being interpreted as a regular expression meta character. The following lists the characters that MUST be escaped to be inserted in a string. Attempts to insert the characters listed below without preceding them with a \ will generally cause an error message when Turbo SNR reads the substitution string: ;; \ = " ' : With the exception of the quotes and the backslash all the characters listed above are considered commands by Turbo SNR if they aren't preceded with a \. Failure to not use a preceding \ when you want to insert a quote or backslash in a string will generally cause SNR to give undesired results. Turbo SNR - Users Guide 39 UUssiinngg CCoommmmaanndd FFiilleess This chapter describes the details on using command files for specifying substitution strings. Command files are a handy way to store a set of related substitution strings to be used on files without having to manually specify the individual strings each time you use Turbo SNR. Additionally, command files can be used to get around the DOS maximum command line length allowing you to specify as many substitution strings at once as memory will hold. To specify the use of a command file you proceed the filename with an @ sign. If you don't specify an extension a default of .TAB will be used. As an example, the following command lines tell Turbo SNR to use a command file called CIPHER.TAB: SNR @cipher MYFILE.EXT SNR MYFILE.TXT @cipher.tab You can specify multiple command files by simply including more on the command line. Turbo SNR supports as many command files as you can specify on the DOS command line (the only limitation is available memory). You may also toggle on and off the use of a one-one table between command files. For instance: SNR -o @table.tab -o- @other.tab MYFILE.EXT The example above uses the one-one table when possible for the entries in the command file called TABLE.TAB. The entries in OTHER.TAB are not allowed to go in the one-one table. For details on the one-one table see the discussion on page 17. There are three types of data that can be in a command file as follows: o Substitution Strings o White space (or blank lines) o Comments When you use a command file to specify substitution strings you don't precede the strings with a -s or /s like you need to on the command line. All you need to do in the command file is list each substitution string on a separate line. If you are unsure 40 Turbo SNR - Using Command Files of the format required for substitution strings refer to the -s option on page 26 or the chapter titled 'Substitution Strings' on page 31. As mentioned earlier white space outside of quotes is ignored by Turbo SNR. This allows you to have leading and/or trailing spaces as well as blank lines in the command file without it changing the substitution strings specified. If you want to use white space in a substitution string the string must be quoted. Comments are supported in command files to allow you a way to document what the command file does as well as any special things you want to say about the substitution strings. When Turbo SNR finds a semi-colon on a line it considers the remaining text on the line to be a comment. The comment can contain any type of information or data you desire - Turbo SNR completely ignores the remainder of a line once the semi-colon is reached. If you want to specify a semi-colon in the search or replace value of a substitution string you must precede the semi-colon with a backslash. See the example files that came with Turbo SNR for a typical example of what a command file can contain. Turbo SNR - Users Guide 41 AAddvvaanncceedd TTooppiiccss This chapter has several sections that deal with some of the more advanced topics regarding the use of Turbo SNR. This chapter covers topics like the order Turbo SNR looks at substitution strings , using the one-one table along with the standard table, and multi-pass processing. T_ a_ b_ l_ e_ s_ a_ n_ d_ t_ h_ e_ O_ r_ d_ e_ r_ S_ u_ b_ s_ t_ i_ t_ u_ t_ i_ o_ n_ S_ t_ r_ i_ n_ g_ s_ A_ r_ e_ L_ o_ o_ k_ e_ d_ A_ t_ This section describes in detail the way that Turbo SNR looks for a match against substitution strings. After reading this section you will have a good idea how Turbo SNR is doing things based on what you give it for options and substitution strings. At default Turbo SNR works well for virtually all the cases it's given - this section helps those who desire to know how to fine tune the way Turbo SNR operates. As has been mentioned several times there are two levels of replacement used by Turbo SNR. To recap, these are: One-One Table Replaces character for character as the file is being read. Replacements in the one-one table are complete before Turbo SNR even starts to search for matches with the substitution strings contained in the standard table. Standard Table This is the table that is used by Turbo SNR for all the strings that don't qualify for the one-one table (qualifying one-one strings are only placed in the standard table if the use of the one-one table hasn't been enabled or if the entry in the one-one table is already used). Strings in this table are searched for after the one to one replacement has been done. If the option to strip the 8th bit is turned on the bit stripping will occur immediately after the one-one replacement (or as the file is being read if the one-one table isn't being used). This means the bit stripping occurs before the standard table strings are searched for. Once one-one replacement and 8th bit stripping have been completed Turbo SNR begins searching the file for matches to the substitution strings contained in the standard table. 42 Turbo SNR - Advanced Topics When regular expressions aren't used, the order you specify substitution strings in doesn't matter. In regular expression mode, Turbo SNR looks for matches in the standard table in the order the strings were specified. When regular expressions are used Turbo SNR scans the input file for a match to the first character of the substitution strings (again note that strings are checked in the order they were specified). Once a match on the first character occurs Turbo SNR checks to see if the entire search value matches. If the search value doesn't match Turbo SNR goes back where it was and starts scanning again for the next first character match. You should be aware that replacements are not searched for a match to one of the substitution strings. When a string is inserted in the file Turbo SNR will begin searching the text immediately following the replaced data. M_ u_ l_ t_ i_ -_ P_ a_ s_ s_ P_ r_ o_ c_ e_ s_ s_ i_ n_ g_ Turbo SNR allows you to make multiple passes on the same file. At times this type of processing can be handy. One example of this is the encryption of files. For instance if you had a file named MYFILE.TXT and typed the following at the command line (assuming you still have the CIPHER.TAB and DECIPHER.TAB available): snr @cipher MYFILE.TXT MYFILE.TXT MYFILE.TXT The only way to decrypt the file would be to process it the same number of passes by: snr @decipher MYFILE.TXT MYFILE.TXT MYFILE.TXT Since Turbo SNR doesn't search for a match in the replacement strings you may wish to use multi-pass processing for special effects on the resulting text from the first pass. Your imaginations the limit using Turbo SNR! Turbo SNR - Users Guide 43 AAppppeennddiixx AA -- TTuurrbboo SSNNRR MMeessssaaggeess There are quite a few messages that can be generated by Turbo SNR while it is in use. This appendix lists the messages generated by Turbo SNR in three categories: o Informational These are messages displayed to advise of things such as the number of replacements (i.e. when you turn count mode on), or display the replace values and ask for input in interactive mode. These type of messages are normal when you set certain options in Turbo SNR. o Warning These are messages displayed to warn you about a possible error condition. Warnings occur for things like such as an input file that can't be opened (i.e. doesn't exist or is read only). o Error There are messages that are displayed to advise you of an error condition that Turbo SNR feels you should correct before it proceeds. A typical example of an error is when Turbo SNR detects a problem with the syntax of the substitution string or runs out of memory. Of the various categories only those messages that are considered errors will stop Turbo SNR from continuing operation. The following pages list the various messages and a description of what the likely cause of the problem is. The messages are listed alphabetically within each category to help simplify locating a particular message. For the purposes of this appendix only the error message text will be listed in the tables. Many of the messages have diagnostic information preceding them such as the file name, line numbers, and message category (i.e. some specify whether it is a warning or an error). 44 Turbo SNR - Appendix A, Program Messages I_ n_ f_ o_ r_ m_ a_ t_ i_ o_ n_ a_ l_ M_ e_ s_ s_ a_ g_ e_ s_ *** 9999 Errors Found *** This is a message that is displayed when Turbo SNR detected syntax errors in the substitution strings. This message is simply to advise you of the total number of errors encountered. 9999 matches, 9999 replacements. This message is displayed when count mode is used with interactive mode. At the end of each file this message indicates the total number of matches that occurred in addition to the number you told Turbo SNR to replace. 9999 replacements This message is displayed as a running counter of the number of replacements in a file when you are using the count option. Backing... This message is displayed to let you know Turbo SNR is backing up the current file. This message will only be displayed when verbose mode is on (see discussion on verbose mode on page 28 for details). Closing... This message is displayed to let you know Turbo SNR is closing the current file. This message will only be displayed when verbose mode is on (see discussion on verbose mode on page 28 for details). Done! This is yet another message displayed when verbose mode is on. This message advises Turbo SNR is finished with the current file. (see discussion on verbose mode on page 28 for details). *** Ignoring remaining matches per you request. *** This message is displayed when you tell Turbo SNR to ignore the current match as well as the remaining matches during interactive mode. <<MORE>> This message is displayed as blinking text during interactive mode to let you know the replacement value for the current match is longer than Turbo SNR is displaying (see the discussion on interactive mode on page 29 for details). Turbo SNR - Users Guide 45 ** Not Changed ** This message is displayed to advise when a file is left unchanged. This occurs when ASCII mode is being used and Turbo SNR determines during the replacement process the file is not an ASCII file (or has a line longer than the max allowed length of 8096 bytes). <<NULL>> This message is displayed during interactive mode to let you know the matched data will be replaced with nothing (i.e. it is to be deleted). See the discussion on interactive mode on page 29 for details. Remaining table memory: 9999 This message is displayed after Turbo SNR reads all the command files and parses the command line substitution strings to give you a rough estimate on the amount of free memory remaining. Note that when you specify that Turbo SNR should search child subdirs some of this memory will be required to store the names of matching files in the subdirs. Replace? <Y>es, <N>o, <A>nd the rest, <I>gnore the rest, <ESC> to Quit This prompt is displayed when a match occurs during interactive mode (see the discussion on interactive mode on page 29 for details). **Replaced** This message is displayed during interactive mode when you tell Turbo SNR to replace the current match. *** Replacing remaining matches per your request. *** This message is displayed when you tell Turbo SNR to replace the current as well as the remaining matches during interactive mode. Scanning directories for files matching: FILE... This message is printed to advise Turbo SNR is searching the child subdirectories for files matching the one listed in the message. This message is displayed when you have verbose set on and use the search dir option. **Skipped** This message is displayed during interactive mode when you tell Turbo SNR to skip the current match. <<START OF MATCH NOT SHOWN>> 46 Turbo SNR - Appendix A, Program Messages This message is displayed as blinking text during interactive mode when the start of the matching data was not displayed by Turbo SNR (see the discussion on interactive mode on page 29 for details). Turbo SNR - Users Guide 47 W_ a_ r_ n_ i_ n_ g_ M_ e_ s_ s_ a_ g_ e_ s_ FILE.EXT is read only. ***Skipped*** This message warns you that the specified file has the read only bit and is not going to be processed by Turbo SNR as you requested. You must set the read only attribute off if you desire to process the file with Turbo SNR. No files matching (FILE) This message warns you that a matching file couldn't be found for the specified file specification. Unable to open FILE! This message warns you that Turbo SNR is unable to open the specified file for reading. This can occur if the file is locked (i.e. already in inclusive use in a SHARE environment) or the specified file is a directory. 48 Turbo SNR - Appendix A, Program Messages E_ r_ r_ o_ r_ M_ e_ s_ s_ a_ g_ e_ s_ = required to specify replace value. This error occurs when an equal sign isn't included in the substitution string on the specified line of the command file. An equal sign is required to mark the end of the value to search for. Ambiguous regular expression not allowed (leading/trailing |). This error means that the regular expression located on the specified line has a leading or trailing | (logical OR operator). This is not valid syntax for a regular expression. Command file name expected This error means that a file name didn't follow the @ on the command line. You must specify a command file name immediately after the @ (no space between the @ and the file name). Command file not found: FILE.EXT This error means that the specified command file doesn't exist. Keep in mind that although Turbo SNR allows wildcards to be used with input files they are not supported for the command file names. Only the first matching file for a given command file specification will be used. Decimal number is out of range (0-255). Use HEX # instead. This error is displayed when an embedded decimal number specification in the substitution string (\999) is greater than the max allowed (255). If you wish to specify a sequence of bytes in numeric format you must use HEX mode (see discussion on Substitution Strings on page 31 for details). Disk full writing temp file! This error is displayed if there isn't enough free space on the drive the temp file is being created on. Turbo SNR creates the temp file on the current drive and directory. ESCape pressed. User aborted. This message is displayed when you press the ESCape key at one of the prompts displayed during interactive mode. Turbo SNR displays this message to let you know why it aborted. Ignore Case flag required to keep existing case. This error occurs when you specify Turbo SNR should keep existing case without also specifying to ignore case when Turbo SNR - Users Guide 49 searching. Turbo SNR considers it to be an error if you use the keep case option without using the ignore case option. 50 Turbo SNR - Appendix A, Program Messages Internal inconsistency. This error is an internal error message. Please report any occurrence of this message, and if possible a set of steps that will help reproduce the problem so it may be looked into. Invalid option This error is displayed when you specify a command line option that is not valid. Type SNR ? or SNR /h for a list of all the valid options. Invalid [] range. This error is displayed when the range for a class is specified in an incorrect manner. A typical example of this would be: [9-1]. The first value of the range must be the smallest value. Invalid context flag: This error occurs when Turbo SNR detects an invalid context flag specification in the input file (see the discussion on Substitution Strings on page 31 for details on how Turbo SNR evaluates substitution strings). Invalid replace group specifier This error occurs when regular expressions are used and you specify a replacement group that is non-numeric. No valid file(s) specified. This error occurs when Turbo SNR can't locate any of the input files specified and you have directory searching turned off. This means the input files you specified don't exist. Nothing to do! This error occurs when Turbo SNR doesn't have anything to do. This means that no substitution strings were specified and none of the options like 8th bit stripping were specified. NULL expression before closure. This error occurs when using regular expressions if you attempt to use closure (@ +) before defining a character to use them on. See the discussion on regular expressions on page 20 for details on using regular expressions. No search value specified. This error occurs when a substitution string doesn't contain a value to search for. Look at the offending line and Turbo SNR - Users Guide 51 insure you typed the substitution string in as intended. See the discussion on substitution strings on page 31 for details. Out of memory. This error occurs when Turbo SNR doesn't have enough memory to process all the substitution strings and/or file names that you specified. If this error occurs you'll have to specify fewer files, turn off searching directories, and/or reduce the number of substitution strings specified at once. In most cases this error will only occur when you search subdirs and Turbo SNR is working on a very large number of files at once. Regular expressions not valid across newline. This error message is displayed if you specify a substitution string that attempts to use regular expressions in a way that wraps around the end of line. Regular expressions may only be used to go up to (and optionally include) the end of line. If you wish to wrap around lines you must not use regular expressions. See the discussion on regular expressions on page 20 for details on the use of regular expressions). Replace group specifier (999) is out of range. This error occurs when regular expressions are used and you specify a replacement group that is out of range (i.e. you ask Turbo SNR to replace with regular expression group 5 when there is only one group defined). See the discussion on regular expressions on page 20 for details about using replacement groups. Replace value too long (255 chars max!) This error occurs if you attempt to specify a replace value that is longer than the maximum allowed by Turbo SNR. Search value too long (255 chars max!) This error occurs if you attempt to specify a search value that is longer than the maximum allowed by Turbo SNR. Too many nested RE groups - Max is 10! This error occurs when using regular expressions if you specify more groups in the search portion of the substitution string than Turbo SNR allows. 52 Turbo SNR - Appendix A, Program Messages Trailing \ is not allowed. This message is displayed when the last character on a line in a command file is a single \. \ is not allowed as a single character (you probably meant to use \\ instead of a single \). Unable to open temp file (FILE.EXT) This error occurs when Turbo SNR is unable to open it's temp file for writing. Turbo SNR uses a temp file name of S_N_R_V1.CBL (which is written to the current directory). Turbo SNR must be able to open and write to this file to operate properly. Unexpected '=' in replace value This error occurs when a substitution string contains more than one equal sign. If you want to search for a string containing the equal sign or replace with a string that contains an equal sign you need to precede the equal sign with a backslash. See the discussion on substitution strings on page 31 for syntax. Unexpected context specifier This error occurs when Turbo SNR detects a context specification in the substitution string where it didn't expect one (this is caused by using a colon in the search/replace string without remembering to precede it with a backslash). See the discussion on substitution strings on page 31 for syntax. Unmatched [] This error occurs when regular expressions are used and a substitution string has the start of a set but doesn't contain the closing bracket. Unmatched {} This error occurs when regular expressions are used and a substitution string has the opening brace but doesn't contain the closing brace. Turbo SNR - Users Guide 53 AAppppeennddiixx BB -- SSppeeeedd CCoonnssiiddeerraattiioonnss Turbo SNR was designed to provide extremely fast search and replace capabilities, however, under certain conditions even Turbo SNR can be slowed down somewhat by the options that are being used. The following table lists the options that have an effort on speed in worst case order (items with the greatest impact on speed are listed first). Suggestions for speeding each of the items are listed in the table as well. Time Consumption Description and Suggestions for Speeding Problems Things Up A large number The number of replace strings specified has of search a great effect on how fast Turbo SNR strings operates. Since Turbo SNR must perform a linear search to insure checking all valid options it will take longer as new strings are specified for searching. Suggestions: Use the one-one table where possible since one-one table entries have virtually no processing overhead associated with them. Use of regular Using regular expressions is significantly expressions slower than searching using other methods. Suggestions: Avoid the use of regular expressions when possible. List matching Due to the relative slow speed data is lines displayed to the screen each of these three options will eat a great deal of processing List matching time. line numbers Suggestions: Avoid using the options that Count Matches cause Turbo SNR to produce a lot of output. Redirect Turbo SNRs output to a file when using any of these options. 54 Turbo SNR - Appendix B, Speed Considerations Time Consumption Description and Suggestions for Speeding Problems Things Up Use of ASCII Using ASCII mode is a little bit slower than mode using the binary search method due to the extra processing required to handle the line terminators. Suggestions: Avoid the use of ASCII mode when possible. Use of the Word Searching for words takes just a bit longer Flags than would be required if the word flags were off. Suggestions: Only use the word flags when it's really required. Other options have very little effect on the runtime speed of Turbo SNR. The main time consumers are as listed in the table above. Turbo SNR - Users Guide 55 AAppppeennddiixx CC -- TTeecchhnniiccaall SSppeecciiffiiccaattiioonnss The following table lists the limits when using Turbo SNR. The limits can vary depending on the mode being used as shown in the table. Regular ASCII mode Binary Expr. Mode Maximum Line Length of No limit No limit No limit Input Files Maximum Search String 255 bytes* 255 bytes 255 bytes Size Maximum Replace String 255 bytes* 255 bytes 255 bytes Size Maximum Memory for 45,000 45,000 45,000 table space bytes bytes bytes Maximum Regular 10 Doesn't Doesn't Expression Groups Apply Apply Maximum Command Files No limit No limit No limit Maximum substitution No limit No limit No limit strings Maximum Input files No limit No limit No limit Maximum File Size No limit No limit No limit * Regular expression wildcards can be used to match values longer (and replace using values longer) than the 255 character limit. All entries listed above as no limit have no limitations imposed by Turbo SNR, however, memory limitations do apply as each requires some amount of the limited table memory. Although there is no limit imposed by Turbo SNR on maximum input file size, enough free space on the current drive and directory is required to create the new file. (Turbo SNR doesn't directly modify the original file - Turbo SNR was designed to be safe in the event of a power failure). 56 Turbo SNR - Appendix C, Technical Specifications IInnddeexx Turbo SNR - Users Guide 57 8th bit option 29 stripping 12 keep old case ASCII option 15 mode 12 line numbers Word Star Conversion listing 12 12 line terminators 12 backup list lines name generation 13 option 17 option 13 maximum calling groups 26 Turbo SNR 8 messages case error 49 ignoring 15 informational 45 keep existing 15 warnings 48 characters modes special 36 ASCII 12 command file interactive 29 contents 40 multi-pass details 40 processing 43 command files 9 one-one table using 40 context restrictions context modes 18 details 31 option 17 one-one restrictions options 18 command line 9 using 31 descriptions 12 count overview 8 option 14 specifying 10 directories parameter searching 14 types 8 error parameters, messages 49 optional 6 files precedence command 40 regular expressions groups 25 maximum allowed 26 programmer words regular expressions option 19 23 regular expressions replacing with 24 evaluation 25 hi bit groups 23 stripping 12 option 20 ignore case 15 replacement using informational 23 messages 45 wildcards 21 interactive mode replace string 34 58 Turbo SNR - Index replacment with groups 24 search string 34 searching directories 14 order 42 special characters in strings 36 speed considerations 54 improving 54 string specifiers using 34 strings 34 in command files 40 including white space 35 using special characters 36 substitution string option 26 syntax 27, 31 substitution strings details 31 in command files 40 order looked for 42 syntax for substitution string 27 for substitution strings 31 tables one-one 17 order processed 42 verbose option 28 warning messages 48 white space in strings 35 wildcards regular expressions 21 Word Star convert to ASCII 12 words option 28 programmer 19 Turbo SNR - Users Guide 59