NetBeans Manifest File Syntax Highlighting Module Tutorial

Creating Tokens

Do the following:

1. Create the file. Right-click the ManifestSupport project node, choose New > Java Class, and type ManifestTokenContext in Class Name. Click Finish. The new Java class opens in the Source Editor. Replace the default code with the following:

   package org.netbeans.modules.manifestsupport;
   
   import org.netbeans.editor.BaseTokenID;
   import org.netbeans.editor.TokenContext;
   import org.netbeans.editor.TokenContextPath;
   import org.netbeans.editor.Utilities;
   
   public class ManifestTokenContext extends TokenContext {
          
       // Numeric-ids for token categories
       public static final int NAME_ID = 1;
       public static final int COLON_ID = 2;
       public static final int VALUE_ID = 3;
       public static final int END_OF_LINE_ID = 4;
       
       // Token-ids
       public static final BaseTokenID NAME = new BaseTokenID("name", NAME_ID);
       public static final BaseTokenID COLON = new BaseTokenID("colon", COLON_ID);
       public static final BaseTokenID VALUE = new BaseTokenID("value", VALUE_ID);
       public static final BaseTokenID END_OF_LINE =
               new BaseTokenID("end-of-line", END_OF_LINE_ID);
      
       // Context instance declaration
       public static final ManifestTokenContext context = new ManifestTokenContext();
       public static final TokenContextPath contextPath = context.getContextPath();
       
       /**
        * Construct a new ManifestTokenContext
        */
       private ManifestTokenContext() {
           super("mf-");
           
           try {
               addDeclaredTokenIDs();
           } catch (Exception e) {
               Utilities.annotateLoggable(e);
           }
       }
   }

2. Understand the file. This Java class specifies a token for each item in the Manifest file with which we want to work. Each distinct item in a Manifest file is a token: 'name', 'colon', and 'value'. In addition, there is also a token for the end of the line, because we need to work with the end of the line—the end of the line determines where a value ends and the next name begins. The constructor above specifies that all tokens will be prefaced by 'mf-'. So, we've now created tokens called 'mf-name', 'mf-colon', 'mf-value', and 'mf-end-of-line'.

Creating Syntax

Do the following:

1. Create the file. Right-click the ManifestSupport project node, choose New > Java Class, and type ManifestSyntax in Class Name. Click Finish. The new Java class opens in the Source Editor. Replace the default code with the following:

   package org.netbeans.modules.manifestsupport;
   
   import org.netbeans.editor.Syntax;
   import org.netbeans.editor.TokenID;
   import org.openide.ErrorManager;
   
   public class ManifestSyntax extends Syntax {
       
       /**
        * The logger for this class. It can be used for tracing the class activity, 
        * logging debug messages, etc.
        */
       private static final ErrorManager LOGGER = 
               ErrorManager.getDefault().getInstance("org.netbeans.modules." +
               "manifestsupport.ManifestSyntax");
       
       /**
        * Used to avoing calling the log() or notify() method if the message 
        * wouldn't be loggable anyway.
        */
       private static final boolean LOG = 
               LOGGER.isLoggable(ErrorManager.INFORMATIONAL);
       
       // The states for the lexical analyzer
       
       private static final int ISI_NAME = 1; // inside the name part
       private static final int ISA_AFTER_NAME = ISI_NAME + 1; // immediately after the name part
       private static final int ISA_AFTER_COLON = ISA_AFTER_NAME + 1; // immediately after the 
                                                                      // colon between the name 
                                                                      // and the value
       private static final int ISI_VALUE = ISA_AFTER_COLON + 1; // inside the value part
       
       protected TokenID parseToken() {
           TokenID result = doParseToken();
           if (LOG) {
               LOGGER.log(ErrorManager.INFORMATIONAL, "parseToken: " + result);
           }
           return result;
       }
       
       private TokenID doParseToken() {
           char actChar;
           
           while (offset < stopOffset) {
               actChar = buffer[offset];
               
               switch (state) {
                   case INIT:
                       switch (actChar) {
                           case ':':
                               state = ISA_AFTER_COLON;
                               offset++;
                               return ManifestTokenContext.COLON;
                           case '\n':
                               state = INIT;
                               offset++;
                               return ManifestTokenContext.END_OF_LINE;
                           default:
                               state = ISI_NAME;
                       }
                       break;
                       
                   case ISI_NAME:
                       switch (actChar) {
                           case ':':
                           case '\n':
                               state = ISA_AFTER_NAME;
                               return ManifestTokenContext.NAME;
                       }
                       break;
                       
                   case ISA_AFTER_NAME:
                       switch (actChar) {
                           case ':':
                               state = ISA_AFTER_COLON;
                               offset++;
                               return ManifestTokenContext.COLON;
                           case '\n':
                               state = INIT;
                               offset++;
                               return ManifestTokenContext.END_OF_LINE;
                           default:
                               assert false;
                       }
                       break;
                       
                   case ISA_AFTER_COLON:
                       switch (actChar) {
                           case '\n':
                               state = INIT;
                               offset++;
                               return ManifestTokenContext.END_OF_LINE;
                           default:
                               state = ISI_VALUE;
                       }
                       break;
                       
                   case ISI_VALUE:
                       switch (actChar) {
                           case '\n':
                               state = INIT;
                               return ManifestTokenContext.VALUE;
                       }
                       break;
               }
               
               offset++;
           }
           
           /*
            * At this stage there's no more text in the scanned buffer.
            * It is valid to return a token here only if this is the last
            * buffer (otherwise the token could continue in the next buffer).
            */
           if (lastBuffer) {
               switch (state) {
                   case ISI_NAME:
                       state = INIT;
                       return ManifestTokenContext.NAME;
                   case ISI_VALUE:
                       state = INIT;
                       return ManifestTokenContext.VALUE;
               }
           }
           
           return null;
       }
       
   }

2. Understand the file. This Java class tells the IDE which part of the text is which token. It does this by starting in an initial state and sequentially looking at each character in the text and deciding if it stays in that state, moves to another state, or announces that a token was found.

   For example, for names the IDE starts in the initial state and the first time it encounters a valid character for a name, it enters the ISI_NAME state. It stays in this state until it encounters a \r, \n or : character, which cannot be part of a name. When it encounters such a character, the IDE knows that the characters it just traversed make up a name token. The code runs within a while loop. At the end there is a break statement, which increases the offset in the text. The return statement in the code avoids increasing the offset and ensures that the parsing of the next token, after a name, will start with this character (it will likely be a colon, which is a meaningful token itself). The break statement, on the other hand, ensures that offset is increased. When all the characters up to the colon are tested, the IDE knows whether the cursor is inside a name or not.

Giving the IDE a Reading Test

Do the following:

1. Create the file. Right-click the Unit Test Packages node, choose New > Java Class, type ManifestSyntaxTest in Class Name, and type org.netbeans.modules.manifestsupport in Package. Click Finish. The new Java class opens in the Source Editor. Replace the default code with the following:

   import java.util.Arrays;
   import java.util.Iterator;
   import java.util.List;
   import junit.framework.TestCase;
   import org.netbeans.editor.Syntax;
   import org.netbeans.editor.TokenID;
   import org.netbeans.modules.manifestsupport.*;
   import junit.framework.TestCase;
   
   public class ManifestSyntaxTest extends TestCase {
       
       public ManifestSyntaxTest(String testName) {
           super(testName);
       }
       
       public void testNextToken() {
   	doParse("Manifest-Version: 1.0", new TokenID[] {
               ManifestTokenContext.NAME,
               ManifestTokenContext.COLON,
               ManifestTokenContext.VALUE,
           });
           doParse("Manifest-Version: 1.0\n\n" + 
                    "OpenIDE-Module: org.netbeans.modules.manifestsupport\n", 
                    new TokenID[] {
              ManifestTokenContext.NAME,
              ManifestTokenContext.COLON,
              ManifestTokenContext.VALUE,
              ManifestTokenContext.END_OF_LINE,
              ManifestTokenContext.END_OF_LINE,
              ManifestTokenContext.NAME,
      	   ManifestTokenContext.COLON,
              ManifestTokenContext.VALUE,
              ManifestTokenContext.END_OF_LINE,
           });
       }
           
       public void doParse(String m, TokenID[] expected) {
           Syntax s = new ManifestSyntax();
           s.load(null, m.toCharArray(), 0, m.length(), true, m.length());
           
           TokenID token = null;
           Iterator i = Arrays.asList(expected).iterator();
           do {
               token = s.nextToken();
               if (token != null) {
                   if (!i.hasNext()) {
                       fail("More tokens returned than expected.");
                   } else {
                       assertSame("Tokens differ", i.next(), token);
                   }
               } else {
                   assertFalse("More tokens expected than returned.", i.hasNext());
               }
               System.out.println(token);
           } while (token != null);
       }
   }

2. Understand the file. This Java class checks that the IDE is able to correctly convert text to tokens. To run the test, right-click the project node and choose Run Unit Tests. The test should succeed, returning the following result in the JUnit Test Results window:

   

   You can play with the testNextToken() method to see what the IDE does when the entered text does not comply with the specified tokens. For example, change the method by deleting one of the token IDs (ManifestTokenContext.VALUE), so that the method looks as follows:

   public void testNextToken() {
      doParse("Manifest-Version: 1.0", new TokenID[] {
           ManifestTokenContext.NAME,
           ManifestTokenContext.COLON,
      });
   }

   Now there are more tokens than token IDs. (There are two token IDs here—ManifestTokenContext.NAME and ManifestTokenContext.COLON.) When you run the JUnit test, the message 'More tokens returned than expected.' is returned:

   

   Now change the method by deleting the colon between Manifest-Version and 1.0, as shown below:

   public void testNextToken() {
      doParse("Manifest-Version 1.0", new TokenID[] {
           ManifestTokenContext.NAME,
           ManifestTokenContext.COLON,
           ManifestTokenContext.VALUE,
      });
   }

   Now there are too few tokens. When you run the JUnit test, the message 'More tokens expected than returned.' is returned:

   

   Finally, let's test to see that the IDE understands more than just when there are too many or too few tokens—it should also know when a token is in the wrong place. Add the token that specifies the end-of-line. For example, here \n is added right after the name and before the colon:

   public void testNextToken() {
     doParse("Manifest-Version\n:1.0", new TokenID[] {
          ManifestTokenContext.NAME,
          ManifestTokenContext.COLON,
          ManifestTokenContext.VALUE,
     });
   }

   When you run the test, the following error is returned:

   

   Now that we know that the IDE correctly converts manifest entries into tokens, lets create an editor to work with Manifest files and associate colors with tokens.

Creating the EditorKit

Do the following:

1. Create the file. Right-click the ManifestSupport project node, choose New > Java Class, and type ManifestEditorKit in Class Name. Click Finish. The new Java class opens in the Source Editor. Replace the default code with the following:

   package org.netbeans.modules.manifestsupport;
   
   import javax.swing.text.Document;
   import org.netbeans.editor.BaseDocument;
   import org.netbeans.editor.Syntax;
   import org.netbeans.editor.SyntaxSupport;
   import org.netbeans.modules.editor.NbEditorKit;
   import org.openide.ErrorManager;
   
   public class ManifestEditorKit extends NbEditorKit {
      
       public static final String MIME_TYPE = "text/x-java-jar-manifest"; // NOI18N
       
       /** 
        * Creates a new instance of ManifestEditorKit 
        */
       public ManifestEditorKit() { 
       }
       
       /**
        * Create a syntax object suitable for highlighting Manifest file syntax
        */
       public Syntax createSyntax(Document doc) {  
           return new ManifestSyntax();
       }
       
       /**
        * Retrieves the content type for this editor kit
        */
       public String getContentType() {
           return MIME_TYPE;
       }
   }

2. Understand the file. This Java class specifies an EditorKit specifically for a NetBeans editor. Therefore, it extends the NBEditorKit class. An editor kit establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content. In this case, the editor is for content that uses the text/x-java-jar-manifest MIME Type.

Creating the Syntax Coloring

Do the following:

1. Create the file. Right-click the ManifestSupport project node, choose New > Java Class, and type ManifestSettingsInitializer in Class Name. Click Finish. The new Java class opens in the Source Editor. Replace the default code with the following:

   package org.netbeans.modules.manifestsupport;
   
   import java.awt.Color;
   import java.awt.Font;
   import java.util.Map;
   import org.netbeans.editor.BaseKit;
   import org.netbeans.editor.Coloring;
   import org.netbeans.editor.Settings;
   import org.netbeans.editor.SettingsDefaults;
   import org.netbeans.editor.SettingsNames;
   import org.netbeans.editor.SettingsUtil;
   import org.netbeans.editor.TokenCategory;
   import org.netbeans.editor.TokenContext;
   import org.netbeans.editor.TokenContextPath;
   
   public class ManifestSettingsInitializer 
           extends Settings.AbstractInitializer {
       
       public static final String NAME = 
               "manifest-settings-initializer"; // NOI18N
       
       /**
        * Constructor
        */
       public ManifestSettingsInitializer() {
           super(NAME);
       }
       
       /**
        * Update map filled with the settings.
        * @param kitClass kit class for which the settings are being updated.
        *   It is always non-null value.
        * @param settingsMap map holding [setting-name, setting-value] pairs.
        *   The map can be empty if this is the first initializer
        *   that updates it or if no previous initializers updated it.
        */
       public void updateSettingsMap(Class kitClass, Map settingsMap) {
           if (kitClass == BaseKit.class) {
               new ManifestTokenColoringInitializer().
                       updateSettingsMap(kitClass, settingsMap);
           }
           
           if (kitClass == ManifestEditorKit.class) {
               SettingsUtil.updateListSetting(
                       settingsMap,
                       SettingsNames.TOKEN_CONTEXT_LIST,
                       new TokenContext[] 
               { ManifestTokenContext.context }
               );
           }
       }
       
       /**
        * Class for adding syntax coloring to the editor
        */
       /** Properties token coloring initializer. */
       private static class ManifestTokenColoringInitializer 
               extends SettingsUtil.TokenColoringInitializer {
           
           /** Bold font. */
           private static final Font boldFont = 
                   SettingsDefaults.defaultFont.deriveFont(Font.BOLD);
           /** Italic font. */
           private static final Font italicFont = 
                   SettingsDefaults.defaultFont.deriveFont(Font.ITALIC);
           
           /** Key coloring. */
           private static final Coloring keyColoring = 
                   new Coloring(boldFont, Coloring.FONT_MODE_APPLY_STYLE, 
                   Color.blue, null);
           /** Value coloring. */
           private static final Coloring valueColoring = 
                   new Coloring(null, Color.magenta, null);
           /** Colon coloring. */
           private static final Coloring colonColoring = 
                   new Coloring(null, Color.DARK_GRAY, null);
           /** Empty coloring. */
           private static final Coloring emptyColoring = 
                   new Coloring(null, null, null);
           
           
           /** Constructs PropertiesTokenColoringInitializer. */
           public ManifestTokenColoringInitializer() {
               super(ManifestTokenContext.context);
           }
           
           
           /** Gets token coloring. */
           public Object getTokenColoring(TokenContextPath tokenContextPath,
                   TokenCategory tokenIDOrCategory, boolean printingSet) {
               
               if(!printingSet) {
                   int tokenID = tokenIDOrCategory.getNumericID();
                   
                   if(tokenID == ManifestTokenContext.NAME_ID) {
                       return keyColoring;
                   } else if(tokenID == ManifestTokenContext.VALUE_ID) {
                       return valueColoring;
                   } else if(tokenID == ManifestTokenContext.COLON_ID) {
                       return colonColoring;
                       
                   }
               } else { // printing set
                   return SettingsUtil.defaultPrintColoringEvaluator;
               }
               
               return null;
           }
           
       } // End of class ManifestTokenColoringInitializer.
       
   }

2. Understand the file. This Java class sets the default colors for our tokens. Thanks to the supporting files described in the following sections, the user will be able to use the Options window to change the defaults.

Creating the Color Restorer

Do the following:

1. Create the file. Right-click the ManifestSupport project node, choose New > Java Class, and type RestoreColoring in Class Name. Click Finish. The new Java class opens in the Source Editor. Replace the default code with the following:

   package org.netbeans.modules.manifestsupport;
   
   import org.netbeans.editor.LocaleSupport;
   import org.netbeans.editor.Settings;
   import org.openide.modules.ModuleInstall;
   import org.openide.util.NbBundle;
   
   public class RestoreColoring extends ModuleInstall {
       
       /**
        * Localizer passed to editor.
        */
       private static LocaleSupport.Localizer localizer;
       
       /**
        * Registers properties editor, installs options and copies settings.
        * Overrides superclass method.
        */
       public void restored() {
           addInitializer();
           installOptions();
       }
       
       /**
        * Uninstalls properties options.
        * And cleans up editor settings copy.
        * Overrides superclass method.
        */
       public void uninstalled() {
           uninstallOptions();
       }
       
       /**
        * Adds initializer and registers editor kit.
        */
       public void addInitializer() {
           Settings.addInitializer(new ManifestSettingsInitializer());
       }
       
       /**
        * Installs properties editor and print options.
        */
       public void installOptions() {
           // Adds localizer.
           LocaleSupport.addLocalizer(localizer = new LocaleSupport.Localizer() {
               public String getString(String key) {
                   return NbBundle.getMessage(RestoreColoring.class, key);
               }
           });
       }
       
       /** Uninstalls properties editor and print options. */
       public void uninstallOptions() {
           // remove localizer
           LocaleSupport.removeLocalizer(localizer);
       }
       
   }

2. Understand the file. This Java class is used to install the module and maintain its state. In addition to creating it, you must specify this class in the module's manifest file, by adding the following line:

   OpenIDE-Module-Install: org/netbeans/modules/manifestsupport/RestoreColoring.class

   Note that the OpenIDE-Module-Install key belongs at the end of the first section (it is highlighted in bold below):

   Manifest-Version: 1.0
   OpenIDE-Module: org.netbeans.modules.manifestsupport
   OpenIDE-Module-Layer: org/netbeans/modules/manifestsupport/layer.xml
   OpenIDE-Module-Localizing-Bundle: org/netbeans/modules/manifestsupport/Bundle.properties
   OpenIDE-Module-Specification-Version: 1.0
   OpenIDE-Module-Install: org/netbeans/modules/manifestsupport/RestoreColoring.class
   
   Name: org/netbeans/modules/manifestsupport/dataobject/ManifestDataLoader.class
   OpenIDE-Module-Class: Loader

Creating the Supporting Files

In this section, you update the Options window to allow the user to customize the way the tokens are presented in the IDE. Not only the colors, but also the font type and style, and the Manifest editor itself, can then be modified by the user in the Options window.