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 a subsystem definition along with at least a 640K server size (750K is safer as that provides room for future enhancements and the addition of user-written macros). RKTools installation contains more information about setting up the environment for SoulEdit.

SoulEdit is built into SirPro, one of the RKTools family of products from Rocket Software, and it can also be run as a standalone editor by setting up a separate application subsystem. At Rocket it runs as an application subsystem called SE, so it is executable from the command line. Details for setting up your own SoulEdit subsystem are also in the RKTools installation guide.

SoulEdit requires Model 204 version 7.5 or higher.

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 procedures. If SoulEdit is defined as a standalone subsystem (for example, SE), simply type the subsystem 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, where n specifies replacements per line. 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. A command without a 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 screen.
[IN fileName ]GET procName	Obtain the named procedure and insert into editor. You can use line command targeting.
SAVE [procName]	Save current editor content (optional save into a different named procedure, including temporary procedures).
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 to 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 through the command stack.
SET COMMAND STACK n	Defaults to 10; user may 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	Reinstate 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 and runs code in a daemon) RUN TERM (saves and 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]	Show the output from the last executed code or command line VAR/SHOW [SEQ] CHANGES.
SHOW CHANGES	Compares current content against procedure on file, and display in a scrollable form.
SHOW SEQ CHANGES	Do compare against SEQ version in same procedure file.
SCALE (toggles on/off)	|...+....1....+....2....+....3... etc.
PFKEYS (toggles on/off)	Show valid PF keys on 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 procedure name ends with .xsl.
HELP (PF1)	Display Help text.
VAR | VARS | VARIABLES	Show variable usage(counts) within scope.
SETUP | PROFILE	Set user editor preferences.
COLORS	Set user editor-color preferences.
.value	Bookmarks. For example: .foo as a line command bookmarks the line. .foo as a command focuses the bookmark.
CLEAR BOOKMARKS	Clear all bookmarks.
XCOMPARE | XC [EXACT | DEBLANK | COMPRESS]	XCompares current content against procedure on file; displays in a scrollable form.
XCOMPARE SEQ | XCS [EXACT | DEBLANK | COMPRESS]	Do XCompare against SEQ version in same procedure file (only works for SirLib users).
LAYOUT | MAP	List all class/subroutines/functions. PF4 focuses entry from listing.
INCLUDES command	Show hierarchy of all includes referenced within the current procedure.
PROTECT/UNPROTECT	Force the displayed content to be protected/unprotected.
BB | BLOCK WHERE	Add BB markers to the current "where" scope.
AUDIT [minutes | timestamp | LAST[RUN]]	Shows the journal lines for the user. It defaults to the last minute, unless an optional time is supplied.
SET FILE fileName	Sets the file name 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 character is *, comments are removed).
BB	Block boundaries. Used with editor commands: SORT, ALIGN, FORMAT. Optional for R, REPLACE.
FF	Format the specified block. Sets indenting to the number of spaces specified in the user profile.

Block prefixes, with repeating honored

For example, ""3 replicates the block three 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...
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 character is *, 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.
PF10	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 lets you add command-line extensions to the editor.

As an example, INFO is a user-written command-line extension provided by Rocket Software. It provides XML-formatted information about any Model 204 system method (output from a LoadSystemMethodInfo method call). If during an ordinary editing session you type info currenttimestring into the command line of SoulEdit:

User-defined command entered on command line

You see the output of the LoadSystemMethodInfo call displayed in a scrollable screen:

Pressing the PF3 key returns to the 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 the RKTools SIRIUS file.

To create your own commands, specify the procedure file where they will reside using the PROFILE command and Custom Macros File. SoulEdit scans this file for procedures prefixed with SCMD\ and loads 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 can take timed backups of the procedures you are editing. This feature can be enabled on a user-by-user basis with the PROFILE command. Backups are taken by default to the same file in which a procedure is being edited. Optionally a separate backup file can be specified, also using PROFILE.

Auditing

SoulEdit has an auditing feature to list entries from the current journal. AUDIT options are:

AUDIT	Lists the previous minute of the current journal.
AUDIT n	n is a numeric value from 1 to 999 indicating how many minutes of the journal to display.
AUDIT HH:MI[:SS.XX]	Lists the journal entries from the specified time. The colon (:) and period (.) are optional.
AUDIT LAST[ RUN]	After a GO or RUN command runs a procedure from inside SoulEdit, AUDIT LAST shows all the journal entries pertaining to the job run. It excludes anything not associated with the GO or RUN. In addition to the journal entries for the thread, it also includes all child threads spawned by the GO or RUN thread.

The colors used by SoulEdit for displaying journal entries are taken from your SIRSCAN profile. If you do not have a SIRSCAN profile, SIRSCAN default colors are used.

See also

• SirPro
• SirLib