SoulEdit

SoulEdit is a code editor, written in SOUL, specifically designed for SOUL application development. SoulEdit features extended editing capability - like split/join, bookmarks, display filtering and syntax-specific colors - as well as facilities that make running, debugging and testing SOUL code more seamless and intuitive.

SoulEdit runs as an application subsystem, so it needs an apsy definition for it to operate along with a minimum 640K server size - 750K would be safer as that provides room for future enhancements and the addition of user-written macros. See the ULSPF Installation Guide for more information on setting up the environment for SoulEdit. SoulEdit is built into SirPro, which is part of the UL/SPF family of products from Rocket Software, and it can also be run as a standalone editor by setting up a separate APSY - at Rocket ir runs as an apsy called SE so it's executable from the command line. Details for setting up your own SoulEdit apsy are also in the installation guide.

Overview

SirPro is a menu-driven application subsystem that provides tools for programmers, database administrators and application managers inside the Model 204 environment. SirPro's primary feature set is centered on the manipulation of Model 204 procedures contained in Model 204 files. To access SoulEdit from SirPro, use the E prefix command from the list of procedure. If SoulEdit is defined as a standalone apsy (for example, SE), simply type the apsy name with a procedure: SE MYPROCEDURE, where MYPROCEDURE is a procedure in the current file.

One of the most useful features of SoulEdit is the ability to run a program via the GO command and immediately view the output in a scrollable StringList. If errors occurred while running, a series of AUDIT commands is available to display the audit trail output of the procedure you've just run.

SoulEdit main editing screen

The top line shows the name of the SOUL procedure, the file where the procedure lives, and a warning if the file is in read-only mode. At the right are shown the line numbers with the current top-of-the-screen line number. Note the color-coding of lines in the sample; colors are user-settable via the COLORS command.

Command Line options

Command	Result
T[ n]|TOP[ n]|M+PF7	Go to the Top of the editor content; optional n (linenum) as top of page
B|BOTTOM|M+PF8	Go to the Bottom of the editor content
C <lineNumber>	Center the line specified by lineNumber... lineNumber is absolute... not relative
+|-<numericValue>	Position content relative to the numeric value
[-]F|Find <value>	Find previous/next value from cursor position (PF5 repeats last find)
[-]/<value>	Find previous/next value from cursor position (PF5 repeats last find)
R|REPLACE/<replaceThis>/<withThis>[[/n] ALL]	Replace... n = replacements per line for replace... the character immediately following the R or REPLACE is used as a delimiter between tokens(cannot be alphanumeric)
A|ALL <value>	Hide all lines that do not match <value>... command without <value> performs a SHOW ALL instead
HIDE <value>	Hide all lines that match <value>
SHOW|HIDE COMMENTS	Show or hide all comment lines
UNHIDE <value>	Unhide all lines that match <value>
CLEAR HIDDEN|RESET HIDDEN	Clear all hidden lines (unhide)
SHOW ALL|SHOW HIDDEN	Clear all hidden lines (unhide)
GO	Run the program and capture the output into a scrollable
[IN <fileName> ]GET <procName>	Obtain the named proc and insert into editor... can use line command targeting
SAVE[ <procName>]	Save current editor content (optional save into a different named proc including temp procs)
END	Perform SAVE and exit the editor
QUIT	Exit the editor without saving or giving a modification warning
ALIGN <value>	Requires BB line command range (has issues when crossing 'block' statements)
SORT [A|D|ASC|DESC|ASCENDING|DESCENDING]	Requires BB line command range
CLEAR	Clear all line commands
RESET PROC|RELOAD|RELOAD PROC	Discards any changes by reloading the current procedure from file
REFRESH PAGE	Ignore any changes upon this page since last enter
NUM|NUMS|NUMBERS [ON|OFF]	Show line numbers in prefix field (toggle)
=	Repeat last command (same as PF9)
command stack (pf6)	Cycles thru the command stack
SET COMMAND STACK n	Defaults to 10... but user may want to increase/decrease.
split/join lines (pf2)	Cursor sensitive... if no data from cursor a join is performed else split is performed
FLIP HIDDEN	Flip the hidden state of lines... hidden->shown && shown->hidden
FF|BB+FORMAT - FORMAT [width] [INDENT n]	Format range (indents and alignment)... not fully completed... but mostly functional
UNDO FORMAT	Reinstates the last FORMAT to its state before the format (does not check if code has changed)
SET FORMAT <type>	Force the formatting type used by FORMAT/FF .. Valid types: M204, XSL
RUN (saves & runs code in a daemon) RUN TERM (saves & runs code on current thread) RUN [TERM] [<procName> [FILE <filename> [PASS <password]]]	Output from the execution is scrollable (lost daemons are trapped and reported)
SHOW [ [RUN|OUTPUT]|RUN OUTPUT]	Shows the output from the last executed code or commands line VAR/SHOW [SEQ] CHANGES
SHOW CHANGES	Compares current content against proc on file and is displayed in a scrollable form
SHOW SEQ CHANGES	Do compare against SEQ version in same procfile
SCALE (toggles on/off)	|...+....1....+....2....+....3...etc.
PFKEYS (toggles on/off)	Show valid pfkeys upon the last line of the page
NEW PROC[EDURE]	Clear current code (essentially a quit)... and start with a blank procedure
Formatting for XSL	Change formatting where proc name ends with .xsl
HELP (pf1)	Displays Help text
VAR|VARS|VARIABLES	Show variable usage(counts) within scope
SETUP|PROFILE	Set user editor preferences
COLORS	Set user editor color preferences
bookmarks .<value>	Bookmarks...example. .foo as a line command bookmarks it... command .foo focuses the bookmark
CLEAR BOOKMARKS	Clear all bookmarks
XCOMPARE|XC [EXACT|DEBLANK|COMPRESS]	XCompares current content against proc on file and is displayed in a scrollable form
XCOMPARE SEQ|XCS [EXACT|DEBLANK|COMPRESS]	Do XCompare against SEQ version in same procfile (only works for SirLib users)
LAYOUT|MAP	List all class/subroutines/functions... can use pf4 to focus entry from listing
INCLUDES command	Show heirarchy of all includes referenced within the current procedure
PROTECT/UNPROTECT	Force the displayed content to be protected/unprotected
BB¦BLOCK WHERE	Used to add BB markers to the current 'where' scope
AUDIT [minutes¦timestamp¦LAST[RUN]]	This command shows the journal lines for the user... defaults to the last minute unless an optional time is supplied
SET FILE <fileName>	Sets the filename for saving procedures... also clears the procedure name
SNAP¦SNAPSHOT	Takes a copy of the code in the current editing session and saves it as snapshot
XCB [previous snapshot offset]	Compare the current code against the last snapshot taken

Used in conjunction with the pf12 key on the run output when compilation/runtime errors occur, the following commands can be used to navigate through the errors in the currently loaded procedure:

NE¦NEXT ERROR	Navigate to the next error
PE¦PREVIOUS ERROR	Navigate to the previous error
CE¦CURRENT ERROR	Navigate to the current error
CLE¦CLEAR ERRORS	Clear the error bookmarks

Line Prefix Commands

Block Prefixes - with repeating ignored

    CC = Block Copy                     (requires targeting prefix)                                                                          
    MM = Block Move                     (requires targeting prefix)                                                                          
    DD = Block Delete                                                                                                                        
    HH = Block Hide                                                                                                                          
    ** = Block Comment (set/clear - first line is used to determine state switch... if first char is * then comments are removed)
    BB = Block Boundaries.. used with editor commands: SORT, ALIGN, FORMAT.    Optional for R, REPLACE                           
    FF = Format specified block - sets indenting to the number of spaces specified in the user profile.

Block Prefixes - with repeating honored

  (so, for instance, ""3 replicates the block 3 times)
 RR "" = Block Replicate                                                                                                         
 << (( = Block Shift Left  (with protections to prevent loss of leading text)                                                    
 >> )) = Block Shift Right (with protections to prevent loss of trailing text)                                                   
                                                                                                                                 

Targeting Prefixes

     A = Target After Line                                                                                                       
     F = Target Following Line                                                                                                   
     B = Target Before Line                                                                                                      
     P = Target Previous Line                                                                                                    
                                                                                                                                 

Singular Prefixes - with repeating ignored

     C = copy                           (requires targeting prefix)                                                              
     M = Move                           (requires targeting prefix)                                                              
     E = Expand line to 255 bytes  (toggles on/off)                                                                              
     / = center this line                                                                                                        
     - = folding of blocks... hide lines from marked line to closing/opening block... example: if -> end if... etc               
     X = Expand/collapse INCLUDE inline... only usable on INCLUDE lines... the expanded INCLUDE lines are protected              
                                                                                                                                 

Singular Prefixes - with repeating honored

     H = Hide                                                                                                                    
   S + = Show                                                                                                                    
     D = Delete                                                                                                                  
   R " = Replicate                                                                                                               
     * = Comment (set/clear - if first char is * then comments are removed)                                                      
   < ( = Shift Line Left  (with protections to prevent loss of leading text)                                                     
   > ) = Shift Line Right (with protections to prevent loss of trailing text)     

PF Keys

 PF1   = Help
 PF2   = Split the current line at the cursor, or join the current line with the next line if cursor is at end-of-line.                                    
 PF3   = Quit the editor without saving
 PF4   = 
 PF5   = 
 PF6   = Cycle through the command stack. The command stack size defaults to 10 but can be reset via SET
 PF7   = Scroll up / use with M to scroll to top
 PF8   = Scroll down / use with M to scroll to bottom
 PF9   = Repeat previous command
          = shift+PF10 performs an ALL for the text under the cursor 
 PF11  = creates/appends the value under the cursor to a traceText upon the following line
 PF12  = saves current procedure and opens the INCLUDEd text under the cursor. If the cursor is not on an INCLUDE line, no action is taken.

User Written Extensions (SCMDs)

SoulEdit has a facility that allows anyone to add command-line extensions to the editor.

Starting with an example, "INFO" is a user-written command extension provided by Rocket Software. It provides information about any Model 204 system function in XML format via the LoadSystemMethodInfo method call. If you type info currenttimestring into the command line of SoulEdit, like this:

User-defined commands are entered on the command line.

You'll see the output of the LoadSystemMethodInfo call displayed in a scrollable screen, like this:

The output of commands appears in a scrollable screen. PF3 takes the user back to their in-progress editing session.

The editor extensions are created via SCMD procedures stored in a user-designated file. You can see how INFO works by looking at procedure SCMD\INFO in SIRIUS.

To create your own commands, specify a procfile file where they will live, via the PROFILE command and Custom Macros File. SoulEdit will scan this file for procedures prefixed with SCMD\ and will load them into memory at the beginning of the editing session. Copy SCMD\INFO into your Macros file with a new name and customize the run method to your liking.

Timed Backups

SoulEdit will take timed backups of the procedures you're editing - this feature can be turned on, on a user-by-user basis via the PROFILE command. Backups are take by default to the same file in which a procedure is being edited. Optionally a separate backup file can be specified, also via PROFILE.

Auditing

After running a procedure via the GO command from inside the editor, the user can then see the journal output of the run by typing AUDIT on the command line of the output display. AUDIT options are:

See also

SirPro

SirLib