|
| 1 | +--- |
| 2 | +uid: 0ff35371-69b5-48dd-a062-037abe2469de |
| 3 | +alt-uid: ClassifierDefinition |
| 4 | +title: Defining Solution/Project Spell Check Classifiers |
| 5 | +keywords: classifier definition |
| 6 | +--- |
| 7 | + |
| 8 | +Unlike spell check as you type and the active document spell checking tool window, the |
| 9 | +solution/project spell checking tool window must classify the content of each and every file for itself to |
| 10 | +determine what parts need to be spell checked. To facilitate this process, a configuration file is used to |
| 11 | +define a well-known set of filename extensions and map them to an appropriate classifier definition. |
| 12 | + |
| 13 | + |
| 14 | +In the event that an unrecognized filename extension is encountered, the spell checking process looks |
| 15 | +at the content and tries to determine whether or not it is well-formed XML. If it is, it parses the content as |
| 16 | +XML. If not, it treats the file's content as plain text. |
| 17 | + |
| 18 | +<autoOutline lead="none" excludeRelatedTopics="true">2</autoOutline> |
| 19 | + |
| 20 | + |
| 21 | +## Classifier Types |
| 22 | + |
| 23 | +There are seven different types of classifier: |
| 24 | + |
| 25 | + |
| 26 | +- `PlainTextClassifier` - This is the simplest of the classifiers. It |
| 27 | +just returns all of the file's content as a single block to be broken up into words for spell checking. |
| 28 | +- `XmlClassifier` - This classifier is used to parse XML files and spell |
| 29 | +check them based on the active configuration settings. For example, it skips the inner text of unwanted XML |
| 30 | +elements and spell checks the values of attributes that have been specified as needing spell checking. This |
| 31 | +classifier can only be used on well-formed XML content. |
| 32 | +- `ResourceFileClassifier` - This is a variant of the XML classifier used |
| 33 | +for resource files (*.resx*). This classifier will automatically ignore certain non-words |
| 34 | +common to the default comments in resource files which describe the elements within it. It also automatically |
| 35 | +ignores `data` and `metadata` elements with a |
| 36 | +`type` attribute with any value or a `mimetype` attribute with |
| 37 | +"base64" in its value. These typically do not contain a value that should be spell checked. A common example is |
| 38 | +base 64 encoded image data. This prevents a number of unwanted issues being reported. |
| 39 | +- `ReportingServicesClassifier` - This is a variant of the XML classifier |
| 40 | +used for Reporting Services report files (*.rdl* and *.rdlc*). This |
| 41 | +classifier will automatically ignore various elements that should not be spell checked, will limit the content |
| 42 | +that is spell check in `Code` elements to comments and string literals, and will limit the |
| 43 | +content that is spell checked in expressions to literal strings. This prevents a number of unwanted issues being |
| 44 | +reported. |
| 45 | +- `HtmlClassifier` - This classifier is used to parse HTML files and works |
| 46 | +in a manner similar to the XML classifier. Unlike the XML classifier, this one can handle ill-formed content |
| 47 | +common to many HTML file types. |
| 48 | +- `MarkdownClassifier` - This classifier is identical to the HTML |
| 49 | +classifier but it is used on markdown files and excludes spans that look like inline or fenced code blocks. This |
| 50 | +helps reduce the number of false misspelling reports that can result in such spans. |
| 51 | +- `CodeClassifier` - This classifier is geared toward parsing code. It |
| 52 | +uses a series of regular expressions to identify file content that looks like code comments and literal strings. |
| 53 | +Once done, it takes additional steps to further classify different string literal types (i.e. verbatim and |
| 54 | +interpolated) as well as parsing XML documentation comment elements to remove sections that should not be |
| 55 | +spell checked and include attribute values that should. Expressions can be added to classify text as undefined. |
| 56 | +Such undefined spans are removed from other classified spans to reduce the number of false misspelling reports |
| 57 | +from the removed spans. |
| 58 | +- `ScriptWithHtmlClassifier` - This classifier is similar to the |
| 59 | +`CodeClassifier` described above but is specific to JavaScript and TypeScript files that |
| 60 | +contain embedded HTML elements. It will parse the code and also the HTML elements to include the wanted HTML |
| 61 | +element parts such as inner text and exclude the unwanted HTML elements parts such as ignored attribute values. |
| 62 | +- `RegexClassifier` - This is a general classifier that uses a series of |
| 63 | +regular expressions to classify file content as code comments or string literals. This is useful for non-code |
| 64 | +files such as style sheets or SQL scripts that do not require the extra classification steps performed by the |
| 65 | +`CodeClassifier` described above. |
| 66 | + |
| 67 | + |
| 68 | + |
| 69 | +## Classification Configuration Files |
| 70 | + |
| 71 | +The package comes with a standard configuration file that contains the current set of classifier |
| 72 | +definitions and recognized file types. By creating your own *Classifications.config* file in |
| 73 | +the spell checker's application data configuration folder (see below), you can add additional classifier |
| 74 | +definitions, override existing ones, and/or add additional recognized file types and map them to a classifier. |
| 75 | +The following sections describe the various elements found in the configuration file. For an example, see the |
| 76 | +package's [standard configuration file](https://github.com/EWSoftware/VSSpellChecker/blob/master/Source/VSSpellChecker/Classifications.config "Classifications.config"). This is also where you can see which file extensions are currently recognized and to which |
| 77 | +classifier they are being mapped. |
| 78 | + |
| 79 | + |
| 80 | + |
| 81 | +#### Classifications |
| 82 | + |
| 83 | +This is the root element. All other elements are nested within this one. |
| 84 | + |
| 85 | + |
| 86 | + |
| 87 | +#### Classifiers |
| 88 | + |
| 89 | +This element contains the classifier definitions. It consists of a set of |
| 90 | +`Classifier` elements that define the ID, type, and configuration for each one. |
| 91 | + |
| 92 | + |
| 93 | + |
| 94 | +#### Classifier |
| 95 | + |
| 96 | +This element defines a classifier. The `Id` element uniquely identifies |
| 97 | +the classifier. Typically, it will be set to a language name or content type. The `Type` |
| 98 | +attribute is used to indicate which type of classifier it will use. The value should be set to one of the |
| 99 | +classifier types described in the first section. If the classifier has configurable elements, they will be |
| 100 | +nested within this element. |
| 101 | + |
| 102 | + |
| 103 | +The `XmlDocCommentDelimiter` attribute can be used to define the XML |
| 104 | +documentation comment delimiter which can vary by language. For example, the C-style classifier defines it as |
| 105 | +`///` while the VB-style classifier defines it as `'''`. In a |
| 106 | +similar manner, the `QuadSlashDelimiter` attribute can be used to define the quad-slash |
| 107 | +delimiter and the `OldStyleDocCommentDelimiter` attribute can be used to define the |
| 108 | +delimiter for the older style of XML comments. Currently, these two options are only used by the C# classifier |
| 109 | +to exclude quad-slash commented code and to determine old-style XML commented code if so indicated in the C# |
| 110 | +configuration options. |
| 111 | + |
| 112 | + |
| 113 | +The `Mnemonic` attribute can be added to define the mnemonic character |
| 114 | +for user interface label text that indicates a hot key. Only the ampersand and underscore are recognized as |
| 115 | +valid mnemonic characters. If not specified, it defaults to the ampersand character. This is used when the |
| 116 | +Ignore Mnemonics option is enabled in the General Settings configuration category. |
| 117 | + |
| 118 | + |
| 119 | + |
| 120 | +#### Match |
| 121 | + |
| 122 | +This is a configuration element used by several of the classifiers to define a regular |
| 123 | +expression that will be used to find content and classify it accordingly. The `Expression` |
| 124 | +attribute is used to define the regular expression. The `Options` attribute is used to |
| 125 | +define one or more regular expression options that should be used with the expression. Specify a comma-separated |
| 126 | +list of [](@T:System.Text.RegularExpressions.RegexOptions) |
| 127 | +values as needed. If omitted, no options will be defined for the expression. The `Classification` |
| 128 | +attribute defines how the matched text is to be classified. Below are the most common classifications: |
| 129 | + |
| 130 | +- `DelimitedComments` - Delimited comments in code such as `/* Comments */`. |
| 131 | +- `SingleLineComment` - A single line comment such as `// Comment`. |
| 132 | +- `NormalStringLiteral` - A normal string literal such as `"A text string"`. |
| 133 | +- `RegionDirective` - A region directive such as `#region Private data members`. |
| 134 | +- `Undefined` - Some classifiers use this to mark spans of text that should be removed from other classifications |
| 135 | + to reduce false misspelling reports from unwanted text. |
| 136 | + |
| 137 | +There are several other classifications not typically used within the configuration files. |
| 138 | +These are used mostly by the classifiers themselves after parsing the file to further classify a range of text. |
| 139 | +For example, the code classifier will change the `NormalStringLiteral` classification to |
| 140 | +`VerbatimStringLiteral` or `InterpolatedStringLiteral` based on |
| 141 | +whether or not it has the appropriate prefix character before the opening quote. The code classifier will also |
| 142 | +reclassify `SingleLineComment` and `DelimitedComments` if necessary |
| 143 | +to handle XML documentation and quad-slash comment types when necessary. Typically, these subtypes will not |
| 144 | +appear within the classifier configurations. The `RangeClassification` enumerated type |
| 145 | +in the source code contains all of the currently defined range classifications used by the spell checker. |
| 146 | + |
| 147 | + |
| 148 | + |
| 149 | +#### Extensions |
| 150 | + |
| 151 | +This element contains the file type definitions that map file extensions to the classifiers. |
| 152 | +It consists of a set of `Extension` elements that define the extension and classifier for |
| 153 | +each one. As noted above, any extension not represented is tried first as XML and, if not XML, then as plain |
| 154 | +text. |
| 155 | + |
| 156 | + |
| 157 | + |
| 158 | +#### Extension |
| 159 | + |
| 160 | +This maps a specific file extension to a classifier definition. The `Value` |
| 161 | +attribute defines the extension without the leading period. The `Classifier` attribute |
| 162 | +defines the ID of the classifier to use for this file type. It should match the `Id` |
| 163 | +attribute value of a `Classifier` element defined earlier in the configuration file or one |
| 164 | +from the standard configuration file. |
| 165 | + |
| 166 | + |
| 167 | +An exception is the `None` classifier ID. This is technically not a |
| 168 | +classifier. It is a simple means of excluding certain file types from being spell checked. For example, the |
| 169 | +*aff* and *dic* file extensions are mapped to this classifier to prevent |
| 170 | +dictionary files from being spell checked. This is a convenient way of excluding a class of files from being |
| 171 | +spell checked in the solution/project spell checking process without having to exclude them explicitly in the |
| 172 | +global configuration or within each solution or project's configuration. |
| 173 | + |
| 174 | + |
| 175 | +> [!NOTE] |
| 176 | +> Extensions for binary file types do not need to be specifically excluded using the |
| 177 | +> `None` classifier. Binary files are automatically excluded from being spell checked prior |
| 178 | +> to reaching the point of determining the classifier type. |
| 179 | +> |
| 180 | +> |
| 181 | +
|
| 182 | + |
| 183 | +## Defining Your Own Classifier Configurations |
| 184 | + |
| 185 | +To define additional file extension mappings or to define your own classifiers for new file types, |
| 186 | +create a file in the *%LOCALAPPDATA%\EWSoftware\Visual Studio Spell Checker* folder |
| 187 | +called *Classifications.config*. In it, add the necessary sections as described above. If |
| 188 | +all you need to do is map file extensions to classifiers, just add an `Extensions` section |
| 189 | +and define the mappings. You can reuse the existing classifier IDs if you find one that will suit your needs. |
| 190 | + |
| 191 | + |
| 192 | +Redefining a classifier or an extension with an ID that appears in the standard configuration file |
| 193 | +will effectively replace its definition with yours. This is a convenient way to try out changes or fixes to the |
| 194 | +existing classifier expressions should you find an issue with them. |
| 195 | + |
| 196 | + |
| 197 | +> [!IMPORTANT] |
| 198 | +> Any changes made to the classifications configuration file will not take effect until Visual |
| 199 | +> Studio is restarted. |
| 200 | +> |
| 201 | +> |
| 202 | +
|
| 203 | +``` XML{title="Example Custom Configuration Files"} |
| 204 | +<Classifications> |
| 205 | + <!-- A simple example that maps new file types to existing classifier definitions --> |
| 206 | + <Extensions> |
| 207 | + <Extension Value="myext" Classifier="XML" /> |
| 208 | + <Extension Value="xyz" Classifier="HTML" /> |
| 209 | + |
| 210 | + <!-- Never spell check "xxx" files as part of the project --> |
| 211 | + <Extension Value="xxx" Classifier="None" /> |
| 212 | + </Extensions> |
| 213 | +</Classifications> |
| 214 | +``` |
| 215 | + |
| 216 | +``` XML{title=" "} |
| 217 | +<Classifications> |
| 218 | + <!-- An example of defining a new classifier type --> |
| 219 | + <Classifiers> |
| 220 | + <Classifier Id="SomeLanguage" Type="RegexClassifier"> |
| 221 | + <Match Expression="\s*#.*?[\r\n]{1,2}" Classification="SingleLineComment" /> |
| 222 | + <Match Expression="("")|(@"(.|[\r\n])*?"|"(.|\\"|\\\r\n)*?((\\\\)+"|[^\\]{1}"))" |
| 223 | + Classification="NormalStringLiteral" /> |
| 224 | + </Classifier> |
| 225 | + </Classifiers> |
| 226 | +
|
| 227 | + <Extensions> |
| 228 | + <Extension Value="abc" Classifier="SomeLanguage" /> |
| 229 | + </Extensions> |
| 230 | +</Classifications> |
| 231 | +``` |
| 232 | + |
| 233 | + |
| 234 | +## See Also |
| 235 | + |
| 236 | + |
| 237 | +**Other Resources** |
| 238 | +[](@fa790577-88c0-4141-b8f4-d8b70f625cfd) |
| 239 | +[](@df2a45c1-1996-46f6-9d33-e73f0fa1d88a) |
0 commit comments