
     //\   //\        ==========                       Version 2.0.2
    //  \ //  \ o .==_ o   \ .==_ \  \ .==_              (Alpha #3)
   //    //    \ \ \  \ \   \ \    \  \ \__)             1999/12/21
  //    //      \ \ \  \ \   \ \    `=/\ \__=
                                               http://www.pagesz.net/~minitrue
      Copyright (C) 1995-99 Andrew B. Pipkin         minitrue@pagesz.net
      Released under the GNU Public License


==============================================================================


Introduction

    MiniTrue is a versatile utility which combines a fast and powerful
    search/replace functionality with a full-featured textviewer, enabling
    quick and efficient browsing, searching and/or modification of a large
    number of files. MiniTrue can operate interactively and prompt to see if
    a replacement should be made or it can make all desired substitutions
    automatically. MiniTrue can also print out matching lines in the manner
    of the utility grep. If no strings to search for are present, MiniTrue
    functions like the pager program less.

    Version 2.0 offers many improvements over version 1.5. The source has
    been completely rewritten, making possible ports to Linux and 32-bit DOS
    which do not suffer from the memory limitations of the original version.
    Extended regular expressions are supported and much more functionality
    has been added to the text viewer. Many additional improvements have been
    made. The source code is now available to the public. The new features do
    not compromise the speed and flexibility of the original version.

    The name of the program is the shorthand form of Ministry of Truth, which
    in George Orwell's _1984_ was the name of the bureaucracy responsible for
    perpetually revising historical documents. Many revisions just involved
    the replacement of one word with another, such as the substitution of
    the previous enemy state with the current enemy.

    MiniTrue is released as free software and without any warranties express
    or implied, including but not limited to, any warranty for
    merchantability or fitness for a particular purpose. See the file COPYING
    included with the MiniTrue distribution for more information about the
    warranty and license.


Invoking MiniTrue

    The general format of a MiniTrue command line is as follows:

        mtr <OPTIONS> <FILES> - <STRINGS>

        The first group of arguments determines which program options will be
        enabled. The second lists the files which are to be scanned. The
        final group contains the strings which are to be searched for and
        their replacements. The - is used to separate the filenames and
        strings. If the - is omitted, the first argument after the options is
        treated as a filename with the remainder considered strings.

        -- can be used as a separator, which will reverse the positions of
        the files and strings, making the command line:

        mtr <OPTIONS> <STRINGS> -- <FILES>

        Reversing the position of the strings and files enables interaction
        with programs such as xargs which assume that the filenames will be
        the final part of a command line.

        Piping standard input into MiniTrue, as in dir | mtr, results in
        standard input being scanned as if it were a file (unless the -@ or
        -i cause standard input to be treated as a list of filenames or
        strings). If standard input is scanned as a file, and neither - nor
        -- is present on the command line, all arguments which are not
        options are considered strings.

        Strings on the command line have the following format (Square brackets
        indicate something is optional):

        FIND1 [= REPLACE1 ] [ FIND2 [= REPLACE 2] ] [ FIND3 [= REPLACE3 ]] ...

        The text matched by the FIND strings will be displayed in the
        textviewer (or written to standard output if the -o option is used).
        If the find string is followed by a = which is preceded and followed
        by at least one space, a prompt will be displayed asking whether the
        matched text should be replaced by the string following the =. If no
        string follows the final =, the string preceding it will be be
        deleted. Deletion can also be obtained by using a replacement string
        of \z.

        More than 3 find/replace pairs can be used. Strings which contain
        spaces must be enclosed in quotes. If no strings are present on the
        command line, MiniTrue will display all files in the text viewer.

Options

    Default Options

        Case insensitivity, regular expressions and making numbered backup
        files are the original preset options. These options can be disabled
        by using -c-, -x- and -b- respectively.


    Setting Default Options

        The default settings can be stored in the $MINITRUE environment
        variable. The contents of the $MINITRUE variable is processed as if
        it is the first argument on the command line. The $MINITRUE
        environment variable is set in the following manner in various
        operating systems:

            set MINITRUE=-nq                DOS
            MINITRUE=-nq; export MINITRUE   UNIX Bourne shell or bash
            setenv UNZIP -nq                UNIX C shell

        The $MINITRUE environment variable can contain more than one option
        if it is enclosed in quotes, like MINITRUE="-@:files.lst -nq".

        It is also possible to alter the default options by changing
        DEFAULT_FLAGS in the file minitrue.h and recompiling. To disable a
        default option, follow the character of the option with a -, as in
        -c-.


    Setting Default Parameters

        It is possible to set default parameters for an option without making
        that option enabled by default. To set default parameters, insert a -
        between the option and its parameters. To make printing line numbers
        the default behavior if the -o option is invoked without making -o
        the default, put -o-# in the $MINITRUE environment variable. If a
        command line option has any parameters, then the default parameters
        will not be used. To use an option which has default parameters
        without any parameters, it is necessary to first clear the default
        parameters, as in -o- -o.


    Parameter Syntax

        Parameters which are enclosed in square brackets are optional.
        Parameter names in upper case preceded by a # represent numbers while
        upper-case parameter names without a # indicate text parameters.

        Options can be combined as long as they do not have a text parameter.
        -a -c -e can be replaced with -ace. If an option does have a text
        parameter, subsequent options must have their own -. If -b:.bakt4
        is used, the tab size will not be set. Either -b:.bak -t4 or -t4b:.bak
        should be used to change the tab size to 4.


    Options list

    -a  search All files

        The normal behavior of wildcard expansion and subdirectory recursion
        is to skip all files which are considered hidden by the operating
        system. In UNIX, files which begin with a dot are considered hidden,
        while in DOS, hidden files have the hidden attribute set. If the -a
        option is used, then those files will not be skipped when directories
        are scanned. Hidden individual files listed on the command line will
        always be scanned regardless of whether the -a option is used.


    -b[+]:EXT  make Backup files

        If the -b option is used and modifications are made to files, then
        the original version of the file is saved with the extension EXT
        appended to its filename. If a + follows -b, then the original file
        is left unchanged while the altered version is saved with the
        extension.

        If * is embedded in the extension, then the * will be replaced with a
        number that will guarantee that the backup filename is unique. This
        will insure that MiniTrue will never overwrite any existing files
        (including backups).  Putting multiple *'s together will cause the
        backup number to have at least as many digits as *'s are present,
        padding with 0's if necessary.

        If the backup extension is preceded by .. then the backup extension
        will replace the original filename's extension instead of being
        appended to it.


    -c[+][~]  Case insensitivity

        If the -c option is used, then searches will be conducted in a
        case-insensitive manner. The two parameters determine how case is
        matched in a replacement. If -c+ is used, then the case of each
        character in the replacement will match the case of the corresponding
        character in the found string. -c~ will match case only in the
        initial characters of the strings.


    -d  preserve original file Datestamp

        Normally, if a file is modified the file's date/time is changed to
        the current time. Using the -d option will preserve a modified file's
        original date/time stamp.


    -e[+]  ignore file Errors

        The -e option will suppress error messages when a file cannot be
        opened or read. Using -e+ will suppress file write errors as well.


    -f[+]  control line Folding

        Normally lines which are longer than the screen length are wrapped
        around to the next screen line. -f will prevent line-wrapping from
        occurring between two characters which are defined as members of the
        word set (by the -w option), so words will not be divided between
        different screen lines. -f+ will prevent line wrapping completely,
        with lines longer than the screen length being truncated.


    -h  Hex mode

        -h will cause MiniTrue to begin with the hex viewer.


    -i[+][:FILENAME]  read strings from Input file

        The -i option allows strings to be read from a file. The strings in
        the file are treated as if they follow the strings on the command
        line. Strings which contain a space or other whitespace character
        such as a tab or newline must be enclosed in ". A # in the file
        begins a comment, with the remainder of the line following the #
        being ignored. If :FILENAME is not present, strings will be read from
        standard input.

        The + parameter is intended to be facilitate the ability of UNIX to
        automatically invoke an interpreter for a file if the file begins
        with #!. If the first line of a string input file is

        #! mtr -<options>i+

        and the file is made executable with chmod, typing the name of the
        string file (along with the files it is to operate on) will
        automatically invoke MiniTrue. Using -i+ makes the following argument
        the name of the string input file and causes all non-option arguments
        to be treated as filenames.


    -k  Keep statistics

        A report listing the number of matches will be printed when the
        program is finished if -k is used. The number of matches found for
        each file and each string will be listed.


    -l[:LOGFILE]  generate Log file

        Using -l will generate a log file which will record the file and line
        number of all matches and the replacement string if a substitution is
        made. If :LOGFILE is not present, the information will be written to
        the file minitrue.log. If a log file already exists, the new data
        will be appended to it.


    -m[+]#MARGIN[:#MINJUMP]

        The first parameter of -m determines the positions of matches on the
        screen. If + is not present, the screen will be generated so that
        #MARGIN lines are positioned between the top of the screen and the
        match. +#MARGIN will place #MARGIN lines between the bottom of the
        screen and the match. Matches will appear in the center of the screen
        if the -m option is not present.

        The second parameter controls when the start of the screen jumps to a
        different location when a new match is found. If #MINJUMP is present,
        the screen start will not change if the new match is at most #MINJUMP
        lines away from the line the cursor is on and the new match is
        located within the current screen. Setting #MINJUMP to 0 will result
        in changing the screen start with each match. The default is to not
        jump as long as the new match is found on the current screen.


    -n  No prompting

        Using -n results in all replacements being made automatically and
        suppresses display of the found text.


    -o[#][~][^][/][+][$][#CONTEXT[:#TRAIL]]  write matches to standard Output

        The -o option will cause MiniTrue to behave like the utility grep.
        Matches and their surrounding context will be written to standard
        output instead of being displayed in the textviewer. Replacements
        will be made automatically in the text which is written to standard
        output. The parameters for the -o option are;

        #   Number lines

        ~   Print non-matching lines instead of matching lines

        ^   Normally the filename is printed before the start of the lines if
            more than one file is searched and not written if a single file
            is scanned. Using ^ will invert this behavior, not printing
            filenames when multiple files are used and showing the filename
            for a single file.

        /   Do not print matches and only print filenames where matches
            occur. If ~ is used, print filenames where matches do not occur.

        +   Print both matching and non-matching lines, causing MiniTrue
            to behave like the cat utility. If # is used in conjuction with
            +, MiniTrue will operate like a line-numbering utility.

        $   Do not print any context, just write the matching strings to
            standard output. If ~ is used with $, the entire file is printed
            with the exeception of the matches.

        #CONTEXT[:TRAIL] Usually the only context printed is the line a
            match occurs on. Using #CONTEXT will result in #CONTEXT lines
            before the match being printed. If :#TRAIL is present, #TRAIL
            lines after the match will be displayed, otherwise #CONTEXT
            lines of trailing context will be printed.


    -p:PRINT_SET  define the set of Printing characters

        The -p option determines which characters are displayed in the
        textviewer. PRINT_SET has the same syntax as a regular expression
        set. Characters which are not found in PRINT_SET are not displayed by
        the textviewer.


    -q  Quiet mode

        -q will prevent anything from being written to the screen until a
        match is found. The filename currently being scanned will not be
        displayed in the status line.


    -r[^][+][~][#][#LEVEL[:#MAX]]  Recurse through subdirectories

        Using -r will result in subdirectories being scanned. The search will
        begin in the leading directory of a filename. If a filename lacks a
        leading directory, the current directory will be recursed through. If
        a directory is used as a filename, all files in the directory will be
        scanned.

        The parameters for -r are:

        ^   Do a depth-first instead of a breadth-first search

        +   Follow symbolic links (UNIX only)

        ~   Skip files which are not regular files. In UNIX, regular
            files are not devices, pipes or sockets. In DOS, files
            which are do not have the system archive set are considered
            regular files.

        #   Go through the files in a directory in alphabetical order

        #LEVEL[:#MAX] These parameters determine the depth of recursion
            through the directory tree. If #LEVEL is present without :MAX,
            #LEVEL is the maximum level of recursion. The presence of :#MAX
            will make #LEVEL the minimum level, with the second parameter
            representing the maximum.


    -s[#MAX][:#NCONSEC]  control behavior of accelerated Scrolling

        Pressing an up or down arrow key normally causes the position of the
        screen to change by one line. If accelerated scrolling is enabled and
        the arrow key is held down, the arrow key will result in movement of
        more than one line, allowing faster movement through the file. #MAX
        determines the maximum position change that an arrow key can produce.
        #NCONSEC sets the number of consecutive arrow presses which will
        increment the number of lines scrolled. Using -s without any
        parameters will disable accelerated scrolling.


    -t#TABSIZE  set Tab size in text viewer

        The -t option determines how many spaces tab characters embedded
        in files are expanded to.


    -u[#NLINES][:#NBYTES]  control proximity needed for boolean matches

        The -u option determines the maximum distance allowed between members
        of a boolean match. #NLINES determines the number of lines in the
        region in which the strings in the boolean match must occur. If
        #NLINES is 1, then the strings in a boolean match must appear on the
        same line. The maximum number of characters between the parts of a
        boolean match is set with the #NBYTES parameter. If both #NLINES and
        #NBYTES are present, the smaller region will be used. If neither
        parameter is used, the members of a boolean match can be anywhere in
        a file.


    -v[+][:mono][:COLORS]  set Video mode

        In DOS, the + parameter will write the screen through the terminal
        instead of writing directly to video memory. ANSI.SYS or another
        terminal driver must be used. In UNIX, + will pad the ends of lines
        with spaces. Some terminals, such as nxterm, always clear the screen
        to black. This requires that the ends of the lines be padded with
        spaces to make the right side of the screen the same color as the
        rest of the screen.

        The :mono parameter will suppress screen colors. :mono must be present
        if a non-ANSI terminal is used.

        The COLORS parameter allows user definition for the screen colors.
        COLORS is a string of background/text color pairs. The following
        abbreviations represent valid background colors:

            bk - black      bl - blue        gn - green     cy - cyan
            re - red        ma - magenta     br - brown     Gr - bright gray

        The text color can be any background color or any of the following:

            gr - gray           Bl - bright blue    Gn - bright green
            Cy - bright cyan    Re - bright red     Ma - bright magenta
            ye - yellow         wh - white

        A color pair is represented by preceding the background color before
        the text color. bkwh will produce white text on a black background.

        The parts of the screen in COLORS occur in the following order:

            :Normal text:Current match:Previous matches:Wrapped lines ...
            :Lines with unknown starts:Status line:Substituted text

        To use white text on a black screen with current and previous matches
        having black text on a bright gray background, use:

        -v:bkwh:Grbk:Grbk

        The default color will be used if a color pair is not present.


    -w[+][:WORDSET]  Whole words only

        If -w is used and the leading and trailing characters of a match are
        in the set of word characters, the characters preceding and following
        the string must not be members of the set of word characters. The
        WORDSET parameter allows definition of the set of word characters.
        WORDSET has the same syntax as a regular expression character set.
        The regular expression assertions \b and \B along with the -f+ option
        use WORDSET to determine where a word break occurs. If the +
        parameter is used, the set of word characters can be changed without
        requiring matches to be whole words.


    -x  use regular eXpressions

        Using -x will result in the strings being interpreted as regular
        expressions. Regular expression symbols must be preceded by a \ for
        them to be processed as normal characters.


    -y[+]  skip binarY files

        The -y option will skip files which are presumed to be binary files.
        Files are considered binary if more than 10% of their characters are
        characters not commonly found in text files. This is not foolproof
        and some files which are binary might be considered text and vice
        versa. Using -y+ will skip all files which are not considered binary.


    -z:EXT:PROGNAME:OPTIONS[:EXT:PROGNAME:OPTIONS] ...  unZip files

        The -z option allows compressed files to be decompressed before they
        are scanned. The first parameter, EXT is the extension of the
        filenames which are to be decompressed. PROGNAME is the name of the
        decompression program. The third parameter is the flag required by
        the decompression program to write the expanded data to standard
        output. (This is -c for pkunzip, -p for unzip, -c for gunzip).
        Decompressing the archive to standard output avoids the need to alter
        the compressed file. More than one type of decompressor can be used
        by following the initial parameters by additional parameter sets.
        Writing to a file which has been expanded is not allowed.

        If PROGNAME is not present, then files with the extension EXT
        are skipped completely. To skip graphics files, use:
        -z:.jpg:::.gif:::.tif


    -@[+][:FILENAME]  read filenames from file

        -@ scans filenames contained in a file in addition to the filenames
        listed on the command line. If :FILENAME is omitted, filenames are
        read from standard input. The + parameter requires that a null
        character (\0) separate the filenames, otherwise any whitespace is
        sufficient to demarcate the filenames.


File Names

    File names for all versions of MiniTrue use UNIX wildcards. Like DOS
    wildcards, * matches a variable amount of text in a filename and ?
    matches any single character in the filename. UNIX wildcards also allow a
    set of characters to match at a location in the filename. To represent a
    set, enclose the desired characters in []. minitrue.[ch] will match both
    minitrue.c and minitrue.h. A range of characters can be specified by
    placing a - between the endpoints of the range. *[0-9] will match all
    filenames which end with a number. If ! is the first character inside the
    set, all characters not in the set will be matched. ??[!o] matches all
    three character filenames which do not end in o.

    Either \ or / can be used as a directory separator in the DOS versions.

    UNIX shells usually expand wildcards before passing the command-line
    arguments to a program. If automatic wildcard expansion is used and *.txt
    is appears on the command line, *.txt will not appear in the argument
    list seen by the program. Instead, *.txt will be replaced by whatever
    files match the wildcard, such as a.txt, b.txt and c.txt. The expansion
    of wildcards should not cause any problems if a separator - is present,
    but if one is missing problems might result because only the first
    expanded filename will be treated as a filename. Expansion of wildcards
    can be prevented by quoting the filename. Wildcards must also be quoted
    for recursion to work properly.


Strings

    Quoting

        If a string contains a space or a whitespace character such as a tab
        or newline, the string must be enclosed in " regardless of whether it
        appears on the command line or in an input file specified with the -i
        option. Any additional unquoted spaces beyond the space used to
        separate strings are ignored. \s, an abbreviation for all whitespace
        characters, does not require quoting. A string must also be enclosed
        in quotes if contains characters which are treated specially by the
        command shell. For COMMAND.COM in DOS, these characters are <, | and
        >. Quoting strings containing these characters is not required in an
        input file.

        To search for a literal = and @, which are normally considered
        MiniTrue symbols, precede them with a \, like \= and \@. A leading \
        is not needed if a string of more than one character begins with = or
        @.


    Multiple String Considerations

        If more than one string matches at a particular point in a file, the
        string which occurs first on the command line will be displayed
        first. Matches will not be made in the altered text of other strings;
        to modify substituted text, the program must be run again.


    Escape Sequences

        The following escape sequences enable the representation of
        non-printing characters in a string:

            \a  alert (bell)        \b backspace
            \e  escape              \f formfeed
            \n  newline             \r carriage return
            \t  tab                 \z zero-length string
            \\  backslash           \[symbol] treat symbol as normal text

            \x[hexdigit][hexdigit]  hexadecimal number between 00 and ff
            \[digits]               numbers up to 3 digits, with no 8s or 9s
                                    are considered an octal number, assuming
                                    the sequence is not interpreted as a
                                    backreference

        If regular expressions are used, \b will represent a word break
        instead of a backspace. \b must be enclosed in a character set, like
        [\b], to obtain a backspace character.

        Backslashes and their following characters are always treated as
        escape sequences regardless of whether regular expressions are used.


    Regular Expressions

        Regular expressions enable the search for strings which match a
        general pattern. The parts of a match have a variable identity and
        the number of times those parts of can occur can be altered as well.
        All regular expression symbols are treated as normal text if they are
        preceded by a \


        Character Sets

            Character sets allow a more than one character to match at a
            location in a string. The members of the set are enclosed in
            square brakets, like [abcde]. Placing a dash between two
            characters in a set will match all characters from the character
            before the - to the character following the dash. [a-e] and
            [abcde] are equivalent sets. If ^ is the first character in a set,
            all characters will be matched with the exception of the
            characters which follow the ^. [^0-9] will match all characters
            which are not digits. When ^ occurs at a position besides the
            start of a character set, the characters following the ^ are
            removed from the set. [a-z^aeiou] will match the consonants.


            Character set abbreviations

                These escape sequences represent commonly used character
                sets. The escape sequences can be either inside or outside
                another character set.

                    \d digits                   \D non-digit characters
                    \l lower case letters       \L non-lower case letters
                    \u upper case letters       \U non-upper case letters
                    \c alphabetic characters    \C non-alphabetic characters
                    \w word characters          \W non-word characters

                    (The default word set contains all alphanumeric
                    characters and _ It can be modified with -w)

                    \s whitespace characters    \S non-whitespace characters

                    (The set of whitespace characters consists of the space,
                    tab, new line, carriage return, form feed and vertical
                    tab characters.)

                    \p punctuation characters   \P non-punctuation characters

                    (Punctuation characters are defined as all ASCII
                    characters which are neither alphanumeric or a space
                    character.)

                . represents all characters with the exception of \n.
                [^], a negated set with no negated characters, acts as
                shorthand for a set with all characters including \n.


        Alternations

            Alternations are similar to character sets because they allow
            more than one item to match at a point in a string. Unlike
            character sets, the variable text for an alternation can be
            longer than one character. A | is used to demarcate the
            alternatives. abc|def|ghi will match abc, def or ghi. The
            alternation must be enclosed in parentheses for some parts of the
            regular expression to appear outside the alternation.


        Quantifiers

            The following quantifiers enable part of a regular expression to
            occur a variable number of times.

                +           match 1 or more times
                *           match 0 or more times
                ?           match 0 or 1 times
                {n}         match n times
                {min,}      match at least min times
                {min, max}  match between min and max times

            Quantifiers operate only on the character or set immediately
            preceding them unless parentheses are used. abc+ will match abc,
            abcc, abccc, ... To match abcabcabc, the regular expression
            (abc)+ must be used.

            Numeric quantifiers can be any positive number smaller
            than the maximum signed integer of the machine (32767 for 16-bit
            DOS, 2147483647 otherwise).


        Zero-width Assertions

            The following characters and escape sequences do not match any
            particular characters. Instead, they test if a certain condition
            is true at the point they occur.

            ^   line start
            $   line end
            \b  word break
            \B  non-word break
            \A  start of file
            \Z  end of file

            $, the line end assertion, assumes that a single newline is used
            to represent a line end. In DOS text files, which use a carriage
            return-new line pair to mark the end of a line, $ will match
            between the carriage return and the new line. For $ to work as
            intended in a DOS file, the carriage returns must be stripped
            before the regular expression match is attempted. The line ends
            can be reconverted back to normal DOS format when done.


        Backreferences

            The text where a backreference occurs must match the contents of
            a parentheses which occurs previously in a regular expression.
            \(digit) represents the parentheses contents for parentheses 1
            through 9. Parentheses between 10 through 99 are represented by
            \v(digit)(digit). ([a-z])([a-z])\2\1 will match a four letter
            palindrome. The parentheses corresponding to a backreference must
            be closed before the backreference occurs.

            The text captured by a pair of parentheses is displayed in a
            different color from the rest of the match if a color terminal is
            used, making obvious the text that would match a backreference.
            The contents of parentheses #1 is red, #2 is yellow, #3 is green
            and then the color sequence repeats for subsequent parentheses.
            The text color is determined by the innermost parentheses.


        Regular expression replacements

            The following escape sequences can be embedded in regular
            expression replacements and allow the replacement text to vary in
            accordance with the text that was matched.

            \(digit)            replace this escape sequence with the text
                                enclosed by parentheses number (digit). The
                                regular expression must have at least (digit)
                                pairs of parentheses.

            \v(digit)(digit)    This functions like \(digit), but the
                                parentheses number ranges from 10-99 instead
                                of 1-9.

            \l                  Make the following character lowercase

            \u                  Make the following character uppercase

            \L                  Make the following characters lowercase
                                until a \E or \U appears

            \U                  Make the following characters uppercase
                                until a \E or \L appears

            \E                  End the case modification caused by \L or \U



    Boolean Expressions

        The occurence of a string which appears in a boolean expression will
        not be recorded unless other strings are found within a specified
        distance from the match. To specify a set of strings which must must
        appear together, place a @ between the strings on the command line.
        If the region for a boolean match is not changed, a @ b @ c will
        locate a, b and c only when they are present on the same line.
        Boolean expressions can be nested by enclosing parts of them in
        square brackets. If the strings enclosed in square brackets do not
        have a @ between them, there is an implicit or. [ a b ] @ [ c d ]
        requires a or b to occur close to where c or d occurs. A space must
        precede and follow both the @ and the square brackets on the command
        line.

        The default region for a boolean match is a single line. The maximum
        distance allowed between strings in a boolean match is set by the
        -u option.

        If there are multiple permutations for a boolean match in the desired
        region, some permutations might not be recorded. a @ b will only
        match the second a in aab.


Textviewer Commands

Movement Commands

    <SPACE>, <PAGE DOWN>  Move down one page
      Control-v
    b, <PAGE UP>          Move up one page
    <DOWN ARROW>          Move down one line (accelerated)
    v                     Move down one line (non-accelerated)
    <UP ARROW>            Move up one line (accelerated)
    f                     Move up one line (non-accelerated)
    <HOME>, ^             Move to start of file
    <END>, $              Move to end of file
    g                     Move to line number in file
    @                     Move to address in file
    %                     Move to percentage into file
    h                     Move to current found string
    j, Control-n          Move cursor down one line
    k, Control-p          Move cursor up one line
    >, +                  Move to next file
    D                     Move to next file in a directory outside the
                            current one
    Control-d             Move to next file in a directory outside the
                            current one and its subdirectories

Searching Commands

    n, <RIGHT ARROW>      Move to next matching string
    N                     Move to next instance of current string
    p, <LEFT ARROW>       Move to previously found string
    P                     Move to previous instance of current string
    c                     Have next search begin at bottom of screen
    C                     Have next search begin at bottom of screen and
                            make all replacements to bottom of screen
    .                     Toggle between moving automatically to next
                            file and requiring pressing > to move to
                            next file
    /                     Enter string to search for. The search for the new
                            string will begin after the most recently found
                            string.

Replacement Commands

    n                     Do not replace and move to next string
    y                     Replace and move to next string
    Y                     Replace without moving to next string
    s                     Enter substitute replacement text
    S                     Enter substitute replacement which will
                            become the default replacement for the string
    A                     Automatically replace all subsequent instances
                            of this string in this file
    Control-a             Automatically replace all subsequent instances
                            of this string in all files

Miscellaneous Commands

    q                     Quit program (restore original screen if possible)
    Q                     Quit program (do not restore original screen)
    Control-c, <ESC>      Abort program, abandoning whatever changes have
     (<ESC> must be typed   been made in the current file
     twice in UNIX)
    <TAB>                 Toggle between text and hexadecimal viewing modes
    Control-l             Rewrite screen
    #                     Count number of lines in file if unknown
    ;                     Toggle cursor location between file and status line
    H                     Toggle highlighting
    W                     Write region from top of screen to line containing
                            cursor to a file
    Control-w             Save file in its current state to another file
    ?                     Show help file


Text Entry Commands

    <LEFT ARROW>, Control-b     Move cursor to left
    <RIGHT ARROW>, Control-f    Move cursor to right
    <BACKSPACE>, Control-h      Move cursor to left, deleting character
                                  originally before cursor
    <DELETE>, Control-d         Delete character under cursor
    <HOME>, Control-a           Move to start of typed text
    <END>, Control-e            Move to end of typed text
    Control-u                   Erase all text
    Control-k                   Erase text from cursor to end
    <ESC>, Control-g            Cancel command
      (<ESC> must be pressed
      twice in UNIX)


Terminating Program Execution

    To stop MiniTrue from running while it is searching, press Control-C.
    (Use Control-Break for the 32-bit DOS version).


Return Values

    0 is returned if a match if found, 1 if no matches are found. If an error
    occurs, 2 is returned.


Examples

    Some strings might require quoting depending on the shell used. (Replace
    mtr with mt for the DOS 16-bit version)


    Example 1 - The original MiniTrue

        mtr -rnw * - Eastasia = Eurasia

        This will replace all instances of "Eastasia" with "Eurasia" in all
        files on the current drive. The -r option is necessary for scanning
        to recurse through the subdirectories. The -n option will make
        replacements automatically, and the -w option will only find whole
        words


    Example 2 - Determining the frequency of each letter

        mtr -kn /docs/* - a b c d e f g h i j k l m n o p q r s t u v w x y z

        This will determine the number of times each letter appears in the
        files (with case insensitivity) in the subdirectory /docs. The -n
        option will avoid displaying a prompt screen after each find, while
        the -k option will print statistics telling how many times each
        letter was found when the program is finished.


    Example 3 - Inserting blank lines between paragraphs

        mtr -x *.txt - "(^[ \t]+)" = \n\1

        Assume that all paragraphs will start with an indentation consisting
        of spaces or tabs. These indentation characters will be matched with
        [ \t]+. The ^ is used to indicate the start of a line. Quotes are
        required because the regular expression contains a space. In the
        replacement string, \1 represents the indentation, with \n being the
        inserted newline.


    Example 4 - Stripping tags from HTML files

        mtr -xb+:.txt *.htm - "<[^>]*>" = \z

        This will strip most (but not all) tags enclosed in angle brackets
        from HTML files. -x will enable regular expressions and b+:.txt will
        save the stripped files with the extension .txt and leave the
        original html files unaltered. < indicates start of the tag, [^>]*
        will match until the closing bracket and > finishes the tag. Quotes
        around the string are necessary to prevent the brackets from being
        interpreted as I/O redirection symbols.


    Example 5 - Stripping all the C++ comments from a program file

        mtr -x prog.cpp ^\s*//.*\n = \z  //.*$ = \z

        This will remove all // comments from a C++ source file. The first
        find/replace pair will eliminate all comments which have nothing else
        on their line. ^\s* will skip over leading space. After the comment,
        all characters before the newline symbol will be matched with .*
        Finally the \n itself will be included. The replacement string of \z
        (representing a null string) will result in the comment being
        completely deleted.

        The second find replace pair will handle comments with something else
        on their line. Once the // has been found, all characters before the
        end of the line will be matched with .*$ Because there is something
        else on the line, it is not necessary to delete the \r\n at the end
        of the comment.


    Example 6 - Printing the start of a file

        mtr -ox file.txt \A(.*\n){10}

        This will function like the head utility and print out the first
        10 lines of a file. -o will print out the matched text. \A matches
        the start of the file and (.*\n) will match a line including
        its ending newline. The number in brackets tells how many times
        the line should occur.

        The tail utility, which prints lines at the end of a file, can be
        implemented with the string "(^.*\n){10}\Z".


    Example 7 - Determining the density of C++ files

        mtr -knx *.cpp *.h - \n ^\s*$ // ^\s*// ^\s*[{}]\s*$

        These strings provide information about how densely packed a C++
        program file is. /k will keep track of the number of finds and /n
        will prevent the individual strings from being displayed. \n counts
        the number of lines in the file and ^\s*$ locates the blank lines. //
        counts the comments in the file while ^\s*// finds the comments
        occupying a line by themselves. The last string, ^\s*[{}]\s*$, finds
        lines with nothing on them except for a curly bracket.


    Example 8 - Finding words in which all the vowels appear consecutively

        mtr -x * - a[\l^aeiou]*e[\l^aeiou]*i[\l^aeiou]*o[\l^aeiou]*u

        The set of lower case consonants is represented by [\l^aeiou]. These
        consonants can appear any number of times between the vowels. This
        should match abstemious and facetious.


    Example 9 - Converting a text file into a C string constant

        mtr -x cstring.txt ([\\\?\"\']) = \\\1   (\r?\n) = \\n\\\1

        These find/replace strings will convert a text file into the form
        used by C string constants. The first find/replace pair will preface
        ", ', ? and \ with a necessary backslash. The second pair will insert
        a \n, to indicate a new line, and a \, to indicate line continuation,
        before the ends of all lines.


    Example 10 - Finding a six-letter palindrome

        mtr -x * - \b(\l)(\l)(\l)\3\2\1\b

        A palidrome reads the same forwards and backwards. The first three
        letters of the regular expression are enclosed in parentheses to
        enable backreference matching. The final three characters are
        represented by backreferences, which match the corresponding
        characters in the first half of the string. The \bs at the start and
        end of the regular expression insure that the regular expression will
        only match a whole word.


    Example 11 - Extracting email addresses from a non-ASCII file

        mtr -xo$ addrbook.dat ([\w\.]{2,}@[\w\.]{4,}) = \1\r\n

        An email address consists of a @ surrounded by alphanumeric
        characters and dots. The non-@ characters will be represented by
        [\w\.] Assume a minimum of 2 characters to the left of the @ and 4
        characters to the right, so the entire address will be represented by
        [\w\.]{2,}@[\w\.]{4,} The x+ option will match the longest string
        possible. Since a binary file is being searched, and the rest of the
        line is not of interest, the o$ option will write only the addresses
        to standard output. It is necessary to append a CR/LF to the
        addresses to avoid having them printed on the same line. To do this,
        make \1\r\n the replacement string. \1 will represent the address and
        \r\n the CR/LF.


    Example 12 - Finding consecutive duplicate (non-empty) lines

        mtr -x file.txt (^.+\r\n)\1+

        The ^ matches the start of a line, .+ matches the body of lines which
        contain at least one character and \r\n matches the trailing
        carriage return/newline. (Remove the \r for UNIX text files).
        This is enclosed in parentheses so the backreference \1+ will match
        the parentheses contents at least once and possibly more.


    Example 13 - Removing trailing whitespace from the end of lines

        mtr -x file.txt "[ \t]+(\r?\n)" = \1

        [ \t]+ matches a sequence of spaces and/or tabs. \r?\n matches
        both DOS and UNIX line end characters. The replacement string \1,
        will replace the entire matched string with the line end characters,
        which are enclosed in parentheses.


    Example 14 - Normalizing line ends in a DOS text file

        mtr file.txt \r\n = \r\n \n = \r\n \r = \z

        This example is used to convert a file which contains both DOS and UNIX
        line end characters (\r\n and \n, respectively) to all DOS line ends.

        The first find/replace pair has no apparent effect, but it will
        prevent the \n = \r\n from adding an unwanted \r to line ends which
        already contain both a carriage return and new line. The second pair
        will add a \r if there is not already one before an \n. The final
        replacement removes stray \r.


