ContextualSettings

ContextualSettings allow you to customize common actions for your particular syntax. 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 Cocoa API.

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>html, xml</language-context>
		<value>&lt;!--</value>
	</setting>

	<setting name="comment-multiline-end">
		<language-context>html, xml</language-context>
		<value>--></value>
	</setting>

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

	<setting name="comment-singleline-start">
		<language-context>html, xml</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 plug-in

If you want to leverage ContextualSettings, you will be able to define settings using a unique name and then access them with the Cocoa API 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.