Syntax of a ModeFile

ModeWhen files define which mode StrongED uses when a file is initially loaded. If the ModeWhen files haven't caused such a decision, then BaseMode is used.

A word of warning: inspecting StrongED's files can be instructive, even necessary in order to understand them. However as StrongED writes out many of its own files, the primary file, as supplied with the StrongED release, can look different in places to the changed file. These descriptions apply to the primary files.

ModeFile sections

A mode file can consist of the following sections:

Bitmap Deprecated

A string telling which bitmap font to use (deprecated)

FoldParm

A string to determine how a text should be folded

HelpPath

A string describing which StrongHelp manuals to search.

PrintHead

A string to come at the top of a printout

PrintFoot

A string to come at the bottom of a printout

Tabstops

A string defining the width of each column

OnLoad

A list of functions executed when a file is loaded

KeyList

Block of functions tied to keys

Search

Block of named search expression definitions

Replace

Block of named replace expressions

Functions

Block of functions tied to menu or toolbar icon or Hotkey

Shortcuts

Block of shortcut definitions

ID_FirstChar

Simple set defining what an ID can start with

ID_Middle

Simple set defining the chars in the ID body

ID_LastChar

Simple set defining optional final char for ID

SyntaxWords

Block of reserved words

SyntaxOptions To do

Block of options for syntax colouring

SyntaxComment To do

Block describing how a comment looks

SmartIndent In preparation

Defines when to indent/outdent

ClickList

Block of matchpatterns tied to functions

WriteProtect To do

A list of path patterns that should be loaded write protected

Bitmap

ClickList

• Select1 = single click Select
• Select2 = double click Select
• Adjust1 = single click Adjust
• Adjust2 = double click Adjust

Other named ClickLists can be tied to key presses rather than mousebutton presses. See Named Search Expressions

ClickList [name]
  search-name   List of functions
End

When you double click with Select, this list is consulted. StrongED will go through it and see if the clicked word matches any of the search expressions in the Search section of the ModeFile of the current mode or the BaseMode. If it does, the corresponding list of functions will be executed. In the above case, the function is BroadcastURL

The search-name needs to match a named expression in the Search section of the ModeFile.

The list of functions is one or more of StrongED's functions, separated by spaces.

You can prefix a clicklist name with for instance, s-. It will then only apply if Shift was held in while you clicked. The full syntax of the mouse-clicklist name is then:

[a][c][s]- Select|Adjust 1|2

Example: cs-Select2 = Doubleclick Select, with Ctrl and Shift pressed.

Example 2: To run a file when a filename is double-clicked you could use:

ClickList Select2
  Filename   Run("Filer_Run ")
End

Search
  FileSys   "ADFS" | "RAM" | "SCSI" | "SDFS"
  FileName  FileSys "::" {~(Ctrl|White) Any}+
end

There is more on ClickLists

Fold Parameters

When is executed, a fold is performed based on FoldParm1 and FoldParm2 as defined in the ModeFile(s). FoldParm1 is defined in the BaseMode file and is used globally unless otherwise re-defined. FoldParm2 is optional.

These FoldParms passed to the FoldSpecial function.

The syntax is: FoldParm1(Startfold, Endfold, Where, Case)
Each parameter may be either a text string, enclosed in double inverted commas, or it may be a named search expression, as defined in the Search section of the ModeFile. In many Modes, these named expressions are actually called e.g. fold_start, fold_end, startofline, case (or similar names).

Startfold

determines what constitutes a fold start.

Endfold

determines what constitutes a fold end. Optional.

Where

specifies where on a line Startfold and Endfold will be matched. If not given then a match can occur anywhere on a line. The following pre-named definitions can be used.

• "StartOfLine" Matches at start of line only.
• "StartSpace" As above, but preceding white space is allowed
• "EndOfLine" Matches at end of line only.

Case

specifies if the matching should be case-sensitive.

• "Case" Match case-sensitively.
• "NoCase" Match case-insensitively.

There is a list of Fold Parameters Pre-defined in ModeFiles which should clarify this. For instance in Document mode both FoldParms are defined thus:

FoldParm1    (fold1start,fold1end,StartOfLine,NoCase)
FoldParm2    (fold2start,fold2end,StartSpace,NoCase)

• fold1start "["
• fold1end "]"
• fold2start "{"
• fold2end "}"

You can override the fold parameters in the modefile by specifying them directly in the start of a text.

NB1: Due to a bug, the open fold markers will not redraw correctly. Unfortunately I (FG) have so far been unable to fix this.

NB2: As far as I (FG) can see, 'EndOfLine' is not supported.

Example

Foldparm2	("<H",,,nocase)

Functions

Sections are in blocks: only some lines call internal functions, others assign names to icons or names to keys which will perform the same action as the mouse click defined in the same block.

You may want to inspect an existing ModeFile. If doing so, beware of the above warning!

Items in a block may be in any order, except that Key or Menu should start the block.

Icon or Menu

One or other is necessary within a block.
Icon defines the name of the Icon to which the block refers.
Menu quotes the menu text to which the block refers. This text is added as an entry to the Mode's submenu of the main menu of the window concerned. In a window press Menu. In the menu that opens, the last entry is the Mode name. The block's Menu text creates a line in the last section of the submenu here. See note

Help

The word is followed by either the help string or a message token that is looked up in a Messages file in the mode's resources. This is the Help text that will be displayed by interactive !Help (also by !Float) if interactive Help is enabled in StrongED (Iconbar Choices -> Misc).

This file may be, for example, <StrongED$Dir>.Defaults.Modes.BaseMode.Resources.UK.Messages or in a Mode directory such as !StrED_cfg.UserPrefs.Modes.HTML.Resources.UK.Messages

Key

The key that corresponds to the Icon click or Menu entry.

Select

Function that is called by Select on the Icon or Menu entry.

Adjust

Function that is called by Adjust on the Icon or Menu entry.

Drag

Function that is called by dragging the Icon or Menu entry. Dragging with Select or with Adjust will have the same effect.

Any Select, Adjust or Drag entry may also have a qualified version such as cs-Select which means Ctrl + Shift + Select

However, when more than a single mouse-click operations is defined, it would be ambiguous as to which mouse action applied to the defined Key. So an empty line is required before or after lines which do not apply to the Key definition. The mouse action which is not separated by two Returns is the one that applies to the Key. There is an example which should clarify this.

HelpPath

This is not a filer path but simply a comma separated string listing which StrongHelp manuals should be searched. The manuals will be searched in the order they listed. The manuals known to StrongHelp can be determined by Adjust-click on StrongHelp.

The definition may end with a trailing comma in which case StrongHelp will search all remaining manuals if those listed do not produce a match.

The BaseMode ModeFile does not include a HelpPath but most other modes do.

ID_FirstChar
ID_LastChar
ID_Middle

One of the items in a mode's Choices -> Colours list of colourable Elements is Identifiers. These three items define what words should be coloured as Identifiers.

The colouring of other words, as defined in SyntaxWords or SyntaxOptions, will be applied preferentially.

This is useful for such things as variables in a programming language. Or for tags in html.

ID_FirstChar defines which characters an Identifier can start with. Some programming languages have restrictions on this, eg in BBC BASIC IDs can't start with a digit.

ID_Middle defines which characters can be in the middle (ie not first or last) of an Identifier.

ID_LastChar is used for special characters that denote the end of an Identifier. In BBC BASIC integer variables end with '%', and string variables with '$'.

As an example, consider the html ModeFile where these three are defined:

ID_FirstChar	<
ID_Middle	/A-Za-z_0-9
ID_LastChar	A-Za-z_0-9>

This example is interesting - ID_LastChar is optional. If it is not defined then it is ignored. Its only purpose is to colour the last character. In the above case the set A-Za-z_0-9 has already been defined in ID_Middle, so will be coloured. It is then redundant to redefine that set again as ID_LastChar and a clearer definition of ID_LastChar would be simply <

However the ModeFile for HTML is old, a better definition of these three IDs might be

ID_FirstChar	<
ID_Middle	/A-Za-z _0-9
ID_LastChar	>

KeyList

Keylist is followed by the name of what it is to be tied to. If a name is not specified, then it defaults to Mode which is the only name which can be used in a normal mode file, so in practise is not used there. The other possible names are only used in BaseMode and are all listed below:

CopyCursor

is the list of keys that will be consulted first, when the Copy Cursor is active.

Mode

is the list used for normal text entry, defining what key actions apply only to the relevant mode..

TaskWindow

SearchReplace

Interactive

WhatNext

SaveBox

ListOfWinds

ListOfFound

LoF_dbox

Throwback

Print

These are all names of dialogue boxes, specifying how keys act therein.

Global

is the list that will be consulted last of all, always, even if StrongED doesn't have the input focus.

syntax

<Key name>
	<List of Functions=>!ref_function>
End

Some example key definitions:

  ^Right 1  EndOfWLine
  ^Right 2  EndOfTLine
  ^D,^D     DateAndTime ("%DY%MN%YR")
  ^D,^T     DateAndTime ("%24:%MI")
  ^D,^W     DateAndTime ("%WK")

Note the use of the old ASC &5E for Ctrl and ASC &8B for Shift: new representation would be e.g. cs-T.

OnLoad

OnLoad	<list of functions\>

PrintHead and PrintFoot

PrintHead     <String to send to printer>
PrintFoot     <String to send to printer>

PrintHead     |i|i |m
PrintFoot     |m|i----  ----

To split the output into multiple lines use |m (=carriage return). Each line can be divided into three sections (left, center, right) by using |i (=tab) as a separator. Examples

PrintHead   |i Centred

and The default, as defined in BaseMode is

PrintHead   <StrongED$Tmp_FileName>|i|i<Sys$Time> <Sys$Date> <Sys$Year>

• StrongED$Tmp_FileLeaf
• StrongED$Tmp_FileName
• StrongED$Tmp_FilePath
• StrongED$Tmp_MarkWord
• StrongED$Tmp_ModeName
• StrongED$Tmp_ModePath
• StrongED$Tmp_Page

Replace

The BaseMode contains only one:

The syntax is the same as that for Advanced Replace

Search

Syntax of the block is

Search
  name   Expression
  ..
End

1. Some functions take an expression as parameter, but the expression must be called by name.
2. The names can be used in the ClickList section of the ModeFile
3. You can define often-used expressions here and just type their name in the Search/Replace dbox. See Named search Expressions in Advanced Search and Replace.
4. StrongED uses named search expressions in a number of areas to guide its behaviour. There is a list of known expressions.

You can also name such Search Expressins in a Patterns File.

There is a screen shot of the BaseMode's Search section. It is long! However you can open the ModeFile of the BaseMode by a Ctrl-Adjust click on StrongED's iconbar icon. any of these named definitions can be used in a Search expression.

Shortcuts

Syntax

Shortcut
 typed_text    replacement_text
  ...
End

Whenever the 'shortcut' is typed, and it is floating, it will be replaced by the 'replacement_text'.

The shortcut is floating when the characters that are before and after it in the text are of a different type than the first and last letter of the shortcut. Thus in html mode, some of the shortcuts defined are:

so that typing ``1This is a heading will be expanded to <h1>This is a heading</h1>. The ``1 bit is expanded immediately you type it since the white space following it means it is floating. The caret, after the expansion, is positioned at the first \@ in the expanded text, so after the <h1>.

However if you type This is a heading first and then go back and insert the ``1, it does not expand because of the T following the typed text!

The replacement text can contain some special escape sequences:

  \n	is replaced with a newline
  \t	is replaced with a TAB
  \i	is replaced with the indent that the first line has
  \@	Defines where the caret should be placed after expansion.

These \@ markers for the cursor position behave in a manner somewhat similar to the @ markers in Search and replace. If an \@ marker is followed by a number, then this number will refer to a previous @ marker in the replacement text - StrongED keeps internal note of the quantity of \@ markers in the expansion.

On pressing return to jump to the next \@ marker, when the Caret reaches this numbered \@ marker, the (expanded) word before the position it refers to is copied to the cursor.

Example 1

  ``f    function \@()\n-- end of \@0

  function Foobar()
  -- end of

  function Foobar()
  -- end of Foobar

Example 2

<h2 id="Shortcuts">Shortcuts</h2>

	<<h2	<h2 id="\@">\@0</a>\n\@

 <<h2Shortcut

It is very well worth looking at the shortcuts in the modes you use a lot to see what is available there.

SmartIndent
	IndentSize	
	IndentChar	
	OutdentChar	
	IndentAfter	
	OutdentLine	
End

SmartIndent Case
	IndentSize	2
	IndentAfter	< {" "} ("do" | "if" | "elseif" | "else" | "for" | "function" | "repeat" | "while") \s
	OutdentLine	< {" "} ("end" | "elseif" | "else" | "until") \s
End

SyntaxWords

Here are defined groups of words that you want picked out in a particular colour. Each Group relates directly to the Mode's choices -> Colours dialog box whyere they will be listed. In StrongED 4.6 there are 16 possible groups (1-16). In StrongED 4.7 this is increased to 32 (Group1 to Group32). There are also some named syntax words:

SyntaxWords Group1..32 [case|nocase] [StartOfLine|StartSpace] EndType
  list of words
End

• Group number relates directly to the colours section in the Mode Choices dbox.
• case|nocase defines whether the match is case sensitive or not.
• StartOfLine means we only match these words if they appear at the absolute start of the line
• StartSpace accepts them also if they are preceded by spaces.

Below is an example of how EndOfExpr could be used to do the same job as EndAsm. This would be slightly slower than EndAsm itself, but not noticeably so, since assembly is normally written one statement a line, meaning a full screen redraw would cause only about 40 matches against ee_asm.

Search
  ee_opt    "eq" | "ne" | "cs" | "cc" | "mi" | "pl" etc...
  ee_asm    [ee_opt] ["S" | "B" | "P"]
  ...
SyntaxWords Group1 EndofExpr {f*:ee_asm} nocase
  ADC ADD AND BIC CMN CMP EOR MLA MOV MUL
  ..

SyntaxWords Group8 StartOfLine EndOfLine nocase
>>>>    ">>> >"  ">> >>"  ">> > >"  "> >>>"  "> >> >"  "> > >>"  "> > > >"
">>>> " ">>> > " ">> >> " ">> > > " "> >>> " "> >> > " "> > >> " "> > > > "
End

As an example, I wondered whether it was possible to make URLs starting with other than https:// or www coloured and clickable. There are problems!

Tabstops

By default, Tabstops are only defined in the BaseMode.Modefile where the definition is:

Tabstops      3*

However much more complicated definitions are possible, for example:

Tabstops     1,2,[3,4]*5,6,7*3,8*

Should the cursor position be greater than the total of all tabstops then pressing the tab key will have no effect.

Tabstops can also be defined by setting StrongED$Tabstops = (definition) in the start of a file. See Options embedded in Files

TabStops insert the required number of spaces to tab to the appropriate column. It does nor affect the lenght of the dotted line display.

Example definition strings

WriteProtect