Package org.eclipse.xtext.formatting2

Class AbstractFormatter2

java.lang.Object

org.eclipse.xtext.formatting2.AbstractFormatter2

All Implemented Interfaces:

IFormatter2

Direct Known Subclasses:

AbstractJavaFormatter

public abstract class AbstractFormatter2
extends java.lang.Object
implements IFormatter2

This is an abstract base class for language-specific formatters.

It is the formatters responsibility to create a list of text replacements, which, when applied to a text document, increase the documents readability for humans. At the same time the text changes should not have an impact on the semantic model a parser would create from the document.

Formatters based on this class compute text replacements in two logical steps: First, they traverses the semantic model and collect text replaces. Each replacer is responsible for a (small) section of the document. In a second step, the replacers are executed from the beginning to the end of the document and create the actual text replacements. This decoupling allows it to traverse the semantic model in arbitrary order and yet compute information that requires sequential processing of the document, e.g. indentation.

To allow subclasses to implement this mechanism conveniently, there are several helper classes:

• ITextRegionAccess allows to obtain text regions for elements in the semantic model.
• ITextReplacer creates replacements for a specific region in the document.
• IFormattableDocument collects replacers and validates if they overlap.

A formatter based on this class typically uses the ITextRegionAccess to obtain the IHiddenRegion which precedes or trails semantic object, features, keywords, or rule calls. This IHiddenRegion represents the whitespace, newlines and comments between semantic tokens. No matter if there are zero or N hidden tokens between two semantic tokens, there is always exactly one IHiddenRegion. In other words, the IHiddenRegion groups all hidden tokens between two semantic tokens.

For the IHiddenRegion, the formatter will create a ITextReplacer and store the replacer in the IFormattableDocument. Typically this is a HiddenRegionReplacer parameterized with an IHiddenRegionFormatting. The HiddenRegionReplacer will then delegate to a WhitespaceReplacer or CommentReplacer, depending on which kind of tokens are inside the hidden region.

To format a document with syntax confirming to the parser rule:

 Entity:
        'entity' name=ValidID '{'
                features+=Feature*
        '}';
 

the following formatter implementation (Xtend code) can be used:

        def dispatch void format(Entity entity, extension IFormattableDocument document) {
                val open = entity.regionFor.keyword("{")
                val close = entity.regionFor.keyword("}")
                entity.regionFor.feature(ABSTRACT_ELEMENT__NAME).surround[oneSpace]
                entity.superType.surround[oneSpace]
                open.append[newLine]
                interior(open, close)[indent]
                format(entity.getSuperType(), document);
                for (Feature feature : entity.features) {
                        feature.format
                        feature.append[setNewLines(1, 1, 2)]
                }
        }
 

For the full example, see the DomainModel Example. It can be accessed via Eclipse -> File -> New -> Example.

The class Entity is part of the semantic model.

The method calls regionFor.feature() and regionFor.keyword() are using extension methods: ITextRegionExtensions.regionFor(EObject) and ISemanticRegionFinder.keyword(String) respectively ISemanticRegionFinder.feature(EStructuralFeature). They return an ISemanticRegion.

The methods prepend(), append() and surround() are extension methods from IFormattableDocument. They create and register an HiddenRegionReplacer for the IHiddenRegion before and/or after the provided ISemanticRegion.

Override create*() methods to customize formatter-local services.

This implementation is stateful and cannot be used in parallel.

Since:

2.8

See Also:

The package for an introduction to the topic, : the interface to invoke the formatter, The method should be overridden to implement a formatter, The method should be overridden to set values of member fields, The method should be overridden to cleanup after execution.

Field Summary

Fields

Modifier and Type	Field	Description
protected ITextRegionExtensions	textRegionExtensions	Offer subclasses access to the methods from ITextRegionAccess as extension methods.

Constructor Summary

Constructors

Constructor	Description
AbstractFormatter2()

Method Summary

Modifier and Type	Method	Description
protected void	_format(java.lang.Object obj, IFormattableDocument document)	Fall-back for types that are not handled by a subclasse's dispatch method.
protected void	_format(java.lang.Void obj, IFormattableDocument document)	Fall-back for subclasses that accidently try to dispatch over null values.
protected void	_format(org.eclipse.emf.ecore.EObject obj, IFormattableDocument document)	Fall-back for types that are not handled by a subclasse's dispatch method.
protected void	_format(XtextResource resource, IFormattableDocument document)	For resources, assume we want to format the first EObject from the contents list only.
ITextReplacer	createCommentReplacer(IComment comment)
IFormattableDocument	createFormattableRootDocument()
IFormattableSubDocument	createFormattableSubDocument(ITextSegment region, IFormattableDocument parent)
IHiddenRegionFormatter	createHiddenRegionFormatter(IHiddenRegionFormatting formatting)
IHiddenRegionFormatter	createHiddenRegionFormatter(IHiddenRegionFormatting f1, IHiddenRegionFormatting f2)
IHiddenRegionFormatting	createHiddenRegionFormatting()
IMerger<IHiddenRegionFormatting>	createHiddenRegionFormattingMerger()
ITextReplacer	createHiddenRegionReplacer(IHiddenRegion region, IHiddenRegionFormatting formatting)
ITextReplacerContext	createTextReplacerContext(IFormattableDocument document)
IMerger<ITextReplacer>	createTextReplacerMerger()
ITextReplacer	createWhitespaceReplacer(ITextSegment hiddens, IHiddenRegionFormatting formatting)
abstract void	format(java.lang.Object obj, IFormattableDocument document)	Implement this method to create a language-specific formatter.
java.util.List<ITextReplacement>	format(FormatterRequest request)	Execute the formatter.
<T> T	getPreference(TypedPreferenceKey<T> key)
ITypedPreferenceValues	getPreferences()
FormatterRequest	getRequest()
ITextRegionAccess	getTextRegionAccess()
protected IFormattableDocument	handleTraceMissing(IFormattableDocument problematic, RegionTraceMissingException e)
protected void	initalize(FormatterRequest request)	Deprecated.
protected void	initialize(FormatterRequest request)	Overwrite this method to initialize member fields before format(Object, IFormattableDocument) is called.
protected boolean	isInRequestedRange(org.eclipse.emf.ecore.EObject obj)
protected java.util.List<ITextReplacement>	postProcess(IFormattableDocument document, java.util.List<ITextReplacement> replacements)
protected void	reset()	Overwrite this method to clean up member fields after format(Object, IFormattableDocument) has been called.
boolean	shouldFormat(java.lang.Object obj, IFormattableDocument document)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

textRegionExtensions

@Extension
protected ITextRegionExtensions textRegionExtensions

Offer subclasses access to the methods from ITextRegionAccess as extension methods.

Constructor Detail

AbstractFormatter2

public AbstractFormatter2()

Method Detail

_format

protected void _format(java.lang.Object obj,
                       IFormattableDocument document)

Fall-back for types that are not handled by a subclasse's dispatch method.

_format

protected void _format(org.eclipse.emf.ecore.EObject obj,
                       IFormattableDocument document)

Fall-back for types that are not handled by a subclasse's dispatch method.

_format

protected void _format(java.lang.Void obj,
                       IFormattableDocument document)

Fall-back for subclasses that accidently try to dispatch over null values.

_format

protected void _format(XtextResource resource,
                       IFormattableDocument document)

For resources, assume we want to format the first EObject from the contents list only. Because that's where the parser puts the semantic model.

createCommentReplacer

public ITextReplacer createCommentReplacer(IComment comment)

createFormattableRootDocument

public IFormattableDocument createFormattableRootDocument()

createFormattableSubDocument

public IFormattableSubDocument createFormattableSubDocument(ITextSegment region,
                                                            IFormattableDocument parent)

createHiddenRegionFormatter

public IHiddenRegionFormatter createHiddenRegionFormatter(IHiddenRegionFormatting formatting)

createHiddenRegionFormatter

public IHiddenRegionFormatter createHiddenRegionFormatter(IHiddenRegionFormatting f1,
                                                          IHiddenRegionFormatting f2)

createHiddenRegionFormatting

public IHiddenRegionFormatting createHiddenRegionFormatting()

createHiddenRegionFormattingMerger

public IMerger<IHiddenRegionFormatting> createHiddenRegionFormattingMerger()

createHiddenRegionReplacer

public ITextReplacer createHiddenRegionReplacer(IHiddenRegion region,
                                                IHiddenRegionFormatting formatting)

createTextReplacerContext

public ITextReplacerContext createTextReplacerContext(IFormattableDocument document)

createTextReplacerMerger

public IMerger<ITextReplacer> createTextReplacerMerger()

createWhitespaceReplacer

public ITextReplacer createWhitespaceReplacer(ITextSegment hiddens,
                                              IHiddenRegionFormatting formatting)

format

public final java.util.List<ITextReplacement> format(FormatterRequest request)

Description copied from interface: IFormatter2

Execute the formatter.

Specified by:

format in interface IFormatter2

handleTraceMissing

protected IFormattableDocument handleTraceMissing(IFormattableDocument problematic,
                                                  RegionTraceMissingException e)

format

public abstract void format(java.lang.Object obj,
                            IFormattableDocument document)

Implement this method to create a language-specific formatter. See the JavaDoc of this class for a more detailed description of what your code should do.

Parameters:

obj - An XtextResource or an object for from your semantic model.

document - The document to collect and execute ITextReplacers.

getPreference

public <T> T getPreference(TypedPreferenceKey<T> key)

Returns:

a preference value from FormatterRequest.getPreferences()

getPreferences

public ITypedPreferenceValues getPreferences()

Returns:

the preferences from the FormatterRequest

getRequest

public FormatterRequest getRequest()

Returns:

the FormatterRequest that was passed into IFormatter2.format(FormatterRequest) when invoking the formatter.

getTextRegionAccess

public ITextRegionAccess getTextRegionAccess()

initalize

@Deprecated
protected void initalize(FormatterRequest request)

Deprecated.

This method is deprecated, use #initialize(FormatterRequest) instead

initialize

protected void initialize(FormatterRequest request)

Overwrite this method to initialize member fields before format(Object, IFormattableDocument) is called.

isInRequestedRange

protected boolean isInRequestedRange(org.eclipse.emf.ecore.EObject obj)

postProcess

protected java.util.List<ITextReplacement> postProcess(IFormattableDocument document,
                                                       java.util.List<ITextReplacement> replacements)

reset

protected void reset()

Overwrite this method to clean up member fields after format(Object, IFormattableDocument) has been called.

shouldFormat

public boolean shouldFormat(java.lang.Object obj,
                            IFormattableDocument document)