CslModularization

Contents

Current CSL status

Mixed API/SPI

The API/SPI of CSL is intemixed. Conceptually, CSL itself has no or close to no APIs, since its main purpose is to adapt modules (SPI implementations) to the standard raw APIs which are seen as rather complex. Currently SPI types intended for plugin implementations are mixed in API package with real callable APIs.

Convolution with other modules

CSL provides an integration platform and layer between a language and core APIs. Therefore CSL is tightly bound to all the target APIs and is hard to maintain - CSL needs to adapt to changes of all those APIs.

Poor extensibility

CSL design exhibits certain lack for extensibility from language plugins. For example folding types, or coloring types cannot be extended by individual languages. Implementors must unnaturaly transpose their language's needs to Java, which the CSL definitions were originally derived from.

Viral Architecture

The architecture of CSL can be seen as 'viral' - a CSL-based language support does not cooperate with non-CSL languages well. For example, CSL attempts to solve embedding, but solution is already provided by standard Lexer and Parser APIs. While it's beneficial to base language support on CSL, on the other hand it blocks language module's capability to integrate with non-CSL modules.

Dependency Nexus

CSL is designed as a central point for implementations of different features. Therefore it contains dependencies on all those features. Languages which would like to use just a certain support, such as Java or XML would be forced to have full dependencies required

Code Duplication

Code duplication and overlaps can be seen in CSL and non-CSL languages, which could be consolidated if only CSL APIs were shaped differently. The APIs should be more open - instead of integration platform the APIs should rather provide supports and adaptors to the real raw APIs (e.g. syntax highlighting).

Features and Enhancements

Code Completion

Go to type (symbol)

Edit Lists / History

Hints

Rules

Instant Rename

Find in File (occurences)

Method overrides

Commenting

Commenting in CSL needs changes - not just one option to comment line (php has 2 #, //) and uncommenting when line comment is not exactly at the beginning of the line.

Commenting action in Java is quite independent and simple (editor.lib ExtKit). It could be changed to use more robust commenting when CSL - commenting will go to different module.

Navigation

Filters are hardcoded - static, non-public, fields, inherited.

Enumerations

The following enumerations are used by CSL:

  • semantic highlight - ColoringAttributes
  • element kinds - ElementKind
  • folding kinds - does not have constants
  • modifiers

According to input from CSL clients, they would like to have the set of element types extensible, but still present typesafe constants. Extensibility should be limited to the language defining module only; although other API should anticipate possible extensions, notably for all-values or string-to-value queries. If we find a compelling use-case, we might open a SPI for extending the set of values.

Note that kinds for folding and elements (structure) could be merged: CSL infrastructure could then easily imply folding based on pure structure client SPI with minimal intervention of the client.

Highlighting

  • HTML and CSS provide their own internal dispatch: why ?
  • ColoringAttributes is not extensible. However we need a common base for coloring, so it can be centrally controlled. E.g. thre will be a keyword-like ColoringAttribute in most languages.
  • handles embeddings
    • coloring combinations are cached for each language separately
  • runs on top of parser result

CSL requires clients to register with CSL, and does not do any significant coordination / computation except cycling through embeddings (see Registration). The only added feature is that an embedding might replace outer language's highlight for exactly the same area - as a side effect of implementation. If an embedded language would be about to alter outer's highlight, it should merge or replace subranges of the outer highlight, not exactly equal ranges

ColoringManager can be kept separately, as per-MIME type coloring flyweight factory + translation of coloring requests using user font/color settings. It should be exposed in the Editor MIME lookup.

The SemanticHighlighter can be changed as follows:

  • CSL client will produce Map<OffsetRange, Coloring> as usual
  • SemanticHighlighter will create a HighlightsLayer around the CSL client
    • create flyweight colorings through ColoringManager shared for the whole language
    • translate Colorings through user preference colors
    • schedule the highlight task
    • adjust highlight positions, according to edits - this should be shared across all such coloring layers for a document.

Performance might be affected comparing to current impl: in the current impl, theoretically all highlighters even from embedded languages operate on one GSF Highlighter layer and share one Edit adjusment cache. When the highlighters are directly registered on Editor APIs, there will not be a man-in-the-middle who coordinates them all under one document.readLock. The current implementation updates the colorings under document.readLock(), then tracks all subsequent edits; similar approach could be implemented, with a window of remembered edits sliding as individual contributions (from highlighter instances) are updated.

Java Support

Java support contains its own copy of ColoringManager; this copy should be merged with CSL and Java support should depend on the CSL base module

Data Object, Data Loader

According to PHP, CSS, HTML guys, they are limited by the fact that CSL grabs DataObject for their files. CSL provides just very basic file operations at the moment, and editing support

TBD - exact issues with GsfDataObject

Features provided by CSL:

  • dataloader registration + data object. Zero cost for module developers
  • handleCopyRename
  • editor support (all the SaveCookie, EditCookie, OpenCookie etc)
    • this means inability to intercept/override the cookie implementations

CSL users would like to retain the ability to have DataObject "for free" for simple cases, on the other hand, creating a DataObject + DataLoader is not a terrible tasks with current templates. If we provide CSL users with features now implemented by GsfDataObject, we may entirely drop this part of CSL and require that users create their own DL+DOs.

DataObjectLoader is easy to avoid by using DataLoaderPool.factory() support for declarative, MIME-based DataLoaders.

The editor support is mostly covered by SimpleES from openide API; except for adding FileObject as document attribute - openide does not provide such customization. Some Document processing callback could be added to OpenIDE, and the whole GsfDataObject could be discarded or replaced with stock implementations. A CSL user may register a Dataloader factory with lower order (higher priority) than the CSL default support - this renders the pseudoAPI of language.useCustomEditorKit obsolete.

Documentation steps must be written, so users understand how to register a DataObject, how to write a DataLoader which can step in and steal e.g. files with a certain contents, or declaration (netty vs. plain PHP files), how to include stock EditorSupport in their DOs.

Registration

Current GSF support requires a central registration in form of a GsfLanguage implementation. This approach has the following issues:

  • connects too many unrelated features in one class, prevents modularization of CSL client code
  • does not allow to enhance an existing support - the GsfLanguage must be changed

The registration mechanism itself is no more powerful than Mime Lookup. The mechanism should be changed so that CSL core searches for a certain SPI interface in the MimeLookup. Easy registration of a service class should be done by:

  • using @MimeRegistration annotation - an existing API in Mime lookup API module. This form of registration does not provide any attributes, just the service itself.
  • using a customized annotation, which could as well define certain (constant) attributes of the registration, which would have to be provided by the service otherwise. Attributes like preferredExtension

Most of DefaultLanguageConfig could be replaced by simple @MimeRegistration.

EditorKit

  • standard common actions
  • key interceptor, bracket completion
    • Old editor API is used - should be changed
  • goto XXX action


Structure

  • 'StructureItem'
    • type enum - inextensible
    • icon support - poor extensibility

Folding

Current folding support allows to identify foldable parts, as FoldInfos, based on j.s.t.Position. Unlike Java support, fold infos do not contain guarded area, although Folding API supports such a thing.

Folds could have been connected to StructureItems, which describe (block) structure of the document in an abstract way. Typically some of the structural items are foldable. Note there are notable exceptions, which does not contribute to the structure, however create foldable elements:

  • comments
  • documentation (attached to elements, initial comment, ...)
  • "here" docs

So the structure scan could eventually produce more than just the basic structure, and just a part of it could be presented in a Navigator window

Languages register their StructureScanner with CSL. CSL adapts StructureScanner to FoldingManager API. CSL drives the scanning. Inner languages are looked up in CSL registry -> if inner language does not support CSL, it is not processed; but this is perhaps natural. Other way: inner language supports CSL, outer does not: the embedding does not simply work.

Goal: allow embedded language to seamlessly participate on the outer one. See section 'Registration' for general pattern, which should be usable for this case.

XML Support

XML now implements folding on its own, in a simple form. Each time folds are re-scanned, all folds are replaced, their state trashed - folded XML elements now expands after each edit in the XML document.

Java Support

Java folding could eventually migrate to this infrastructure, but scheduling of Java Folding scanner currently does not use Parsing API. This part of Java would have to migrate to Parsing API first, in order to fully use CSL infrastructure. Note that parsing API does not support all the features the Java support utilizes, namely Phases and Priorities.

CSL FoldManager could be separated into 'planning' and 'updating' classes, or planning methods could be overridable; in that case, Java could reuse the diff/commit behaviour of CSL - java+CSL implementation could merge. Java folding support would retain its proprietary scheduling implementation.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo