M2 Mode Help
Name:Modula-2 Mode
Version:4.8.0
Last update:2019-11-27 08:39:25



Help file for Alpha's M2 Mode, the mode for Modula-2 Programmers.

About M2 Mode

This mode is for programming in Modula-2 and supports entire edit, compile, run cycles for some Modula-2 language systems such as the RAMSES or MacMETH shell or the P1 Modula-2.
RAMSES is an acronym for Research Aids for Modelling and Simulation of Environmental Systems https://www.sysecol.ethz.ch/RAMSES
RAMSES is based on MacMETH Fast Modula-2 Language System for the Apple Macintosh by N. Wirth et al., the inventor of Pascal, Modula-2, and Oberon, Swiss Federal Institute of Technology Zurich (ETH Zurich), Switzerland. https://www.ethz.ch
The M2 mode does not only color your code according to the Modula-2 syntax, but also provides very sophisticated support when programing in Modula-2. It provides many templates for almost all language constructs and can automatically generate code snippets (electric completions) including an entire implementation module from a given definition module. When fully integrated into a Modula-2 language system the M2 mode allows for comfortably switching between say a shell, i.e. the application running the compiler, linker, your programs etc. and Alpha. Compiler errors are shown in the editor's status bar (top or bottom of screen) and with CTRL-E you can locate easily any location(s) in your source code where the compiler detected errors during last compilation.
Modula-2 for the Macintosh is available as FreeWare, courtesy ETH Zurich as part of the software packages RAMSES or MacMETH, (see links below).
To really make good use of this mode see topics Working with Modula-2 Files, Keyboard bindings, Typing and Templates, Looking Up Information, and Marks and Functions popups. Have fun!

Working with Modula-2 Files

Alpha will automatically switch into Modula-2 Mode (abbreviated M2) if you open a file with the extension .MOD, .mod, .DEF, .def, .PRJ, .prj, *.DTF, *.MOD.MSTR, *.M2 or *.m2. It also switches into the M2 mode if press CTRL-0, a global key binding, or when Alpha is newly launched from a Modula-2 shell (Note: In later versions of this mode, CTRL-0 is only globally available if the user has initially configured the installation of the mode to work this way). Then the M2 mode opens all so-called working files as listed in the file err.ALPHA (or M2_err.ALPHA if you use P1 Modula-2). The latter file is searched in the folder in which the Modula-2 shell, i.e. the RAMSES or MacMETH shell, resides (in Alpha's cache folder if you use P1). Uou have specified that folder during initial automatic or explicit configuration of the M2 mode. The Modula-2 shell is the application which can execute the Modula-2 compiler, linker, debugger, and your own so-called subprograms. They can all be executed from within the same application, since RAMSES and MacMETH feature a dynamic linking-loader! BTW, for the record only: In the late eighties MetroWorks purchased from the Swiss Federal Institute the source code license for the MacMETH Modula-2 compiler and the Dialog Machine to offer a commercial Modula-2 development system. Then they built CodeWarrior. AFAIK MetroWerks no longer offers this Modula-2 development system. However, the MacMETH language system or its superset RAMSES are still available as freeware, courtesy the Swiss Federal Institute of Technology Zurich ETHZ https://www.ethz.ch (notably https://www.sysecol.ethz.ch).
As of M2 version 4.2 this mode also supports fully the use of the P1 Modula-2 compiler in particular while using the RASS-OSX utilities. RASS-OSX is also available as freeware , courtesy the Swiss Federal Institute of Technology Zurich ETHZ https://www.ethz.ch. For more information see https://www.sysecol.ethz.ch/RAMSES/ and https://www.awiedemann.de/compiler/.
IMPORTANT: Here some basics which gets you started. Press CTRL-0 (zero) and Alpha opens the current work file(s). If none opens (maybe the case if neither MacMETH nor RAMSES present or you have turned this feature off), choose File ↣ New and force M2 mode (choose M2 from lower right pop-up menu button in status bar) and choose menu item M2 ↣ Templates ↣ New Program MODULE. Save it and press CTRL-1 to switch to the Modula-2 shell. In the latter compile with CMD-C and if the compiler reports errors press CMD-E (for AlphaEdit) to reenter Alpha. Alpha will then automatically open for you all files lately compiled (implicit CTRL-0) and will display any possibly detected compiler errors (implicit first CTRL-E). CTRL-E lets you scan through all errors in your source code(s) in a circular fashion. That all really works as described, you need to properly configure your setup Installation. The mode must be properly installed in Alpha and you should have a functioning Modula-2 shell present, which has AlphaEdit installed and associated with CMD-E (AlphaEdit is in directory M2Tools). By default the latter is the case only in the so-called big RAMSES shell (activate it by the student proof keyboard shortcut CMD-SHIFT-CAPSLOCK-B (B for big).
As soon you are in the M2 mode an additional menu, named M2, is inserted in the menubar. It offers essential functions and the support for programing in Modula-2 via menu commands. For keyboard shortcuts (key bindings) see below (Keyboard bindings). The latter make actually all the difference!
Hint: If you start from scratch with menu command File ↣ New or with any other file having a different extension and you wish to activate the M2 mode, you can always force the M2 mode by using the Mode Pop-up menu (button in lower right corner of the message/status bar).
Related topics: Configuration and Customization, Installation, Keyboard bindings, Typing and Templates, Looking Up Information, Marks and Functions popups, Known Bugs - Problems and Solutions (should you encounter difficulties).

Typing and Templates

In M2 mode Alpha examines every keystroke and expands automatically your typing. For example: FOR<Space bar>i<Tab>0<Tab>9<Tab> will give you 
    FOR i := 0 TO 9 DO
      |<- cursor will be placed here
    END;(*FOR*)
and the cursor will be placed just below FOR, indented by the proper amount of spaces. Note, the mode writes deliberately no real tabs, since this makes the code more readable in the debugger. You may configure the number of spaces indents uses (see also Configuration and Customization). Instead of the last Tab you could have also used Shift-Return as an alternative to jump out of the current line and to position the cursor in the line below with language specific indentation. Typing 
    for<((e ah::combo {z Tab} e))>...
works similarly. Check it out for yourself. There are many electric keys available in the M2 mode. They are there for your convenience. In particular some shortcuts are only available to make typing on NoteBooks less awkward (e.g. num keypad 1 can be typed on Apple NoteBooks by fn-1, which is quite a convenient shortcut). Note also, if the mode specific completion does not give language specific support, these keys do always resort to Alpha's standard electric completion, e.g. completing a word according to one already somewhere above or below where you edit. Watch the status bar at the bottom of the screen to learn about such actions. Please consult the Alpha Manual to make good use of completions. Please consult also the M2 mode's Completions Tutorial (available via menu Alpha ↣ Mode Setup ↣ Completions Tutorial) or M2 Tutorial.M2 Mode Tutorial.
Note, the key <Return> breaks not only the current line, but does also indent on the next new line intelligently according to the current, Modula-2 language specific context. Only <Shift-⌃-Return> will break the line at the current position without any indentation. For more nifty features offered by the M2 mode, e.g. check out <⌥-Return> or <⌘-Return>, see topic Keyboard bindings.
<⌃-Tab> (or ESC followed by space bar) will expand the current word, if there is an equivalent in the Modula-2 reserved word list or if you have defined a word (typically an identifier) in your program text which begins with what you have just typed. The latter is searched above and then below. Note, the M2 mode still supports CMD-TAB, given you have turned off or changed MacOS' default application switching (see also Alpha Manual).
For example, typing PROC<⌃-Tab> (or PROC<ESC>) will result in PROCEDURE and typing a further blank will automatically trigger the insertion of the entire PROCEDURE template, e.g. resulting in 
    PROCEDURE MyProcedure;
    BEGIN (* MyProcedure *)
    END MyProcedure;
after having entered in the dialog the procedure's name MyProcedure.
Hints: There is a diffference between typing IF<Space bar> vs. if<Space bar>, or if<⌃-Tab>, check it out. In DEFINITION modules, it is convenient to type proce<Space bar> to get an expansion to PROCEDURE. Did you know, once you've written an entire definition module, M2 offers automatic IMPLEMENTATION MODULE generation? Use menu command M2 ↣ Def To Mod when DEFINITION is front window. Note also the big templates for entire modules, see the menu commands M2 ↣ Templates ↣ New xyz MODULE. In case you don't like a particular feature of these large templates, sorry, but you gonna have to modify the code of the file "m2Templates.tcl" yourself and to reinstall it afterwards. Look for the procedures defBODY, and modBODY. (see also sections Installation and Configuration and Customization). To customize the completions edit m2Completions.tcl and correspondingly M2 Tutorial.M2 Mode Tutorial.
For all details on electric completions see the Completions Tutorial (menu Alpha ↣ Mode Setup ↣ Completions Tutorial) or "M2 Tutorial.M2". For general information on typing in Alpha see Alpha Manual (Help ↣ Alpha Manual), and Alpha's Default Key Bindings (Help ↣ Default Key Bindings in Alpha 7.6) or Key Bindings (Help ↣ Key Bindings in Alpha8 or Alpha or AlphaTk).

Marks and Functions popups

The M2 mode supports the Marks and Functions popups in the document windows (thanks to Tom Featherstone!).

Mark Popup

The Marks popup lists so-called structural marks, modules, and all procedures and of course function procedures. There are several options (modes) which let you control the actual appearance of the generated list. You can list: Use the M2 mode's preference settings, i.e. choose menu Alpha ↣ Mode Setup ↣ Mode Preferences... ↣ Navigation and Reference (or F12 ↣ Navigation and Reference) to define what is listed by the Marks popup. Normally items are listed in order of occurrence, but flag sortListedItems lets you sort the list alphabetically. Structural marks stand out. Main ones are preceeded by a '•', section ones by a '-'. Indentations of procedures and modules represent Modula-2 scopes. If flag Mark Sees Comments is off, procedures within comments are not marked.
Structural marks are particular comments in your source code. Main marks start with '(*#####', end with '#####*)', and are made by Control-3 while having selected some text. Section marks start with (*====, end with =====*), and are made by Control-4 while having selected some text. Flag Boxed Section Marks determines the format of section marks (3 line, boxed (see example below) or single line format). Ex.: To get a main structural mark select some text like <My Header>, press Control-3 and you get 
    (***********************)        
    (*##### My Header #####*)        
    (***********************)

Note, for your convenience, not selected parts of the current line or possibly present remainders of an older mark are discarded and replaced by the new mark!!

Functions Popup

The Functions popup lists all Modula-2 procedures and function procedures in alphabetical order. The formal parameter list of each procedure is analyzed and shown in an abbreviated form after its name within curly braces. Value parameters are listed with a '•', variable (name) parameters with a 'v'. Function procedures are always listed with curly braces plus the symbolic representation of the returned value as ': v'. Ex.: 
    PROCEDURE AParlessProcedure;
    PROCEDURE VarProc (VAR c: Complex; n: INTEGER; VAR y: ARRAY OF REAL);
    PROCEDURE LightIsOn(): BOOLEAN;
    PROCEDURE Func(x: REAL; VAR y: Complex): REAL;
The Functions popup lists above code as 
    AParlessProcedure
    Func {•v}: v
    LightIsOn {}: v
    VarProc {v•v}
Related topics: Configuration and Customization, Keyboard bindings

Looking Up Information

The M2 mode supports the looking up of marked information. Simply Shift-Command-Double-Click a particular identifier, typically you click on the identifier of a procedure, and its declaration is searched in other files like definition modules or so-called quick reference files. The file in which the declaration has been found is then opened and positioned such that the found mark is displayed and the cursor placed at the procedure heading. This allows the programmer to lookup procedure declarations, in particular the formal parameter list (Quick Reference files) and to read the comments explaining the functioning and use of the double-clicked Modula-2 object. First the current file is searched and the cursor is placed at its declaration in case it is a local one. Otherwise, i.e. if the procedure is an imported one, all currently open files and then finally all quick reference files are searched and displayed at the corresponding declaration.
Quick reference files are searched as described below under step 5).
IMPLEMENTATION RESTRICTION: Unless the identifier is a RAMSES object the search works only for procedure identifiers. The same restriction applies regardless whether the object is a RAMSES object or not, if M2 mode preference Use Text File For M2 Object Reference is currently turned on. The same as Command-DoubleClick, but an attempt is made to show the corresponding partner module, e.g. the object exporting DEFINITION MODULE. For instance, if you currently work within the IMPLEMENTATION of a module and Control-Command-DoubleClick there an identifier, the corresponding DEFINITION MODULE is searched and positioned such that the clicked identifier becomes visible; or vice versa. With the keyboard shortcut ⌃-Option-O you can conveniently flip back and forth between the two files, i.e. the definition and implementation. If the clicked object is from an external library, an attempt is made to show the DEFINITION MODULE of the library module from which the object has been imported at the position of the declaration.
Modules are searched as follows:
  1. within the current folder
  2. if the current folder ends with .MOD within a folder ending with .DEF (but otherwise the same path). Supports for large projects to keep all DEFINITION MODULEs within a folder named e.g. MyProject.DEF and all IMPLEMENTATION MODULEs within a folder named e.g. MyProject.MOD.
  3. if the current folder ends with .DEF within a folder ending with .MOD (but otherwise the same path). Supports for large projects to keep all DEFINITION MODULEs within a folder named e.g. MyProject.DEF and all IMPLEMENTATION MODULEs within a folder named e.g. MyProject.MOD.
  4. within any currently open window regardless whether it is a .DEF or .MOD file (given M2 mode preference First Look In All Open Windows is turned on).
  5. within a collection of DEFINITION MODULEs as contained in a folder such as folder Docu, which is available as part of every RAMSES release (given M2 mode preference 'Use Text File For M2 Object Reference' is currently turned on).
    Note, the choice of that folder can be customized easily using menu command Alpha ↣ Current Mode ↣ Preferences ↣ Navigation and Reference ↣ Docu Folder. The M2 mode assumes that within this folder reside subfolders containing all DEFINITION MODULEs as well as quick reference files (ending with Quick Reference). To keep things organized, it is assumed that the DEFINITION MODULES are grouped by software layers (https://www.sysecol.ethz.ch/RAMSES/) into folders named M2, DM, MW, AuxLib, ISIS , RAMSES, RAMSES Extras, or ScienceLib, which contain again folders with a name ending with .DEF.
    If M2 mode preference Use Internet M2 Object Reference is turned on, above folder is ignored and web pages are searched at the URL given by preference Ramses Objects Reference URL.
    If M2 mode preference Use Internet M2 Object Reference is turned off, you need not be connected to the internt. Instead local html pages are searched within a folder as specified by M2 mode preference Ramses Objects Reference Folder (given M2 mode preference Use Text File For M2 Object Reference is currently turned off as well).
  6. within any currently open window regardless whether it is a .DEF or .MOD file (given M2 mode preference First Look In All Open Windows is turned off).
IMPLEMENTATION RESTRICTION: Unless the identifier is a RAMSES object the search works only for procedure identifiers. The same restriction applies regardless whether the object is a RAMSES object or not, if M2 mode preference Use Text File For M2 Object Reference is currently turned on.
On RAMSES Objects: As of M2 mode 4.4 and later for step 5) the web page based RAMSES Objects Reference is supported as well. The RAMSES Objects Reference is available at https://www.sysecol.ethz.ch/RAMSES/Objects Whenever above described rules require to access a quick reference file or a DEFINITION MODULE (notably step 5), M2 mode will attempt to access the RAMSES Objects Reference, given the M2 mode's preference Use text file for M2 Object Reference is currently turned off. If you wish to use the online RAMSES Objects Reference while being connected to the internet, check also the preference Use Internet M2 Object Reference. If you have downloaded RAMSES Objects Reference and installed it in the RAMSES folder, you can alternatively uncheck the latter preference for off-line viewing of the RAMSES Objects Reference. You can download the needed RAMSES Objects Reference folder from https://www.sysecol.ethz.ch/RAMSES/Objects or https://www.sysecol.ethz.ch/RAMSES/Documentation.html.
The RAMSES Objects Reference offers several advantages over the traditional text based one: It allows to search not only for modules and procedures, but also for any other Modula-2 object, i.e. constants, types, and variables. Moreover, that reference offers hyperlinks, which support easier finding of related information. Thus the M2 mode 4.4 and later is by default configured to use the internet based RAMSES Objects Reference.
Note: Searches of procedures can only succeed if the file has been marked with option List procedures (see topics Marks and Functions popups and Configuration and Customization). Preference Auto Mark may help to ensure this.
Related topics: Keyboard bindings (for keyboard shortcuts) Installation, and Configuration and Customization

Keyboard bindings

The following are the default keyboard bindings provided by the M2 mode. In more recent Alpha versions they can be customized to other shortcuts.

Launching shell & Compiler errors

CTRL-0
Open recently compiled work object file(s) and jump to 1st error
CTRL-e
Jump to next compilation error (as detected by last compilation) (Successful only after initial CTRL-0 has been issued)
CTRL-1
Launch M2 shell such as the MacMETH or RAMSES Shell or Terminal application under OS X (choice depends on current configuration.
CTRL-2
Like CTRL-1 but also triggers some extra action such as a program execution, e.g. the simulation of a MDP in the RAMSES shell, or changes the current working directory to that of the file you are editing in Alpha's topmost window.

Modula-2 place holders & Moving around

CTRL-g
Jump to the next Placeholder ( = comment of form (*. text .*) )
CTRL-SHIFT-g
Jump to the previous Placeholder (also CTRL-OPTION-g)
CTRL-RETURN
Resume position before last jump caused e.g. by TAB, CMD-RET etc.

Selections

CTRL-SHIFT-DOWN
Select entire current line; Hint: to expand SHIFT-cursorUP/DOWN
CTRL-SHIFT-s
Select surrounding comment of form (* xyz *) (if present)
OPT-CMD-b
Select string if cursor within text delimited by double or single quotes (similar to balance, recognizes Modula-2 strings)

RETURN key

RETURN
Breaks line & indents intelligently, e.g. if after BEGIN, inserts new line and indentation amount of spaces (amount configurable)
SHIFT-RETURN
Jumps to end of current line (no break) and then performs RETURN
CMD-RETURN
Like SHIFT-RETURN but never indents in a language specific way SHIFT-CTRL-RET Breaks line and does no indentation
OPTION-RETURN
New line and move cursor down (same position within line)
CMD-SHIFT-RET
Open new line above current
CMD-CTRL-SH-RET
Skip next line and perform SHIFT-RETURN

Electric completions

CTRL-TAB
Triggers electric completions (see M2 Tutorial.M2 Mode Tutorial and Typing and Templates)
fn-J/ESC
On laptops more conveniently to press alternatives for CTRL-TAB Note on laptops key 'fn-j' corresponds to Numkeypad-1. Numeric keypad keys were offered by Apple on their laptops for several years. However, note on those laptops numeric keypad keys do only work if NLCK is turned off (there you may toggle NLCK using SHIFT-CTRL-OPTION-n). Unfortunately, Apple has dropped numeric keypad emulation from its more recent laptop models. To regain the numeric keypad simply install freeware keyremap4macbook from https://pqrs.org/macosx/keyremap4macbook/. Mapping: 0:fn-m, 1:fn-j, 2:fn-k, 3:fn-l, 4:fn-u, 5:fn-i, 6:fn-o -:fn-;, +:fn-+, *:fn-p - no NLCK toggling needed anymore.
CTRL-OPTION-TAB
Force electric completion even if you have already white space between the cursor and the word (also Numkeypad-1-CTRL)

TAB key / Indentation

TAB
Move cursor in a context specific way to next insertion point of interest, e.g. as given by a bullet. Otherwise make indentation
SHIFT-TAB
Reverse TAB, i.e. unindent (configurable)
OPTION-TAB
Force indent similar to TAB, but ignore subsequent insertion points
CTRL-OPT-CMD-TAB
Inserts an actual ASCII TAB (use only if you really have to). Note, the use of TAB in Modula-2 source code is discouraged for a readable display in M2 debuggers.
CTRL-UP
Adjust indentation to that of non-white line above
CTRL-DOWN
Adjust indentation to that of non-white line below

Editing helpers

CTRL-]/OPT-]
Shift lines in selection to the right (by indentation spaces)
CTRL-[/OPT-[
Shift lines in selection to the left (by half indentation spaces)
OPT-DEL
Deletes the current line from the cursor position to the end
CTRL-OPT-DEL
Deletes the entire current line
CTRL-m
Minimize space surrounding cursor position to a single space
CTRL-j
Jump to end of line & join it with next & minimize white-space
CTRL-OPT-SH-f
List content of a directory in a new window
CMD-SHIFT-f
Filter entire source for current conditional compiler flags
CTRL-OPTION-o
Open other lib. module if in same folder (DEF->MOD or MOD->DEF)
CMD-OPTION-n
Show path and file name of top window in status bar
CTRL-8
Set default font (same as menu M2 ↣ Set Default Font, also Numkeypad-2)

Modula-2 comments

CTRL-c
Comment selection (using configurable prefixString, suffixString)
CTRL-SHIFT-c
Uncomment selection (revert CTRL-c; also CTRL-OPTION-c)
CTRL-k
Comment selection to a place holder of form (*. selection .*)
CTRL-SHIFT-k
Uncomment selected place holder (also CTRL-OPTION-k)
CTRL-SHIFT-a
Wrap selected Text; top left char in selection is left margin
CTRL-a
Wrap comment (configurable right margin) to form: 
    (*
      text 
    *)
Note these shortcuts are similar to the ones of MEdit (see RAMSES software package) or the legacy MPW (Macintosh Programer's Workshop). MEDIT users, simply think: Command is now control.
Related topics: Typing and Templates, "M2 Tutorial.M2", Working with Modula-2 Files

Installation

As of Alpha 7.5 the M2 mode forms part of the standard Alpha release. There is no need to install the M2 mode anymore (albeit the mode is still available as a separate package from the RAMSES home or the easiest from https://www.sysecol.ethz.ch/SimSoftware/SimSoftware2.html).
However, note, a smooth collaboration between the M2 mode and your Modula-2 development system requires to observe a few rules. Notably, it is recommended to have the home directory of Alpha to reside in the same directory where the RAMSES folder, or the MacMETH folder, respectively, resides. In most cases this will already do. In particular, if Control-1 from within Alpha as well as Command-E from within the RAMSES or MacMETH shell switches smoothly between the two applications back and forth, your installation seems to be fine (see also Working with Modula-2 Files). In all other cases, please read on.

Modula-2 Development Environment Configuration

If you enter the M2 mode and you get some alerts telling you that the mode had troubles finding some expected files or information, you need to alter slightly your current configuration. These warnings or error messages try to help you and don't imply there is something wrong with the mode. Instead, fix your installation and the benefit is a smoothly working programing environment at all times. In this context you should understand the following points:

Configuring Alpha

  • The M2 mode is designed to closely collaborate with a so-called Modula-2 shell. This is either the RAMSES shell or the MacMETH shell (Note, you need a Modula-2 shell in order to compile any Modula-2 source code). When you launch for the first time the M2 mode, it will inspect your Macintosh and search for one of these shells (priority: 1st RAMSES, 2nd MacMETH). Then it will try to remember where they reside or remind you of the fact that it failed to do so, for instance because they are absent from your computer system. Note, the M2 mode makes sense fully only if it can collaborate with a Modula-2 shell. Hence it will warn you if it could not successfully locate a Modula-2 shell.
  • If the Modula-2 compiler detected some source code errors, it won't display them. It informs you only wether it encountered some errors or not. That's where the M2 mode from Alpha comes in handy.
  • The M2 mode can open and display compiler errors in the source code. For instance the command Control-0 (global key binding) tries to open the so-called working object (see also Working with Modula-2 Files). In case there was a compilation error this command will also jump to the first error location and display the appropriate error message in the status bar at the bottom of the screen. Control-E jumps to the next error etc. (file after file, in a loop). However, for this behavior the M2 mode needs possibly lots of information (possilby hundred of files with thousands of errors). Wether it can find it depends on your current configuration of the Modula-2 development environment.
  • The M2 mode expects to find information about the current working object in the same directory where the current Modula-2 shell resides. This information means the names of the lately compiled files and possibly encountered compiler errors (see note below). More precisely, since you might have several Modula-2 shells on your system, e.g. RAMSES and MacMETH, the M2 mode searches at any time only in the shell directory it is currently associated with. Simply use the menu command M2 ↣ Configure Launching to specify with which Modula-2 shell you wish the mode to collaborate. Use this command, should you not be happy with the current settings, e.g. if you wish to switch between the RAMSES and the MacMETH shell (Of course, alternatively, you may also edit the mode preferences (F12) and there modify the item M2_shell Name, cumbersome!).
    Note: The working object is either a single file or consists of a set of files. In the first case it is a Modula-2 program module (extension .MOD). In the second case the work object consists of many source code files, forming an entire project (listed in a file with extension .PRJ). This may consist of many library modules, i.e. DEFINITION (extension .DEF) and IMPLEMENTATION plus program modules (extensions .MOD).
    To really know all, note: Compiler errors are stored in the binary file err.DAT. Each time you use the compiler, regardless of the Modula-2 shell from where you launch it, the compiler generates a new file err.DAT in the same directory where the calling shell resides. The name of the files compiled lately are listed in the text file err.ALPHA. This file is generated by the utility AlphaEdit. AlphaEdit is a little prelinked Modula-2 subprogram stored in directory M2Tools within the RAMSES or MacMETH folder. Error messages to be displayed in the status bar are stored in the simple text file ErrList.DOK, again in directory M2Tools (M2::openErrListFile).
  • For your convenience, the M2 mode can listen to Apple events sent to it by another application, e.g. the RAMSES or MacMETH shell. It understands a single command, i.e. open the current work object. It executes the same procedure as does the global key binding Control-0. Typically there is rarely need to press Control-0, since the menu command Edit (Alpha)... in the RAMSES or AlphaEdit in the MacMETH shell sends such a command to Alpha, where the M2 mode should pick it up and execute it.

Configuring RAMSES or MacMETH

Alas, having Alpha to open working objects as described above does NOT yet mean that your installation is really fine. This is because the Modula-2 shell you currently use needs also to know where Alpha is (or with which you wish to work). This is where the recommendation matters to have Alpha, RAMSES, and MacMETH reside in the same directory.
  • When you get compiler errors while compiling from within the RAMSES or MacMETH shell the compiler will tell you about this fact. In order to edit the source, remember, ALWAYS and ONLY use the menu command Edit (Alpha)... from the RAMSES or AlphaEdit from the MacMETH shell (Command-E). NEVER simply switch to Alpha by other means, e.g. via the Finder's application menu etc. Otherwise you won't be able to display the compiler errors! Why?
  • The menu command Programing ↣ Edit (Alpha)... from the big RAMSES shell actually executes the M2 tool AlphaEdit. This is a little Modula-2 subprogram, which does all you need to switch to Alpha for error display and editing. More precisely, it reads the file User.Profile to read the name and location of Alpha, in order to launch the application Alpha and bring it to the foreground later on. Then it generates the file err.ALPHA and sends the open work object command (Apple event) to Alpha (Avoid to have more than one Alpha running in such a situation). This works also if Alpha si currently not running ad needs first to be launched. Finally Alpha is brought to the foreground, where it should open the working object (one or more files) and jump to the source location of the first compiler error encountered. Control-E will get you to the next error etc. This is the normal behavior when the installation is fine, i.e. the RAMSES shell finds Alpha at its actual location on your computer.
  • Should you see any error messages instead of what is describeda above, simply open the file User.Profile within the RAMSES or MacMETH folder and edit the path and file name of the Alpha you wish to use. Search for section Alias where you should have an entry similar to this (all quotes etc. exactly as shown below): 
        "Alias"
      'Edit2'   is   ' MEdit 1.80'  
      'Alpha'   is   '::Alpha ƒ:Alpha'
Note, above example assumes again you have Alpha's directory Alpha ƒ in the same parent directory as where your Modula-2 shell resides. Your file system structure is similar to this, the recommended setup! 
    			   /-----\_________
    			   | parent folder |
    			   -----------------
    			  /        |        \
    			/          |          \
    		  /            |            \
       /---\_____      /---\_____      /---\_____
       | Alpha ƒ |     | MacMETH |     | RAMSES  |
       -----------     -----------     -----------
(Note, the relative path ::Alpha ƒ: is going first one level upwards then into directory Alpha ƒ). This flexible mechanism allows you also to choose among different Alphas, e.g. to use Alpha 68k instead of Alpha, should you work on an 68K Mac. IMPORTANT: Then you will need to edit the text file User.Profile in any case!
You can find even more on this topic, e.g. hints on how to customize the menu of the MacMETH shell, at https://www.sysecol.ethz.ch/RAMSES/READ_ME.RAMSES_Extras.html or in the file READ to AUTOINSTALL M2. This is available at https://www.sysecol.ethz.ch/SimSoftware/SimSoftware2.html as part of the separately available M2 mode package (row Alpha editor).

Manual (Re)Installation

In Alpha version 7.x and higher simply double-click file OPEN-TO-INSTALL and perform an easy installation and follow all recommendations. That's all!
You may obtain the M2 mode also separately from Alpha, as part of the RAMSES Extra release from https://www.sysecol.ethz.ch/RAMSES/#RAMSES_Extras or ftp://atitlan.ethz.ch/pub/mac/RAMSES/ or only the mode from https://www.sysecol.ethz.ch/SimSoftware/SimSoftware2.html or ftp://ftp.ucsd.edu/pub/alpha/
All this software is freeware, courtesy ETH Zurich, Switzerland https://www.ethz.ch.
For links to get a Modula-2 language system (including compiler, loading-linker, debugger, skeleton source code, huge libraries etc.) see topic About M2 Mode.
Once you have installed the M2 mode and you restart Alpha, Alpha will prompt you to configure your Modula-2 environment as explained under topic Configuration and Customization.
To learn about how to use your installation, see at least topics Working with Modula-2 Files, Keyboard bindings, and Typing and Templates.

Configuration and Customization

The first time you activate the M2 mode, it will try to configure itself by searching the desktop database for the presence of a RAMSES or MacMETH shell. The purpose is to establish the links between the Modula-2 shell running the compiler, e.g. the MacMETH or RAMSES shell. The M2 mode can display compiler errors properly in your source code only if the mode's settings match exactly the location of the Modula-2 shell you are using. Once configured, you may then easily jump back and forth between the Modula-2 shell and Alpha via THE two essential keyboard shortcuts, i.e. CMD-E and CTRL-1 (see also Working with Modula-2 Files, Keyboard bindings, and Installation).

Using several Modula-2 shells

Use menu command M2 ↣ Configure Launching to configure the use of a particular Modula-2 shell. M2 ↣ Configure Launching lets you select the shell to which the shell launching commands (CTRL-1, CTRL-2) will transfer, and optionally to choose the file which contains the messages which help you to interpret the compiler generated error codes (ErrList.DOK in folder M2Tools, residing in the same folder where you find the MacMETH or RAMSES shell). ErrList.DOK is needed for displaying readable messages at the bottom in the status bar when you press CTRL-E while searching for error locations in your currently open Modula-2 working file. Note, this command is automatically executing at very first M2 mode activation.

Alpha's global preferences and M2 mode

Use menu command Alpha ↣ Mode Setup ↣ Mode Preferences... (or F12) Alpha ↣ Mode Setup ↣ Mode Preferences... (or F12) lets you edit all settings of the M2 mode while the mode is active. The mode specific core settings are characterized by prefix M2_ .... Partly their values are also configurable via the mode's menu M2. This is now only the case for m2_errListDOK, m2_shellName (see above), in Alpha < 7.x this is also the case for a few other variables (see below)).
To obtain best results recommended settings are all flags on except for these:
Auto Continue Commentoff(M2 F12)Fatal for free format Modula-2
Backup off(M2 F12)creates a mess (IMHO)
Mark Sees Commentsoff(M2 F12)slows down marking considerably
Sort Listed Itemsoff(M2 F12)rarely of use
Smart Cut Pasteoff(M2 F12)Was always a buggy Alpha feature

To obtain best results it is recommended to set global Alpha settings as follows:
Backupoff(Alpha ↣ Preferences ↣ Backups)
Emacs keyboard navigationoff(Alpha ↣ Preferences ↣ Features...)

Other recommendations: Set Docu Folder to the folder Docu within the RAMSES folder or ⌘-Double-Clicks respectively ⌃-Double-Clicks won't have the desired effect!

Personalization and customization of M2 mode

Use menu command M2 ↣ Configure M2 Mode (available only in Alpha < 7.x) M2 ↣ Configure M2 Mode lets you enter your name used by defaults in module templates, to set tab spaces (shift right, shift left respectively) and other parameters specific to the M2 mode.

Customization of electric completions of M2 mode

Customizing templates: If you don't like any of the templates you gonna have to modify them in the files M2Completions.tcl and correspondingly M2 Tutorial.M2 Mode Tutorial or m2Templates.tcl. Especially you may wanna modify the procedures defBODY, or modBODY in m2Templates.tcl.

MacOS (notably OS X) and electric completions

To use electric completions, i.e. the old fashioned keyboard shortcut <⌘-Tab>, the MacOS default settings for application switching may get into your way. An easy fix if you use MacOS 9.x is to customize your MacOS by choosing menu Help ↣ Help Center in the Finder and search for Application switching. There click onto switching between open programs and Help me modify the keyboard shortcuts. Turn the feature off or use another shortcut to free <⌃-Tab> to be used by the M2 mode. In MacOS X I know unfortunately of no remedy for this problem. The only solution is to abandon using <⌘-Tab> and using Alpha's new alternative, i.e. <⌃-Tab>. For your convenience the M2 mode offers several more alternatives (see Typing and Templates, M2 Tutorial.M2 (Alpha ↣ Mode Setup ↣ Completions Tutorial), "Alpha Manual" (Alpha Manual), and Alpha's Default Key Bindings or Key Bindings to learn all you need for efficient typing in Alpha).
Related topics: Installation, Known Bugs - Problems and Solutions, Typing and Templates, and Marks and Functions popups

Known problems and Solutions

Please report any problem or bug you encounter in Alpha's Bug Tracker.
  • Completions won't work when you press ⌘-Tab. Instead you end up in another application. You have the default MacOS application switching active or are using MacOS X. See topic Configuration and Customization for hints on how to fix or circumvent this.
  • You are using several Modula-2 shells at the same time, which reside not in the same folders. Alpha opens working files only when launched from one shell, but not if launched from the other, newly used one. Explanation: Mode M2 can support only one shell at a time. You have to use menu M2 ↣ Configure Launching to get a new shell communicating with Alpha properly again. To get the cooperation with the old one back, reconfigure launching once again.
  • While writing comments you get additional, unwanted '(*' at the begin of each line. Uncheck the check box Auto Continue Comment in the dialog offered by menu Alpha ↣ Mode Setup ↣ Mode Preferences... (F12)! This feature is not only meaningless or a nuisance, but is dangerously error-prone in a free-format, nested comment syntax as featured by Modula-2 (all code becomes a comment).
  • Oddly jagged source code when looked at from within the symbolic debugger of MacMETH or RAMSES. You're source code probably contains horizontal tab characters (ASCII 11C). Fix: Select all and choose menu command Text ↣ Tabs To Spaces. Note, M2 mode deliberately avoids inserting horizontal tabulations into the source code (e.g. pressing key TAB in M2 mode inserts only blanks). However, many predefined Alpha routines behave differently in this respect. In particular you should also refrain from inserting tabs in your source code, e.g. by calling menu command Text ↣ Spaces To Tabs.
  • You wish to use another Alpha than the one the Modula-2 shell (MacMETH or RAMSES Shell) launches for you. Make sure the last alias Alpha in Alias section of the User.Profile is the one you wish the Modula-2 shell to launch. E.g. that section in the User.Profile might look similar to this 
          'Alpha'   is   '::Alpha7.6:Alpha7'
      'Alpha'   is   '::Alpha:Alpha8'
      'Alpha'   is   'HDX:Applications:Alpha:Alpha.app'
    Here it is Alpha which will be launched by the Modula-2 shell. (Note, here it is also assumed that the boot volume for MacOS X is named HDX and that you have isntalled Alpha at the default location). Wish the Modula-2 shell to launch another Alpha, move that line to the bottom. Make also sure to edit really the User.Profile which resides in the same folder where your Modula-2 shell resides.
  • Alpha does not open the Modula-2 work files you have recently compiled. Check the configuration of the M2 mode. It should be set such, that the Modula-2 shell you wish to use is currently selected. To ensure this use use Alpha while the M2 mode is active and choose the menu command M2 ↣ Configure Launching and select the Modula-2 shell of your choice. Alternatively you can also look at the mode's preferences by pressing function key F12. On page 3 you find the path and name of the Modula-2 shell. You may edit this directly to define the Modula-2 shell which the M2 mode should recognize. The path should also be the same as the one shown on page 2 of the dialog for preference M2_err List DOK.
  • Ctrl^0 is no longer opening the Modula-2 working files. Activate the global feature Global M2 Bindings Alpha ↣ Global Setup ↣ Features.... Once activated it allows you to use the Ctrl^0 key anytime. You no longer need to have a file open, which activates the M2 mode. Alternatively you may control this feature also from within the M2 mode by using the preference dialog (F12). Either technique has the same effect and activates or deactivates the global feature Global M2 Bindings.

Mode M2 3.8.x

  • When using Alpha8 or Alpha (e.g. 8.0b8) the work objects may no longer be opened and compiler error messages are no longer shown. Solution: Install tclAE >= 2.0b14 or activate at least once the M2 mode, e.g. by opening the work object manually. Subsequently work objects should be opened again and encountered compiler errors shown again automatically.
  • When using Alpha8 or Alpha (e.g. 8.0b8) and a Command^double-click does open a quick reference file, the latter may be shown only in text mode. Fix: Activate the M2 mode using the pop-up menu in the status bar. fixed in M2 mode >=3.8.9
  • Under MacOS 9.x you crash your system when you try to switch from MacMETH or RAMSES shell to Alpha. Remedy: Please upgrade to latest MacMETH or RAMSES. fixed in MacMETH >=3.2.7 or RAMSES 3.0.1 >=b5
  • Word wrapping behavior (lower right corner of status bar menu) should be controllable by a M2 mode specific preference called Word Wrap. This seems not to work properly in the same way as this is the case for other global preferences. This means you won't find in the M2 preference dialog the option Word Wrap albeit the mode supports this option as a M2 specific preference (see Alpha ↣ Mode Setup ↣ Mode Preferences... or F12). I know of no fix and this seems to be an idiosynchracy of Alpha 7.6, not a problem of the M2 mode. If you wish to control this option, i.e. to have it turned on by default, you need to alter the preference settings for wordWrap in m2Prefs.tcl. Fortunately, of course, you can always control this option on a case by case basis by using the pop-up menu in the status bar.
  • You get the message "There was BAD problem loading 'M2' mode: invalid command name "M2::enterM2Mode"... " etc. This should only occur after a partial deinstallation of the M2 mode. Please reinstall the mode from the separate package downloadable from various sites, notably those listed under topic About M2 Mode.
  • Links in this help file won't work. This is a general problem of Alpha 7.6 tcl, not of this mode. Hopefully this will be fixed in a future release of Alpha.

Mode M2 3.6.x and older versions

  • The menu command Wrap Text (⌃-Shift-A) fails. Remedy: Run anywhere first Wrap Comment (Control-A), then try again Wrap Text.
  • You are using the MacMETH shell and Alpha opens the Modula-2 working files only when launched, but afterwards no more. Explanation: The MacMETH shell is not high level event aware. Remedy: Either make the shell high level event aware (using ResEdit, resource SIZE or use RMSMacMETH shell from RAMSES Extras; disadvantage: the shell ignores shut downs and needs to be quit manually) or press Control-0 each time you switch to Alpha. The latter is the only means to open Modula-2 working files in case you are using a MacOS older than System 7, regardless of the shell (MacMETH, RMSMacMETH, or RAMSES) you are using. fixed in MacMETH >=3.2.6 or RAMSES 2.2.3 >=b26

Mode M2 3.2.x and older versions

  • Slow entering into M2 mode. Fix: Disable copyRing (or leave it on all the time) while in mode M2 Alpha Prefs ↣ Menus and Features... and uncheck copyRing in 2nd dialog "Select features for mode M2".
  • AlphaLite 6.5.2 wrongly reports "Your Preferences file 'Prefs.tcl contains an error" while closing windows. Remedy: Ignore or use big Alpha
  • Sometimes Alpha won't open the most recent M2 work file(s), whatever you do in the RAMSES shell. Simply throw away the files err.ALPHA and token.ALPHA in the folder where the RAMSES (or MacMETH) shell resides and proceed; that usually helps to get you going again. fixed in V >= 1.0
Related topics: Installation, Configuration and Customization.

License and Disclaimer

Original Author: Andreas Fischlin. Systems Ecology, ETH Zurich, Switzerland, https://www.sysecol.ethz.ch
Copyright (c) 2005-2019, Andreas Fischlin.
All rights reserved.
The Modula2 Mode package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of Andreas Fischlin nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANDREAS FISCHLIN BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.