Mode Central

The SubEthaEdit Mode File Format

General

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

Download the SubEthaEdit Mode Development Kit here. (Includes sample artwork for symbol images.)

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.

Scripts

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.

Structure

This is the structure of a SubEthaEdit mode bundle:

Begin with setting your modes name and copyright in Info.plist and InfoPlist.strings. If in doubt just replace "Template" with you mode's name and "Author" with your name.

Mode Settings

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

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>(((?&lt;!\\)(\\\\)*)|^)"</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>&lt;(?=script)</regex></begin>
                <end><regex>/script&gt;</regex></end>
    
                <import mode="Javascript" />

                <keywords id="Script Tags"  color="#881280" font-style="italic">
                    <regex>(\A&lt;\Z)</regex>
                    <regex>(&lt;/script[^&gt;]*&gt;)</regex>
                </keywords>

                <state id="Opening Script Tag" color="#881280" font-style="italic"
                  usesymbolsfrommode="HTML" useautocompletefrommode="HTML">
                    <begin><regex>\Ascript</regex></begin>
                    <end><regex>&gt;</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

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>

Autocomplete Dictionaries

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.