Most of the macros in this package are used to find a string target. They are logical extensions and enhancements of the KEDIT CLOCATE and ALL commands. A key objective is to minimize screen movement as you first display one instance of the target and then move on to display the next. The macros highlight each found target (usually one at a time). They try to always display sufficient surrounding lines to provide context for the target. The macros allow easy specification of the case used to do a particular search without affecting the current case for the KEDIT session. The macros are integrated to let you easily use the same search target for all of them without having to retype it. One of the macros lets you scan a whole directory tree and collect all the lines containing a target along with information about the file where each target line was found.
KEDIT commands like CLOCATE and ALL do their searches according to the case setting currently active, e.g., as specified by the latest "SET CASE" command. The ENHSRCH string search macros can temporarily change the current case to do their searches. They examine the first delimiter of the search target to determine the case to be used. "CASE M R R" is set for the search when one of the following three delimiters is used : ' (single quote), " (double quote), and > (greater than). "CASE M R R" means uppercase and lowercase letters are considered to be different in the search; thus "Abc" and "abc" are seen as different. Using any delimiter other than the above three means "CASE M I I" is set for the search, meaning uppercase and lowercase letters are considered to be the same, so "Abc" and "abc" are seen as the same.
If multiple items for a search are specified (a compound search target), e.g., SHALL 'ABC' | /XYZ/, only the first delimiter of the first search term (the first single quote in this example) is used for the case determination. The delimiters of any other terms are considered to be the same as that first one (the "/"s are considered to be single quotes in this example).
All the ENHSRCH search macros save their target data in an EDITV LKLAST global variable in the form LF target. Thus the target used by one macro can serve as the default target for another macro within that KEDIT session. There is no need to retype the search target; just use "/" for the target and the LKLAST data after the "LF" will replace the "/". For example, if LKLAST contained LF /atmospheric changes/, then SHALL / would become SHALL /atmospheric changes/.
However, if the KEDIT session ends, any data recorded by EDITV is lost. To get around this, LKJGK, SHALL, COLLECT, and LKREVERS now save the target data in a file as well as in an EDITV variable. The file is named in the LKLAST_FILE global EDITV variable. If the EDITV data is found to be unavailable in a subsequent session, the file data is used instead to do the search and also to enable a new EDITV save of the data.
When any of the ENHSRCH macros find LKLAST is null and the LKLAST_FILE variable is also null, the macros invoke LKLAST_FILE_SETUP to set up a file to hold the LKLAST data. This macro records the name of the file in the LKLAST_FILE variable and also adds an EDITV SETL statement to WINPROF.KEX to set up LKLAST_FILE whenever a new KEDIT session is started. The default location for the file is in the first directory listed by KEDIT's MACROPATH. The user can modify and/or move the statement added to WINPROF.KEX to use a different file name and location for saving the LKLAST data.
The string target used by the ENHSRCH macros can include almost all the forms and modifiers valid for the ALL and CLOCATE commands. For example: COLLECT word 'John' | reg /:c[1-5]+:w/. SHALL does not support some search string modifiers: "~" (negative), "^" (negative), "-" (backward), and "&" (and). LKJGK does not support "&" (and).
You can define keys and mouse buttons to invoke your macros. For a macro invocation it is important to know the difference between where the mouse pointer is and where KEDIT has recorded the file cursor to be. You can move the mouse pointer anywhere on the screen, e.g, to any visible file line, the prefix area, command line, etc. However KEDIT does not know that location until you take some action to notify KEDIT about the new desired location for the file cursor, e.g., by doing a left click of the mouse. It is easy to forget to do that left click first and instead just click your macro key, thinking that the mouse pointer position is the file cursor location. However KEDIT will use the current (un-updated) file cursor location for the macro work, not the mouse pointer position where you want the file cursor to be for the macro. So be sure to left click first to show where you want your macro to operate. Of course some people may have other ways to do such "left click" selection, e.g., they may have swapped the left and right mouse buttons or they may use a touchpad. Just make sure you have gotten the file cursor in the right place before invoking your macro. [See the suggestion box at the end for a possible way to automatically do the left click.]
LKJGK is an extension of CLOCATE. It is typically invoked initially by using one of the "synonym" macros (described below) to search for a string target, e.g., LK /climate/. The search starts from the current cursor position, or from a defined extreme position if the cursor is on the command line. LKJGK highlights the found target and saves the target information in the LKLAST EDITV session variable. LKJGK tries to minimize movement of the display for initial and repeat searches by appropriately positioning the found target in the display. At the same time it tries to show at least a user-specifiable number of lines surrounding the target when a new page is displayed. See the Help text at the end of LKJGK.KEX.
Usually you will have LKJGK (no parameters) assigned to a key. When the key is pressed, a repeat search is done for the target found in the EDITV LKLAST variable. The initial search direction and wrap status are determined by which "synonym" macro is used to invoke LKJGK. The search direction can be easily reversed by first clicking in the prefix area and then pressing the LKJGK key again. The search direction can also be reversed by using the LKREVERS macro (see below).
LF, LB, LW, LK and LKREVERS are "synonym" macros used to invoke LKJGK. True KEDIT synonyms do not tell the invoked macro which synonym was used to invoke the macro. To get around this for LKJGK, each of these small invoking macros passes its name to LKJGK as a parameter to tell the LKJGK macro how to operate for that invocation.
Below are the "synonym" macros for LKJGK and how they tell LKGJK to search for the specified target. If the target is not passed to LKJGK by the "synonym" macro, the previous target data (gotten from the EDITV LKLAST variable) is used.
LF target Search forward
LW target Search forward with wrap enabled
LB target Search backward
LW -target Search backward with wrap enabled
LK target Search forward
LK -target Search backward
LKREVERS alters the LKLAST data to cause the previous search direction to be reversed if a repeat LKJGK search is done immediately after LKREVERS. Thus a saved LF becomes LB on the repeat search and LB becomes LF. For LW and LK, target becomes -target and -target becomes target.
SHALL is an extension of the KEDIT ALL command. "SHALL target", e.g., SHALL /climate/, is used to do the basic KEDIT target line selection function using ALL, but with some improvements. You will typically define a key or mouse button to invoke MACRO SHALL FLIPFLOP. Once you have searched for a target, e.g., via SHALL /climate/ and created a partial (filtered) display of the file, if you repeatedly invoke SHALL FLIPFLOP, the display alternates between showing the full file (via "ALL") and the partial file (via "ALL target"). The cursor can be used in the partial file display to select the next line to be the current line in the full file display. This makes it easy to cursor-select any line in the partial file, flip to the full file to see the full context of the line, flip back to the partial file to point to some other line, flip back to the full file with the newly-selected line as the new current line, etc. You can edit the file while in either the full or partial display.
A SHALL session starts for a file when you issue the first "SHALL target" for that file, e.g., SHALL /climate/. Within that SHALL session you can invoke SHALL many times, e.g., to flipflop back and forth between partial and full displays of the file, as described above. In the session you can even invoke SHALL to search for other targets in the file, e.g., SHALL /hurricane strength/. Finally you explicitly end the SHALL session, e.g., by issuing SHALL CANCEL, or by invoking SHALL FLIPFLOP right after clicking in the prefix area. You can then start a new SHALL session for that file by issuing another "SHALL target" for either the same or a different target.
Note this is all on a per-file basis. You can have multiple SHALL sessions, one per file, within a KEDIT session in which multiple files are being edited. The SHALL sessions operate independently of each other. Caution: However KEDIT also allows you to have multiple, simultaneous "views" (KEDIT terminology) of the same file, e.g., two windows with one showing the lines near the top of the file and another showing lines near the bottom. SHALL is NOT designed to work with multiple, simultaneous views of the same file. To use SHALL on any file, you need to close all views of that file except one.
For each SHALL session, the pre-SHALL KEDIT environment for that file is saved when the session starts; it is restored when the SHALL session ends. During the session, special coloring is done for the prefix area and TOF/EOF lines to indicate you are currently in a SHALL session and whether the display is a full display or a partial display. The latest found search term is CLOCATE highlighted. Its line is also TAG highlighted. If multiple target instances are in the current line, a maximum of 20 are flagged with column markers. The cursor is placed on the first target in the line.
When you cancel a SHALL session, an attempt is made to leave the screen unmoved, avoiding screen jumpiness. The latest found target is normally left highlighted, if you haven't scrolled it off the screen. There may be an unavoidable jump if you are currently very near the top or bottom of the file, depending on where you configured the current line field (SET CURLINE) in your pre-SHALL KEDIT environment.
It is very useful to assign MACRO SHALL SWORD to a mouse button or key. Having done that, you can put the file cursor on a word to select it, e.g., with a left mouse click, then invoke SHALL SWORD via its assigned mouse button or key to search for the cursor-selected word. The initial word selection, e.g., by clicking the left mouse button, must be on a character in the word, not on a word delimiter. When SHALL is invoked it will then execute a search for the cursor-selected word using KEDIT's "ALL WORD target". A "/" delimiter is used for the word search, meaning case is not respected for this search. If you want to do a case-respected search, you instead have to enter something like SHALL WORD >target>. That requires typing all this, but it shouldn't be required often. [See the warning notes below about KEDIT's "ALL WORD target" when certain unusual characters are encountered. This then indirectly affects SHALL SWORD.]
A consideration for SHALL SWORD is that the target pointed to must be a simple word. The usual valid "word characters" for the English-based world are the A-Z, a-z, and 0-9 alphanumerics, plus the underscore, "_". However to assist in editing text of some other languages, KEDIT uses an ASCII/ANSI extension that allows many more word characters, including letters marked with a diacritic, plus a few more. Thus all characters from X'C0' thru X'FF' (almost all are letters with diacritics) are also considered to be word characters. Finally, as described in the warning notes below, KEDIT adds to the list many more characters, ranging from X'80' thru X'BF'; these are mainly rarely used symbols, e.g., copyright and double-dagger. KEDIT considers all of them to be word characters (and you might not!)
Because there is no choice (the above is hardcoded in KEDIT), SHALL SWORD must consider the above extended set of characters to all be word characters, including the X'80'-X'BF' set. Any character other than those listed above is a "non-word character" and acts as a word delimiter. A word consists of a consecutive string of only word characters -- no embedded spaces, dashes, periods, colons, etc. The word is delimited by any non-word characters, such as spaces, punctuation, line start or line end, "*", "%", etc., i.e., any non-word characters. [See the warning notes below about X'80'-X'BF' characters.]
KEDIT is somewhat inconsistent in its handling of the underscore and the characters in the X'80'-X'FF' range. For word searches, they are treated just like alphabetic characters, i.e., like a "z". Thus "Ab_cd" is a findable word. However these characters can also act as string delimiters in an ALL or LOCATE. Thus "ALL _abc_" will search for "abc". This is in contrast to a letter like "z", which cannot be used as such a string delimiter -- an "ALL zabcz" will quite properly result in an error message. To avoid confusion, it is recommended that you never use these characters as string delimiters in commands.
To help clarify the above, if your cursor selected the ab_c3d "word" in a file, SHALL SWORD would try to find all word instances of ab_c3d in the file. It would find all those flagged below with a Yes, but not those flagged with a No. To be found, a word cannot have any adjacent alphanumeric or "_" characters (or any of the X'C0'-X'FF' or X'80'-X'BF' characters) because that would form a larger word, not matching the one being searched for. These are examples of just a few of the cases in which this string would and would not be found.
Findable String Delimiters around ab_c3d
-------- ------------ -----------------------------------------
Yes ab_c3d leading/trailing spaces or line start/end
Yes ab_c3d. space at start, period at end
Yes ab_c3d, space at start, comma at end
Yes "AB_c3d" enclosed in quotes, also case does not matter
Yes (ab_C3D) enclosed in parens, also case does not matter
Yes ?z#ab_c3d*r misc. delimiters -- having several on each side doesn't matter
Yes {ab_c3d x misc. delimiters -- just one on each side is enough
No Mab_c3d extra leading alphabetic -- now wrong word
No ab_c3d5 extra trailing numeric -- now wrong word
No ab_c3d_ extra trailing "alphabetic" -- now wrong word
No ab_c3dé extra trailing X'E9' (acute e) "alphabetic" -- now wrong word
No ab_c3d‡ extra trailing X'87' (double dagger) "alphabetic" -- now wrong word
Most of the time SHALL SWORD will meet your needs. However sometimes you may want to search for a non-word target. Then something like SHALL /%turkey in# the straw!/ can be used. With it you can specify non-word search targets, as well as specify search modifiers such as suffix, and also the case to be used for the search. SHALL /div.warning/ could be used to find "div.warning" (which is NOT a word -- embedded "."). However if all you needed to find was just the "warning" part or just the "div" part, SHALL SWORD could handle those searches and be much easier to invoke. For example, just do a mouse click to select the word part you want to search for ("div" or "warning") and then invoke SHALL SWORD with another key or mouse click.
Instead of typing a long "SHALL target", you may be able to use Ctrl-C to put the target data in the clipboard. Then use SHALLCLIP, which will build the SHALL invocation text on the command line for you to edit (if desired, perhaps to add a search modifier) and then press Enter to execute the SHALL search. SHALLCLIP will automatically provide appropriate delimiters which don't conflict with the data. If the cursor is in the prefix area, "CASE M R" delimiters are used; otherwise CASE M I" delimiters are used.
Sometimes you may want to search thru a large number of files to look for a specific string target. This can be done easily with the COLLECT macro. Just create a text file listing the files to be searched -- one file per line, usually via a fully-qualified fileid. Then edit that list file with KEDIT and invoke COLLECT to search for the target, e.g., COLLECT /climate/.
The list file might be a KEDIT DIR file. Or you might have a simple BAT tool to create the file that lists the files you want to search thru. Below is a BAT file I use to list the files in my NOTES directory and its subdirectories. The created NOTES_files.txt listing file goes into my JUNK directory. I then open it with KEDIT and use COLLECT to search for some target. This sample BAT file uses the "/s" parameter for the Windows DIR command, saying DIR should also list files in any subdirectories. Thus a COLLECT using this list file will search all files in the NOTES directory tree, maybe many levels deep.
SET UNAME=%USERNAME%
dir C:\Users\%UNAME%\NOTES\*.* /s/b/a-d > c:\junk\NOTES_files.txt
exit
COLLECT marches thru the list of files, edits each one in turn, and does "ALL target" to select the lines containing the string target. If desired, the user can specify a KEDIT profile (via an EDITV variable) to tailor the environment for ALL, e.g., to specify the boundaries of the zone examined by ALL. The lines selected by ALL are appended to a workfile with each such line set preceded by a header line identifying the origin file for those lines. When finished,COLLECT displays the workfile.
EDDQFILE searches the focus line (the cursor-designated line or the current line) for a fileid delimited by doublequotes and then edits that file. If there is only one pair of doublequotes in the line, they are assumed to delimit the fileid; the cursor can be anywhere in the line in that case. If all the doublequotes are to the left of the cursor, the rightmost pair is used. Similarly, if all doublequotes are to the right of the cursor, the leftmost pair is used. If the cursor is on a double quote and there is another to the right, the one under the cursor is assumed to be the left cursor of the pair. Finally, if the cursor is not on a doublequote, but is somewhere between two, they are assumed to be the left and right doublequotes.
Suggestion to Add a Left Click: KEDIT does not supply a way for a macro to simulate a mouse left click, i.e., to place the file cursor where the mouse pointer currently points. This then requires the user to remember to first left click at the desired location and only then invoke the macro to operate at that location.
A way around this is to use something like AutoHotKey to capture a key or mouse button click and then do a left click before invoking the macro. For example, I have a Logitech mouse which allows configuring most of its buttons to simulate a key stroke when a button is pressed. This configuration can be done differently depending on what program is active when the button is pushed. Meanwhile the AutoHotKey program can capture a keystroke and do many things, e.g., emulating keystrokes to send on to the system, executing programs, and moving the cursor. And, of course, KEDIT lets the user define a key press to execute a macro. Configuring the three as shown below means pressing my mouse's shift speed button first causes a mouse left click to be sent to the system (getting the file cursor in the right place) and then causes SHALL FLIPFLOP to be invoked:
^F11:: ; key definition for Ctrl-F11
Send {Click Left} ; emulate a click of the left mouse button
Send !{F11} ; emulate a press of Alt-F11
return
I did a similar thing with another mouse button (wheel press) and another pair of keys (Ctrl-F9 and Alt-F9) to get a left click in front of SHALL SWORD.
This scenario shows how these macros can be used together. Of course most of them are also very helpful when used individually. Let's say you want to examine all the files in your KEDIT user directory to get a list of all the lines containing the string "myTOFEOF" and then maybe editing some of those files, initially focusing on the lines that contain "myTOFEOF". Let's say you want case to matter for this search, so the ">" delimiter is used for the ENHSRCH macros instead of maybe a "/". Single or double quotes could have been used instead of ">", but the ">" graphic shows up better in the writeup below.
The output file from the COLLECT macro will get you started on this task. It will list only the files that contain "myTOFEOF" and for each file will list all the lines with that string target. Now let's say you want to edit one of the target files and you want to start by going right to one of the target lines listed in the COLLECT output file for that target file. Then maybe you want to do the same thing with other target lines listed for that file. Finally you want to close that file and move on to another one to examine and edit. And so on until you're done with any files of interest.
The ENHSRCH macros automate much of this labor. They let you focus on some key lines in maybe only a few of thousands of files, each of which may be quite long. You can then choose to edit some of those files, looking first at the "myTOFEOF" lines in full context. Below are some "how to" details.
You might have MACRO SHALL FLIPFLOP, MACRO LKJGK, and MACRO EDDQFILE assigned to keys or mouse buttons. (Having an easy way to invoke MACRO SHALL FLIPFLOP is probably the most important for this example, with MACRO LKJGK second most.) You might also have MACRO SHALL SWORD and MACRO LKREVERS so assigned.
Issue DIR for your KEDIT user directory to get a DIR listing of its files. For example, "DIR C:\Users\Jeff\KMACROS" does it for me. While editing the KEDIT DIR file, enter COLLECT >myTOFEOF> to search all these files and display a workfile containing all the lines with the "myTOFEOF" string. Each set of lines is preceded by a header line which identifies the origin file for the following line set. COLLECT also saves LF >myTOFEOF> in the LKLAST EDITV variable where it becomes available for LKJGK, COLLECT, and SHALL to use later in the KEDIT session, e.g., for the SHALL invocation in the following paragraph.
Put the cursor on the header line of any file of interest and invoke EDDQFILE. This causes the subject file to be edited. If you haven't changed the standard KEDIT key assignment for Alt-X, you could also start this edit by clicking on the file name and then pressing Alt-X. Now enter SHALL /. This does a KEDIT "ALL >myTOFEOF>" on the file. (The ">myTOFEOF>" part had been previously saved in LKLAST by COLLECT.) Cursor select any line of interest in this partial display of the file, which shows just the lines containing "myTOFEOF". Then press the SHALL FLIPFLOP key to display the full file with the cursor-selected line as the new current line. In this full display you can see the cursor-selected line in full context, surrounded by a screen full of its neighboring lines. You can scroll and edit the file while in this full display mode.
When you're finished looking at that target area, press the SHALL FLIPFLOP key, which issues another "ALL >myTOFEOF>", to return to the partial display. The cursor will be placed where it was originally in this display. This assumes that during your editing in the full display you haven't deleted all targets from the target (current) line or even deleted the whole line. If you did either of these, no problem. SHALL will just issue an explanatory message and then set up a new list with whatever targets remain, making some other target line be the new current line. Now cursor-select another line of interest and repeat the process with the SHALL FLIPFLOP key to return to the full display, but now with that new cursor-selected line as the center of attention since it is now the current line. You can continue this back and forth operation as much as you want.
After finishing with this file, you can close it and then use EDDQFILE or Alt-X to edit some other file listed in the workfile that COLLECT created. Or you can leave the file open while you go on to work with another file. You can have multiple SHALL sessions active in a KEDIT session, one per file.
While editing any file, instead of (or together with) using SHALL, you can press the LKJGK key to search for the ">myTOFEOF>" string (or a different string) and highlight it. Pressing the LKJGK key again finds the next occurrence in the file. You can reverse the search direction by putting the cursor in the prefix area before pressing the LKJGK key. You can also reverse the direction by using LKREVERS or by using another of the LKJGK synonym macros described above. If the SHALL partial display has many lines, it may be hard to see where the target is located in each of them since only one target is highlighted in the whole list. Invoking LKJGK lets you go thru the display, target by target, highlighting the next (or previous) one with each press of the LKJGK key. That can help you determine which line you want to click on next and then invoke SHALL FLIPFLOP.
If at any time you override the search term saved in LKLAST, you can easily reload it by issuing something like LK >myTOFEOF>. All the ENHSRCH macros get and save that default search information in the LKLAST variable.
If you assign MACRO SHALL SWORD to a key, you can just point to a word in a file and click the key to start a SHALL search for that word in the file. This can be done while you are already in a SHALL session, currently working with a different search target. The SHALL SWORD causes the previous SHALL operation to end and the cursor-selected word to become the new target and the basis for future flipflopping, etc., in this SHALL session.
Warning Notes: It's informative to see the list of the 256 ASCII/ANSI characters that KEDIT supports. They are used for creating and delimiting words. Some may be a surprise to you and have unintended consequences if found in your file. See hexchars.txt in the ENHSRCH package for a chart showing how most of those 256 characters display on my PC. They may display differently on yours, but the chart should give you a general idea of what graphic is associated with each codepoint. Also in the package is the HEXCHARS.KEX macro that generated the chart; you can run it on your own PC.
The characters are divided into four groups: