/**
* Copyright (c) 2013 Puppet Labs, Inc. and other contributors, as listed below.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Puppet Labs
*/
package com.puppetlabs.xtext.dommodel.formatter.comments;
import com.puppetlabs.xtext.dommodel.IDomNode;
import org.eclipse.emf.ecore.EObject;
import org.eclipse.xtext.AbstractRule;
import org.eclipse.xtext.nodemodel.ILeafNode;
import org.eclipse.xtext.nodemodel.INode;
import com.google.inject.ImplementedBy;
/**
* <p>
* An ICommentConfiguration describes the configuration of comment (container-) extraction, parsing, and formatting.
* </p>
* <p>
* It is responsible for <i>comment classification</i> - associating a more specific comment type for an IDomNode representing a comment. The class
* used to describe the comment type is configurable via the generic type {@code T}. The default implementation uses {@link CommentType} as {@code T}.
* This type is expected by the default configuration of comment formatting, but a custom implementation may use a different type (throughout) if
* needed).
* </p>
* <p>
* The comment type classification can be used in a CSS selector, thus allowing a layout manager to be selected per comment type. The default layout
* manager is capable of providing reasonable formatting as described by an {@code ICommentConfiguration}, but can naturally be customized.
* </p>
* <p>
* Since the style classifiers of an IDomNode is a Set of Objects, a concrete implementation may choose any suitable instances to describe the various
* types of comments in the DSL language being laid out. This interface contains an enumerator for the three most common comments types (
* {@code Singleline}, {@code Multiline}, and {@code Documentation}), but this enumerator says nothing about the interior syntax and semantics of the
* respective comments.
* </p>
*
* <p>
* Note that the default {@code ICommentConfiguration} implementation assumes that the three default comment types use Java conventions. Simply bind a
* specialization of the {@link ICommentConfiguration.Default} class, or a different/more advanced implementation when so required:
* <ul>
* <li>If comment grammar rules are not "ML_COMMENT" and "SL_COMMENT". (This also requires customization of the {@code IHiddenTokenHelper} class which
* is used to determine if a token is a comment (of any type).</li>
* <li>If comments do not follow Java comment syntax (e.g. using '#' instead of '//' for single line comments.</li>
* <li>A different comment type scheme is wanted than {@link CommentType}.</li>
* <li>If different types of comments should be formatted with different {@link ICommentFormatterAdvice}.</li>
* </ul>
* </p>
* <p>
* To summarize: The {@code ICommentConfiguration} classifies a comment. The resulting classifier is used to select styling (i.e. a selection of an
* {@code ILayoutManager} and and other style information as determined by a CSS driven formatter). The selected ILayoutManager is responsible for the
* formatting of the comment(s). By default an ILayoutManager is configured for comments that use an {@code ICommentConfiguration} to map the
* {@code CommentType} to a description of the comment's syntax and semantics ({@link #getContainerInformation(Object)}), and a description of wanted
* formatting ({@link #getFormatterAdvice(Object)}). It is the responsibility of the selected {@code ILayoutManager} to apply the container
* information and formatting advice to the comment using an implementation specific comment processor.
* </p>
*
*/
@ImplementedBy(ICommentConfiguration.Default.class)
public interface ICommentConfiguration<T> {
public static enum CommentType {
/**
* Returned when a comment classifier is asked to classify something that
* is not one of the known comment types (or not a comment at all).
*/
Unknown, SingleLine, Multiline, Documentation;
}
/**
* <p>
* An implementation of {@link ICommentConfiguration} that classifies comments based on the grammar rule name of the comment terminals;
* "ML_COMMENT", and "SL_COMMENT". This implementation returns {@link CommentType#Unknown} for all other nodes.
* </p>
* <p>
* When asked to classify an IDomNode, this node must either have an INode attached, or an attached grammar rule that describes the comment type.
* </p>
*/
public static class Default implements ICommentConfiguration<CommentType> {
private static final ICommentFormatterAdvice defaultAdvice = new ICommentFormatterAdvice.DefaultCommentAdvice();
@Override
public CommentType classify(EObject grammarElement) {
if(grammarElement != null && grammarElement instanceof AbstractRule) {
AbstractRule rule = (AbstractRule) grammarElement;
if("ML_COMMENT".equals(rule.getName()))
return CommentType.Multiline;
if("SL_COMMENT".equals(rule.getName()))
return CommentType.SingleLine;
}
return CommentType.Unknown;
}
/**
* Returns the comment type based on the node's attached {@code INode} if available, otherwise
* the node's attached <i>grammar element</i>. The node must be a leaf node.
*/
@Override
public CommentType classify(IDomNode node) {
INode inode = node.getNode();
if(inode != null)
return classify(inode);
if(node.isLeaf())
return classify(node.getGrammarElement());
return CommentType.Unknown;
}
@Override
public CommentType classify(INode node) {
EObject ge = node.getGrammarElement();
if(node instanceof ILeafNode)
return classify(ge);
return CommentType.Unknown;
}
@Override
public ICommentContainerInformation getContainerInformation(CommentType commentType) {
// Preconditions.checkArgument(genericCommentType instanceof CommentType, "must be instance of CommentType");
// CommentType commentType = (CommentType) genericCommentType;
switch(commentType) {
case SingleLine:
return new ICommentContainerInformation.JavaSLCommentContainer();
case Multiline:
return new ICommentContainerInformation.JavaLikeMLCommentContainer();
case Documentation:
return new ICommentContainerInformation.JavaDocLikeCommentContainer();
}
// Unknown type
return new ICommentContainerInformation.UnknownCommentContainer();
}
/**
* @return {@link DefaultCommentFormattingAdvice} irrespective of {@code commentType}.
*/
@Override
public ICommentFormatterAdvice getFormatterAdvice(CommentType commentType) {
return defaultAdvice;
}
}
public T classify(EObject abstractRule);
public T classify(IDomNode node);
public T classify(INode node);
/**
* Returns an {@link ICommentContainerInformation} for the given commentType (a classifier produced
* by one of the {@code classify} methods, typically an instance of {@link CommentType}), describing
* the expected container for this type of comment.
*
* @param commentType
* describes the comment type
* @return information about the comment container of the given {@code commentType}
*/
public ICommentContainerInformation getContainerInformation(T commentType);
/**
* Returns an {@link ICommentFormatterAdvice} describing how a comment of the given commentType (a classifier produced
* by one of the {@code classify} methods, typically an instance of {@link CommentType}) should be formatted
* with respect to its textual content and in relationship to its container.
*
* @param commentType
* describes the comment type
* @return formatting advice for a comment of the given {@code commentType}
*/
public ICommentFormatterAdvice getFormatterAdvice(T commentType);
}