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.

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 In preparation
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 In preparation
Block of functions tied to menu/toolbar/key
Shortcuts Done
Block of shortcut definitions
ID_FirstChar To do
Simple set defining what an ID can start with
ID_Middle To do
Simple set defining the chars in the ID body
ID_LastChar To do
Simple set defining optional final char for ID
SyntaxWords In preparation
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
ClickListFoldParm1Functions
KeyListPrintFootPrintHead
ReplaceSearchShortcuts
SyntaxWordsTabstops 

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 NoCasethe 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.

This section is in preparation.

Functions

The functions section ties StrongED's functions to menu, toolbar icons and keypresses. There is a Functions Index listing available funtions.

HelpPath

A string describing which StrongHelp manuals should be searched. The manuals will be searched in the order they listed.

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.


ID_FirstChar

ID_LastChar

ID_Middle


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>
Printion the source of this html file results in: printhead/png
this may not be what you want - <StrongED$Tmp_FileName> includes the full path name. Other StrongED$Tmp_ include so it is easy enough to change StrongED$Tmp_FileName to StrongED$Tmp_FileLeaf

Replace

In this block can be defined any Replace expressions that will be called by name. The BaseMode contains only one:
replace/png

Syntax is the same as that for Advanced Replace


In this block can be defined any search expressions that will be called 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	<h1 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


SyntaxOptions


SyntaxWords

This section is quoted direct from StrongHelp and needs expanding.

These define groups of words that you want picked out in a particular colour. They are in Groups, where each Group relates directly to the Mode's choices -> Colours dialog box. In adition to 31 possible Groups (Group1 to Group32) there are also named syntax words

Text Tabs Ctrl Spaces
HardSpc Brackets Newlines Caret
Block Mark Border Margin
Hardwrap Linenumbers Identifiers Functions
Strings Comments Numbers Punctuation
SyntaxWords Group1..16 [case|nocase] [StartOfLine|StartSpace] EndType
  list of words
End
EndTypes are: For Assembly : The following EndTypes are considered obsolete and should no longer be used. They are still supported but simply map onto EndOfAsm. 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 {f/: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 ..

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, 03 Jul 2018 08:46:41 BST
© 2018 - 2018 Richard Torrens.