This page is currently under construction. Comments and questions are welcome

Syntax of a ModeFile

An individual Mode is defined in a single directory. Within this directory the ModeFile governs how StrongED looks and behaves. The ModeFile contains everything that is too cumbersome to have in the ModeChoices dialog box, so everything but a few Choices.

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 Done
A string to determine how a text should be folded
HelpPath Done
A string describing which StrongHelp manuals to search.
PrintHead Done
A string to come at the top of a printout
PrintFoot Done
A string to come at the bottom of a printout
Tabstops Done
A string defining the width of each column #-
OnLoad Done
A list of functions executed when a file is loaded
KeyList Done
Block of functions tied to keys
Search Done
Block of named search expression definitions
Replace Done
Block of named replace expressions
Functions Done
Block of functions tied to menu/toolbar/key
Shortcuts Done
Block of shortcut definitions
ID_FirstChar Done
Simple set defining what an ID can start with
ID_Middle Done
Simple set defining the chars in the ID body
ID_LastChar Done
Simple set defining optional final char for ID
SyntaxWords Done
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 Done
Block of matchpatterns tied to functions
WriteProtect To do
A list of path patterns that should be loaded write protected
All sections are optional. For instance the BaseMode has the following sections
PrintHeadPrintFootTabstops
SearchSyntaxWordsReplace
FoldParm1ClickListKeyList
FunctionsShortcuts 
Most sections consist of a list, one entry per line, which starts with the section name and terminate with "End". Other sections are single line so do not have an "End" marker.

Bitmap


ClickList

You can define many clicklists, as long as you give them unique names. Four names have special meanings: These four lists will be checked when you single or double-click with either the Select or the Adjust button. These and any other lists, can be used via the ClickList function.

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

Syntax of a ClickList

ClickList [name]
  search-name   List of functions
End
Thus in the BaseMode file you will find two ClickLists. The first is:
clicklist/png

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
and in the search section you would put:
Search
  FileSys   "ADFS" | "RAM" | "SCSI" | "SDFS"
  FileName  FileSys "::" {~(Ctrl|White) Any}+
end

Fold Parameters

Two Fold Parmameters can be defined: FoldParm1 and/or FoldParm2. These define how a fold should be executed.

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)
All the parameters are named, StartOfLine and NoCase being internally defined and the other names being defined in the Search section:

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

In editing this text, I decided that folding would be useful. So I entered into the HTML ModeFile:
Foldparm2	("<H",,,nocase)
This folds, showing <H Headings as the fold points.

Functions

The Functions section of the ModeFile is similar to the ClickList and KeyList sections in that it ties a list of internal functions to a toolbar icon or a menu item. However many line do not call a Function but define other actions.

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
Other items in the block are all optional and may include any of the following:
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 Control + 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 picks out start tags such a <a or <span. It will of course also pick out non-tags such as <z

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	>
Notice the space after the z - this colours the whole of a tag, including any class definition.

KeyList

The KeyLists - for there can be many of them in a the BaseMode - define how the keyboard relates to the working of StrongED.

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")
Another example, in HTML mode:
key_html/png
These are all e.g. ctrl-shift-Key and set up the key combination to read and insert the relevant files which will probably be in !StrED_cfg.UserPrefs.Modes.HTML.Files where they can easily be changed to suit your own rquirements. It is well worth viewing the ModeFiles you frequently use to see what goodies have already been thus defined.

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\>
The OnLoad keyword can be used to automatically execute a list of commands every time a file is loaded. No ModeFiles as supplied include the command. Execution of the OnLoad function is controlled on a mode by mode basis in the ModeLock File

PrintHead and PrintFoot

Format
PrintHead     <String to send to printer>
PrintFoot     <String to send to printer>
The BaseMode is the only mode that has these pre-defined. So unless you define them in other modes the header and footer (if printed) will default to:
PrintHead     |i|i |m
PrintFoot     |m|i----  ----
The string is passed through OS_GSTrans so you can use system variables such as Sys$Time, Sys$Date and Sys$Time. In addition you can use the variables defined by the Function SetTmp, StrongED also defines the variable StrongED$Tmp_Page which holds the page number of the page being printed.

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
gives a header:
Centred

and The default, as defined in BaseMode is

PrintHead   <StrongED$Tmp_FileName>|i|i<Sys$Time> <Sys$Date> <Sys$Year>
Printing the source of this html file that you are reading results in: printhead/png
this may not be what you want - <StrongED$Tmp_FileName> includes the full path name. However other available StrongED$Tmp_ variables include so it is easy enough to change StrongED$Tmp_FileName to StrongED$Tmp_FileLeaf or whatever you want.

Replace

In this block can be defined any Replace expressions that will be called by name.

The BaseMode contains only one:
replace/png

The syntax is the same as that for Advanced Replace


In this block can be defined any search expressions that you may want to call by name.

Syntax of the block is

Search
  name   Expression
  ..
End
where Expression is a valid search expression as explained in Advanced Search and Replace. There are four uses for named search expressions;
  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

Shortcuts are otherwise known as Macros - short bits of text that, when typed, will be expanded into the full version.

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:
html_shorts/png
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.
If \@ is not present, the caret will be placed at the end of the inserted text.
If there are several \@ markers present, then the caret will be moved to the next when you press return.

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 cursor reaches this numbered \@ marker, the (expanded) word before the position it refers to is copied to the cursor.

Example 1

Thus if we have this shortcut:
  ``f    function \@()\n-- end of \@0
Then, after typing ``f and the function name we might have:
  function Foobar()
  -- end of
The cursor will be just after Foobar. If we now hit return the cursor will be moved to after 'end of ' and the word before the first \@ will be copied there, in this case 'Foobar', so that we end up with:
  function Foobar()
  -- end of Foobar

Example 2

In writing this html page, I have headings thus:
<h2 id="Shortcuts">Shortcuts</h2>
So I now have added the shortcut
	<<h2	<h2 id="\@">\@0</a>\n\@
To get the above heading all I would then type would be
 <<h2Shortcut
followed by Return twice.

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

This section is in preparation.

SmartIndent

This section is quoted direct from StrongHelp and needs expanding.

Syntax

SmartIndent
	IndentSize	
	IndentChar	
	OutdentChar	
	IndentAfter	
	OutdentLine	
End
The SmartIndent section provides two ways to make StrongED indent text automatically. It is possible to use both methods at the same time, in that case the indent characters take precedence over the indent expressions. For both methods IndentSize determines by how much the indent will be increased/decreased.

The current line is re-indented when Return is pressed by seeing if there's a match against any of the definitions. If so, the indent of the current line is increased or decreased by IndentSize as appropriate.

Please note that SmartIndent works best with the option 'Automatic indent after Return' in the Edit section of the Mode Choices is turned on. However you can use SmartIndent with the option turned off.

Indent characters

The first way is by defining a pair of characters, IndentChar and OutdentChar.

When Return is pressed StrongED checks if the previous line ends with the IndentChar. If so, the indent of the current line is increased by IndentSize.

Next StrongED checks if the current line starts with the OutdentChar (which may be preceded by whitespace). If so, StrongED scans backwards through the text to find the matching IndentChar taking nesting into account. If a match is found the indent of the current line is set to be the same as the line producing the match.

This method is useful for languages that use certain characters to delimit blocks of code, such as curly braces in C.

Indent expressions

The second way is by defining two (advanced) search expressions, IndentAfter and OutdentLine.

When Return is pressed StrongED checks if the previous line matches IndentAfter. If so, the indent of the current line is increased by IndentSize.

Next StrongED checks if the current line matches OutdentLine. If so, the indent of the current line is decreased by IndentSize.

Example

The example below shows the expressions used to indent the Lua language.
SmartIndent Case
	IndentSize	2
	IndentAfter	< {" "} ("do" | "if" | "elseif" | "else" | "for" | "function" | "repeat" | "while") \s
	OutdentLine	< {" "} ("end" | "elseif" | "else" | "until") \s
End

SyntaxComment

This section is quoted direct from StrongHelp and needs expanding. SyntaxComment [1 | 2] CommentType OneLine | MultiLine | (Recursive) StartWhere Anywhere | StartLine | StartSpace StartWith String EndWith String End

This tells the syntax colouring routines what a comment looks like. Two can be defined. The parameters are described below, defaults are shown in italics. *CommentType* specifies how far a comment spans. /OneLine/ Comments spans just one line, e.g. REM in BASIC. MultiLine Comments can span several lines, e.g. /*..*/ in C. Recursive Comments can span several lines, they can also be nested. *StartWhere* defines where on a line a comment can start. /AnyWhere/ Comments can start anywhere on a line. StartLine Comments must be right at start of line. StartSpace As above but may be preceded by whitespace. *StartWith* String that a comment will start with. *EndWith* String that a comment will end with. /Notes/ Recursive comments are not yet supported. Previously /CommentType/ was called /Type/ which is still supported but deprecated. The EndWith part is optional, if omitted it'll default to end-of-line for OneLine and to end-of-text for MultiLine/Recursive comments.


SyntaxOptions

This section is quoted direct from StrongHelp and needs expanding.

Various options for the syntax colouring routines.

SyntaxOptions

SingleQuote yes|no 'String'
DoubleQuote yes|no "String"
QuoteQuote yes|no "String with ""Quote"""
SplitString yes|no Can a string continue on next line?
QuoteChar char Which char is used to prefix quotes & such?
HexPrefix string After this a hexadecimal number follows
HexSuffix string Terminates a hexadecimal number
BinPrefix string After this a binary number follows
BinSuffix string Terminates a binary number
Numbers Off|Int|Flt|Exp Determines which numbers are coloured
Functions None|NoSpace|Spaces|White Determines what may separate a function name from '('
End

SyntaxWords

This section is quoted direct from StrongHelp and needs expanding.

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:

Text Tabs Ctrl Spaces
HardSpc Brackets Newlines Caret
Block Mark Border Margin
Hardwrap Linenumbers Identifiers Functions
Strings Comments Numbers Punctuation
Format:
SyntaxWords Group1..32 [case|nocase] [StartOfLine|StartSpace] EndType
  list of words
End
where EndTypes are:
EndAlways Accept now
EndNonID Accept if next char is not in the ID_Middle set
EndOfID Accept and continue until first non-id char
EndOfLine Accept and continue until end of line
EndOfExpr /name/ Accept and match against the search expression /name/
For Assembly :
EndOfAsm Accept if it's a valid instruction
EndOfFlt Accept if it's a valid instruction
The following EndTypes are considered obsolete and should no longer be used. They are still supported but simply map onto EndOfAsm.
EndAsm Accept if rest matches [condition] [B | P | S]
EndSTM Accept if rest matches [condition] direction
EndBL Accept if rest matches [L] [condition]. Use for B and BL

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
  ..
As an example consider the SyntaxWords section of the NewsMode file. Of particular interest are groups 5 to 8 where four different colours are used for different quoting levels. The fourth level is


SyntaxWords Group8 StartOfLine EndOfLine nocase
>>>>    ">>> >"  ">> >>"  ">> > >"  "> >>>"  "> >> >"  "> > >>"  "> > > >"
">>>> " ">>> > " ">> >> " ">> > > " "> >>> " "> >> > " "> > >> " "> > > > "
End
These definitions include every variation of four < signs and single spaces. Note that to incl;ude a space in the word to be highlighted you must enclose that word in double quote marks.

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*

The tabstop string consists of a series of elements separated by commas. Each element can be either a number or a substring enclosed in '[..]', which can be nested. An element can be followed by a repeat count, prefixed by '*'. If the last element has a repeat count indicator ('*') but has no repeat count, then that means that the element will be repeated indefinitely as required.

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

3,5*4,8*one 3 char column, then four 5s and then 8s forever
[6,9]*Alternating 6 and 9 char columns
[3*2,5*3]*4Two 3s then three 5s, repeated four times and then no more
[[4*3,5]*2,7]*An endless series of 4, 4, 4, 5, 4, 4, 4, 5, 7

WriteProtect


Other relevant pages

Top of page


Page Information

http://css.torrens.org/valid-html401-bluehttp://css.torrens.org/valid-css Document URI: http://stronged.torrens.org/man/modes/syntaxmodefile.html
Page first published Wednesday the 13th of June, 2018
Last modified:Tue, 18 Sep 2018 08:42:06 BST
© 2018 - 2018 Richard Torrens.