Extension:SyntaxHighlight/VisualEditor

SyntaxHighlight nodes in VisualEditor

SyntaxHighlight nodes are made editable via VisualEditor syntaxhighlight module. Although the module is related to SyntaxHighlight GeSHi, it doesn't use the extension for editing ‎<syntaxhighlight> blocks. Rather, the module only displays and manipulates parsed ‎<syntaxhighlight> block, provided by Parsoid, with it's own language highlighting and validating rules. A more straightforward relationship graph:

SyntaxHighlight GeSHi (wikitext) <--> Parsoid <--> syntaxhighlight module

The module's language rules are stored as JSON files, which will be described in detail below. All files mentioned below are under the module's folder, except where specified.

Language rules

Language rules are located under rules/. The file name should match the language name used by SyntaxHighlight GeSHi extension's lang="??". For example, JavaScript is javascript, plus the file extension .json, therefore javascript.json. For a certain language, highlighting and validating rules are stored in the same JSON file, with highlighting rules defined in "highlighter", and validating rules in "validator".

Regex objects are used to define matches that a certain rule can fit. Since JSON file is not ideal for storing regex objects, the "regex objects" in the rule files are string representations of javascript RegExp object, which will be parsed on load. For each regex, you should use one and only one capturing group to indicate which part will be linked with related CSS style.

Highlighting rules

Example:

{
	"match" : "/(\\+|-|\\*|\\/|%|\\!|@|&|\\||\\^|<|>|\\=|,|;|\\?|:|\\.)/g",
	"style" : "ve-ce-mwSynHi-symbol"
}

Each highlighting rule consists of a regex object ("match"), and a css class name ("style"). Use g modifier in your regex such that every match will be associated with the related CSS style. The CSS are defined in styles/ve.ui.MWSyntaxHighlight.css.

You can use SyntaxHighlight GeSHi highlighting definitions as a reference to create these rules.

Validating rules

Example:

{
	"match" : ["/([\\t ]+)$/gm"],
	"except" : [],
	"within" : [],
	"outside" : [],
	"decisionMaker" : "error",
	"style" : "ve-ce-mwSynHi-error",
	"tip" : "Trailing whitespace character"
}

Each validating rule consists of the following:

• "match": an array of regex objects. These regex objects will be parsed and passed to "decisionMaker" as parameters.
• "except": an array of regex objects. Use this to define certain patterns that you want to exclude from "match". Use [] to disable.
• "within": an array of regex objects. Use this to define ranges that are whitelisted. Any matches outside these ranges will be discarded. Use [] for default range, which is the entire code text.
• "outside": an array of regex objects. Use this to define ranges that are blacklisted. Any matches within these ranges will be discarded. Use [] to disable.
• "decisionMaker": a string that can be referenced to a helper method. Helper methods and reference list can be found in helpers/ve.ce.MWSyntaxHighlightValidator.js.
  • ve.ce.MWSyntaxHighlightValidator.roster: all helper methods are listed in this object, with key being the method name, and value being the reference to the method.
  • Helper methods: currently there are several helper methods available for validator. Each method acts as a decision maker that only checks one criterion.
    • Available methods:
      • 'error': simply style matches as errors.
      • 'balanceAA': balance the existence of the same token; validates 1-1 relationship.
      • 'balanceAB': balance the existence of two different tokens; validates 1-1 relationship.
      • 'matchAB': check the co-existence of two different tokens; validates n-1 relationship.
    • Making new helper method:
      • A helper method should take an array of RegExp objects as parameter, and validate a criterion based on the matches.
      • Since the helper is referenced via an object, the helper method should take a context parameter, such that the validator context is correctly referenced.
      • A helper method returns an object which defines whether there are errors and indices that should be styled. Example as following:

return {
	'needMarks' : true, // return true if there are errors
	'matches' : [] // return an array of matches if there are errors; an empty array if the code is validated.
};

• "style": a css class name. This style will be applied once "decisionMaker" returns places that need error marks.
• "tip": error tip that will be displayed when user hovers on the error.