IEDIT - Include Edit support
Auto Include files in a Multi-Edit (MEDIT) session
Multi-Edit is a method in SPFLite which allows multiple files to be edited in one tab. This can be very helpful when a program's source is maintained in multiple files for convenience, and are brought together at compile time by using the programming language's Include statement. There are times when you want to perform global changes to the source, and MEDIT provides that ability. More details on using MEDIT can be found HERE.
Using MEDIT itself requires you to somehow select all the modules which are to be loaded into the MEDIT session. This could involve multiple selections from a file-list. Or creating an FLIST containing the list of files. Both are somewhat awkward and do not dynamically reflect changes to the mixture of included files.
IEDIT is basically an automatic scanning front-end to assist in dynamically creating a list of all the Included files in program.
It can be invoked in two ways:
- As a Primary command, specifying the filename of the main program. This can also be invoked in File Manager by using the I or IEDIT line command. It will proceed to create a list of all Included files (including nested Include statements) and then invoke a normal MEDIT session containing all these files.
- As a Primary command in a tab which currently contains an EDIT or MEDIT session. It will scan the current session contents and locate included files (which are not currently loaded in the session) and add these files (if a current MEDIT session) or convert the current EDIT session to a MEDIT session and add the files.
Following either of the above 2 methods, IEDIT will save the list as a normal FLIST under the same name as the INCLUDE variable of the Profile for the main program. If the fie list already exists, it will be updated.
IEDIT must scan the main program, locate the specific compiler's Include statement and extract the filename(s). Then it must locate and scan each included file since that file may, itself, include other files. To do this it needs:
- To know the keyword that indicates the compiler's Include statement.
- To know what 'word' in the statement contains the filename.
- To know any 'exemption' strings which may help identify includes for system headers / include files.
- To know if any extraneous characters need to be removed (end-of-line markers, brackets, etc)
- To know how to identify in-line comment strings, so they can be properly ignored.
- To know 'where' to look for included files if located other than in the same folder as the main program.
So, you must provide this information somehow. When support for IEDIT is activated (via the Profile INCLUDE command), you specify a name (usually the same as the Profile name, but it can be anything). This name is used to build the names of 2 SET variables.
INCLPARSE.name - This provides the 1st 5 items listed above.
INCLPATHS.name - This provides non-default locations (folders) to search for included files.
To set things up for using the IEDIT command, issue a PROF EDIT xxx command for the Profile being used by the primary code module. On the first tab, change the INCLUDE value from NONE to your choice (we recommend using the actual Profile name).
Next, create the INCLPARSE.name SET entry as follows. Note: This SET symbol is mandatory to use IEDIT.
INCLPARSE.name
The format is:
"TRIG:trigger-string WORD:nn CMNT:comment-string DLMS:chars-to-blank SUPP:suppress-string"
We recommend enclosing the entire string in a single pair of quotes.
TRIG:trigger-string
The trigger-string specifies the text which indicates the statement is an INCLUDE type statement. e.g. COPY in COBOL, INCLUDE in C and many other languages. Before checking for this string any leading numeric fields are removed (i.e. line numbers) and leading spaces are ignored. Meaning the trigger-string must be the 1st item on the line.
WORD:nn
The word-number on the line which contains the filename to be included. The number 99 indicates the last word of the line. The specified word may be in quotes or unquoted. The number should be the word number after extraneous items like line-numbers, comments and unneeded delimiters have been removed.
CMNT:xx
The string (xx) which is used to indicate trailing line comments. For example ' in Powerbasic, // in C, /* etc. This is used to remove these comments from the line so that, for example, using WORD:99 to indicate the last word does not get confused.
DLMS:cc
cc is a list of characters which should be 'blanked' since they are not needed for parsing these statements. This may include things like ; to mark end-of-line, brackets, braces etc. These will be removed so as not to be included in any result strings.
SUPP:suppress-string
This string, if present, will cause this statement to be ignored. It is typically used to prevent Including large unneeded include files such as system header files from being included. The string could be things like ONCE, or the < angle braces used in C to indicate system libraries.
Some samples:
TRIG:COPY WORD:2 for COBOL
TRIG:#INCLUDE SUPP:ONCE CMNT:' WORD:99 for PowerBasic
TRIG:INCLUDE SUPP:< WORD:99 CMNT:// for C
Next, create the INCLPATHS.name SET entry as follows. Note: This SET symbol is optional and is only required when the included files may not all be located in the same folder as the main source program.
INCLPATHS.name
This symbol is simply a list of paths, separated by the | symbol (vertical bar). You may use an * to refer to the main module's folder location. The * may appear in any position, not necessarily the 1st. Agai, we recommend enclosing the entire statement in a single set of quotes.
e. g. The following statement:
INCLPATHS.myname = "*|C:\User\Me\Documents\|D:\Data\"
requests searching in the main module's folder + C:\User\Me\Documents + D:\Data\
At this point you should be "good to go".
The IEDIT command validates all this setup information and will report any errors to you. Since it is a front-end for MEDIT, if any errors occur, then nothing untoward happens. MEDIT is only invoked if all validation is correct. Simply correct the errors and retry.
This is new support and we may not yet have everything nailed down. Please report any and all problems and suggestions.