PED4DOS Programmable Editor with extended facilities for searching and replacing for batch processing with MS-DOS version 1.40 December 1995 Copyright 1995 Software-Quelle GmbH Software-Quelle Datentechnik GmbH Erfurter Strasse 15 D-85386 Eching Germany Telefax: +49 89 327133 36 Compuserve: 100034,2365 Internet: 100034.2365@compuserve.com 1 Introduction 4 2 Command-line syntax 5 3 Operating PED4DOS at run time 8 3.1 Find a matching string 8 3.2 Replace a string 8 3.3 Show statistical information 9 3.4 Write changes to the current file 9 3.5 View data at search position 10 3.6 Change perform options 11 3.7 Trace menu 12 4 Editing facilities 14 4.1 Introduction 14 4.1.1 Search and replace 14 4.1.1.1 Simple search 14 4.1.1.2 Search multiple different strings 14 4.1.1.3 Search for words, search case sensitive 14 4.1.1.4 Simple search and replace 15 4.1.1.5 Search pattern 15 4.1.1.6 Hexadecimal characters 15 4.1.1.7 Search for unknown character strings 16 4.1.1.8 Replacing pattern 17 4.1.1.9 Search Region 17 4.1.2 Jump statements and labels 18 4.1.3 Variables 19 4.1.3.1 String variables 19 4.1.3.1.1 Implicit assignment to string variables 19 4.1.3.1.2 Use string variables 20 4.1.3.1.3 Explicit assignment to string variables 20 4.1.3.1.4 Compare string variables 22 4.1.3.2 Numerical variables 22 4.1.3.2.1 Implicit assignment to numerical variables 22 4.1.3.2.2 Use numerical variables 23 4.1.3.2.3 Explicit assignment to numerical variables 23 4.1.3.2.4 Compare numerical variables 24 4.1.3.3 Functions 24 4.1.3.3.1 String functions 24 4.1.3.3.2 Numerical Functions 25 4.2 Syntax summary 27 4.2.1 Executing a search program 27 4.2.2 Syntax description 28 4.2.2.1 Definitions 28 4.2.2.2 Conventions 28 4.2.2.3 Syntax part 1 29 4.2.2.4 Syntax part 2 30 5 Examples 34 5.1 Check the FILES parameter in CONFIG.SYS 34 5.2 Convert special letters from ANSI to OEM or ASCII 34 5.3 Format a list file as input for a spreadsheet program 35 6 Contents of the PED4DOS software package 39 6.1 Executable Files 39 6.2 Samples 39 6.3 Documentation 40 1 Introduction PED4DOS is designed for searching and replacing complex character strings in ASCII text or binary files according to a search program with a minimum of interaction with the user; it is not a "full screen text editor". PED4DOS enables you to extract data from any file that is built according to a known syntax and write it to another file, or modify the data within the original file. Here is a short survey of the outstanding facilities: * search (and replace) multiple character strings within a single pass through the file * search (and replace) unknown character strings, that match a given pattern * store the matching strings to string variables for later use * replace character strings by the content of string variables * search complex character strings, that match a pattern consisting of simple character strings and/or string variables and/or unknown character strings; replace by complex character strings, that consist of simple character strings and/or string variables and/or parts of the matching string * move the search position within the file * modify the contents of string variables by use of functions * output character strings to the screen * copy any or part of the output to a log file Please execute the accompanying command file DEMO.BAT file if you want to see how PED4DOS works. Document conventions: The following conventions are used throughout this manual to define syntax: Bold text Denotes a term to be typed literally, such as a command or a command line option. You must type a term exactly as shown (but letters are not case sensitive) Italic text Denotes a placeholder or variable: You must provide the actual value. If surrounded with < and > characters, denotes a syntactical symbol (see the syntax description in chapter 4.2) monospace This font is used for examples and program output [] Enclose optional parameters | Separates alternatives {} Enclose alternative parameters: You must provide exactly one of these parameters ... Specifies that the preceding item may be repeated CAPITALS Denotes keys of the keyboard, filenames 2 Command-line syntax The following line shows PED4DOS command-line syntax: P4D input-file [ search-program ] [ options ] input-file(s) Replace input-file by the fully or partially qualified name of the file to be edited; if input- file contains wildcard characters, all corresponding files will be edited. search-program Replace search-program by the of a ; a describes what PED4DOS shall do. (The syntax of a is described in chapter 4.2; an introduction is contained in chapter 4.1). Search-program must be passed as a single parameter to PED4DOS (i.e. if search-program contains white spaces, it must be surrounded with delimiting characters such as " or ` , and search-program itself must not contain the delimiting character). Note: Some command interpreters handle the delimiting characters in their own way; see the description of your command interpreter. If the consists of multiple statements, it is recommended to write the to a file and use the option /f (see below) options PED4DOS accepts the following command-line options: /c:command-file Replace command-file with the name of an ASCII text file, that contains further command-line options. This is useful, if the length of the command-line exceeds the limits of the command interpreter (e.g. COMMAND.COM). /f:prog-file Replace prog-file with the name of an ASCII text file, that contains the . The must not be surrounded with delimiting characters. If PED4DOS cannot find prog-file within the current working directory, it will search for prog-file within the following directories: 1. the directory where the executable file P4D.EXE resides 2. the directories that are contained in the PATH environment variable /l:log-fileReplace log-file with the name of an ASCII text file, that PED4DOS will create at startup time; all program output will be copied to log-file unless inhibited by the /p option (see below). /p:[+|-]p[e..][:..] (perform modes): while editing the , PED4DOS will start a dialog with you whenever one of the following events occurs: 1) PED4DOS finds a that matches a 2) PED4DOS finds a that shall be replaced by a 3) PED4DOS has edited a file, that contains at least 1 ; PED4DOS would like to display statistics of the (and the if any). 4) PED4DOS has edited a file and replaced at least one by a ; PED4DOS would like to write the changes to (or to another file at your request) 5) PED4DOS executes a that requires to display a on the screen Use the /p option to change the behavior of PED4DOS in the above events; the string /p: may be followed by one or more option strings, separated by colons; each option string consists of up to 3 parts: 1) A + or - character activates or deactivates the perform mode p for the event e, respectively; the + character may be omitted. 2) Replace the perform mode p by one of the following letters: c (confirm) : if activated, every event e must be confirmed s (show) : if activated, the message according to event e will be displayed on the screen d (dialog) : combination of c and s l (logging) : if activated, the message according to event e will be copied to log-file (see also the option /l) b (batch mode): same as -c:-s; deactivates any show and confirm mode 3) Replace the event e by one or more of the following letters; if omitted, it defaults to a(all): m (match): a has been found in the r (replace): a shall be replaced by a s (statistics): at least 1 was found in the w (write): at least 1 < matching string> has been replaced o (output): a requires to display a . a (all): all of the above events; default, if no event letter has been typed examples: /p:-cmsno confirmation for matching strings and statistical information /p:-dmsno output, no confirmation for matching strings and statistical information /p:b no display, no confirmation during batch processing (same as /p:-sa:-ca ) /p:-l:+lo write only the output of display to the logging file /s[:n] PED4DOS will search subdirectories up to a level of n to find files corresponding to input-file. /b:ext If the option /bn (see below) is omitted, every modified file will be copied to a backup file with the filename extension ext before being updated. If this option is omitted, ext defaults to BAK /bn The modified files will not be saved in backup files before being updated (no backup) /help PED4DOS will display a short description of the options on the screen and ignore all other parameters (i.e. will not edit any file) /nologo PED4DOS will not display the startup message /trace[:n] Set the trace mode for the . The optional parameter n denotes the number of that shall be executed without interruption; if omitted, n defaults to 1 (see chapter 3.7) Example: The following command will search SPACES in the files DEMO*.IN, display only statistical messages (i.e. number of SPACE characters within the files) and write only statistical messages to the log file DEMO.LOG: p4d demo*.in " ' ' " /l:demo.log /a:-d:+ds:-l:+ls See the file DEMO.BAT for further examples. 3 Operating PED4DOS at run time The following chapters describe the dialog between PED4DOS and you at run time: 3.1 Find a matching string Whenever PED4DOS finds a , that matches a defined in the , it displays a message like the following: file:input.txt, line: 22, offset: 0x337 = 823 followed by the and a predefined quantity of characters surrounding the , followed by the menu line: continue? (yes / all / skip file / view .. / perform options .. / quit) Press one of the following keys so PED4DOS will act according to the description: y continue executing the (i.e. execute the next ) a continue executing the , but only count (i.e. no display, no confirmation) s discontinue editing the ; if any changes have been made before, PED4DOS will attempt to write the changes to the file (see chapter 3.4) v show the "view" menu (see chapter 3.5) that enables you to view the data at the current p show the "perform options" menu (see chapter 3.6) that enables you to change perform options q discontinue editing the and any further files; if any changes have been made before, PED4DOS will attempt to write the changes to the file (see chapter 3.4) 3.2 Replace a string Whenever PED4DOS finds a , that matches a defined in the and shall be replaced by another , it displays a message like the following: file:input.txt, line: 22, offset: 0x337 = 823 followed by the and a predefined quantity of surrounding characters, followed by a line like the following: replace by: followed by the and a predefined quantity of surrounding characters, followed by the menu line: ok? (yes / no / all / skip file / view .. / perform options .. / quit) Press one of the following keys so PED4DOS will act according to the description: y replace the by the ; continue executing the (i.e. execute the next ) n continue executing the without replacing the a replace the by the ; continue executing the and perform all further replacements without display and confirmation s do not replace the ; discontinue editing the ; if any changes have been made before, PED4DOS will attempt to write the changes to the file (see chapter 3.4) v show the "view" menu (see chapter 3.5) that enables you to view the data at the current p show the "perform options" menu (see chapter 3.6) that enables you to change perform options q do not replace the matching string; discontinue editing the and any further files; if any changes have been made before, PED4DOS will attempt to write the changes to the file (see chapter 3.4) 3.3 Show statistical information If PED4DOS found any matches in the , it displays a message like the following: file:input.txt, found 9 match(es), 2 replaced, 4 not replaced followed by the menu line: continue? (yes / perform options .. / quit) Press one of the following keys so PED4DOS will act according to the description: y continue p show the "perform options" menu (see chapter 3.6) that enables you to change perform options q discontinue editing any further files; if any changes have been made to the before, PED4DOS will attempt to write the changes to the file (see chapter 3.4) 3.4 Write changes to the current file If PED4DOS has replaced any in the , it will attempt to write the changes to the file after terminating the ; PED4DOS will display a message like the following: write changes to file input.txt ? followed by the menu line: ok? (yes / no / save as / perform options .. / quit) Press one of the following keys so PED4DOS will act according to the description: y write the changes to the n ignore the changes; leave the unchanged s show a message like the following: save as: input.txt you should overwrite the old filename with the new filename, then press the ENTER key, or press the ESC key to cancel p show the "perform options" menu (see chapter 3.6) that enables you to change perform options q ignore the changes; leave the unchanged; discontinue editing any further files 3.5 View data at search position If you selected the view option from one of the above menus (see chapters 3.1 and 3.2), PED4DOS will display the menu line: view nnn / hex / ascii / data / trace / ESC Press one of the following keys or type one of the strings replacing nnn by a number less than 1000 so PED4DOS will act according to the description: >nnn subsequently display a maximum of nnn characters trailing the x subsequently show the data in hexadecimal mode a subsequently show the data in ASCII mode d display the (and the ) again t after completion of the current dialog, enter the trace mode (i.e. interrupt before the next of the will be executed) ESC exit from the "view" menu If you selected the view option from the "trace" menu (see below, chapter 3.7), PED4DOS will display an extended "view" menu: view nnn / hex / ascii / data / var / hit flag / ESC Here is the description of the additional options: v display the content of a (see chapter 4.1.3); PED4DOS will display the line view varname: you should type the name of a valid (i.e. used within the ) , then press the ENTER key, or press the ESC key to cancel. If you typed the name of a valid , PED4DOS will display the content of that , otherwise display an error message h display the current setting of the that indicates whether the most recently executed found a (see chapter 4.2.1) 3.6 Change perform options If you selected perform options from one of the above menus (see chapters 3.1 and 3.4), PED4DOS displays the menu line: set (+) / reset (-) perform options .. / batch mode .. / ok / cancel Press one of the following keys so PED4DOS will act according to the description: + display the menu: set perform options for this file .. / all files .. / ESC Press one of the following keys so PED4DOS will act according to the description: t set perform options for editing the a set perform options for all input files ESC exit from this menu If you pressed one of the letter keys, PED4DOS displays a menu of the perform modes that are currently not set: set confirm/show/dialog/execute/log/all modes for .. / ESC Press one of the following keys so PED4DOS will act according to the description: c set confirm mode for the events selected from the following menu s set show mode for the events selected from the following menu d set dialog (show and confirm) mode for the events selected from the following menu e set execute mode for the events selected from the following menu l set logging mode for the events selected from the following menu a set all above modes ESC exit from this menu If you pressed one of the letter keys, PED4DOS displays a menu of the available (i.e. currently not set) events for the selected perform mode, for example: set show mode for match/replace/write/statistic/output/all / ESC Press one of the following keys so PED4DOS will subsequently display: m + surrounding characters r + + surrounding characters w messages when writing changes to the s messages containing statistical information o output from display within the a all of the above options ESC exit from this menu - opposite to + (see above); reset (instead of set) the selected option(s) b display the "batch" menu, that enables you to enter the batch mode (no display, no confirmation) edit this file / all files in batch mode (no display, no confirm) / ESC Press one of the following keys so PED4DOS will act according to the description: t exit from the "perform options" menu; edit the in batch mode a exit from the "perform options" menu; edit all input files in batch mode ESC exit from the "batch" menu o accept the modified perform options and return to the previous menu c ignore the modified perform options and return to the previous menu Example: If you don't want to confirm and statistical messages, select the menu options in the following order (the example shows the menu line, then describes your input): set (+) / reset (-) perform options .. / batch mode .. / ok / cancel - you want to reset options reset perform options for this file .. / all files .. / ESC a you want to reset options for all input files reset perform options for all files ... reset confirm/show/dialog/execute/log/all modes for .. / ESC c you want to reset confirm mode reset confirm mode for match/replace/write/statistic/all / ESC m you don't want to confirm reset confirm mode for replace/write/statistic/all / ESC s you don't want to confirm statistical messages reset confirm mode for replace/write/all / ESC ESC exit from this menu reset confirm/show/dialog/execute/log/all modes for .. / ESC ESC exit from this menu set (+) / reset (-) perform options .. / batch mode .. / ok / cancel o accept the modified perform options and return to the previous menu This corresponds to the command-line option /p:-cms . 3.7 Trace menu The "trace mode" enables you to step through the by , and view the currently edited data and the used . While PED4DOS is editing an input file, you may enter the "trace mode" by pressing any key; alternatively you may start PED4DOS in "trace mode" using the command-line option /trace . PED4DOS will interrupt execution of the and display the next like the following: INTERRUPT 'old string'='new string'; trace cmd: trace / go / set .. / view .. / perform options .. / quit Press one of the following keys so PED4DOS will act according to the description: t trace (display and execute) a previously defined (see set option) number of , then interrupt again g leave trace mode and execute further without interruption s display the following menu: set trace steps / set breakpoint / remove breakpoint / ESC Press one of the following keys so PED4DOS will act according to the description: t display the line: trace nnn steps / ESC You should type the number of to execute without interruption, followed by the ENTER key, or press the ESC key to cancel b display the line: set breakpoint at label (. = current statement) / ESC You should type the label of the where PED4DOS should interrupt execution of the (or a decimal point denoting the current ), followed by the ENTER key; PED4DOS will then interrupt every time before executing that . Press the ESC key to exit from this menu r display the line: remove breakpoint at label (. = current statement) / ESC You should type the label of the where you previously set a breakpoint, followed by the ENTER key; PED4DOS will no longer interrupt before executing that . Press the ESC key to exit from this menu p display the "perform options" menu (see chapter 3.6) q discontinue editing the and any further files 4 Editing facilities 4.1 Introduction PED4DOS needs a to do its job. A consists of one (or more) , separated by ; characters. As a progressive introduction, here are some examples, that you can find in the demonstration file DEMO.BAT, too. The complete syntax of a is described in chapter 4.2. 4.1.1 Search and replace 4.1.1.1 Simple search The most simple consists of a , that PED4DOS shall search in the ; a is a sequence of , surrounded with apostrophe characters '. PED4DOS will search the in the . Whenever PED4DOS finds a , it displays an appropriate message containing the within the , and the , then waits for your confirmation. After searching the whole file, PED4DOS displays a statistical message, if at least one was found. Example 1: search for an abbreviation: 'P4D' 4.1.1.2 Search multiple different strings PED4DOS can search for multiple different during a single pass through the file; simply separate the different by ; characters. Example 2: search for several abbreviations in a single pass: 'P4D'; 'SQ'; 'e.g.' Note: You may separate the different of a by SPACE and TAB characters and by comments (a comment starts with a double-slash sequence (//) and ends at the end of the line) If you use the /f option (read the search program from a file), you may separate the by NEWLINE characters, too. You must separate adjacent from one another by SPACES or .... 4.1.1.3 Search for words, search case sensitive If a shall match only whole words (i.e. no letter must be adjacent to the ), the must be followed by the word. If the shall match only C-identifiers (i.e. whole words consisting of letters, digits and the underscore character), the must be followed by the cword. Note: in both cases, the search string itself may contain any character! If upper and lower case letters must match exactly, the must be followed by the case_sensitive. Note: You may abbreviate any as long as the abbreviation is unambiguous. Example 3: the following will match 'high' and 'High', but not 'Highway': 'high' wo Example 4: the following will match 'high' and 'highway', but not 'High': 'high' case 4.1.1.4 Simple search and replace A will be replaced by a if you append a = character and the to the searched . Example 5: search for several abbreviations and replace them by their expansions: 'P4D' = 'PED4DOS'; 'SQ' = 'Software-Quelle'; 'e.g.'='for example' Note: Whenever PED4DOS found a , it skips over the (or the , if the was replaced) before executing the next , so no part of this will match a subsequently executed . 4.1.1.5 Search pattern Multiple may be concatenated with + characters to form a simple . Two words, separated by a space, can be equally found by the following : Example 6 'two words' 'two' + ' ' + 'words' 4.1.1.6 Hexadecimal characters If a contains characters that cannot be displayed and/or entered via the keyboard, you may use the hexadecimal mode: 1. a single within a may be typed using the notation \xhh, where the placeholder hh must be replaced by the appropriate pair of 2. a that contains merely may be written using the format x'hh...', where the placeholders hh must be replaced by the appropriate pairs of If a contains one of the following characters, use the notation on the right hand side: TAB Use the notation \t (equivalent to \x09 ) NEWLINE Use the notation \n (equivalent to \x0d\x0a ) ' Use the notation \' \ Use the notation \\ Here are several equivalent ways to describe a consisting of the numbers '12' and '34', separated by a TAB character: '12\t34' '12\x0934' x'3132093334' '12' + x'09' + '34' 4.1.1.7 Search for unknown character strings If you search for words, that may be separated by multiple SPACE characters, you should search for an , consisting of SPACES. An is represented by the * character and may be further specified by the (i.e. the set of characters that the may contain) and its . Example 7: the following will match the sequence of 'two' and 'words', separated by one or more spaces: 'two' + *(' ') + 'words' The may be composed from the following components, using the + and - operators: 1. a ; any character contained in becomes member of the 2. a (i.e. two character strings that contain a single character each, associated by the .. ) '0'..'7' is equivalent to '01234567' 3. one or more of the following list, that denote a : letters, denotes any ASCII letter ('a'..'z' + 'A'..'Z'), digits, denotes any decimal digit ('0'..'9'), specials, denotes any special character ((x'20'..x'7f') - (letters + digits)) white_spaces or ws, denotes SPACE and TAB characters (x'20'+x'09') new_lines or nl, denotes the NEWLINE characters Note: the may be abbreviated. Multiple may be grouped using parentheses. A - preceding the first item of a means "any character except the following" Examples: *('abc') matches the letters 'a', 'b' and 'c' *('0'..'9') matches any digit from '0' to '9' *(l+d) matches any ASCII letters and digits *(ws+nl) matches SPACE and TAB and NEWLINE characters *(-(ws+nl)) matches any character except SPACE, TAB and NEWLINE *(x'21'..x'7f')matches any printing ASCII character *(sp - ’;,.’) any special character except semicolon, comma and decimal point If you want to explicitly define a for the , use the length, followed by the or by an interval of lower and upper limit, enclosed in parentheses. If you do not explicitly define a , it defaults to length (1 .. 256): Examples: length 4 exactly 4 characters l (4 .. 9) at least 4, at most 9 characters len ( .. 9) at most 9 characters len (4 .. ) at least 4 characters 4.1.1.8 Replacing pattern If the shall contain a part of the that corresponds to a single within the , you may reference the string by that consists of a * character, followed by a number n; this refers to the string, that matches the n-th within the . Example 8: two words, separated by SPACE characters, shall be exchanged: *(letters) + *(' ') + *(letters) = *3 + *2 + *1; If the searched words may be separated by SPACES as well as TAB and NEWLINE characters, modify the second : Example 9: two words, separated by SPACE, TAB and NEWLINE characters, shall be exchanged: *(l) + *(ws + nl) + *(l) = *3 + *2 + *1; Preview: Chapter describes how to store parts of the to , modify the contents of , and use as part of the . 4.1.1.9 Search Region You may restrict searching on certain columns within any line. The may define exactly one column or a column range. If a contains a , the must start within the denoted columns. A consists of a single column number or a interval of column numbers, surrounded with < and > characters. Example 10:the : <1 .. 10> 'word'; or <7> 'word'; will find the first occurrence of 'word' within the following line, but not the second one first word, second word 4.1.2 Jump statements and labels The sequential execution of the may be modified by ; execution of a may depend on whether a was found. A starts with a : character, followed by an optional keyword, followed by the . may be 1. the