                               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 <statements> of a
               <search program>; a <search program> describes what
               PED4DOS shall do. (The syntax of a <search program>
               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 <search program> consists of multiple
               statements, it is recommended to write the <search
               program> 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
                           <search program>. The <search program>
                           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 <current file>, PED4DOS will start a
                           dialog with you whenever one of the
                           following events occurs:
                           1) PED4DOS finds a <character string>
                               that matches a <search pattern>
                           2) PED4DOS finds a <character string>
                               that shall be replaced by a
                               <replacing string>
                           3) PED4DOS has edited a file, that
                               contains at least 1 <matching
                               string>; PED4DOS would like to
                               display statistics of the <matching
                               strings> (and the <replaced strings>
                               if any).
                           4) PED4DOS has edited a file and
                               replaced at least one <matching
                               string> by a <replacing string>;
                               PED4DOS would like to write the
                               changes to <current file> (or to
                               another file at your request)
                           5) PED4DOS executes a <statement> that
                               requires to display a <character
                               string> 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 <matching string> has
                                   been found in the <current file>
                               r   (replace): a <matching string>
                                   shall be replaced by a <replacing
                                   string>
                               s   (statistics): at least 1
                                   <matching string> was found in
                                   the <current file>
                               w   (write): at least 1 < matching
                                   string> has been replaced
                               o  (output): a <statement> requires
                                   to display a <character string>.
                               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 <statements> 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 <search
                           program>. The optional parameter n
                           denotes the number of <statements> 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 <character string>, that matches a <search
pattern> defined in the <search program>, it displays a message like
the following:
file:input.txt, line: 22, offset: 0x337 = 823
followed by the <matching string> and a predefined quantity of
characters surrounding the <matching string>,
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 <search program> (i.e. execute the
       next <statement>)
a      continue executing the <search program>, but only count
       <matching strings> (i.e. no display, no confirmation)
s       discontinue editing the <current file>; 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 <search position>
p      show the "perform options" menu (see chapter 3.6) that
       enables you to change perform options
q       discontinue editing the <current file> 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 <character string>, that matches a <search
pattern> defined in the <search program> and shall be replaced by
another <character string>, it displays a message like the
following:
file:input.txt, line: 22, offset: 0x337 = 823
followed by the <matching string> and a predefined quantity of
surrounding characters,
followed by a line like the following:
replace by:
followed by the <replacing string> 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 <matching string> by the <replacing string>;
       continue executing the <search program> (i.e. execute the
       next <statement>)
n      continue executing the <search program> without replacing the
       <matching string>
a      replace the <matching string> by the <replacing string>;
       continue executing the <search program> and perform all
       further replacements without display and confirmation
s       do not replace the <matching string>; discontinue editing the
       <current file>; 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 <search position>
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
       <current file> 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 <current file>, 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 <current file> 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 <character string> in the <current
file>, it will attempt to write the changes to the file after
terminating the <search program>; 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 <current file>
n      ignore the changes; leave the <current file> 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 <current file> 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 / >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 preceding
       the <matching string>
>nnn   subsequently display a maximum of nnn characters trailing the
       <matching string>
x       subsequently show the data in hexadecimal mode
a      subsequently show the data in ASCII mode
d      display the <matching string> (and the <replacing string>)
       again
t       after completion of the current dialog, enter the trace mode
       (i.e. interrupt before the next <statement> of the <search
       program> 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 / >nnn / hex / ascii / data / var / hit flag / ESC
Here is the description of the additional options:
v       display the content of a <variable> (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
       <search program>) <variable>, then press the ENTER key, or
       press the ESC key to cancel.
       If you typed the name of a valid <variable>, PED4DOS will
       display the content of that <variable>, otherwise display an
       error message
h      display the current setting of the <hit flag> that indicates
       whether the most recently executed <search statement> found a
       <matching string> (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 <current file>
       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      <matching strings> + surrounding characters
       r       <matching strings> + <replacing strings> +
               surrounding characters
       w       messages when writing changes to the <current file>
       s       messages containing statistical information
       o      output from display <statements> within the <search
               program>
       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
               <current file> 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 <matching strings> 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 <matching strings>
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 <search program>
<statement> by <statement>, and view the currently edited data and
the used <variables>.
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 <search program> and display the next
<statement> 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 <statements>, then interrupt again
g      leave trace mode and execute further <statements> 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 <statements> 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 <statement> where
               PED4DOS should interrupt execution of the <search
               program> (or a decimal point denoting the current
               <statement>), followed by the ENTER key; PED4DOS will
               then interrupt every time before executing that
               <statement>.
               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 <statement> where
               you previously set a breakpoint, followed by the
               ENTER key; PED4DOS will no longer interrupt before
               executing that <statement>.
               Press the ESC key to exit from this menu
p      display the "perform options" menu (see chapter 3.6)
q       discontinue editing the <current file> and any further files


4   Editing facilities


4.1 Introduction
PED4DOS needs a <search program> to do its job. A <search program>
consists of one (or more) <statements>, 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 <search program> is described in chapter 4.2.

4.1.1    Search and replace

4.1.1.1  Simple search
The most simple <search statement> consists of a <character string>,
that PED4DOS shall search in the <current file>; a <character
string> is a sequence of <characters>, surrounded with apostrophe
characters '. PED4DOS will search the <character string> in the
<current file>. Whenever PED4DOS finds a <matching string>, it
displays an appropriate message containing the <search position>
within the <current file>, and the <matching string>, then waits for
your confirmation. After searching the whole file, PED4DOS displays
a statistical message, if at least one <matching string> was found.
Example 1: search for an abbreviation:
'P4D'


4.1.1.2  Search multiple different strings
PED4DOS can search for multiple different <character strings> during
a single pass through the file; simply separate the different
<character strings> by ; characters.
Example 2: search for several abbreviations in a single pass:
'P4D'; 'SQ'; 'e.g.'

Note:  You may separate the different <statements> of a <search
       program> 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 <statements> by NEWLINE
       characters, too.
       You must separate adjacent <keywords> from one another by
       SPACES or ....

4.1.1.3  Search for words, search case sensitive
If a <search string> shall match only whole words (i.e. no letter
must be adjacent to the <matching string>), the <search string> must
be followed by the <keyword> word.
If the <search string> shall match only C-identifiers (i.e. whole
words consisting of letters, digits and the underscore character),
the <search string> must be followed by the <keyword> cword.
Note: in both cases, the search string itself may contain any
character!
If upper and lower case letters must match exactly, the <search
string> must be followed by the <keyword> case_sensitive.
Note: You may abbreviate any <keyword> as long as the abbreviation
is unambiguous.
Example 3: the following <search string> will match 'high' and
           'High', but not 'Highway':
'high' wo
Example 4: the following <search string> will match 'high' and
           'highway', but not 'High':
'high' case


4.1.1.4  Simple search and replace
A <matching string> will be replaced by a <replacing string> if you
append a = character and the <replacing string> to the searched
<character string>.
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 <matching string>, it skips over the
<matching string> (or the <replacing string>, if the <matching
string> was replaced) before executing the next <statement>, so no
part of this <character string> will match a subsequently executed
<search statement>.


4.1.1.5  Search pattern
Multiple <character strings> may be concatenated with + characters
to form a simple <search pattern>. Two words, separated by a space,
can be equally found by the following <search statements>:
Example 6
'two words'
'two' + ' ' + 'words'


4.1.1.6  Hexadecimal characters
If a <character string> contains characters that cannot be displayed
and/or entered via the keyboard, you may use the hexadecimal mode:
1. a single <hex character> within a <character string> may be
   typed using the notation \xhh, where the placeholder hh must be
   replaced by the appropriate pair of <hex digits>
2. a <character string> that contains merely <hex characters> may
   be written using the format x'hh...', where the placeholders hh
   must be replaced by the appropriate pairs of <hex digits>

If a <character string> 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 <search pattern>
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 <unknown character string>,
consisting of SPACES. An <unknown character string> is represented
by the * character and may be further specified by the <character
set> (i.e. the set of characters that the <unknown character string>
may contain) and its <length limits>.
Example 7: the following <search pattern> will match the sequence of
           'two' and 'words', separated by one or more spaces:
'two' + *(' ') + 'words'

The <character set> may be composed from the following components,
using the + and - operators:
1. a <character string>; any character contained in <character
   string> becomes member of the <character set>
2. a <character interval> (i.e. two character strings that contain
   a single character each, associated by the .. <operator>)
   '0'..'7' is equivalent to '01234567'
3. one or more <keywords> of the following list, that denote a
   <predefined character set>:
   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 <keywords> may be abbreviated.
Multiple <character sets> may be grouped using parentheses.
A - <operator> preceding the first item of a <character set> 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 <length limit> for the <unknown
character string>, use the <keyword> length, followed by the <exact
length limit> or by an interval of lower and upper limit, enclosed
in parentheses. If you do not explicitly define a <length limit>, 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 <replacing pattern> shall contain a part of the <matching
string> that corresponds to a single <search item> within the
<search pattern>, you may reference the string by <replacing item>
that consists of a * character, followed by a number n; this
<replacing item> refers to the string, that matches the n-th <search
item> within the <search pattern>.
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 <search item>:
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 <matching
string> to <string variables>, modify the contents of <string
variables>, and use <string variables> as part of the <replacing
pattern>.

4.1.1.9  Search Region
You may restrict searching on certain columns within any line. The
<search region> may define exactly one column or a column range. If
a <search statement> contains a <search region>, the <matching
string> must start within the denoted columns. A <search region>
consists of a single column number or a interval of column numbers,
surrounded with < and > characters.

Example 10:the <search statements>:
<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 <search program> may be modified by
<jump statements>; execution of a <jump statement> may depend on
whether a <matching string> was found.
A <jump statement> starts with a : character, followed by an
optional <condition> keyword, followed by the <jump target>.
<jump target> may be
1. the <label> of the <statement> that shall be executed next
2. the <file position> in the <current file>, where searching shall
   continue.
Supply a <statement> with a <label> by simply typing the name of the
<label> followed by a : character in front of the statement. The
<label> may contain from 1 to 15 characters (any combination of
letters, digits and underscores (_)); the <label>is not case
sensitive.
Execution of the <jump statement> may depend on the current setting
of the global <hit flag>. <hit flag> is set to true each time a
<matching string> is found in the <current file>; <hit flag> is set
to false each time a <search statement> is executed and no <matching
string> is found at the current <search position>. Use the
<condition> keyword true, if the <jump statement> shall only be
executed when the <hit flag> is set to true. Use the <condition>
keyword false, if the <jump statement> shall only be executed when
the <hit flag> is set to false. Omit the <condition> keyword, if the
<jump statement> shall be executed anyway.
Replace the <file position> with the absolute or relative number of
the line, column or byte no. (denoted by one of the <data item>
keywords lines, columns, or bytes, respectively) within the <current
file>, where searching shall continue. A relative number is denoted
by the + (or -) sign preceding the numerical value and means: skip n
<data items> from the current <search position> towards the end (the
beginning) of the <current file>.
Note: A relative number counts from the current <search position>.
Replace the <file position> with one of the <position operators> ++
or --, if you want to set the <search position> to the end or the
beginning of the <current file>.

Note: if the <jump target> of the <jump statement> denotes a new
<search position>, the <hit flag> will be set to false if that
<search position> does not exist in the <current file>; ignoring the
"end of file" condition might result in an endless loop!

Example 11:search the word 'FILES' near the beginning of a line; on
           error, set the <search position> to the beginning of the
           next line and continue searching if a next line exists.
search:
<1>*(ws) + 'files' word : false error;
// edit the line that contains the word 'files'
// see examples

error: : <+ 1 line>; : true search;

The following labels are implicitly defined and have a special
meaning:
begin          first <statement> of the <search program>
end            past the last <statement> of the <search program>
stop           terminate the <search program>

You may define your own begin <label> past the "initialization
statements" of a <search program>: all <statements> preceding the
begin label will be executed only once when starting execution of
the <search program>.

The following label has a special meaning:
eof            the <statement> following this label will be executed
               when the end of the <current file> is reached unless
               when execute a <jump statement> to a <file position>
               that doesn't exist.

Example 12:search the first occurrence of the word 'FILES' and
           terminate the <search program>.
'FILES' word case : true stop;

Example 13:small (and incomplete) part of a syntax checker:
'if' cw ca : t if_stmnt;
'switch' cw ca : t switch_stmnt;
'while' cw ca : t while_stmnt;
...
if_stmnt:// check syntax of the if statement
   *(ws+nl) len(0..) + '(' + * + ')' :f error;
...
error: : s ;


4.1.3    Variables

4.1.3.1  String variables

4.1.3.1.1Implicit assignment to string variables
If you want to store the <matching string> to a <string variable>
for later use, append the <search item> with the  >  <operator>,
followed by the <name> of the <string variable>. The <name> of a
<string variable> must begin with a $ character, followed by 1 to 15
characters (any combination of letters, digits and underscores (_));
the name is not case sensitive.
If you want to append the <matching string> to the content of a
<string variable>, use the  >>  <operator> instead of the  >
<operator>:

Note: When searching for a compound <search pattern>, consisting of
multiple <search items>, no <implicit assignment> will take place
unless a <matching string> was found that matches the whole <search
pattern>.

Example 14:search any word in column 1 and store it to the <string
           variable> $word.
<1> *(letters) > $word;


4.1.3.1.2Use string variables
A <string variable> may be used wherever a <character string> must
be supplied within a <statement>.
Whenever a <string variable> is used (for example as part of a
<replacing pattern>) before assigning it a value, PED4DOS will try
to get the value of an <environment variable> with a corresponding
name (i.e. the <name> of the <string variable> without the leading $
character).

Example 15:two words, separated by SPACE, TAB and NEWLINE
           characters, shall be exchanged (same result as Example 9,
           but using <string variables>):
*(l) > $w1 + *(ws + nl) > $sp + *(l) > $w2 = $w2 + $sp + $w1;

Example 16:find two words, separated by SPACE, TAB and NEWLINE
           characters; store the first word to the <string variable>
           $string; append the separating characters to $string;
           append the second word to $string:
*(l) > $string + *(ws + nl) >> $string + *(l) >> $string;
Example 17:find the word 'PATH' and replace it by the current value
           of the PATH environment variable:
'PATH' w ca = $path;


4.1.3.1.3Explicit assignment to string variables
If you want to explicitly assign a value to a <string variable>, use
the notation
( <string variable> = <string expression> )
The surrounding parentheses are required in order to distinguish the
<explicit assignment> from a <search statement>.
Use the following notations for <string expression> where <string
item> may be a <string constant>, a <string variable> or a <string
function> (<numerical expression> is explained in chapter 4.1.3.2.3:
1. <string item>
2. (<string expression> )
3. <string expression> <string operator> <string expression>
   Replace <string operator> by one of the following:
   +  Concatenation
      Example:
      'abc'+'123' // == 'abc123'
   .. Interval (both <string items> should contain exactly 1
       character; otherwise only the first character is used)
      Examples:
      'a' .. 'd' // == 'abcd'
      x'fd' .. x'02' // == x'fdfeff000102'
   &  Bitwise AND
      Example:
      x'13f2' & x'7633' // == x'1232'
   ^  Bitwise XOR
      Example:
      x'13f2' ^ x'7633' // == x'65c1'
   |   Bitwise OR
      Example:
      x'13f2' | x'7633' // == x'77f3'
4. <string expression> * <numerical expression>
   Example:
   'abc' * 3 // == 'abcabcabc'

The <hit flag> is set to true if the result of the <string
expression> contains at least one character, otherwise to false.
Example 18:combination of Example 15 and Example 16:
*(l) > $w1 + *(ws + nl) > $sp + *(l) > $w2;
($string = $w2 + $sp + $w1);

One predefined <string variable> named display may be used to
display the content of a <string expression> on the screen.
Example 19:display the content of the PATH environment variable:
(disp = $PATH);

Example 20:display the <matching string>:
<1>*(l) > disp;

One predefined <numerical variable> named retcode may be used to set
the exit code of PED4DOS during execution of the <search program>.
Example 21:set the exit code for PED4DOS to 2:
(retcode = 2);


4.1.3.1.4Compare string variables
If you want to check the current value of a <string item> or a
<string expression>, use the notation
( <string expression> <relational operator> <string expression> )
The surrounding parentheses are required. <string expression> was
explained in chapter 4.1.3.1.3.
Note: The result of comparison is a <numerical value> (1 == true, 0
== false).
The following <relational operators> are valid and set the <hit
flag> to true if the description is true:
==     both operands are equal
!=     both operands are different
<      the left operand is alphabetically less than the right
       operand
>      the left operand is alphabetically greater than the right
       operand
<=     the left operand is alphabetically less than or equal to the
       right operand
>=     the left operand is alphabetically greater than or equal to
       the right operand

Example 22:modification of Example 13:
*(l) > $keyword: f e;
($keyword == 'if') : t if_stmnt;
($keyword == 'switch') : t switch_stmnt;
($keyword == 'while') : t while_stmnt;
...
if_stmnt:// check syntax of the if statement
   *(ws+nl) + '(' + * + ')' :f error;
...
error: : s ;


4.1.3.2  Numerical variables

4.1.3.2.1Implicit assignment to numerical variables
If you want to store the <search position> of a <matching string> to
a <numerical variable> for later use, append the > <operator>,
followed by the <name> of the <numerical variable>, to the <search
item>. The <name> of a <numerical variable> must begin with a #
character, followed by 1 to 15 characters (any combination of
letters, digits and underscores (_)); the name is not case
sensitive. A <numerical variable> can hold any integer value in the
range from -999999999 to +999999999.

Note: When searching for a compound <search pattern>, consisting of
multiple <search items>, no <implicit assignment> will take place
unless a string matching the whole <search pattern> was found.


4.1.3.2.2Use numerical variables
A <numerical variable> may be used wherever a <numerical item> must
be supplied within a <statement>.
Whenever a <numerical variable> is used before it was assigned a
value, PED4DOS will use the value 0.

Example 23:search the word 'placeholder' and save its <search
           position>; search the new value for 'placeholder'
           elsewhere in the <current file>; go to the saved <search
           position> and replace 'placeholder':
'placeholder' > #ph;
// search the new value for 'placeholder'

// $ph contains the new value for 'placeholder'
: <#ph>; 'placeholder' = $ph : stop;


4.1.3.2.3Explicit assignment to numerical variables
If you want to assign a value to a <numerical variable>, use the
notation
(<numerical variable> = <numerical expression> )
The surrounding parentheses are required.
Use the following notations for <numerical expression> where
<numerical item> may be a <numerical constant>, a <numerical
variable> or a <numerical function>:
1. <numerical item>
2. (<numerical expression> )
3. <numerical expression> <numerical operator> <numerical
   expression>
   Replace <numerical operator> by one of the following:
   +  Addition
   -  Subtraction
   *  Multiplication
   /  Division
   %  Remainder
   << Bitwise shift left
   >> Bitwise shift right
   &  Bitwise AND
   ^  Bitwise XOR
   |   Bitwise OR
   && Logical AND
   ||   Logical OR

The <hit flag> is set to false if the result of the <numerical
expression> equals 0, otherwise to true.

Example 24:
(#1 = (#2 * (#3 + 3)));


4.1.3.2.4Compare numerical variables
If you want to check the current value of a <numerical item> or a
<numerical expression>, use the notation
( <numerical expression> <relational operator> <numerical
expression> )
The surrounding parentheses are required. <numerical expression> was
explained in chapter 4.1.3.2.3.
Note: The result of comparison is a <numerical value> (1 == true, 0
== false).
The following <relational operators> are valid and set the <hit
flag> to true if the description is true:
==     both operands are equal
!=     both operands are different
<      the left operand is less than the right operand
>      the left operand is greater than the right operand
<=     the left operand is less than or equal to the right operand
>=     the left operand is greater than or equal to the right
       operand


4.1.3.3  Functions
If you want to get the result of a <function>, use the notation
<function> ( <parameter>, <parameter>,... )
The number of parameters and their type depend on the <function>;
each <parameter> must be replaced by a <variable> or <constant
value> of the required type. Several predefined <functions> are
available (see below).

4.1.3.3.1String functions
A <string function> may be used wherever a <string item> is
required.
The following <string functions> are available:

$num(#var)              returns a <character string> that contains
                        the value of #var in a printable format.
                         Example:
                        $val = $num(123) // = '123'
$hex(#var, #len)        returns the value of #var as a hexadecimal
                        string, that contains at least #len (at
                        most 8) <hex digits>.
                        Example:
                        $val = $hex(0x123, 4) // = '0123'
$mem(#var, #count)      returns the low order #count (at most 4)
                        bytes from the <numerical variable> #var
                        as a <character string>.
                        Example:
                        $val = $mem(0x616263, 2) // = 'cb' =
                        x'6362'
$substr($var, #start,   returns a part of the string contained in
#len)                   $var, starting at #start and containing at
                        most #len characters. (#start == 1 means:
                        starting at the first character)
                        Example:
                        $val = $substr('abcdef', 2, 3) // = 'bcd'
$input($var)            displays the string contained in $var;
                        returns the string that you enter via the
                        keyboard
                        Example:
                        $val = $input('new value for $val ')
$lower($var)            Converts the string contained in $var to
                        lower case letters.
                        Example:
                        $val = $lower('AbCDef') // = 'abcdef'
$upper($var)            Converts the string contained in $var to
                        upper case letters.
                        Example:
                        $val = $upper('AbCDef') // = 'ABCDEF'
$file(0)                returns the name of the <current file>
                        (the parameter value 0 is requested for
                        future use)


4.1.3.3.2Numerical Functions
A <string function> may be used wherever a <string item> is
required.
A <numerical function> may be used wherever a <numerical item> is
required.
The following <numerical functions> are available:

#len($var)              returns the number of characters contained
                        in $var.
                        Example:
                        #val = #len('abc') // = 3
#byte()                 returns the current <search position>,
                        i.e. the offset from the beginning of the
                        <current file> to the character, that will
                        be checked next to find a <matching
                        string>; the value 0 denotes the first
                        character of the file
                        Example:
                        #val = #byte() // = 0 at the begin of the
                        file
#line()                 returns the number of the line, that
                        contains the <search position>; the value
                        1 denotes the first line of the file.
                        Note: This function returns the value 0,
                        if the current input file is not an ASCII
                        text file.
                        Example:
                        #val = #line() // = 1 at the begin of the
                        file
#column()               returns the number of the column, that
                        corresponds to the <search position>; the
                        value 1 denotes the first column of the
                        line.
                        Note: This function returns the value 0,
                        if the current input file is not an ASCII
                        text file.
                        Example:
                        #val = #column() // = 1 at the begin of a
                        line
#num($var)              returns the integer value of the printable
                        number contained in $var.
                        Example:
                        #val = #num('123') // = 123
#hex($var)              returns the integer value of the
                        hexadecimal number contained in $var.
                        Example:
                        #val = #hex('1f2') // = 0x1f2
#mem($var, #count)      returns the first #count (at most 4) bytes
                        from the <string variable> $var as an
                        integer value.
                        Example:
                        #val = #mem(x'010203', 2) // = 0x0201
#options($var)          modifies the perform options for all files
                        according to the string contained in $var;
                        the string must start with the characters
                        'p:', followed by the option strings as
                        described in chapter 2
                        Example:
                        #options('p:b') // set batch mode for all
                        files


4.2 Syntax summary

4.2.1    Executing a search program
This chapters describes exactly how PED4DOS executes a <search
program>:
1.     The <search position> is set to 0 (that is the offset to the
       first character of the <current file>; the first <statement>
       of the <search program> becomes the current <statement>.
2.     If the current <statement> is a <search statement>:
       2.1    The <character string> starting at the <search
               position> is checked against the <search pattern>. If
               a <matching string> is found:
               2.1.1  The <hit flag> is set to true
               2.1.2  If a <replacing pattern> has been defined,
                       the <matching string> is replaced by a
                       <replacing string> after a confirmation
                       dialog
               2.1.3  The <search position> is set past the
                       <matching string> (or past the <replacing
                       string> if a replacement took place)
3.     If the current <statement> is an <assignment statement> or a
       <compare statement>
       3.1    The assignment or the comparison is executed
       3.2    The <hit flag> is set according to the result
4.     If the current <statement> is a <jump statement> whose <jump
       target> is a <label>, the <statement> past that <label>
       becomes the current <statement> (continue with 2.)
5.     If the current <statement> is a <jump statement> whose <jump
       target> is a <file position>, the <search position> is set to
       <file position> and the <hit flag> is set to true if <file
       position> exists (otherwise the <search position> is set past
       the last byte of the <current file> and the <hit flag> is set
       to false)
6.     If the current <statement> is the last <statement> of the
       <search program>, or a <jump statement> to the predefined end
       <label> is executed
       6.1    The <search position> is incremented by 1 unless
               either any <matching string> was found while
                       executing the preceding <search statements>
               or     the <search position> was modified while
                       executing a <jump statement>
       6.2    If the end of the <current file> has been reached
               6.2.1  If a eof <label> has been defined in the
                       <search program>, a <jump> to that label is
                       executed.
               6.6.2  Otherwise, the <search program> is terminated
                       (stopped).
       6.3    Execution is resumed at the first <statement> (or at
               the <statement> following the begin label if you have
               explicitly defined it).
7.     The <statement> past the current <statement> becomes the
       current <statement> (continue at 2.)

4.2.2    Syntax description

4.2.2.1  Definitions
Terminals are endpoints in the syntax definition. No other
resolution is possible. Terminals include the set of reserved
keywords and user-defined identifiers. Keywords may be abbreviated
as long as the abbreviation is unambiguous.
Nonterminals are placeholders in the syntax and are defined
elsewhere in the syntax definition. Definitions can be recursive.
A production rule describes how nonterminals may be replaced by a
composition of terminals and other nonterminals (commonly called
symbols). The operator ::= means "may be replaced by a composition
of".

4.2.2.2  Conventions
The following characters and/or fonts have a special meaning:
Bold text         Denotes a terminal; you must type a terminal
                  exactly as shown (but letters are not case
                  sensitive); any character or character sequence,
                  that doesn't have a special meaning as described
                  in this chapter, is a terminal (even if not
                  printed in a bold font)
<nonterminal>     Denotes a symbol, that may be replaced by a
                  composition of terminals and other nonterminals;
                  the name of a nonterminal may contain spaces.
                  Example: <character string>
|                 Separates alternatives
[]                Enclose optional symbols
{}                Enclose symbols that may be repeated
{}n               Enclose symbols that must be repeated exactly n
                  times
{}n1..n2          Enclose symbols that must be repeated at least
                  n1 times and at most n2 times (if n2 is omitted,
                  the symbols may be repeated unlimited)
"..."             Comment that describes the production rule

Symbols, that are separated by spaces throughout this syntax
description, may be separated by SPACE, TAB and NEWLINE characters
as well as comments; a comment starts with a double-slash sequence
(//) and ends at the end of the line.

4.2.2.3  Syntax part 1
The first part of the syntax descriptions shows the fundamental
construction of a <search program> in hierarchical order:

nonterminal       may be replaced by          comment
<search program>  <statement> {; <statement>  "a <search program>
::=               } 0..n                      consists of one or
                                              more <statements>,
                                              separated by ;
                                              characters"
<statement> ::=   [ <label> : ]               "a <statement> is a
                  [   <search statement>      <search statement>
                     | <explicit assignment>  or an <explicit
                     | <comparison> ]         assignment> or a
                  { <jump statement> } 0..n   <comparison>; it
                                              may begin with an
                                              optional <label>,
                                              followed by a :
                                              <character>; it may
                                              be followed by one
                                              or more optional
                                              <jump statements>"
<label> ::=       <name>                      
<search           [<search region>]           
statement> ::=    <search pattern>
                  [ = <replacing pattern> ]
<explicit           ( <string variable> =     
assignment> ::=   <string expression> )
                  | ( <numerical variable> =
                  <numerical expression> )
<comparison> ::=    ( <string expression>     
                  <relational operator>
                  <string expression> )
                  | ( <numerical expression>
                  <relational operator>
                  <numerical expression> )
<jump statement>  : [ <condition> ]           
::=                {
                     <label>
                  |   < <file position> >
                   }


4.2.2.4  Syntax part 2
The second part of the syntax description shows all <nonterminals>
of a <search program> in alphabetical order:

nonterminal       may be replaced by     comment
<character> ::=     <printable           
                  character>             
                  | \x<hex character>    "TAB character (=
                  | \t                   x'09')"
                  | \n                   "NEWLINE characters (=
                                         x'0d0a')"
<character        '<character>' ..       "any <character> within
interval> ::=     '<character>'          the range from the first
                                         <character> to the
                                         second <character>
                                         inclusive"
<character set>   [ - ] <character set   "set of all characters
::=               item>                  that may be contained
                   [ { + | - }           within an <unknown
                  <character set> ]      character string>"
                  |  [ - ] ( <character
                  set> )
                  
<character set    <character interval>   "set of characters"
item> ::=         | <string item>
                  | <predefined
                  character set>
<condition> ::=   true                   "jump if <hit flag> is
                  | false                set"
                                         "jump if <hit flag> is
                                         cleared"
<data item> ::=      lines               "valid only in text
                  |  columns             files"
                  |  bytes               "valid only in text
                                         files"
                                         "default"
<digit> ::=       0 | 1 | 2 | 3 | 4 | 5  
                  | 6 | 7 | 8 | 9
<exact length>    1 .. 256               "any value in the range
::=                                      from 1 to 256 "
<file position>      [ <data item> ]     "<numerical item>
::=                  [ <relative         denotes the number of a
                  operator> ]            line or of a column
                     <numerical item> >  within the current line
                                         (based 1) or the number
                                         of bytes (based 0),
                                         depending on <data
                                         item>"
                  |  --                  Note: the items may
                  |  ++                  appear in any order"
                                         "begin of file"
                                         "end of file"
<hex character>   <hex digit><hex digit> "example:
::=                                      x'1b' corresponds to the
                                         ESC key"
<hex digit> ::=   <digit>                
                  | A | a | B | b | C |
                  c | D | d | E | e | F
                  | f
<implicit            > <string variable> "store the <matching
assignment> ::=                          string> to <string
                  |  >> <string          variable>"
                  variable>              "append the <matching
                                         string> to the content
                  |  > <numerical        of <string variable>"
                  variable>              "store the <search
                                         position> of the
                                         <matching string> to
                                         <numerical variable>"
<jump target> ::=   <label>              
                  | <predefined label>
                  | < <file position> >
<label> ::=       <name>                 
<length limits>    length                "either <lower length
::=               { <exact length>       limit> or <upper length
                     | ( [ <lower length limit> is required; if
                  limit> ] .. [ <upper   both are supplied,
                  length limit> ] )      <lower length limit>
                  }                      must be less than <upper
                                         length limit> "
<letter> ::=      a | b | c | ... | y |  "any lower case and
                  z | A | B | ... | Y |  upper case letter"
                  Z
<lower length     0 .. 256               "any value in the range
limits> ::=                              from 0 to 256 "
<name> ::=        { <letter> | <digit> | " not case sensitive"
                  _ }1..15
<numerical        -999999999 ..          "any integer value in
constant> ::=     999999999              the range from -
                                         999999999 to +999999999"
<numerical           [ - |  ]           "examples:"
expression> ::=   <numerical item> [     " (-1+2) "
                  <numerical operator>   " -(2*(3+4)) "
                  <numerical expression> " 200 / #var1 "
                  ]
                  |  [ - |  ] (
                  <numerical expression>
                  )
                  
<numerical        #<name> ( <parameter   "see description of
function> ::=     list> )                functions in chapter
                                         4.1.3.3.2"
<numerical        <numerical item> ..    "the value of the first
interval> ::=     <numerical item>       <numerical item> must be
                                         less than the value of
                                         the second <numerical
                                         item>"
<numerical item>    <numerical constant> 
::=               | <numerical variable>
                  | <numerical function>







<numerical            +                  "the operators are
operator> ::=     |   -                  described in chapters
                  |   *                  4.1.3.2.3"
                  |   /
                  |   %
                  |   <<
                  |   >>
                  |   &
                  |   ^
                  |   |
                  |   &&
                  |   ||
                  
<numerical        #<name>                "may contain any integer
variable> ::=                            value in the range from
                                         -999999999 to
                                         +999999999"
<parameter list>   [ <parameter>         
::=                 { , <parameter>
                  }0..7 ]
<predefined       letters                "any upper case and
character set>                           lower case letter"
::=               | digits               "any digit"
                  | specials             "any special printing
                  | white_spaces | ws    character"
                                         "SPACE characters and
                  | new_lines | nl       TAB characters "
                                         "NEWLINE characters"
<predefined         begin                "first statement of a
label> ::=                               <search program>; may be
                                         redefined within <search
                  |  end                 program>"
                                         "past the last statement
                  |  stop                of a <search program>"
                                         "terminate the <search
                                         program>"
<printable                               "any character that can
character> ::=                           be displayed on the
                                         screen and entered via
                                         the keyboard"
<relational           <                  "less than"
operator> ::=     |   <=                 "less than or equal to"
                  |   ==                 "equal "
                  |   !=                 "not equal"
                  |   >=                 "greater than or equal
                  |   >                  to"
                                         "greater than"
<relative             +                  "from the <search
operator> ::=                            position> towards the
                  |   -                  end of the file"
                                         "from the <search
                                         position> towards the
                                         begin of the file"
<replacing item>  <string item>          
::=               | * <numerical item>   "<numerical item>
                                         identifies the <matching
                                         string> that matches the
                                         n-th <search item>"
<replacing        <replacing item> { +   
pattern> ::=      <replacing item>}0..n
<search item> ::= {   <string item>      
                     | <unknown string>
                  }
                  {<implicit
                  assignment>}0..n
<search pattern>  <search item> { +      
::=               <search item>}0..n
<search region>   < <first column> [ ..  "the <matching string>
::=               <last column> ] >      must begin between
                                         <first column> and <last
                                         column>; only valid for
                                         ASCII text files "
<string constant>                        
::=               '{<character>}0..256'
                  |  x'{<hex
                  character>}0..256'
<string           <string item> [        " the length of the
expression> ::=   <string operator>      result of <string
                  <string expression> ]  expression> must not
                  | ( <string            exceed 256 "
                  expression> )          "examples:
                  |  <string expression>  ('word1' + 'word2')
                  * <numerical            ' ' * 20
                  expression>             $text & (x'7f' * 256) "
                  
<string function> $<name> ( <parameter   "see description of
::=               list> )                funtions in chapter
                                         4.1.3.3.1"
<string item>       <string constant>    
                  | <string variable>
                  | <string function>
<string operator>     +                  "the operator are
::=               |   ..                 described in chapters
                  |   &                  4.1.3.1.3"
                  |   ^
                  |   |
                  
<string variable> $<name>                "can contain up to 256
::=                                      <characters> "
<unknown string>  * [ ( <character set>  
::=               ) ]
                     [ <length limits> ]
<upper length     1 .. 256               "any value in the range
limits> ::=                              from 1 to 256 "


5   Examples

The SAMPLES directory contains several command files and program
files (i.e. files that contain a <search program> for PED4DOS).
Run the batch file DEMO.BAT if you want to execute some of the
examples in chapter 4.1.
The following chapters describe more complex <search programs>.

5.1 Check the FILES parameter in CONFIG.SYS
If you want to check how many files may be opened at the same time,
refer to the FILES parameter in the file CONFIG.SYS and replace it
by another value if the current setting is not sufficient:
// FILES.PRG
// set the FILES value in config.sys to at least 128

// find the keyword 'files' near the beginning of the current line
<1> *(ws)l(0..) + 'files' :f next_line;
// find the = character and store the current value to $par
*(ws) l(0..) + '=' + *(ws) l(0..) + *(digit)>$par :f next_line;
// convert $par to an integer value
(#par = #num ($par));
// compare with the requested value; terminate if sufficient
(#par >= 128) :t s;
// the current value is to small
// set the search position back to the parameter value
:<- #len($par) bytes>;
// replace by the requested value, then terminate the search program
$par = '128' : s;

// skip 1 line; stop at the end of the file
next_line:
 :<+1 line> :f s;
// end of FILES.PRG


5.2 Convert special letters from ANSI to OEM or ASCII
These <search programs> are especially useful for German users. Use
ANSI2ASC.PRG to convert German umlauts from the ANSI code (used by
MS Windows, MS Word for Windows) to the ASCII code (i.e. convert
each umlaut to 2 ASCII letters). Use ANSI2OEM.PRG to convert German
umlauts from the ANSI code (used by MS Windows, MS Word for Windows)
to the OEM code (used by MS-DOS).
// file ANSI2ASC.PRG
// convert german umlauts from ANSI to ASCII
x'e4'='ae':t b;        // ''
x'f6'='oe':t b;        // ''
x'fc'='ue':t b;        // ''
x'c4'='Ae':t b;        // ''
x'd6'='Oe':t b;        // ''
x'dc'='Ue':t b;        // ''
x'df'='ss':t b;        // ''

// file ANSI2OEM.PRG
// convert german umlauts from ANSI to OEM
x'e4'= x'84':t b;  // ''
x'f6'= x'94':t b;  // ''
x'fc'= x'81':t b;  // ''
x'c4'= x'8e':t b;  // ''
x'd6'= x'99':t b;  // ''
x'dc'= x'9a':t b;  // ''
x'df'= x'e1':t b;  // ''


5.3 Format a list file as input for a spreadsheet program
If you want to copy the data from a list file to your spreadsheet
like MS Excel, you have to separate the data from headlines, control
characters for the printer, etc., and to separate the data fields by
appropriate characters (for example TAB characters). Use LIST1.PRG
to output only the data to the log file. Use LIST2.PRG to delete all
but the data from the original list file.
The original list file LIST.IN looks like this; the first 3 lines
are repeated on each page:

 salesman     |                  invoiced sales in 1995
|
              |  1. quarter  |  2. quarter  |  3. quarter  |  4.
quarter  |
 -------------+--------------+--------------+--------------+--------
------|
 Smith        |   120,000.00 |   120,000.00 |   120,000.00 |
120,000.00 |
 Johnson      |    -3,000.00 |    15,000.00 |    33,000.00 |
36,000.00 |
 Carter       | 2,278,239.89 |    78,055.50 |         0.00 |
0.00 |

The following <search program> will display the data contained in
the list file; use the /l option to copy this output to a log file:

// LIST1.PRG
// display nothing but the data
// use the option /l:list.out to copy the data to a file

// inhibit any other output to the log file
(#options ('p:-l:+lo'));

begin:
find_headline:
// skip empty line
*(ws)l(0..) + nl : t find_headline;
// find the first headline; stop on error
<1> ' salesman ':f s;
skip_line:
// skip this line
* + nl;
// check for dashed line; skip dashed line
<1> ' ------' + * + nl :f skip_line;

check_line:
// check for end of page (empty line)
*(ws)l(0..) + nl : t find_headline;
// skip leading spaces
*(ws);
// display name
*(-ws) > display;

check_number:
// skip column separator
*(ws)l(0..) + '|' + *(ws)l(0..);
// check for end of line
nl > display :t check_line;
// display a TAB character
(display = '\t');
// display sign
'-' > display;

disp_digits:
*(digit) > display;
// skip comma
',':t disp_digits;
// display fractional part
'.' > display + *(digit) > display;
// search next number
:check_number;
// end of LIST1.PRG

The log file will look like this:

Smith    120000.00120000.00120000.00120000.00
Johnson  -3000.00 15000.00 33000.00 36000.00
Carter   2278239.89    78055.50 0.000.00

The following <search program> will modify the list file:

// LIST2.PRG
// delete all but the data from the list file

find_headline:
// delete empty line
*(ws)l(0..) + nl = '' : t find_headline;
// find the first headline; stop on error
<1> ' salesman ':f s;
delete_line:
// delete this line
:<col 1>; * + nl = '';
// check for dashed line; delete dashed line
<1> ' ------' + * + nl = '' :f delete_line;

modify_line:
// delete leading spaces
:<col 1>;
// check for end of page (empty line)
*(ws)l(0..) + nl = '' : t find_headline;
// delete leading spaces
*(ws) = '';
// skip name
*(-ws);

// clean up the numbers
clean_number:
// delete column separator
*(ws)l(0..) + '|' + *(ws)l(0..) = '';
// check for end of line
nl :t modify_line;
// insert a TAB character
''='\t';
// skip sign
'-';
skip_digits:
*(digit);
','='':t skip_digits;
'.' + *(digit);
:clean_number;
// end of LIST2.PRG

After modification the list file will look like this:

Smith    120000.00120000.00120000.00120000.00
Johnson  -3000.00 15000.00 33000.00 36000.00
Carter   2278239.89    78055.50 0.000.00


6   Contents of the PED4DOS software package

The PED4DOS software package (compressed ZIP file or diskette)
contains the following files and directories:
README.1ST     Introduction to the use of PED4DOS
README.GER     Introduction to the use of PED4DOS (in German
               language)
FILE_ID.DIZ    Short description
PED4DOS.TXT    Documentation File (ASCII text file); also
               available in the format of "Microsoft Word for
               Windows" (see 6.3)
LICENSE.TXT    License Conditions (ASCII text file)
REG.FRM        Registration Form (ASCII text file) for purchasing
               a license for PED4DOS
REG_GER.FRM    Registration Form (ASCII text file) for German
               users


6.1 Executable Files
The directory BIN contains the files:
P4D.EXE        MS-DOS based executable file
SETUP.EXE      MS-DOS based executable file;
               used to create a licensed version of P4D.EXE


6.2 Samples
The directory SAMPLES contains the files:
DEMO.BAT        command file
ANSI2ASC.PRG    search program files
ANSI2OEM.PRG
CENTER.PRG
COUNT.PRG
FILES.PRG
LIST1.PRG
LIST2.PRG
CONFIG.SYS      input files for demo
DEMO.IN
LIST.IN


6.3 Documentation
The directory DOC\ENGLISH contains the files:
PED4DOS.DOC    This document in the format of "Microsoft Word for
               Windows"
REG.FRM        Registration Form  (ASCII text file) for purchasing
               a license for PED4DOS

The directory DOC\GERMAN contains the files:
PED4DOS.DOC    This document in German language in the format of
               "Microsoft Word for Windows"
PED4DOS.TXT    This document in German language as ASCII text file
LIZENZ.TXT     License Conditions in German language asASCII text
               file
REG_GER.FRM    Registration Form (ASCII text file) for German
               users


