* *** SHALLFLOW TXT - 7 Aug 2025  19:18:26 - JGKNAUTH

                                 Logic Flow for SHALL.KEX             version 3.7
                                 ----- ---- --- ---------

                                                     {">====> means a call to a subroutine  }
{SND means SHALLNEXTDISPLAY (EDITV file variable)}   {"+++++++++++++" subroutine description}
{SND = '' means this is a new SHALL session      }
{"saved" usually means saved per file via EDITV  }   {">::::> means a signal to a subroutine}
                                                     {"#############" signal description    }

Set up variables for desired color tailoring
Update file cursor to mouse cursor location if MOUSECURSOR option is specified
Set up for later LKLAST_FILE query
restart = 0; target = strip(arg(1))

########################################################################
restart_search:      (signal entry point)
########################################################################
If restart, set target from SHALLTARGET EDITV file variable, saved at the
   start of this SHALL session.

If target = ?, >:::::::::> Help subroutine --> exit 0

                                                       +-------------+
If target = "SWORD", >================================>| SHALL_sword |
<=====================================================<| subroutine  |
If result = '', exit 100; Else, target = result        +-------------+

If target = "CANCEL",
   If SND = '', [EMSG], exit 110                                        'There is no SHALL session to cancel.'
   Else [MSG]                                 +----------------------+  'User canceled SHALL session.'
        >=========================(USER)=====>| cancel_SHALL_session |
        exit 0 <=============================<|      subroutine      |
                                              +----------------------+

If target = "FLIPFLOP", >::::::::::::::::::::> flipflop --> exit misc.

If target = ??, set up command line with SHALL command, exit 0

If target = '',                                                         'A search target is required.  (There'
   If SND = '', [EMSG], exit 120                                           is no SHALL session to cancel.)'
   Else [MSG]                                 +----------------------+  'User canceled SHALL session.
        >==================(USER)============>| cancel_SHALL_session |     (SHALL issued with no search target.)'
        exit 0 <=============================<|      subroutine      |
                                              +----------------------+
If target start = -, ~, or ^, [EMSG], exit 130                          'The "-", "~", and "^" search modifiers
                                                                           are not supported by SHALL.'
Check target syntax; also saves case and target       +--------------+
>====================================================>| check_target |
<====================================================<|  subroutine  |
If result \= 0, exit result                           +--------------+

Get clean target from SHALLTARGET; it was saved by check_target


>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  For the INITIAL entry to SHALL, set up the initial PARTIAL display.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

ALL target        (Displays only the lines containing the target)
      (Uses saved case for search, but preserves/restores old case)     'ALL return code' save_rc '(maybe bad
If rc not 0 or 2,[EMSG], exit 150                                       delimiter) for your search target:' target
If rc = 2,
   [EMSG]                                     +----------------------+  'Could not find the target: ' target
   If restart, >========(IMMEDIATE)==========>| cancel_SHALL_session |
        exit 202 <===========================<|      subroutine      |
                                              +----------------------+
If new SHALL session,   (i.e., SND = '')
   Save pre-SHALL environment.
   Set SHALL column mark color and turn off column marks.
   Get EDITV SHALLCURL, user override of SHALL's M current line placement.
   Calculate gap between SHALL and pre-SHALL current lines; save gap.

Set SND to FULL.
Shift top PARTIAL line to be the current line.  (Put cursor in CMD first.)
Set SHALL environment colors:  prefix, TOF/EOF, current line via TAG.
Save "best-can_do" line for exit.
                                                  +------------------+
>======================(INIT)====================>| highlight_target |
<================================================<|    subroutine    |
  (only returned result is 0)                     +------------------+

Display target count information. [MSG]                                 '# occurrences counted in # lines for
                                                                            target:' target
            But if COUNT rc \= 0, [EMSG], [MSG]                         Give possible reason for KEDIT COUNT failure
exit 0                                                                     and provide line count via nbscope.1


########################################################################
flipflop:            (signal entry point)
########################################################################
When SND = '', [EMSG], exit 300                                         '"SHALL search-target" must be executed
                                                                             before "SHALL FLIPFLOP".'
When in prefix,
   [MSG]                                                                'User canceled SHALL session.'
   If SND = FULL and no targets left in file, +----------------------+
        >=============(IMMEDIATE)============>| cancel_SHALL_session |
        exit 0 <=============================<|      subroutine      |
                                              +----------------------+
                                              +----------------------+
   Else >==============(PREFIX)==============>| cancel_SHALL_session |
        exit 0 <=============================<|      subroutine      |
                                              +----------------------+

------------------------------------------------------------------------
|||||||||||||||||||||||||  Build FULL Display  |||||||||||||||||||||||||
------------------------------------------------------------------------
When SND = FULL,                                                        'Click the cursor on a line in the data
                                                                           area to select that line'
   If cursor on shadow, etc., [EMSG], exit 310                          '  or put the cursor in the prefix area
                                                                           to cancel the SHALL session.'
   If cursor = -1, put cursor on current line.
   Record file line and cursor column.

   ALL to display full file.

   Set .jgktarget point
      (cursor to CMD, locate file_line, set point)

   Put cursor on current line.
   TAG color that line.
   Color prefix area and TOF/EOF lines with FULL colors.
                                                  +------------------+
   >======================(FULL)=================>| highlight_target |
   <=============================================<|    subroutine    |
   If result = 2,                                 +------------------+
      SND = PARTIAL
      [EMSG], [MSG]                                                      'You deleted or moved one or more targets.'
      restart = 1                                                       'SHALL has now tried to rebuild the PARTIAL
      >:::::::::::::::::::::::::::::::::::::> restart_search               display with any remaining targets.'
   restart = 0
   Save current line as "best-can_do" line for SHALL session cancel.
   SND = PARTIAL
   exit 0

------------------------------------------------------------------------
|||||||||||||||||||||||  Build PARTIAL Display  ||||||||||||||||||||||||
------------------------------------------------------------------------
When SND = PARTIAL,

   ALL search for target
          (using saved case for search, but preserving/restoring old case)
      If rc not 0 or 2,
         [EMSG]                               +----------------------+  '***ERROR*** RC='ALL_rc 'from ALL.'
           >===========(PARTIAL)=============>| cancel_SHALL_session |
           exit 320 <========================<|      subroutine      |
      If rc = 2,                              +----------------------+
         [EMSG]                               +----------------------+  'SHALL session canceled.  The target can no
           >===========(PARTIAL)=============>| cancel_SHALL_session |      longer be found in this file.'
           exit 2 <==========================<|      subroutine      |
                                              +----------------------+
   If restart = 0,
      LOCATE .jgktarget point (first put cursor on CMD)
      If rc \= 0, [EMSG], [MSG]                                         'You deleted or moved one or more targets.'
                                                                        'SHALL has attempted to rebuild the PARTIAL
   Put cursor on current line.                                              display with any remaining targets.'
   TAG color that line.
   Color prefix area and TOF/EOF lines with PARTIAL colors.
                                                  +------------------+
   >====================(PARTIAL)================>| highlight_target |
   <=============================================<|    subroutine    |
   If result = 2,                                 +------------------+
      SND = PARTIAL
      restart = 1
      >:::::::::::::::::::::::::::::::::::::> restart_search

   restart = 0
   Save current line as "best-can_do" line for SHALL session cancel.
   SND = FULL
   Display target count information. [MSG]                              '# occurrences counted in # lines for
                                                                           target:' target
            But if COUNT rc \= 0, [MSG]                                 Provide line count via nbscope.1
exit 0

Otherwise and missing exit error handling:  [EMSG], exit 330,           '"'shallnextdisplay'" is not "FULL" or
                                                       or                   "PARTIAL".'
                                                    exit 340            'Should never get here:  FLIPFLOP routine
                                                                           error.'
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++  Cancel SHALL Session   (cancel_SHALL_session subroutine)  ++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Save number of current line.
Save current setting of SHALLNEXTDISPLAY.
If .jgktarget line still exists, use that line number for the target line;
   otherwise use the saved "best can do" line number for the target line.
Calculate gap between current line and target line.

Restore pre-SHALL environment:  CURLINE, ALL, TAG, prefix and TOF/EOF colors .

Set SND = '' to cancel the SHALL session.

Make target line the current line for highlighting.

If cancel_caller \= IMMEDIATE,                    +------------------+
   >=======(CANCEL, cancel caller)===============>| highlight_target |
   <=============================================<|    subroutine    |
Save highlight_target result.                     +------------------+
Save column location of first target in the line (maybe -1).
Restore pre-SHALL environment:  COLMARK list and COLMARK colors

Put cursor on command line.
Scroll to adjust for any target line vs current line gap.

Calculate scrolling needed to adjust for any gap between the pre-SHALL
   session CURLINE setting and the setting used in the SHALL session.

If cancel_caller = IMMEDIATE,
   Locate target line (which is probably the "best-can-do" line).
   Scroll as required.
   Put cursor on target line.
   Return highlight_target result

Scroll as required to account for difference between SHALL setting for
    CURLINE and the user's pre-SHALL setting for CURLINE.

If currently in PARTIAL display (SHALLNEXTDISPLAY = FULL),
   Put cursor on command line.
   Calculate scrolling required to shift target line back from current line.
   Shift target line to current line.
   Preserve environment and set up for target search in the line.
   Highlight the target.
   Save the column location.
   Restore the environment.
   Scroll the target line back to its original location.
   Try to put the cursor on the line and then on the column of the target.
   Return highlight_target result

If currently in FULL display (SHALLNEXTDISPLAY = PARTIAL),
  If target line would not be between first and last screen lines,
     turn off target highlighting with a "LOCATE 0" (nop).
  Else, try to put cursor on target.

return highlight_target result


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++  Highlight Target(s)   (highlight_target subroutine)  +++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

{Input:  The current line with possible target(s) to highlight and/or flag}
{Output: Line still current, now with a possible highlight and column marks}
{Return error code if target cannot be found in the current line}

Turn off any current column markers.
PRESERVE current KEDIT settings.  (Note no RESTORE is done for a while.)
Do settings needed to do CLOCATE of a target on a line.
Put cursor on command line.

CLOCATE target starting from column 0.
If rc = 2,
   When highlight_caller = FULL,    RESTORE, return 2
   When highlight_caller = PARTIAL, RESTORE, return 2
   When highlight_caller = CANCEL,  RESTORE, return 2
   When highlight_caller = INIT,    RESTORE, [EMSG], return 400         '***ERROR*** SHALL cannot find the
                                                                           known-to-exist search target.'
   Otherwise
      [EMSG], RESTORE, return 410                                       'Invalid caller to highlight_target'

If rc \= 0, [EMSG], RESTORE, return 420                                 '***ERROR*** CLOCATE had a problem.
                                                                            RC='rc
Save number of current line and first_found column

If highlight_caller = CANCEL,      (skip the multi-target marking)
   If cancel_caller = USER or cancel_caller = PREFIX,
      Try to put cursor on first target.
      If rc \= 0, [EMSG]                                                'Highlighted target may be off screen
   RESTORE                                                                 to the side.'
   return 0

................  Handle Multiple Targets in the Line  .................

Record current file line and file column numbers for current line.
The file column is for the first target found on this line.

CLOCATE any other targets (KEDIT limit is observed)

Highlight first target found.
Try to put the cursor on the first target,
   but that may fail if the target is offscreen. [EMSG]                 'Highlighted target may be off screen
   However it will have been highlighted by the CLOCATE.                    to the side.'
Column mark all targets.

[MSG] + [beep] if more than one target on this line.                    Multi-line message about target numbers,
                                                                           column locations, cursor location, etc.
RESTORE
Column mark the target(s).  (KEDIT limit is observed.)
return 0


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++  Get Cursor-Selected Word   (SHALL_sword subroutine)  +++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Get cursor column and check that it is in the file area.                'Cursor must be clicked on a word in the
   If not, [EMSG], return ''                                                file.'
Get file line, prefix a space, and move cursor right to stay in sync.

Convert to a space any character that is not a word character.
{Beware that KEDIT considers many symbols as word characters.}

Starting from the adjusted cursor position,
   find the first character of the word, then
   use parse to grab just the cursor-selected word.

If cursor is not on a word character, then [EMSG].                      'The cursor must be on a word character,
                                                                            not on a word delimiter.'
return "WORD /found-word/"


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++++  Check Target Syntax   (check_target subroutine)  +++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Split the proposed target into a possible modifier word and then the
rest of the input.

Handle four possibilities, checking for standalone "/" as an argument:
   No modifier and no "/"
   No modifier but "/" is present
   Modifier and no "/"
   Modifier and "/" is present

When a "/" is present, data is gotten from the LKLAST session variable.
Such data is split into a modifier and rest of data, as above.
Either all the data (no modifier present) or just the data after the
modifier is used from the LKLAST data.  That data replaces the "/" in
the original input.  The original modifier, if present, is unchanged.

Error checks:  "/" in LKLAST data  [EMSG], return 141                   'A standalone "/" is not allowed from
                                                                            LKLAST to form a search target.'
               Empty string
               String is just a single delimiter (other than "/")
               String is two adjacent delimiters, e.g., "//" or "//xyz"
               Invalid delimiter, e.g., an aphanumeric
                                   [EMSG], return 142                   'A search target is required.  This is not
                                                                            valid:' strip(out_mod dstring)

Per the target delimiters, determine the desired case for searching.
Save the case.
If the right delimiter is missing, make one from the left delimiter.
Save the newly constructed target (out_mod dstring) in SHALLTARGET.
Save the new target in the LKLAST variable and the LKLAST_FILE file for
   ENHSRCH macros to use.

return 0


########################################################################
help:                (signal entry point)
########################################################################
Displays help text.
exit
