ExampleMode

Documentation:

The SubEthaEdit Mode File Format - an Example: Example.seemode

Example.seemode is a fully functional SubEthatEdit 4 mode. It can be uses as a starting point into how modes work and where to look for specific information.

It contains files that define the properties of a language that should be recognized for syntax highlighting, additional information for autocompletion support and symbol recognition to fill the symbol popup. It can also contain release notes, custom scripts for that mode, an example file and information on the file extensions that are relevant for the mode's language or file type.

SubEthaEdit's mode files are bundles, like e.g. Keynote presentations or rich text with images (rtfd). This enables you to include custom images, a license or other files you want to within the mode. It also ensures extensibility for further mode specific features, like plugins and the like.

RegEx Tips

• test your expressions with SubEthaEdit's Find All in RegEx mode
• case sensitivity can be set to ignore by including (?i) in your expression
• if you get stuck somewhere with a regular expression, have a look at the modes included with SubEthaEdit or in this repository

SEEMode Tips

• hold ⌥ option and click in the Menu: Mode → Show In Finder submenu to reveal modes that are already in SubEthaEdit in the Finder
• open a mode bundle with SubEthaEdit to be prompted if you want to install it or rather show the package contents (you can also right click a mode bundle and choose Show Package Contents in the context menu)

Notes on XML Escaping

The ampersand character (&) and the left angle bracket (<) must not appear in their literal form, except when used as markup delimiters, or within a comment, a processing instruction, or a CDATA section. If they are needed elsewhere, they must be escaped using either numeric character references or the strings " &amp; " and " &lt; " respectively. The right angle bracket (>) may be represented using the string " &gt; ", and must, for compatibility, be escaped using either " &gt; " or a character reference when it appears in the string " ]]> " in content, when that string is not marking the end of a CDATA section.

In the content of elements, character data is any string of characters which does not contain the start-delimiter of any markup and does not include the CDATA-section-close delimiter, " ]]> ". In a CDATA section, character data is any string of characters not including the CDATA-section-close delimiter, " ]]> ".

To allow attribute values to contain both single and double quotes, the apostrophe or single-quote character (') may be represented as " &apos; ", and the double-quote character (") as " &quot; ".

(from: XML 1.0 - Character Data and Markup)

Characters that might need to be escaped are:

• & → &
• > → <
• < → >
• " → "
• ' → '

Regular expression strings get less legible with ecaped characters so make sure to un-escape (at least in your head) before checking or changing them.
If your regular expression needs a lot of XML related escaping think about using a CDATA section. The following three examples are equivalent:

<autoend>&lt;/\g&lt;xmltagstatename>></autoend>
<autoend>&lt;/\g&lt;xmltagstatename&gt;&gt;</autoend>
<autoend><![CDATA[</\g<xmltagstatename>>]]></autoend>

Example Bundle:

This is the folder structure of Example.seemode and all the included files:

* Example.seemode/
|	* Contents/
|	|	* Info.plist
|	|	* Resources/
|	|	|	* AutocompleteAdditions.txt
|	|	|	* ChangeLog.txt
|	|	|	* CustomImage.png
|	|	|	* CustomImage@2x.png
|	|	|	* ExampleSyntax.txt
|	|	|	* ModeSettings.xml
|	|	|	* NewTemplate.txt
|	|	|	* RegexSymbols.xml
|	|	|	* ScopeExamples.plist
|	|	|	* Scripts/
|	|	|	|	* HelloThere.scpt
|	|	|	* SyntaxDefinition.xml
|   |   |   * WebPreview.js

Bundle Structure

The following reperesents the general structure of a SubEthaEdit mode bundle.
Files and folders that can be added for additional mode features but are not necessary are marked as (optional).
Files in italics are optional custom files without special rules for their naming.

• <modename>.seemode/ -- Mode Bundle - contains all files to describe a language/file type
  • Contents/
    • Info.plist
    • Resources/
      • AutocompleteAdditions.txt (optional)
      • ChangeLog.txt -- see: Additional Files
      • en.lproj/ (optional) -- it is possible to localize modes
        • InfoPlist.strings
        • …
      • ExampleSyntax.txt (optional)
      • ModeSettings.xml (optional)
      • RegexSymbols.xml (optional)
      • ScopeExamples.plist (optional)
      • WebPreview.js (optional)
      • SyntaxDefinition.xml
      • NewTemplate.txt -- see: ModeSettings.xml
      • CustomImage.png -- see: RegexSymbols.xml
      • License.txt -- see: Additional Files
      • Scripts/ (optional)
        • customscript.script -- see: Scripts
      • …

ExampleSyntax.txt

When selecting the style sheet for this mode in Preferences: Styles the content of this file is used to fill the preview.
This file is optional.

Additional Files

Additionally to the mode format specific files the mode bundle can contain custom files like Release notes or a Read me.
The file that is used for template content has a custom name by which it is referenced in the ModeSettings.xml.
Files that are used as symbol icons in the symbol popup are also referenced by name in RegexSymbols.xml.