-
Notifications
You must be signed in to change notification settings - Fork 19
Mode File Format SubEthaEdit 3.x documentation
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. To show its contents ctrl-click on the mode and choose "Show Package Contents".
If you get stuck somewhere with a regular expression, have a look at the modes included with SubEthaEdit. The easiest way to get there is to hold option and click in the Menu "Mode → Show In Finder". The quickest way to put a supplied mode it into your ~/Library/Application Support/SubEthaEdit/Modes folder for customization is as follows:
- Hold option and click in the Menu "Mode → Show In Finder → Open SubEthaEdit Modes Folder"
- Double click the mode you want to customize
- Choose install for this user only
- Hold option and click in the Menu "Mode → Show In Finder" and click on the mode you just installed.
Modes can also contain Scripts in their Resources/Scripts directory that add features, toolbar icons and menu items to SubEthaEdit. For detailed instructions regarding this functionality please consult the scripting page.
ModeSettings.xml is used to configure the mode's triggers, i.e. the extensions, filenames and content it handles. Content (like a shebang) can be configure via a regular expression and will be compared to the first 4MB of a file. These Triggers can be turned on or off in the Modes Preference Pane. The Precedence can be set by rearranging the mode order in that Pane.
<?xml version="1.0" encoding="UTF-8"?>
<settings>
<template>mytemplate.txt</template> <!-- Provide a template for File->new -->
<recognition>
<extension>txt</extension> <!-- Add file extensions -->
<extension casesensitive="yes">C</extension> <!-- Add case sensitive file extensions -->
<filename>Makefile</filename> <!-- Add filenames -->
<regex>\A#!/usr/bin/(env )?perl</regex> <!-- Add regex of content -->
</recognition>
</settings>
Syntax definitions are xml files of the structure as shown in the following paragraph. Please read the comments to learn about the tags used.
<?xml version="1.0" encoding="UTF-8"?>
<syntax>
<!--
The <head> tag encloses some global information about the mode.
This tag is required.
-->
<head>
<!--
The <name> specifies the modes name.
This tag is required and must match with the name in the plist after the SEEMode..
-->
<name>Example Syntax</name>
<!-- optional to add spelling-dicitionary autocomplete words -->
<autocompleteoptions use-spelling-dictionary="yes" />
<!-- optional to define the folding level for ctrl-command-up (default is 1) -->
<folding toplevel="2" />
<!--
The <charsintokens> and the <charsdelimitingtokens> instruct the syntax highlighter
where to tokenize the text for fast finding of plain strings.
The <charsintokens> tag specifies the characters that can occur in strings,
the <charsdelimitingtokens> tag specifies the tags that cannot occur in strings.
One of these tags has to be specified.
Tip: Use CDATA here.
-->
<charsintokens><![CDATA[_0987654321abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ@]]></charsintokens>
<!-- <charsdelimitingtokens><![CDATA[ -]]></charsdelimitingtokens> -->
<!--
the <charsincompletion> defines characters used for autocompletion. e.g. in perl
you want this to include the $ sign to autocomplete variables.
If left out the regular expression word boundaries are used.
-->
<!-- <charsincompletion><![CDATA[_0987654321abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-@$</=>!]]></charsincompletion> -->
</head>
<!--
The <states> tag encloses all syntax states.
States are areas of the test that begin and end with an regex like comments or strings,
with exception of the default state, that exists anywhere where no other state exists.
This tag is required.
-->
<states>
<!--
The <default> tag specifies what is colored within the default state (see above).
It features the following attributes, all optional if not noted otherwise:
id
Has to be a unique string. Has to be specified.
color
a html comptible color in three or six letter hexadecimal format.
Used for text on bright document background colors.
inverted-color
a html comptible color in three or six letter hexadecimal format.
Used for text if a dark document background color is set.
font-weight
normal Normal font-weight (default)
bold Bold text in popup
font-style
normal Normal font-weight (default)
italic Bold text in popup
usesymbolsfrommode
a mode name to use the symbol recognition from
when left out the value is inherited from the parent state
useautocompletefrommode
a mode name to use the autocomplete from - default is this mode
when left out the value is inherited from the parent state
type
a string description of the type. currently only the values
"string" and "comment" have meaning and cause bracket matching
and syntax highlighting to ignore these areas of text
and code folding has special handling for comments
foldable
yes makes this state foldable
no means this state does not fold (default)
-->
<default id="Base" color="#000" inverted-color="#fff">
<!--
The <keywords> tag specifies keyword groups within the current state.
It features the following attributes, all optional if not noted otherwise:
id
Has to be a unique string. Has to be specified.
color
a html comptible color in three or six letter hexadecimal format.
Used for text on bright document background colors.
inverted-color
a html comptible color in three or six letter hexadecimal format.
Used for text if a dark document background color is set.
font-weight
normal Normal font-weight (default)
bold Bold text in popup
font-style
normal Normal font-weight (default)
italic Bold text in popup
casesensitive
yes This group is case sensitive (default)
no Ignore case for the group
useforautocomplete
yes Add this group's strings to the autocomplete dictionary (default)
no Don't add to autocomplete dictionary
-->
<keywords id="Keywords" color="#6C0540" casesensitive="no" useforautocomplete="yes">
<!--
<string> tags specify plain text to be colored. If your tag does not
get colored, check in <charsintokens> if you are tokenizing correctly.
-->
<string>colorme</string>
<string>andmetoo</string>
<!--
<regex> tags specify regular expression to be colored.
Only the first group will be colored, so enclose the part to color
with parens.
The example colors digits prefixed by foo. (only the digits)
-->
<regex>foo([0-9])</regex>
</keywords>
<keywords id="Other keywords" color="#400080" font-weight="bold" font-style="italic">
<string>foo</string>
<string>bar</string>
</keywords>
<!--
The <state> tag specifies a state other than the default state.
It features the same attributes as <default>.
It has to contain a <begin> and a <end> tag which in turn have to
contain a <regex> tag. They can contain <keywords> tags like specified above.
For example here a states for C blockcomments, C++ singleline comments and strings.
The strings state handles escaped quotes with a lookbehind regular expression
(see a regex tutorial) and colors "foobar" with strings.
-->
<state id="Comment" color="#236E25" font-style="italic">
<begin><regex>/\*</regex></begin>
<end><regex>\*/</regex></end>
</state>
<state id="SingleComment" color="#236E25" font-style="italic">
<begin><regex>//</regex></begin>
<end><regex>[\n\r]</regex></end>
</state>
<state id="String" color="#760f15">
<begin><regex>"</regex></begin>
<end><regex>(((?<!\\)(\\\\)*)|^)"</regex></end>
<keywords id="Other keywords" color="#400080" font-style="italic">
<string>foobar</string>
</keywords>
</state>
<!--
The <import> tag lets you import substates and keywords from other modes.
It features the following attributes, all optional if not noted otherwise:
mode
the mode to import from if left out it will import from this mode
state
the state to import - if left out the content of the
default state will be imported
keywords-only
'yes' if you only want to import the keywords and not the substates
of that state
-->
<state id="Inline Javascript" color="#000" usesymbolsfrommode="Javascript"
useautocompletefrommode="Javascript">
<begin><regex><(?=script)</regex></begin>
<end><regex>/script></regex></end>
<import mode="Javascript" />
<keywords id="Script Tags" color="#881280" font-style="italic">
<regex>(\A<\Z)</regex>
<regex>(</script[^>]*>)</regex>
</keywords>
<state id="Opening Script Tag" color="#881280" font-style="italic"
usesymbolsfrommode="HTML" useautocompletefrommode="HTML">
<begin><regex>\Ascript</regex></begin>
<end><regex>></regex></end>
<import mode="XML" state="Tags" />
</state>
</state>
<!--
The <state-link> tag lets you reuse complete states including the
begin and end regex as well as the attributes on the linked .
It features the following attributes, all optional if not noted otherwise:
state
the state to link - not optional
mode
the mode to import from if left out it will import from this mode
-->
<state-link state="PHP" mode="PHP-HTML" />
</default>
</states>
</syntax>
Symbol Definitions are xml files of the structure as shown in the following paragraph. Please read the comments to learn about the tags used.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE syntax SYSTEM "symbol.dtd">
<symbols>
<!--
The <symbol> tag specifies what is being shown in the function popup.
It features the following attributes, all optional if not noted otherwise:
id
Has to be a unique string. Has to be specified.
image
Specify an image includes in the application (no extension) or
specify an image in this modes Resources directory (with extension)
SubEthaEdit comes with the following images:
Symbol#, SymbolC, SymbolE, SymbolF, SymbolF(), SymbolG, SymbolK,
SymbolL, SymbolM, SymbolP, SymbolS, SymbolT, SymbolV, SymbolWarn
indentation
0-15 The level of indentation
font-weight
normal Normal font-weight (default)
bold Bold text in popup
font-style
normal Normal font-style (default)
italic Italic text in popup
The example shows an symbol name "First example" with the image SymbolM
and an indentation of 1.
-->
<symbol id="First Example" image="SymbolM" indentation="1">
<!--
The regex tag specifies the regular expression that is search for this
symbol. It contains a Ruby-flavored regular expression. If groups is
specified in the regular expression the first group is used for the
find string. Escape unwanted groups with (?:).
This tag has to be specified.
Tip: Test your expressions with SubEthaEdits "Find All" command.
Tip: Case sensitivity can be set to ignore by including (?i) in your
expression.
-->
<regex>(function[^\n\r]*)</regex>
<!--
The postprocess tag specifies the find and replaces that should
be executed on the found string. You can use groups like \1 and the
like. It contains a Ruby-flavored regular expression.
This tag is optional.
The example search all strings enclosed by parens and replace them
with a empty string. Then it searches all occurances of "foo" and
replaces them with "bar".
-->
<postprocess>
<find>\([^\)]*\)</find>
<replace></replace>
<find>foo</find>
<replace>bar</replace>
</postprocess>
</symbol>
<symbol id="Second Example" font-weight="bold" image="SymbolF" indentation="0">
<regex>foobar</regex>
</symbol>
</symbols>
AutocompleteAdditions.txt is a text file containing one completion at a line. Here is the place for strings you want to show up in the autocomplete function, that are not a keyword in the syntax definition. If you don't want or need additional autocomplete strings just delete this file.