Implemented folding of section-comments.

This fixes #63, fixes #62, fixes #57

Author: halirutan

.idea/codeStyleSettings.xml

@@ -27,11 +27,17 @@
 import com.intellij.lang.folding.NamedFoldingDescriptor;
 import com.intellij.openapi.editor.Document;
 import com.intellij.openapi.util.TextRange;
+import com.intellij.psi.PsiComment;
 import com.intellij.psi.PsiElement;
+import com.intellij.psi.PsiFile;
 import com.intellij.psi.tree.IElementType;
 import com.intellij.psi.tree.TokenSet;
+import com.intellij.psi.util.PsiTreeUtil;
 import de.halirutan.mathematica.parsing.MathematicaElementTypes;
+import de.halirutan.mathematica.parsing.psi.api.CompoundExpression;
 import de.halirutan.mathematica.parsing.psi.api.FunctionCall;
+import de.halirutan.mathematica.parsing.psi.util.Comments;
+import de.halirutan.mathematica.parsing.psi.util.Comments.CommentStyle;
 import de.halirutan.mathematica.parsing.psi.util.LocalizationConstruct.ConstructType;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -45,6 +51,9 @@
 import java.util.regex.Pattern;
 
 /**
+ * Creates fold-regions from particular nodes of the AST tree. Currently, we support the folding of functions, lists,
+ * and special "sectioning comments".
+ *
  * @author patrick (26.07.15)
  */
 public class MathematicaExpressionFoldingBuilder implements FoldingBuilder {
@@ -87,56 +96,141 @@ private void collectRegionsRecursively(@NotNull final ASTNode node,
         if (matcher.end() - matcher.start() > 3) {
           final String key = symbol.substring(matcher.start() + 2, matcher.end() - 1);
           final TextRange nodeRange = node.getTextRange();
-          final TextRange range = TextRange.create(nodeRange.getStartOffset()+matcher.start(), nodeRange.getStartOffset() + matcher.end());
+          final TextRange range = TextRange.create(nodeRange.getStartOffset() + matcher.start(), nodeRange.getStartOffset() + matcher.end());
           if (ourNamedCharacters.containsKey(key)) {
             descriptors.add(new MathematicaNamedFoldingDescriptor(node, range, null, ourNamedCharacters.get(key), false));
           }
         }
       }
     } else if (foldCharacters && elementType == MathematicaElementTypes.STRING_NAMED_CHARACTER) {
       final String name = node.getText();
-      final String key = name.substring(2,name.length()-1);
+      final String key = name.substring(2, name.length() - 1);
       if (ourNamedCharacters.containsKey(key)) {
         descriptors.add(new MathematicaNamedFoldingDescriptor(node, node.getTextRange(), null, ourNamedCharacters.get(key), false));
       }
-    } else if(elementType==MathematicaElementTypes.LIST_EXPRESSION) {
+    } else if (elementType == MathematicaElementTypes.LIST_EXPRESSION) {
       // Well, we count the number of elements by counting the commas and adding one. Not bullet-proof, but will do.
-    final int numberOfListElements = node.getChildren(TokenSet.create(MathematicaElementTypes.COMMA)).length + 1;
-    descriptors.add(new NamedFoldingDescriptor(
-        node,
-        node.getTextRange(),
-        null,
-        "{ <<" + numberOfListElements + ">> }"));
+      final int numberOfListElements = node.getChildren(TokenSet.create(MathematicaElementTypes.COMMA)).length + 1;
+      descriptors.add(new NamedFoldingDescriptor(
+          node,
+          node.getTextRange(),
+          null,
+          "{ <<" + numberOfListElements + ">> }"));
+    } else if (elementType == MathematicaElementTypes.FUNCTION_CALL_EXPRESSION) {
+      final PsiElement psi = node.getPsi();
+      if (psi instanceof FunctionCall) {
+        final FunctionCall functionCall = (FunctionCall) psi;
+        if (functionCall.getScopingConstruct() != ConstructType.NULL) {
+          descriptors.add(new NamedFoldingDescriptor(
+              node,
+              node.getTextRange(),
+              null,
+              functionCall.getHead().getText() + "[...]"
+          ));
+        }
+      }
+    } else if (node instanceof PsiComment) {
+      collectCommentRegion(node, document, descriptors);
+    }
+
+    for (ASTNode child : node.getChildren(null)) {
+      collectRegionsRecursively(child, document, descriptors);
+    }
+
   }
 
-  else if(elementType==MathematicaElementTypes.FUNCTION_CALL_EXPRESSION)
-
-  {
-    final PsiElement psi = node.getPsi();
-    if (psi instanceof FunctionCall) {
-      final FunctionCall functionCall = (FunctionCall) psi;
-      if (functionCall.getScopingConstruct() != ConstructType.NULL) {
-        descriptors.add(new NamedFoldingDescriptor(
-            node,
-            node.getTextRange(),
-            null,
-            functionCall.getHead().getText() + "[...]"
-        ));
+  /**
+   * Entry method that only check if we have a valid section-comment. The work is done in
+   * {@link MathematicaExpressionFoldingBuilder#collectCommentRegion(PsiComment, Document, List)}
+   *
+   * @param node        node to a PsiComment
+   * @param document    the document of the code
+   * @param descriptors collects all folding descriptors
+   */
+  private void collectCommentRegion(@NotNull final ASTNode node,
+                                    @NotNull final Document document,
+                                    @NotNull List<FoldingDescriptor> descriptors) {
+    final PsiComment psi = (PsiComment) node.getPsi();
+    boolean isAtTopLevel = false;
+    if (psi.getParent() instanceof PsiFile) {
+      isAtTopLevel = true;
+    } else {
+      final PsiElement parent = psi.getParent();
+      if (parent instanceof CompoundExpression && parent.getParent() instanceof PsiFile) {
+        isAtTopLevel = true;
       }
     }
+
+    if (isAtTopLevel && Comments.isCorrectSectionComment(psi)) {
+      final CommentStyle style = Comments.getStyle(psi);
+      if (style != null && style.compareTo(CommentStyle.SUBSUBSUBSECTION) < 0) {
+        collectCommentRegion(node, psi, style, document, descriptors);
+      }
+    }
+
   }
 
+  /**
+   * Here the work is done for finding the correct region to fold for a sectioning-comment. The sectioning comments like
+   * <code>
+   * (* ::Chapter:: *)
+   * (*this is the text of the chapter*)
+   * </code>
+   *
+   * @param node        AST node of the comment
+   * @param comment     the PSI element of node
+   * @param style       Extracted style of the sectioning comment of node
+   * @param document    The document that contains the comment
+   * @param descriptors Collection for the region descriptors for folding
+   */
+  private void collectCommentRegion(@NotNull ASTNode node,
+                                    @NotNull final PsiComment comment,
+                                    @NotNull final CommentStyle style,
+                                    @NotNull final Document document,
+                                    @NotNull List<FoldingDescriptor> descriptors) {
+    final PsiFile file = comment.getContainingFile();
+    StringBuilder placeHolderText = new StringBuilder("<< ::");
+    placeHolderText.append(style).append(":: ");
+
+    final int currentLine = document.getLineNumber(comment.getTextOffset());
+    int endOffset = document.getTextLength();
+
+    for (int i = currentLine + 1; i < document.getLineCount(); i++) {
+      int start = document.getLineStartOffset(i);
+      int end = document.getLineEndOffset(i);
+      final PsiComment commentsInLine = PsiTreeUtil.findElementOfClassAtRange(file, start, end, PsiComment.class);
+      if (commentsInLine != null && Comments.isCorrectSectionComment(commentsInLine)) {
+        final CommentStyle commentStyle = Comments.getStyle(commentsInLine);
+        if (commentStyle != null && commentStyle.compareTo(style) <= 0) {
+          endOffset = start - 1;
+          if (i < document.getLineCount() - 1) {
+            final PsiComment nextLineComment = PsiTreeUtil.findElementOfClassAtRange(
+                file,
+                document.getLineStartOffset(i + 1),
+                document.getLineEndOffset(i + 1),
+                PsiComment.class
+            );
+            if (nextLineComment != null && !Comments.isCorrectSectionComment(nextLineComment)) {
+              placeHolderText.append(Comments.getStrippedText(nextLineComment));
+            } else {
+              placeHolderText.append("No description given");
+            }
+          }
+          break;
+        }
+      }
+    }
+    placeHolderText.append(">>");
+    descriptors.add(new NamedFoldingDescriptor(
+        node,
+        TextRange.create(node.getStartOffset(), endOffset),
+        null,
+        placeHolderText.toString()
+    ));
 
-  for(
-  ASTNode child
-  :node.getChildren(null))
 
-  {
-    collectRegionsRecursively(child, document, descriptors);
   }
 
-}
-
   @Nullable
   @Override
   public String getPlaceholderText(@NotNull final ASTNode node) {

.idea/dictionaries/patrick.xml

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2017 Patrick Scheibe
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * Provides region folding. That is that some expressions or constructs in the code can be folded together so that they
+ * don't occupy space. This is handy if you have long lists or Modules. While the implementation for functions and lists
+ * is simple, there are two special cases.
+ * <p>
+ * First, we provide small fold-regions for Mathematica's special characters like \[Alpha]. If folded, those special
+ * characters are displayed as their UTF8 counterpart which makes the code more readable. I strongly advise against the
+ * massive use of such things in normal code which should be easily readable as ASCII text, but especially in GUI
+ * elements a nice rendering inside Mathematica is often required and in such situations the named-character folding
+ * becomes very handy.
+ * <p>
+ * The second, more complex folding regions we support are Mathematica's special sectioning-comments. The sectioning
+ * comments like
+ * <p>
+ * <code> (* ::Chapter:: *)<br> (*this is the text of the chapter*) </code>
+ * <p>
+ * should always contain the "text" as separate comment directly in the next line. Mathematica is very strict about the
+ * sectioning comments and they always need EXACTLY one space around the style specifier (here ::Chapter::)! If you
+ * don't follow this rule, then it won't be rendered appropriately inside the Mathematica front end. The best approach
+ * to create a valid section-comment is to use Ctrl+/ to create a new empty (**) followed by pressing Ctrl+Space to get
+ * a completion for all possible Chapter, Section, Subsection, Item, etc. Note that correct section comments are always
+ * displayed in bold-face and slightly brighter than other comments.
+ * <p>
+ * The folding of such comments takes care of the "level", meaning if you fold a Section, it will always take the region
+ * to the next Section or any element that has a higher level like "Chapter" or "Subchapter". If you have several
+ * Subsections between two sections, then you can (a) fold each Subsection separately.
+ * <p>
+ * Finally, section-comments can contain some style specifiers, namely ::Closed::, ::Bold::, ::Italic::. Here,
+ * ::Closed:: is maybe the only really useful because it indicates that a section should be displayed as closed when
+ * opened in Mathematica. Note that it has no influence of the folding! A correct example is for instance <code> (*
+ * ::Text::Bold::Italic:: *) </code>
+ * <p>
+ * The supported section-comments can be found in {@link de.halirutan.mathematica.parsing.psi.util.Comments.CommentStyle}.
+ */
+package de.halirutan.mathematica.codeinsight.folding;

src/de/halirutan/mathematica/codeinsight/folding/MathematicaExpressionFoldingBuilder.java

@@ -27,37 +27,26 @@
 import com.intellij.openapi.util.TextRange;
 import com.intellij.psi.PsiComment;
 import com.intellij.psi.PsiElement;
-import de.halirutan.mathematica.codeinsight.completion.CommentCompletionProvider;
-import org.apache.commons.lang.StringUtils;
+import de.halirutan.mathematica.parsing.psi.util.Comments;
 import org.jetbrains.annotations.NotNull;
 
-import java.util.ArrayList;
-import java.util.List;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 
 /**
+ * Provides bold and bright highlighting for tags and sectioning comments.
  * @author patrick (03.03.15)
  */
 public class CommentAnnotator implements Annotator {
 
-  private static final Pattern ourTagPattern;
-
-  static {
-    List<String> commentTags = new ArrayList<>(CommentCompletionProvider.COMMENT_TAGS.length);
-    for (String tag : CommentCompletionProvider.COMMENT_TAGS) {
-      commentTags.add(":" + tag + ":");
-    }
-    ourTagPattern = Pattern.compile(StringUtils.join(commentTags, "|"));
-  }
-
+  private static final Pattern ourTagPattern = Pattern.compile("[^:]:\\w+:[^:]");
 
   @Override
   public void annotate(@NotNull final PsiElement element, @NotNull final AnnotationHolder holder) {
     if (element instanceof PsiComment) {
       final Annotation commentAnnotation = holder.createInfoAnnotation(element, null);
-      if (isCorrectSectionComment(element)) {
+      if (Comments.isCorrectSectionComment((PsiComment) element)) {
         commentAnnotation.setTextAttributes(MathematicaSyntaxHighlighterColors.COMMENT_SPECIAL);
         return;
       }
@@ -76,47 +65,4 @@ private void annotateCommentTags(@NotNull final PsiElement comment, @NotNull fin
       tagAnnotation.setTextAttributes(MathematicaSyntaxHighlighterColors.COMMENT_SPECIAL);
     }
   }
-
-  /**
-   * Tests if a comment is a valid Section, Subsection, ... comment. AFAIK these comments can only contain the section
-   * specifier and nothing else (whitespace should be OK). Therefore, I match comments that look like this
-   * <p>
-   * <code>(* ::Section:: *)</code>
-   * <p>
-   * Please see {@link CommentCompletionProvider#COMMENT_SECTIONS}.
-   *
-   * @param comment the comment PsiElement
-   * @return true if the comment is a valid title, section, ... comment
-   */
-  private boolean isCorrectSectionComment(@NotNull final PsiElement comment) {
-    final String text = comment.getText();
-    final String name = text.replace("(*", "").replace("*)", "").trim();
-    if (name.length() > 0 && name.matches("::.*::")) {
-      final String sectionName = name.replace(":", "");
-      for (String commentSection : CommentCompletionProvider.COMMENT_SECTIONS) {
-        if (commentSection.equals(sectionName)) {
-          return true;
-        }
-      }
-    }
-    return false;
-  }
-
-  /**
-   * This is not as strict as {@link CommentAnnotator#isCorrectSectionComment(PsiElement)} and it does only check
-   * if there is a section tag (::Section::, ::Subsection::, ...) inside the comment.
-   *
-   * @param comment Comment to check
-   * @return true if a section tag could be found inside the comment
-   */
-  private boolean containsSectionTag(@NotNull final PsiElement comment) {
-    final String text = comment.getText();
-    for (String commentSection : CommentCompletionProvider.COMMENT_SECTIONS) {
-      if (text.contains("::" + commentSection + "::")) {
-        return true;
-      }
-    }
-    return false;
-  }
-
 }