# Customizing TAB-completion and the Edit-dialog

All TAB-completions are defined in staticly read .xml-files. This means you can change most of the behaviour of the code-completion feature. After a restart of Eclipse, your changes will be immediately active.

Similarly, which building-blocks are displayed under which category in the Regular-Expression-Edit dialog is defined in .xml-files which can be changed.

There are ten .xml-files in the plugin-directory of QuickREx (to be found at the site of your Eclipse-installation under 'plugins/de.babe.eclipse.plugins.QuickREx_x.y.z' with x.y.z being the version installed on your machine:

- jdkCompletion.xml
- oroAwkCompletion.xml
- oroPerlCompletion.xml
- jregexCompletion.xml
- jakartaRegexpCompletion.xml

and

- jdkCategories.xml
- oroAwkCategories.xml
- oroPerlCategories.xml
- jregexCategories.xml
- jakartaRegexpCategories.xml

## The TAB-completion-configuration files

The files with the names "fooCompletion.xml" contain the definitions for the code-completion feature applicable to the corresponding regular-expression implementation (names should be obvious).

The following is an excerpt from the file jdkCompletion.xml which serves as an example for the explanation on what can be customized and how:

    	<completions>
    	  <proposal key="\\" value="\\" allowPlain="true" displayString="Backslash" additionalInfo="\\">
    	    <retrigger re=".*[^\\]\\$" completion="\"/>
    	    <retrigger re=".*\A\\$" completion="\"/>
    	  </proposal>
              ...
    	  <proposal key="?" value="?" allowPlain="false" displayString="Greedy match 0 or 1 times" additionalInfo="? - match the preceeding expression 0 or 1 times. &#x000A;&#x000A;Greedy: reads the whole input, tries to match &#x000A;and then (repeatedly) backs off by one character &#x000A;and tries again.">
    	    <retrigger re=".*[^\\]$" completion="?"/>
    	    <retrigger re=".*\\\\$" completion="?"/>
    	  </proposal>
              ...
    	  <proposal key="\P{Lower}" value="\P{Lower}" allowPlain="true" displayString="Not Lower-case alphabetic (US-ASCII)" additionalInfo="\P{Lower} - (US-ASCII) not lower-case alphabetic, [^a-z]">
    	    <wordtrigger word="\P{Lower" completion="}"/>
    	  </proposal>
              ...
    	</completions>

For any completion that is to be offered, there is an element <proposal> in the file. The following attributes are applicable and are all mandatory:

1. key: a unique key for the proposal (usually the proposal itself)
2. value: the full value of the proposal, i.e. the value that should be inserted if the completion is choosen and no part of the completion is typed yet (the "plain proposal")
3. allowPlain: can be 'true' or 'false' - flag to indicate whether the proposal should be offered if non of the triggers (see below) fires. This is 'false' e.g. for the multiplication-indicator ? in the above example, since we do not want to offer it if the expression currently is the empty String or ends with an excaped backslash (the situations where the triggers match for the proposal, see below for trigger-details
4. displayString: The String to display for the proposal in the TAB-completion pop-up
5. additionalInfo: The explanation to display in the hover if the proposal is selected in the pop-up

The proposal-element allows two kind of child-elements which define different types of triggers. These and their attributes are as follows:

- <retrigger> a Trigger/Mask based on regular expressions. Attributes are
  1. re: a regular expression (JDK-style) to be matched by the current contents of the regular expression field for the proposal to be applicable
  2. completion: the completion to be used if the regular expression matches
- <wordtrigger> a Trigger/Mask based on a String. Attributes are
  1. word: a String. If this String or a non-zero leading part of it is the last part of the current contents of the regular expression field, the proposal is applicable
  2. completion: the completion to be used if the full String in 'word' is at the end of the current contents of the regular expression field. If only parts of the 'word' are at the end of the field, the remainder of the word plus the completion is inserted

Now consider the examples in the above xml-snippet:

      <proposal key="\\" value="\\" allowPlain="true" displayString="Backslash" additionalInfo="\\">
        <retrigger re=".*[^\\]\\$" completion="\"/>
        <retrigger re=".*\A\\$" completion="\"/>
      </proposal>

This defines a proposal with the value "\\". This is the expression for matching a backslash in all implementations (the first \ escapes the second one). We want this proposal to be shown even if the input currently is empty - in fact we want it to be shown always. Thus, allowPlain="true" - the proposal is offered even if none of the triggers matches.

There are two kinds of trigger-expressions which would both result in only one "\" to be inserted (both have completion="\") if they are matched by the current contents and the proposal is selected. These are re=".*[^\\]\\$" and re=".*\A\\$", i.e. the current contents is anything ending with one but not two backslashes or is simply one backslash at the beginning of the input.

The next example is

      <proposal key="?" value="?" allowPlain="false" displayString="Greedy match 0 or 1 times" additionalInfo="? - match the preceeding expression 0 or 1 times. &#x000A;&#x000A;Greedy: reads the whole input, tries to match &#x000A;and then (repeatedly) backs off by one character &#x000A;and tries again.">
        <retrigger re=".*[^\\]$" completion="?"/>
        <retrigger re=".*\\\\$" completion="?"/>
      </proposal>

This defines a proposal with the value "?". This is the expression for matching the previous atom 0 or 1 times. We want this proposal to be shown only if there is an atom at the end of the input - at least one of the triggers should match. Thus, here allowPlain="false".

The triggers are re=".*[^\\]$" matching any non-empty input not ending with a single "\" (which should be followed by an escaped character) and re=".*\\\\$" matching anything ending with (at least two) backslashes. In both cases, completion="?" will be inserted.

In fact, the last example gives a hint on the complexity of regular expressions: of course, the current input could end with three backslashes - thus the first would escape the second one and the third would be an escaping backslash again. The second retrigger matches this, even though this is not what you would really want ("\\\?" would match "\?", the "?" would not be a multiplicity-operator).

There is a trade-off between simplicity and correctness in this case - I have decided for simplicity as QuickREx will tell you or show you whether the expression does what you expect it to do.

Finally, the last example is

      <proposal key="\P{Lower}" value="\P{Lower}" allowPlain="true" displayString="Not Lower-case alphabetic (US-ASCII)" additionalInfo="\P{Lower} - (US-ASCII) not lower-case alphabetic, [^a-z]">
        <wordtrigger word="\P{Lower" completion="}"/>
      </proposal>

This defines a proposal with the value value="\P{Lower}" - a JDK-variant expression matching any character other than lower-case characters in the standard US-ASCII alphabet (a-z). Again, this proposal is to be shown at any time, thus allowPlain="true".

The trigger in this case is an example of a wordtrigger. This is because for this proposal we want the trigger to fire for content ending with '\', '\P', '\P{', ... Since we would need to construct a lot of retriggers in this case, the wordtrigger is used. A wordtrigger matches if the content ends with some 0-based substring of the word-attribute. It adds the remainder of the word-attribute plus the contents of the 'completion'-attribute if selected.

## The category-configuration files

The files with the names "fooCategories.xml" contain the definitions for the categories and the mapping used for the Reg-Exp-Edit-dialog.

The information is structured as follows (example from jdkCategories.xml):

        <categoryMappings>
          <categoryMapping proposalKey="?" category="Multiplicities">
          </categoryMapping>
          ...
          <categoryMapping proposalKey="." category="Wildcards">
          </categoryMapping>
          ...
        </categoryMappings>

For all proposals as defined in the proposal-configuration-file for the corresponding flavour, this file defines whether they should be used in the edit-dialog at all and if so, under what list they should appear. It also defines, what categories are to be displayed at all for the flavour.

When the dialog is constructed, first all different "category"-attributes from the file are collected. For each category, a drop down is displayed. The order on the dialog (from top to bottom) is identical to the order of appearance in the .xml-file.

Then, the proposals are mapped to the categories as defined by the categoryMapping-elements. The proposals are displayed in the order of their appearance in the category-config file. For the drop-down, the value of the "displayString"-attribute from the proposal-config file (for the entry with proposal.key == categoryMapping.proposalKey) is used. The additional information-field in the dialog displays the value of the "additionalInfo"-attribute for the proposal. When "Insert" is pressed, the value of the attribute "value" from the proposal-file is inserted at the caret-position of the expression.

Thus, to change the category of some entry, change the "category"-attribute. To change the order of appearance, change the order in the file. (To change the order of the categories, change the orders of the first entries for the respective categories.) To remove something from the lists all together, remove the mapping from the file. And to have something new on the dialog, add the entry to the proposals- and the category-config-file.

## Roll your own, share it with others

Should you find improvements to the default completion-definitions which you feel might be interesting to others - or should you have a collection of ready-made regular expressions you want to share - please let me know. I would be happy to TAB-completion definitions on my web-space.