Multi-Edit ships with support for many of the most popular programming languages including ADA, C/C++/C#, CMac, DBase/xBase/CLIPPER, Fortran, Java, JavaScript, Lisp, Lua, Matlab, Modula-2, Pascal, Perl, Php, Pl_Sql, Progress, Python, Rebol, Ruby, SciLab, TclTk, VBasic, Verilog, and Vhdl, and a few more. With a little work unsupported languages can easily be added. This document describes all of the language features Multi-Edit supports and how to go about adding these features for an unsupported language.

As Multi-Edit has evolved over the years, the features users want to change most frequently have been redesigned so that most of the changes could be made without resorting to writing macros and usually consist of filling in entries in dialogs. This idea has been applied to the language support also, but with the vast differences between programming languages there are still some areas where macros are required to provide the needed support.

A number of different language features are provided and can be added independent of each other. This means that when adding support for a new language, all of these features do not need to be implemented to reap the benefit of a particular feature. Thus the new language support can be added and tested in stages or not even support some features.

The following list of language features are provided in Multi-Edit and are shown from the easiest to implement to the hardest. Not all of these features will be covered in detail here since they are covered fairly well in the online help and the manual.

• Color syntax and keyword highlighting
• Code commenting and uncommenting
• Templates
• Compiler support and error processing
• Construct matching
• Smart indenting
• Function tagging
• Properties

The way Multi-Edit identifies different languages is through the filename extension. When a file with a specific extension is loaded, a check is done to see if that extension has been defined, and if it has, the language features associated with it are initialized. The Filename Extension Setup dialog is where the extension specific information is set up and the language associated with that extension is specified. It is also where the templates and compiler entries are associated with a given extension.

The language specific information is mostly defined in the Language Setup dialog accessed from the Tools | Customize dialog or the context menus. Templates are created and changed in the Edit Templates dialog accessed from the Tools | Customize dialog as well.

The ability to highlight keywords and syntax with color is a very powerful feature. This and the Code commenting feature is the easiest to add. All that is required to add this feature is to create a new language record by doing the following:

• From the main menu select Tools | Customize | General | Languages • Select the ‘Insert’ button and type in the name of the new language.

This will bring up the Language Setup dialog for the new language and the fields can then be filled in with the appropriate data. See the online help for more information about what each field should contain.

When the new language record has been defined, it must be associated with a set of file extensions. This is done as follows:

• From the main menu select Tools | Customize | General | Filename extensions • Select a defined extension and hit the ‘Edit’ button, or select the ‘Insert’ button and type a new set of file extensions
• Select the ”…“ button to the right of the “Language” field (top center) and select the newly defined language from the list.

This feature is automatically added as soon as the comment fields are filled out in the Language Setup dialog. See the online help manual for more information.

The template system provided with Multi-Edit allows adding abbreviations for common code fragments and language constructs that fully expand when the space key is pressed. Every language that Multi-Edit supports comes with what is called a 'template set' that contains templates specific for that language and is named after the language with an extension of .TPT (i.e., C.TPT, PASCAL.TPT and JAVA.TPT). These template set files are stored under the /MULTI-EDIT/CONFIG subdirectory.

To edit or add new templates do the following:

From the main menu select Tools | Edit templates

This will open the Edit Template dialog. This is where new templates are added and existing templates are modified. The fields in this dialog allow each template to be modified with specifications as to what will be inserted and when it will be expanded. See the online help manual for more details about all of the fields in the Edit Template dialog.

A language template set is specified in the “Template” field of the Edit Filename Extension Setup dialog for each filename extension. You can set the template set for a filename extension by selecting Tools | Customize | General | Filename Extensions, select your file extension, click ‘Edit’, and in the resulting Edit Filename Extension Setup dialog click the ”…“ button next to the Template field (upper right). Only one language template can be assigned to an extension; however, by adding template set names separated by semicolons in the “Addon templates” field (lower right), it is possible to allow additional templates to be added to the extension. This is how the Windows API template set would be added.

There are three classes of templates sets: language templates, global templates, and other templates. All global templates are stored in the file named GLOBAL.TPT. Other templates are templates that may not be specific to any language, such as templates for the Win32 APIs or templates that are specific to a vendor's language product such as Borland C++ runtime libraries. Any number of these template sets may be used and are set up by entering their names, separated by semicolons, in the “Addon templates” field of any Edit Filename Extension Setup dialog (lower right).

Also, while in the Edit Filename Extension Setup dialog be sure to check the “Auto-template Expansion” option to enable template expansion for the specified filename extension.

Construct matching provides the ability to start with the cursor on a opening or closing construct, i.e. (), {} or begin end, and find (optionally highlighting) the matching construct. This feature can be implemented in two ways, with a macro that does the searching, or through the new general purpose LangDoMatch routine.

The macro method requires that a macro be written to locate and match all supported constructs. This is the older method and will not be discussed in detail here.

The Match Language Structure command enables locating a language construct, such as ( ), { }, and begin/end, matching the one under the cursor. It is also used for quickly navigating through a source file and to check that the code is correctly formed.

For the matching to function correctly the following must be set in the specific Language Setup dialog:

1. The “Init:“ Macros field should contain a macro command line for the language specific Init macro.
2. The “Match:“ Macros field should contain a macro command line for the language specific Match macro.
3. The “Config:“ Macros field should contain a macro command line for showing the language specific Properties Setup dialog.

Below is a general overview of how the Match Language Structure feature is implemented.

Whenever Multi-Edit loads a file, it runs the ExtSetup macro, which locates the language record for the current extension and executes the specified Init macro. This Init macro is responsible for setting three global variables that contain the data that specifies the constructs that can be matched. The first global specifies three sets of delimiter characters, ones that can appear before the construct, ones that can appear after a construct and a delimiter character used to separate construct names that are defined together in one record. The other two global variables contain the patterns and search parameters, one to specify the opening constructs and the other to specify the closing constructs.

Now when the Match Language Structure routine is run either from a key, toolbar or menu, command (i.e. the Language^Match macro), the routine will run the macro specified in the “Match:” Macros field of the specific Language Setup dialog. This is usually a macro that calls the LangDoMatch routine with the language prefix specified /LP= and possibly some other parameters to specify if highlighting is to be done or not. This macro first calls a language specific XxxGetMatchPat macro, which is responsible for locating and returning a pattern to match.

This macro can be as simple as to only check the cursor position and returning the pattern, or as complex as to scan the line searching for one of a number of supported patterns. When this macro returns, the LangDoMatch macro uses the found pattern to scan first the opening construct pattern data global and then the closing construct pattern global for a pattern match. If a matching pattern is found, the search parameters from the found record of the appropriate global pattern data are set. Then a search is stated, a forward search for a match in the opening pattern data global or a backward search for a match in the closing global pattern data. The search continues until either a match or no more matches are found. Once a match is found, the LangDoMatch macro will check the search parameters to see if it needs to continue searching or to finish by highlighting the text if the highlight option is enabled and both the opening and closing construct can be shown in the window. When the pattern data is correctly set up, nested constructs are skipped so that the correct ending construct is found.

The new method of adding construct matching is to define a set of global variables that define the patterns to match and then using the general purpose LangDoMatch macro to do the matching. To implement this, the following steps must be completed.

1. Set up the special pattern global variable.
2. Write a special _xGetMatchPat( ) macro.
3. Write an xMatch macro that calls the LangDoMatch macro passing the correct parameters depending upon the language Properties.
4. Set up the Init:” and “Match:” macro fields in the Language Setup dialog to point to the correct macros.

To set up the special pattern global variables currently requires a xInitMatch macro be written, where x is the language prefix, usually the first three letters of the language support macro filename. Eventually, we hope to move this into a dialog and save them in a DB file so that it could be more easily updated.

There are three global variables that must be set up and are shown below using C as the example. See the CInitMatch macro in C.S for more details.

!CMatchExtra - Characters used to specify the start and end of words.

This global string variable consists of three parts starting with the \x7F character shown below as %
%B=str where str is a list of all of the characters that can precede a construct word.
%E=str where str is a list of all of the characters that can come after a construct word.
%D=char where char is a character that is used to separate multiple construct patterns. The default is to use the space character as the delimiter but should be changed to something else (like “|”) for languages such as Ada and Visual Basic that use double word constructs (e.g. “END IF”, “EXIT FOR”).

!CMatchBegPat - Beginning construct patterns to match

This global string variable consists of a series of records using \x7F as the delimiter character, shown below as %, and each record can consists of up to seven fields.

%Str1%Str2… where Str# is the character string of a beginning construct, i.e. IF or (
%F= Flag where Flag is an optional bit flag used to control how the match routine will work for matching the current construct. See Language.sh for the _mcf_Xxxx flag values.

• _mcf_StrOnly: This flag when set, will cause the matching routine to exactly match the construct ignoring the characters before and after it.
• _mcf_SkipMid: This flag when set, changes the meaning of the %M= strings to cause them to be skipped when searching for a match. The %I= field should be used to specify patterns to ignore when a middle pattern is also required.
• _mcf_ContMatch: This flag when set, will cause matching to continue when the %C= expression is found after a %B= or %E= string was located. When this flag is reset, matching will end if the %C= expression is not found after a %B= or %E= string was located.
• _mcf_AcceptOnMatch: This option when set will cause the matcher to stop searching for a matching construct when a match to the %X= string is found. This is used in the Fortran support to locate DO# constructs in the Watcom F77 compiler extension.
• _mcf_IndentMatch: This is used to find the next/previous text that is at the same indent level as the current line. This was added to provide support for Python files.

%B= Str1 Str2 … where Str# is a %D=char delimited, before and after, list of beginning construct patterns, i.e. IF or (

%M= Str1 Str2 … where Str# is a %D=char delimited, before and after, list of middle construct patterns, i.e. ELSE or blank for (matching. If the %F= flag has the _mcf_SkipMid bit set then the match routine will cause a found string matching one of the %M= strings to be skipped.

%E= Str1 Str2 … where Str# is a %D=char delimited, before and after, list of ending construct patterns, i.e. ENDIF or ).

%X=XStr where XStr is a UNIX style regular expression that will match any of the B, M or E string, i.e. (IF)|(ELSE)|(ENDIF) or [\(\)].

%I=IStr where IStr is an optional %D=char delimited, before and after, list of construct patterns to ignore when doing a match. See VBasic.s or Ada.s for an example of how this would be used.

%C=CStr where CStr is an optional UNIX style regular expression to search for after a %B= or %E= match was found. What happens when a match is found is determined by the value of the _mcf_ContMatch bit of the %F= flag. See VBasic.s for an example of how this would be used.

% The ending delimiter is required

!CMatchEndPat - Ending construct patterns to match

This global string variable serves the same functions as the !CMatchBegPat except that it is used to specify ending patterns.

%Str1%Str2… where Str# is the character string of a ending construct, i.e. ENDIF or )

%F= Flag where Flag is an optional bit flag used to control how the match routine will work for matching the current construct. Used exactly as described above.

%B= Str1 Str2 … where Str# is a %D=char delimited, before and after, list of ending construct patterns, i.e. ENDIF or ).

%M= Str1 Str2 … where Str# is an optional %D=char delimited, before and after, list of middle construct patterns, i.e. ELSE or blank for (matching. If the %F= flag has the _mcf_SkipMid bit set then the match routine will cause a found string matching one of the %M= strings to be skipped.

%E= Str1 Str2 … where Str# is a space delimited, before and after, list of ending construct patterns, i.e. IF or (

%X=XStr where XStr is a UNIX style regular expression that will match any of the B or E string, i.e. (IF)|(ENDIF) or [\(\)].

%I=IStr where IStr is an optional %D=char delimited, before and after, list of construct patterns to ignore when doing a match. See VBasic.s or Ada.s for an example of how this would be used.

%C=CStr where CStr is an optional UNIX style regular expression to search for after a %B= or %E= match was found. What happens when a match is found is determined by the value of the _mcf_ContMatch bit of the %F= flag. See VBasic.s for an example of how this would be used.

% The ending delimiter is required

Before we go into more detail, lets explain how the matching feature works. When the match routine is run either from a key, toolbar or menu, the Match macro looks in the language record specified by the current file's extension for the macro in the Match field. If an entry is found, the specified macro is executed. This is usually a macro that calls the LangDoMatch routine with the language prefix specified /LP= and possibly some other parameters to specify if highlighting is to be done or not.

The first thing that LangDoMatch does is call a special macro for the specified language called _xGetMatchPat, x being the language prefix passed as the /LP= parameter. This macro is to provide special character processing for the specific language. This can be as simple as setting Return_Str to "" and returning (i.e. no special processing), or checking if the current character is one of the special characters and returning the character surrounded by the \x7F delimiters characters, or searching for special characters on the current line and then returning the delimited character. This macro is usually used to process single character and possible double characters (such as comment characters /*) but can also be used to reposition the cursor on another word that is supported. See Fortran.s or Ada.s for an example of the word-repositioning feature. The main LangDoMatch will then process whole words if the _xGetMatchPat returns "" or the special character cannot be matched.

If the _xGetMatchPat returns a pattern then the LangDoMatch routine searches the special MatchBegPat global variable for a beginning pattern match. If one is found, it will parse out the fields of that record. It will then use the specified regular expression to do a forward search. When a match is found, the found string is compared to the beginning, middle and end patterns of the specified record. What happens next depends upon which string the found string is found in. If it is found in the begin string a match count is incremented by one, since a nested construct is found and the search is continued. If the end string contains the found pattern then the count is decremented by one and will exit the search loop when it reaches 0, i.e. the ending construct was found. If the middle string contains the found string then the search is repeated unless the count is at 1, i.e. still inside the first construct and thus a middle construct match.

If the original pattern was not found in the MatchBegPat global variable, then the MatchEndPat global is “search” and the same process as above happens except for searching backwards for matching patterns.

If the _xGetMatchPat returns ”” or the pattern cannot be matched, the word the cursor is sitting on is read using the beginning and end word string to delimit the word. The above process is then repeated with the word instead of a character pattern. Thus if the new language is to only support words then the _xGetMatchpat can always return ””.

When a matching construct is found it will be highlighted if the appropriate parameters are passed. See the LangDoMatch macro in Language.s for
more details.

After the xInit, _xGetMatchPat and xMatch macros are written, the xInit macro needs to be specified in the “Init:” macro field and the xMatch macro in the “Match:” field of the Language Setup dialog.

Smart indenting is the ability to position the cursor in the correct column to continue typing code after the Enter key is pressed. Since this feature is very language dependent, a macro must be written which, when called by the CR system macro, should check the context of the cursor and reposition the cursor on the next line in the correct position.

We have developed two different types of routines that should handle most languages and they can be seen in the C.s and Pascal.s files. The C.s macro, CIndent, checks the line ending characters of previous lines to determine the indent level of the next line, while the Pascal.s macro, PasIndent, checks the first word on previous lines to do likewise.

To implement the indent macro for the new language, determine which type of routine the new language is most like and start with a copy of one of the supplied macros and change it to implement the specific cases.

When you have the macro written and tested, it is installed by doing the following:

1. From the main menu select Tools | Customize | Filename extensions 2. Select the specific extensions and hit the ‘Edit’ button.
3. Set Indent style to Smart.
4. Exit dialog by hitting OK 5. From the main menu select Tools | Customize | Languages 6. Select the new language entry and hit the ‘Edit’ button.
7. Enter the macro name in the Indent macros field, i.e. C^CIndent

This feature requires a macro be written to scan the source file for the function declaration and/or variable names and writes them to a tag file in a specific format. Pretty much all you have to do is come up with a regular expression that will locate all the function declarations you want to tag. This will not be covered in this document since this is rather involved. We hope to eventually make this easier to add in the future.

The properties feature is not really a separate feature in itself, but is used to support some of the other features. The ‘Formatting/Config’ button in the Language Setup dialog, when pressed, will run the macro specified in the “Config:” macro field. This macro should display a dialog that presents the user with configuration options that are supported in the new language support. Examples of this can be seen in the C and Pascal support where the indent style and auto highlighting of closing ')' can be enabled or changed.

If the new language is to support properties then a set of macros needs to be written to support them. These macros are described below using C as the example. Replace the leading C with the first three characters from the name of the new language macro file and make the needed changes for the specific properties.

void CSetProperties(
      str GStr    = Parse_Str( "/GSTR=", MParm_Str ),
      str Parameter = MParm_Str
)
/************************************************************
Function: Set C and CMac specific properties.  Should only be run by the LangSetProperties macro.

Entry   : str GStr - Name of global string containing properties (/GSTR=)
            str ParmStr  - Misc parameters
              /L=str      - Language name to show on title bar

  Exit    : None

**************************************************************( ldh )***/
int CGetProperties( struct tCProperties rCP )
/*************************************************************
  Function: Get the specific language properties for the current file.
  Entry   : struct rCP   - A structure to fill with the properties.
  Exit    : int
              True         - Properties fill from Db
              False        - Properties set to internal defaults

**********************************************************( ldh )***/
void CIndentTmp(
      str Set  = Parse_Str( "/S=", MParm_Str ),
      str Name = Parse_Str( "/N=", MParm_Str )
)
/********************************************************************
  Function: Insert the indent style template Name from the template set.
  Entry   : str Set      - The template set
            str Name     - The template name
  Exit    : None
****************************************************************( ldh )***/

Multi-Edit now makes use of Property Strings allowing language specific functionality to be added without having to add more and more fields. An example of this can be seen in the HTML language/extension setup where Property Strings are used to define the embedded scripting language.
Property Strings may be assigned numeric or string values. When a file is loaded, first the language Property Strings are set, followed by the extension Property Strings. Therefore, in the case of duplicate Property String settings, the extension Property Strings will override the language Property Strings.

Property Strings are configured under Tools | Customize | General | Filename Extensions | Edit – ‘Property Strings’, or Tools | Customize | General | Languages | Edit – ‘Property Strings’. The following settings are currently accepted:

• SCRIPT=1: Process embedded scripts with the <SCRIPT> tag
• SCRIPT_DEF=language: The default language to use for the SCRIPT tag. If this is not defined, it defaults to JavaScript.
• STYLE=1: Process embedded style sheets with the <STYLE> tag
• STYLE_DEF = language: The default language to use for the STYLE tag. If this is not defined, it defaults to CSS • ASP=1: Process ASP code. This enables the use of <% %> style tags.
• ASP_DEF=language: The default language to use for ASP tags. If this is not defined, it defaults to VBSCRIPT.
• COLDFUSION=1: Process cold fusion scripts (CFSCRIPT and CFQUERY).
• PHP=1: Process embedded PHP. This enables the use of <? ?> style tags.

After you've created a new entry in Tools | Customize | General | Languages for your particular language, it's time to associate your language with a filename extension. Go to Tools | Customize | Filename Extensions and click ‘Insert’ to get a new Edit Filename Extension Setup dialog. In the 'Extension(s):' field enter the new filename extension(s). Multiple extensions are separated by a space. Do not include the dot before the extension. Then go to the 'Language:' field (top middle) and click the ”…“ button to the right of that field. Select the new language you just added support for. And you're done. Now when Multi-Edit loads a file with that extension it will associate that language with it and provide all the syntax highlighting and language support features available for that language. You can customize the other fields of the dialog to your liking. See the Filename Extension Specific Customization topic in The Multi-Edit Interface chapter of this manual for information on setting the other options in this dialog.

At present, TipWin supports several languages, retrieving the necessary information from several sources: C and C++ from MeTags and BSC databases; CMac from MeTags and a database of kernel and import functions; Delphi/Pascal from MeTags; and Java, using experimental MeTags support. Since TipWin's functionality is dependent on the quality of data available to it, you should create tag files and, where applicable, BSC browse databases, and keep them as up-to-date as is reasonable for your project by incrementally updating files that change. For the truly ambitious, it's always possible to create function databases from scratch, using the CMac database, CMac.fct as a model.

Multi-Edit is designed to support any compiler, and you can easily add your own compiler support. If you experience any trouble adding support for your compiler, please feel free to contact our Technical Support by email at support@multieditsoftware.com. You can also ask for help on our Support forum at our web site.

Each filename extension may have any number of compiler/program interfaces associated with it. Each compiler/program interface contains its own command line and configuration. Thus you might have multiple compilers, linkers, and debuggers set up for .C extensions. You might have a grammar analyzer set up for .DOC files. When invoked via Tools | Execute Compiler, a list box appears containing a list of compilers available for the active window's filename extension.

The Compiler/Program Setup dialog

To view the Compiler/Program Setup dialog, go to Tools | Customize | General, and press the ‘Filename Extensions’ button to display a standard Multi-Edit list box with a list of existing filename extensions. Select the filename extension from the list and press the 'Edit' button. In the resulting Edit Filename Extension Setup dialog box press the ‘Compiler/Program setup’ button (lower right). This brings up the Compiler/Program list box containing existing Compiler/Program configurations.

Buttons along the side of the list box allow you to Edit, Insert, Delete, or Copy a selection. You can also rearrange the list by moving them up and down in the menu list. The 'Search' and 'Again' buttons allow you to quickly find the list member you are looking for.

Select an item in the list and press the ‘Edit’ button, or just click the ‘Insert’ button, to display the Compiler/Program Setup dialog box with the following fields for editing:

Description: Enter a name or descriptive phrase for the compiler. Your entry will appear in the Compiler/Program Setup list box.

Command: Enter the command-line just as you would if you were running this compiler from the DOS prompt or the Windows Start | Run… prompt. The only exception to this is that you may use Multi-Edit Metacommands to tell the compiler what file you want compiled.

Working Directory: This is an important field! The working directory, as defined in compiler setups, is used by Multi-Edit while executing your compiler. The working directory is the current directory while your compiler is executing. For example, if your working directory is D:\MYPROJ, imagine yourself at the DOS prompt manually typing your compiler command line in with D:\MYPROJ as the current directory.

There are four different working directory settings:

• Current: Uses the current working directory (as defined in either the Session Manager, or in the File | Open dialog) as the working directory for the compiler.
• Source File: Uses the path to the current source file as the working directory.
• Program: Uses the path to the compiler as the working directory.
• Specified: Allows you to specify the working directory. For this option, enter the working directory in the text field provided.

You may click the ”…“ button to the right of the field to get a Select Directory prompt.

Reset Original Line Number:

• Special (default): When this option is specified the following string field can contain a macro command line that will be run before and after the compile is run. This macro is responsible for calling the macro to reset the original line numbers. When the macro is run after the compile, it is passed the ”/POST=1” parameter. If there is no macro command line specified, then the original line numbers are not reset.
• Current: This option causes the original line numbers for only the current file to be reset before a compile.
• Project: This option causes the original line numbers for all files specified in the current project that are loaded in Multi-Edit to be reset before a compile.
• All Files: This option causes all loaded files to have their original line numbers reset before a compile.

Program Type

Click the ”…“ button to the right of this field to bring up the Compiler/Program Type dialog. currently supported compilers. Multi-Edit uses the selection you make here to correctly parse the compiler errors out of the error file your compiler generates. If you don't see your compiler or are using a newer version of a compiler that isn't supported, you can insert your own entry.

EXE Type

This drop-down list box is used to select the type of compiler executable that has been specified in the Command entry. This is used by Multi-Edit to determine how to start the compiler running.

• Auto Detect: This option will cause Multi-Edit to run the IdExe macro to determine the executable type of the compiler. This is the default and will work for most cases, but sometimes the executable will not be identified correctly and thus one of the other options can be used to force the correct compiler invocation.
• DOS: Selecting this option will cause the compiler to be run as a DOS program where the DOSEXEC program is used to start the compiler and capture its output to an error file.
• Windows: Selecting this option will cause the compiler to run as a Windows program.
• OS/2: Selecting this option will cause the compiler to be run as an OS/2 character mode compiler where the OS2EXEC program is used to start the compiler and to capture its output to an error file.
• Win32 Console: Selecting this option will cause the compiler to run as a Win32 Console application.
• Macro: The command line specifies a Multi-Edit macro to be run.
• Remote Telnet: The compiler command will be run via a telnet connection as documented in the Compiling on a remote computer section below.

Show

• Normal: The compiler execution window will appear in the default position and size.
• Minimized: The compiler execution window will appear minimized.
• Maximized: The compiler execution window will start full screen.
• Hide: When the “Hide” option is selected, the compiler execution window isn't even shown. (Also, if the compiler execution window is shown, the output from the compiler can be hidden by setting the Tools | Customize | Program execution – “No output in window” option.)

Options

The following check box options are used to configure the operation of the compile macro.

• Save All Files: Enable this option to cause every file that has changed and not been saved to be saved to disk before the compiler/program is started.
• Reload File: If you expect the compiler/program to modify the current file, then enable this option to have Multi-Edit reload the file after the compiler/program has finished.
• No stdout capture: Enable this option if you do not want to have the standard output stream redirected to the Multi-Edit error file.
• No stderr capture: Enable this option if you do not want to have the standard error output stream redirected to the Multi-Edit error file. If you disable both Stdout and Stderr, then the program will be run directly instead of using one of the redirection programs, i.e. DOSEXEC.EXE
• No error processing: Enable this option to have Multi-Edit not process errors after the compiler/program has finished. This would be enabled for compiler/programs that are not currently supported.
• Command line prompt: Enable this option when you want to have the command line come up in a prompt before you run a compiler. This allows you to make any last minute adjustment to the command line, such as adding or deleting parameters.
• Use cmd processor: Enable this option when you want the command processor to be run, which will start the compiler running. This would be enabled when the command line specifies the compiler/program as a Batch file.
• Run in background: Enable this option to cause Multi-Edit to start the compiler/program running and allow you to continue editing or processing errors from a previous compile while the current compile is being run in the background. If this option is enabled when a compiler is started, check mark will appear next to the task number when that task has completed. By double clicking on any task that has finished, you can start the error processing for that compile.
• Auto run background process: When this option is checked and the Run in background option is also checked for the compiler, the error processing routine will be automatically run when the compiler completes. When not checked, the user will have to double click on the compiler in View | Tasks to process the errors of the compile.
• Load error file only: Enable this option to cause Multi-Edit to load the error file specified in the Command field without actually starting a compiler/program. This allows a user to compile a program outside of Multi-Edit and then load and process the errors from the captured error file. The Program type still needs to be configured for this option to function correctly.

For users who want to set up a compiler type that is not currently supported by Multi-Edit, we have added extra functionality to the Compiler Parsing feature.

To set up your own compiler error-parsing support, you need to create your own Compiler/Program Type. The Compiler/Program Type Setup menu is a bit tricky to get to. Follow these steps:

1. Tools | Customize | Filename Extensions. Select a file extension, click ‘Edit’.
2. In the resulting Edit Filename Extension Setup dialog, click ‘Compiler/Program Setup’ (lower right).
3. In the resulting Compiler/Program dialog click ‘Insert’.
4. In the resulting Compiler/Program Setup dialog, find the Program Type field (left side half way down), and click the '…' button to the right of that field.
5. In the resulting Compiler/Program Type dialog, click ‘Insert’. This brings you to the Compiler/Program Type Setup dialog.

The Compiler/Program Type Setup dialog box has the following fields for editing:

Type:

This string field contains a description of the compiler or program that is being setup. This is what is shown in the Compiler/Program Type dialog.

Defaults

• Exe File: This string field is used to enter the default file name of the compiler executable to run. This field can contain the full path of the executable file as well.

• Release Parms: This string field is used to enter the default command line parameters that you would use when running the compiler to produce a release version of the compiled code.

• Develop Parms: This string field is used to store the default command line parameters that you would use when running the compiler when developing your programs.

Compile Macros

These options are used to expand the default behavior of the compile macro.

• Pre: This string field is used to enter the name of an optional macro that you want to run before the actual compiler executable is started.
• Post: This string field is used to enter the name of an optional macro that you want to run after the compiler executable has finished, but before the error processing is done. This macro should return with the following:
• Return_Int - False. Continue and run error processing macro.
• Return_Int - True. Continue but not run the error processing macro.
• Return_Str - The string to display on the message line when Return_Int = True

Error (Processing)

Error-processing within Multi-Edit can be accomplished by the use of a macro, or regular expressions which is the suggested method.

•File: This string field is used to enter an optional error file name. This would be set for compilers that generate their own error files. When a file name is specified in this entry, the Compile macro will not capture the output to its temporary error file and will instead use specified file name when the process error macro is run.
•Macro: This string field is used to enter an optional error macro that will be called to search for errors in the error file. When an error macro is specified here the main error processing macro will try to run this string as a macro to find the errors.

Multi-Edit 2008 allows the compiler error processing code to not show an empty file when an error is located in a file that doesn't exist. There are two integer global variables that can be set to 1 in Startup.cfg which control this. They are:

!CmpErrorNoFile: When set will cause the empty window to be removed.
!CmpErrorNoDlg: When set will disable the File not found dialog. (Only used when !CmpErrorNoFile is also set)

Regular Expressions

These fields are used to specify regular expressions that the built in error processing macro will use to try to locate error messages in the captured error file. This is the preferred way of processing errors and can easily be updated by the user to provide new compiler/program types. See Error Parsing Expressions for more details.

• Search: This string field is used to enter a regular expression that will be used to search the captured error file for a line that contains an error message. This string is a UNIX style regular expression and should be such that it will match the complete line of the error message. Thus it should always start with the ^ (beginning of line) character and end with the $ (end of line) character. This string can contain regular expression aliases, which make creating these expressions much easier to understand.
• Replace: This string field is used to enter a replacement string for extracting the specific error information from the error message line located in the Search field.
• Extra: This string field is used to enter additional regular expression strings to be used to locate error information that is not located in the error message. For example, this could be used to locate the column the error occurred on for compilers that show the error message on one line, the line with the error on the next line and following that a ^ character to show the column in which the error was found.

Setting up error processing regular expression strings in the Compiler/Program Type Setup dialog is reviewed in this section. We feel this is the best and easiest way to process errors in the captured error file because the user can update these fields and add support for their own compilers with out needing to write a macro to do so.

To use this feature, the Search and Replace strings, at a minimum, must be defined. This is usually sufficient to handle most compilers. The Extra field is provided so built-in error processing macros can do further searching to locate additional error information for those compilers that do not provide all of the needed information on a single line.

To process errors, the built-in error macro uses the text in the Search string to scan the captured error file in an attempt to find a match for a line that contains an error message. There are four items that the error processing macro is looking for to be able to intelligently show you where the error occurred:

1. File Name (Optional): The file name of the file in which the error occurred. This is needed to be able to locate the file that has the error, so that Multi-Edit can load it and position the cursor on the line that contains the error. Not all compilers show the file name of the file that the error was in, so the default is the name of the file that was in the current window when the compile was started.

2. Line Number (Optional): The line number on which the error occurred. If the line number is located, the cursor will be positioned at the new line; otherwise, the cursor will remain where it was when the compiler started.

3. Column Number (Optional): The column number in which the error occurred. When provided, Multi-Edit will position the cursor on this column, which is assumed where the error occurred. Otherwise the cursor will be positioned to column 1.

4. Error Message: The located error message. This will be what is shown on the status line when an error is located.
The Search string is a UNIX style regular expression that should match complete lines that contain error messages. Thus it should always start with the ^ character and end with a $ character. You can use regular expression aliases in this string to make them more readable, which will be translated before the search is done. When designing this string, you should use the grouping characters ”(” and ”)” to group the expression into groups that match the file name, line number, column number, and the error message so that they can be extracted from the line and used to show the source line where the error occurred.

The extraction of the above information is done by using the Replace string to do a regular expression replace of the located error line, read the replaced line in to a variable and then change the error line back to what it was originally. Then the contents of the replaced line are parsed for one or more of the following strings to extract the provided information. The replacement string should contain one or more of the following where \# is the number of the associated replacement group.

/F=\#

When parsed this will return the file name of the file with the error.

/L=\#

This will parse to the line number on which the error occurred.

/C=\#

This will parse to the column number at which the error occurred.

/M=\#

When parsed this will be the located error message. There can be multiple \# with other text so that you can format the message the way you desire.

The Extra string is used to locate additional information that does not appear on the same line as the error message. This string will actually consist of multiple parts. The first part is used to specify the type of information for which to search. Specifying more than one search type allows for searching more than once piece of information. All of the possible values for the search type string are shown below.

/X=x

The search type x is one or more of the following letters. These specify the type of information that will be searched for.

Following the search type string are sets of three more strings, one set for each specified type. These strings specify the direction in which the search will be done, a search string and a replace string. The search and replace strings are defined just like the above search and replace strings but are used to find another line that contains the information specified. In these strings x is replaced with one of the type letters shown above.

/xP=str

The value of str would be one of the following listed below and is the direction the search should take to locate a new line. This direction is from the current position of the cursor, which is usually the last found position. The # is replaced by a number specifying the number of lines to search to try to locate a matching line. The number 0 will be used to cause the search to have no limit, i.e. search to start of file or end of file. Leaving # blank will be the same as entering a 0.

/xS=str

The search string 'str' is a UNIX style regular expression that is designed to match a complete line that contains the information specified by x.

/xR=str

The replace string 'str' is a Unix style regular expression replacement string used to replace the found string to allow for easy parsing to get the specified information. For more information about this string, see the Replace string documentation above.

Examples

Below are some examples of how to set up the Search and Replace strings.

CMac compiler

When the CMac compiler finds an error it will output an error message in the following format:

Filename(line num, col num): ERROR errornum: message

Example:

LANGUAGE.S(92,22): ERROR 1: Syntax Error: 'THIN”

The Search and Replace strings to locate this message in the error file would then be entered as follows:

Search:

 	^(<p>)\((<i>),<b0>(<i>)\): (Error <i>:.#)$ 

Replace:

 	/F=\0/L=\3/C=\4/M=\5  

Following is the description of each element of the Search string:

^ - Match the beginning of a line.
(<p>) - Match group 0 start, followed by an Alias for a filename with full path, followed by group 0 end. This will match filename in the error message line. ( <p> is an alias. See Using Regular Expressions in the Working in Multi-Edit chapter.)
\( - Match a ( character. The \ is needed to make the ( match literally because the ( character by itself is used to start a group.
(<I>) - Match group 3 start, followed by an Alias for an integer, followed by group 3 end. This will match line num in the error message line.

, - Match a comma.
<b0> - Alias to match 0 or more blanks (spaces or tabs).
(<I>) - Match group 4 start, Alias to match an integer, Match group 4 end. This will match column num in the error message line.
\): - Match a ) followed by a : and then a space. The \ is needed in front of the ) because the ) character is normally the end group character.
(Error <i>: - Match group 5 start followed by the word Error followed by a space followed by an integer alias followed by a :.
.#) - Match any character one or more times, followed by group 5 end. This and the line before will match Error errornum: message in the error message line.
$ - Match end of line.

The description of the Replace string is as follows:

So for the error line with LANGUAGE.S on as shown above, the replace string would be replaced as

 /F=LANGUAGE.S/L=92/C=22/M=ERROR 1: Syntax Error: 'THIN' 

Borland Pascal 7.0

When the Borland Pascal compiler finds an error it will output an error message in the following format.

filename(line num): Error errornum: message line with error;
       ^ 
-or-

filename(line num): Warning warningnum: message line with warning;
       ^ 

Example:
D:\ERROR.PAS(7): Error 3: Unknown identifier.
j := 0;
^

The Search and Replace strings to locate this message in the error file would then be entered as follows:

Search:

 	^(<p>)\((<i>)\): ((Error)|(Warning) <i>:.+)$  

Replace:

 	 /F=\0/L=\3/M=\4 

Extra:

  	/X=C/CP=D2/CS=^(<b0>\^)$/CR=//C=\0  

Following is the description of each element of the Search string.

^ - Match the beginning of a line.
(<p>) - Match group 0 start, followed by an Alias for a filename with full path, followed by group 0 end. This will match filename in the error message line.
\( - Match a ( character. The \ is needed to make the ( match literally because the ( character by itself it is used to start a group.
(<I>) - Match group 3 start followed by an Alias for an integer followed by group 3 end. This will match line num in the error message line.

\): - Match a ) followed by a : and then a space. The \ is needed in front of the ) because the ) character is normally the end group character.
((Error)|(Warning) <i>: - Match group 4 start followed by either Error or Warning followed by a space followed by an integer alias followed by :.
.#) - Match any character one or more times, followed by group 5 end. This and the line before will match Error errornum: message in the error message line.
$ - Match end of line.

The description of the Replace string is as follows:

Notice that the column number is not in the found string. Since the column is marked with the ^ character two lines below the found message string an Extra string will be used to locate this line and determine the column the error was located on.

The meaning of the Extra string is shown below.

/X=C - Do an extended search for a line specifying the column number.
/CP=D2 - Search for the column message down 2 lines.
/CS=^(<b0>\^)$ - Match start of line followed by (<b0>\^) group 0 start followed by 0 or more blanks or tabs followed by the ^ character followed by group 0 end followed by $ match end of line.
/CR=//C=\0 - The replacement string will return the column as a string containing the ^ character.

The compiler support in Multi-Edit is very configurable and can allow users to do many things. In the Compiler Setup dialog there is a field “Program Type” which brings up the “Compiler/Program Type Setup” dialog where the data needed to do error processing for different compilers is set. (See the Adding Error Processing section above for instructions on how to get to this dialog.) In this dialog are two “Compile Macros” fields that allow the user to specify Pre and Post compile macros, i.e. macros that can be run before and after the compiler/program is run. By using these fields with a couple of system macros, the user can create a filter program, i.e. a program that takes a file as input, does something to the text and then write its output to stdout and/or stderr.

The two system macros that can be used to run “filter” programs are provided in the Compile.s file and are called PreCmpFilter and PostCmpFilter. See the Compile.s source file for more details about each macro.

The PreCmpFilter macro checks the current window for a marked block and copies the contents of it to a file named “FilterIn.tmp” located in the temporary directory. It also sets a global string variable, !FilterFile, with the full filename of this file. When this macro is specified in the “Pre Compile Macro” field of the “Compiler/Program Type Setup” dialog, it will be run before the compiler program is started so a compiler command line can use the metacommand <~!FilterFile> to pass this filename to the compiler.

The PostCmpFilter macro loads the captured output file that the compiler macro is currently using and copies the contents of it to the current window at the current cursor position overwriting a marked block if one is marked. Thus when this macro is specified in the “Post Compile Macro” field of the Compiler/Program Type Setup dialog, it will be run right after the compiler program has completed, allowing the output of a program to be pasted into the current file.

When both of these macros are specified in the Pre/Post Compiler Macros fields a filter program is created. But each can be used by itself to create other kinds of functions. If the PreCmpFilter macro is used by itself, then a marked block of text can be passed to a program but not be replaced when the program is complete. On the other hand, if only the PostCmpFilter macro is used, then the output of a program can be inserted into the current window without sending any text to the program.

Multi-Edit 2008 comes with a “Filter” Program Type record already defined which will meet most needs, but additional Program Type entries can be created to handle different things. Below are examples of how to set up these types of programs.

Examples:

(Compiler/Program Type Setup)
Type: Filter
Compile Macros
Pre: Compile^PreCmpFilter
Post: Compile^PostCmpFilter

Type: Filter (Col Block)
Compiler Macros
Pre:
Post: Compile^PostCmpFilter /BT=2

Type: Filter (Line Block)
Compiler Macros
Pre:
Post: Compile^PostCmpFilter /BT=1

Type: HtmlTidy Filter
Compiler Macros
Pre: Compile^PreCmpFilter
Post: Compile^PostCmpFilter /F=<~!FilterFile>
Regular Expressions
Search: ^line (<i>) column (<i>) - ((Warning)|(Error): .@)$
Replace: /L=\0/C=\1/M=\2
Extra: /X=F/FP=U/FS=^Tidy \(.@\) Parsing (<q>)$/FR=//F=\0

(Compiler/Program Setup) 

Description: Perl Reverse Filter 
Command: Perl.exe c:\bat\PLRev.pl < <~!FilterFile>
Program Type: Filter 

Descriptions: HtmlTidy Filter
Command: d:\Mew32\HtmlTidy -wrap 79 -ium <~!FilterFile>
Program Type: HtmlTidy Filter

Most compilers add a line number to their error report so that locating the errors can easily be done. Multi-Edit uses this information to locate errors when processing a compile that was started from within it. This usually works very well as long as the source file isn't changed by adding/deleting lines or the errors are fixed from the bottom up. If the source file is changed, starting with the first error onward, eventually the error processing routine will not be able to correctly locate the next error since the line numbers have changed. Multi-Edit Classic File Compare also uses line numbers to determine where differences happen and adding/removing a line will affect the ability to locate the next difference. To overcome this limitation, Multi-Edit 2008 has a feature called Original Line Numbers.

The way this works is an additional line number variable is added to each line record. When a file is loaded, every line's original line number variable is set to be the same as the physical line number. When new lines are added or lines are deleted, the physical line number changes due to the inserted/deleted line, while the original line number does not change. The compiler error processing and the Multi-Edit Classic File Compare routines were also updated to position the cursor to the physical line number specified in the error or difference report as before but now a check is done of the original line number for the current line. If the original line number matches the physical line number no further action is taken. On the other hand, if the original line number doesn't match, the routine will start scanning the file forward or backward, depending upon the difference, for an original line number that matches the error line number.

The above works fine for the first compile or compare. But once a new compile or compare is done, the original line numbers need to be reset to match the physical line number, since the compiler uses the physical line numbers to generate the new error report. If the original line numbers didn't match the physical line numbers the correct line would no longer match. To resolve this issue, the ability to reset the original line number of a file was added. The conditions for resetting the original line numbers can be different for different situations, so the compile interface has a “Reset Original Line Number” option. This option allows the user to determine which files are reset before and after a compile is done. The following values are currently supported:

• Special (default): When this option is specified the following string field can contain a macro command line that will be run before and after the compile is run. This macro is responsible for calling the macro to reset the original line numbers. When the macro is run after the compile, it is passed the ”/POST=1” parameter. If there is no macro command line specified, then the original line numbers are not reset.
• Current: This option causes the original line numbers for only the current file to be reset before a compile.
• Project: This option causes the original line numbers for all files specified in the current project that are loaded in Multi-Edit to be reset before a compile.
• All Files: This option causes all loaded files to have their original line numbers reset before a compile.

For file compares, the original line numbers of both files are always reset before the compare is done.

An option was also added that will enable the original line number to be shown on the status bar with the physical line number. The original line number will appear before the physical line number and be enclosed in []s. A [*] shown for the original line number represents a new line. (This option can be disabled via Tools | Customize | User Interface – uncheck the checkbox for 'Show Original Line Numbers On Status Bar.')

In support of the Original Line Number, the OrigLineNumTime buffer variable was added. When a file is first loaded, this variable is set to the file time of the file. Whenever the original line numbers are reset, this variable will be updated to contain a file time equivalent to current time of when the reset was done. This variable could be used to determine the status of the original line numbers when using an external tag database to determine the best method for locating lines.

The ability to run a program on a remote system via a Telnet login will support any system that allows a telnet login. Any command that can be issued from a telnet command line can be run, the output captured and brought into Multi-Edit for error processing. This feature is accessed through the Compiler setup for individual extensions. In order to use this feature, you must set in the Compiler/Program Setup dialog the exe type to “Remote Telnet”, then pick a Telnet server for the host. Access the Telnet Destination dialog by running the macro Telnet^TelnetSetup (Macro | Run, and enter Telnet^TelnetSetup in the Run Macro dialog.) To create a new entry, select the “A Blank Server Template” entry and click Copy, rename it as desired, then edit the options. Existing entries are edited by clicking the 'Edit' button.

Edit Telnet Setup dialog

• Name: This is just a descriptive name to identify the server. Must be unique to other servers.
• Add: This is the host add. Can be an IP address or a DNS address.
• Port: The port that the telnet server uses, usually 23.
• UserID: The name of the user to login as on the server.
• Password: The password of the user being logged in.

• User ID Prompt: This is the text that precedes a user typing in their login name. Usually, “ogin:” the last 4 chars of “Login:” • Password Prompt: This is the text that precedes a user typing in their password. Usually, “sword:” the last 5 chars of “Password:”.

• Shell Prompt: This is the text that precedes a user typing a command line. This one is more difficult since every user could have a different prompt based on shell used and the environment setup. Possibly, ”:>” or ”]$”.
• Eol Seq: This is the set of characters used to terminate a new command line entry. Most popular would be “\r” or “\r\n”. Also, all standard C style escape characters may be used.
• Login Timeout: Time in milliseconds to wait for a login prompt.
• Compile Timeout: Time in milliseconds to wait for the program to finish compiling.
• Chdir Command: This is the command to be used by the remote system to change to a directory. A common way to type this would be “cd”. “cd” will be used if no entry is made.

Telnet support in earlier versions of Multi-Edit supported remote compilation in a very user-unfriendly fashion. For example, each compiler entry had to have a telnet server assigned to it, so if you used the same compiler on multiple remote hosts, you had to set up duplicate compiler entries for each server.

METerm is a new approach to telnet support in Multi-Edit 2008. The following notable enhancements and new features are provided:

• Compiler entries are now independent of telnet servers, as they should be. If a compiler entry is set up as a Remote Telnet compiler, then the user will be prompted for the desired telnet server after selecting the compiler from the compiler list box. This eliminates the requirement for multiple compiler entries being locked into a single telnet server.
• Telnet configurations now support scripts that can be executed on the remote host before and after a compile operation. This is useful for preparing for a compile on the remote host, and for cleaning up after a compile. Multi-Edit metacommands are fully supported in these scripts, including the new metacommand PROJECT_FTPROOT, which will allow you to reference the remote FTP directory assigned for the Project. This allows the telnet operation to work more seamlessly with the FTP configuration used to transfer the source files to the remote host.
• METerm can run Stand-Alone, providing a simple interactive telnet terminal for quick access to your telnet hosts. While METerm isn’t designed to be a full-features terminal emulator, it is functional enough for most purposes. It is useful for quick chores and can conveniently be launched from within MULTI-EDIT. Currently, VT100 and TTY emulations are supported, which cover the vast majority of telnet servers.
• Passwords within the Telnet configuration are now hashed to prevent clear-text passwords from appearing in MULTI-EDIT configuration files. Note that this isn’t intended to be a secure encryption, but simply a scrambling algorithm to thwart casual glances and minor hack attempts.

• Full telnet trace logging is now supported in each telnet configuration. This feature is enabled when a filename is entered in the Log File field on the configuration dialog. This is useful for troubleshooting communications problems.

First, create a compiler entry for the remote compiler. This will require knowledge of the command-line syntax and options for the specific compiler, as well as configuring of error-parsing support. Multi-Edit already ships with some compiler setups that support remote compiles, such as GCC. It is beyond the scope of this document to go into detail on compiler setup, beyond just the note that “EXE Type” should be set to “Remote Telnet”. If you use the same compiler for both local and remote compiles, you will also need to create a separate remote compiler entry from a local compiler entry. For example, if you use javac or GCC for local and remote projects, you must configure a local compiler setup and a remote compiler setup. However you only need a single remote compiler setup no matter how many remote servers you will target (assuming of course the compiler syntax and options are compatible with all remote servers). This differs from the previous telnet support where each remote server required its own compiler setup.

Next, create the telnet configuration to be used for the desired remote server(s). This can be done either by directly running the macro Telnet^TelnetSetup or during compiler execution when you are prompted to select a Telnet Setup. Telnet Setup uses the conventional Multi-Edit DB dialog format and stores its database in Defaults\Telnet.db. You create a new setup by copying an existing setup, including the Blank Template.

To create a new entry, copy the “A Blank Server Template” entry, rename it as desired, and edit the options in the configuration dialog on the following page. Existing entries are edited by clicking the 'Edit' button.

Many of these parameters are carried over from the original telnet support and thus should be familiar to those who have already used (or tried to use) telnet compiling in prior versions. Below is an item-by-item description:

Terminal Settings

Prompts

Timeouts

Other Options

Entering Pre and Post Compile Scripts

The other tabs in the Telnet Setup dialog are for entering optional scripts that will be executed on the remote host before and after the compiler command is executed.