Download Latest Version sf.eclipse.javacc-1.6.1-updatesite.zip (11.2 MB)
Email in envelope

Get an email when there's a new version of JavaCC Eclipse Plugin

Home / doc / Dev_guide / Projects / UI
Name Modified Size InfoDownloads / Week
Parent folder
README_UI.md 2023-07-04 20.9 kB
0
Totals: 1 Item   20.9 kB 0

sf.eclipse.javacc.ui project description

History

Created 02-03/2021. 1.6.0.

Source folders structure

  • src-plugin: source code:
    • .: constants
    • editors: editor and related features classes
    • filters: view filter for generated files
    • handlers: handlers for commands
    • head: implementations / extensions of base interfaces / classes for the head builds (the headless classes are in the sf.eclipse.javacc.core project)
    • options: projects JavaCC options classes (mostly for compiling)
    • parser: the internal JJT parser grammar and derived classes, for building trees
    • preferences: workbench JavaCC preferences classes (mostly text styling)
    • scanners: scanner classes for text styling
    • variables: classes for variables for string substitution
    • wizards: new grammar wizard classes
  • .settings: standard project settings files
  • doc: license file
  • icons: icons resources
  • META-INF: standard project META-INF files
  • templates: grammar resources for the new grammar wizard
  • /:
    • standard plug-in xml & i18n properties & project files
    • README file
    • about.xxx``andjavacc-pi-32.png` files for installation information

Classes naming conventions

Classes specialized on .jj/.jjt/.jjdoc/.jtb gammar files start with prefixes JavaCC, JJTree, JTB, JJDoc.
Classes extending Eclipse classes with the same name start with prefix J, otherwise have no specific prefix.

Plug-in Overview, Dependencies, Runtime, Extension Points, Build

The sf.eclipse.javacc.core plug-in is required (so is part of the dependencies).

This plug-in uses standard MANIFEST.MF manifest file.
It uses class UIPluginActivator, which extends AbstractUIPlugin, and delegates to the Core plug-in class JPlugin bundles and versions management.

Dependencies, runtime and build settings do not show anything non standard.
No extension points are defined.

Plug-in Extensions

This plug-in uses standard plugin.xml configuration file.
This plug-in uses 24 extensions. They are described below in a kind of inner to outer progression.
Plug-in classes are shown as code, and workbench API classes are shown in italics.

PropertyPage

point="org.eclipse.ui.propertyPages"
class="sf.eclipse.javacc.ui.options.JPropertyPage"

This extension adds the JavaCC Options page to properties pages of any project with JavaCC nature, managed by class JPropertyPage which extends PropertyPage and enables setting:

JPropertyPage sets up a TabFolder to show 5 tabs for these 5 classes.
GlobalOptions extends directly Composite.
The 4 others extend OptionsAbstractTab which extends Composite and implements a lot of (shared) methods.
These 5 classe uses IEclipsePreferences to store the project properties.

These 4 last classes use the Core plug-in classes OptionSet which manages a list of Option.
OptionSet provides a way to generate a command line string, which gathers all the non default individual options in a single String internal property (the first field displayed in the options tab), which is stored in the project properties and is used by Compiler when launching the compile command.

When building, command line options set at the project level override options set a the grammar level (in the options section), as the standard way JavaCC/JJTree/JJDoc/JTB do.
However, this feature is not very useful (specially when the project is under some CI/CD), and could be considered deprecated. So usually all is left to default values.
The real interest of these 4 tabs is to show the options currently managed by the plug-in.
Because the plug-in internal parser checks the grammar options and reports warnings for unknown (non managed) options.

ValueVariables and DynamicVariables

point="org.eclipse.core.variables.valueVariables"
initializerClass="sf.eclipse.javacc.ui.variables.ValueVariableInitializer"

point="org.eclipse.core.variables.dynamicVariables"
resolver="sf.eclipse.javacc.ui.variables.DynamicVariableResolver"

The static and dynamic variables defined in these extensions can be used to set paths in the Project Properties tabs through the Variables buttons (string substitution).
Managed through the ValueVariableInitializer and DynamicVariableResolver classes.

Document Setup Participant

point="org.eclipse.core.filebuffers.documentSetup"
class="sf.eclipse.javacc.ui.scanners.DocumentSetupParticipant"

This extension defines the document setup participant DocumentSetupParticipant which manages document partitioning (into code and comments partitions).

Editor

point="org.eclipse.ui.editors"
class="sf.eclipse.javacc.ui.editors.JJEditor"

This extension defines the class Editor used to edit the grammar files and to bind to the extensions.
Editor extends org.eclipse.ui.editors.text.TextEditor. Allows editing .jj/.jjt/.jtb grammar files.
Editor creates and uses many classes:

In <init> or in overriden methods, Editor:

  • creates a CharacterPairMatcher and a MatchingCharacterPainter which are used to highlight matching pairs

  • creates a JSourceViewerConfiguration, which is used by the workbench to configure:

  • creates a ReconcilingStrategy, which creates a SpellingContext, and when called by the workbench upon reconciling it calls the Editor to update itself and updates the spelling annotations (in an asynchronous thread) (it does only spell checking, not spell correction)

  • gets a ProjectionSupport to handle marker annotations

  • adds an inner EditorSelectionChangedListener to listen to selection changes on the document

  • initializes key bindings for the Editor_SCOPE_ID scope

  • creates an OutlinePage for displaying the grammar outline tree

  • creates an Elements kind of data class

  • tells the workbench to manage navigation history (allowing jumping to last edit locations)

On a selection changes Editor updates the outline page with the node corresponding to the new selection.

On a document modification ReconcilingStrategy calls back its Editor to perform updates: Editor :

  • reparses the (whole) document, with its internal JavaCCParser, building a tree of JJNode with a root, which is used to fill different maps in Elements
  • updates the outline page,
  • updates the call hierarchy view (see further this view)
  • updates the folding structure, through the ProjectionAnnotationModel model of the ProjectionViewer viewer and ProjectionAnnotation annotations which define foldable positions

OutlinePage:

Expressions Definitions, Commands, Handlers & Menus

point="org.eclipse.core.expressions.definitions"
point="org.eclipse.ui.commands"
point="org.eclipse.ui.handlers"
point="org.eclipse.ui.menus"

The expressions definitions extension define in a symbolic way where a command, handler or menu is available.
The handlers extension define the classes implementing the commands.
The menu contributions extension define the locations of the commands in the UI.

These extensions define 4 expressions definitions, 13 plug-in UI commands, 13 associated handlers, and 5 menu contributions.

The 4 expressions definitions are

  • javacc.inEditor.definition, for within an Editor
  • javacc.inViews.definition, for within the Package & Project Explorer views
  • javacc.folderInViews.definition, for on a IFolder in the Package & Project Explorer views
  • javacc.inEditorOrViews.definition, the union of the two first ones

The 3 Compile commands and handlers are available under an Editor and on .jj/.jjt/.jtb files in the Package & Project Explorer views:

  • extcompile for compiling jj/jjt/jtb files
  • jjdoccompile foc generating a jjdoc file
  • checkcompile for displaying the javacc and jtb help on the command line in the console

The 9 other commands and handlers are available under a Editor:

  • comment for commenting in/out source lines
  • format for formating source lines
  • gotorule for jumping to the definition
  • callhierarchy for showing the caller/callees tree in the Call Hierarchy View
  • contentassist for content assist
  • foldingcollapse, foldingcollapseall, foldingexpand & foldingexpandall for folding/unfolding source lines

The last command and handler are available on a folder in the Package & Project Explorer views:

  • deletederivedfiles for deleting all derived (generated) files in a folder/package

The 5 menu contributions define the commands for different locations:

  • the Workbench menu bar (locationURI menu:org.eclipse.ui.main.menu)
  • the Workbench toolbar (locationURI toolbar:org.eclipse.ui.main.toolbar)
  • the Editor and Views context (popup) menus (locationURI popup:org.eclipse.ui.popup.any)
  • the Package Explorer toolbar (locationURI toolbar:org.eclipse.jdt.ui.PackageExplorer)
  • the Project Explorer toolbar (locationURI toolbar:org.eclipse.ui.navigator.ProjectExplorer)

Context and Bindings

point="org.eclipse.ui.contexts"
point="org.eclipse.ui.bindings"

These extensions define an editor context (scope) (used in Editor.initializeKeyBindingScopes()) and bind commands to shortcut keys.

Markers, AnnotationTypes and MarkerAnnotationSpecification

point="org.eclipse.core.resources.markers"
point="org.eclipse.ui.editors.annotationTypes"
point="org.eclipse.ui.editors.markerAnnotationSpecification"

These extensions define the JavaCC markers annotations and link them to the workbench annotations.
They are managed though a ProjectionSupport in the Editor.
On a grammar file compilation, Compiler deletes the JavaCC markers on the file, then Console grabs the JavaCC / JJTree / JTB compilation errors, warnings and info messages through regular expressions in the console ouput, creates hyperlinks on these messages to the corresponding grammar source lines, and creates workbench marker annotations on these lines; these annotations are displayed as problem markers in the Problems and Markers views as well as in the Editor.

PreferencesPage and Preferences

point="org.eclipse.ui.preferencePages"
class="sf.eclipse.javacc.ui.preferences.PreferencePage"

point="org.eclipse.core.runtime.preferences"
class="sf.eclipse.javacc.ui.preferences.PreferencesInitializer"

These extensions add in the Workbench preferences the JavaCC preferences page and a way to initialize them.
Those preferences are mostly for editor text styling (syntax coloring, font attributes) and other editing features (colors, indentation, tooltips).
Remember that all other settings are done at the project level through the Project properties extension.
Class PreferencePage extends TabbedPreferencePage and implements IWorkbenchPreferencePage. On a preference change, all opened editors are updated to apply the changes.
Class PreferencesInitializer extends AbstractPreferenceInitializer.

Preferences are stored in an IPreferenceStore and can be accessed through NewActivator.getJPlugin().getPreferenceStore().

Views

point="org.eclipse.ui.views"

This extension defines 2 views through their associated implementations:

  • a Console View for JavaCC building output:

    class="sf.eclipse.javacc.ui.head.ConsoleView"

  • a Call Hierarchy view for grammar files:

    class="sf.eclipse.javacc.ui.editors.CallHierarchyView"

Class ConsoleView implements IConsole, extends ViewPart, and is used to show JavaCC building outputs.
A Console instance is accessed via NewActivator.getJPlugin().getConsole().
It uses a ConsoleHyperlink to manage hyperlinks from the view to the Editor.

Class CallHierarchyView is quite similar to OutlinePage and extends ViewPart and creates a TreeViewer to show the trees of callers / callees productions in a JavaCC grammar. It uses:

Decorator

point="org.eclipse.ui.decorators"
class="sf.eclipse.javacc.ui.head.Decorator"

This extension defines class Decorator of generated files.
Class Decorator extends LabelProvider, implements ILabelDecorator.
The added text is <gram.jj> for .java files if derived from gram.jj.
The added text is <gram.jjt> for .jj and .java files if derived from gram.jjt.
The added text is <gram.jtb> for .jj and .java files if derived from gram.jtb.
An icon 'G' (for Generated) is added on top right of the file icons.

JavaElementFilters, Common Navigator Framework content and viewer

point="org.eclipse.jdt.ui.javaElementFilters"
class="sf.eclipse.javacc.ui.filters.FilterGeneratedJavaCCFiles"

point="org.eclipse.ui.navigator.navigatorContent"
class="sf.eclipse.javacc.ui.filters.FilterGeneratedJavaCCFiles"

point="org.eclipse.ui.navigator.viewer"

These extensions define the class FilterGeneratedJavaCCFiles used to filter the generated files in the Package Explorer, the Navigator and the Project Explorer views.
These 3 views are not managed by the same workbench plug-ins and different extensions are needed to perform the same feature.

Note that isDerived() is used to filter the files.
If a user chooses to manually modify a generated file, at compiling JavaCC will show a warning and will not overwrite it, but the user should also uncheck the Derived property in the File Property / Resource to let the plug-in know this (and not decorate it).

New Wizard

point="org.eclipse.ui.newWizards"
class="sf.eclipse.javacc.ui.wizards.NewGrammarWizard"

This extension adds new elements in the new wizard mechanism for new JavaCC files, a category and an example file selection page.
Class NewGrammarWizard uses class NewGrammarWizardPage to handle the wizard selection dialog.
This last class heavily relies on restricted classes. Why? Looks like it was the only way to do it at the plug-in birth and has never been revisited since.

How to build

Compile the jjt/jj manually with the UI commands or automatically with the corresponding Builder if the JavaCC project nature is configured.

Build the html documents manually with the ant script build_ui_html.xml or automatically with the corresponding Builder.

Build the project for the update site though Admin_Guide.

Source: README_UI.md, updated 2023-07-04