MacRabbit

ContextualSettings

ContextualSettings allow you to customize common actions for your particular syntax. For instance, the most common usage is to instruct Espresso on how to properly comment out code for the built-in Un/Comment action.

It is possible for other actions to leverage contextual settings, typically for general-use actions created with the CocoaAPI.

Comments

Since defining comments is the most common reason to use ContextualSettings, we will use it as a general example. Although the name of the file doesn’t matter, by convention it is called Comments.xml:

<?xml version="1.0" encoding="UTF-8"?>
<settings>

    <
setting name="comment-multiline-start">
        <
language-context>htmlxml</language-context>
        <
value><!--</value>
    </
setting>

    <
setting name="comment-multiline-end">
        <
language-context>htmlxml</language-context>
        <
value>--></value>
    </
setting>

    <
setting name="comment-multiline-end-inert">
        <
language-context>htmlxml</language-context>
        <
value>--*></value>
    </
setting>

    <
setting name="comment-singleline-start">
        <
language-context>htmlxml</language-context>
        <
no-value/>
    </
setting>
    
</
settings

The names of each setting should be fairly self-explanatory. The “comment-multiline-end-inert” setting is used if the user wraps a comment inside of another comment (the internal comment will use the inert ending value).

Custom settings for your Sugar

If you want to leverage ContextualSettings, you will be able to define settings using a unique name and then access them with the CocoaAPI to determine what your action should do for the given syntax context.

In addition to <language-context>, you can instead filter settings using the <syntax-context> element, which takes a normal syntax zone selector.