Fix MIT license and add CHANGELOG

Implement QuickDoc for usage messages of user functions

Author: halirutan

CHANGELOG.md

@@ -0,0 +1,28 @@
+#Change Log
+
+## Todo
+
+- Show usage for own functions. "Quick Documentation" on a package symbol will show its usage message if available
+- Better rendering for "Go to Declaration" targets
+- Inspection for using the same variable in the e.g. Module definition list several times
+- Quick fix for adding usages and other messages
+- Keeping a leading * when pressing enter inside comments
+- Rework of creating project templates and modules
+- Update to Mathematica version 11.2
+- Quick fix for pushing a variable inside the Module definition list
+- Completion for file names inside strings
+
+## Version 3.0
+
+- Performance improvement through caching
+- Support for Libraries. Libraries are basically a package folder with Mathematica source code. This code is indexed and
+can now be used for completion and navigation. The highlighter shows which functions come from a different file
+- Support for project-wide navigation and resolving of symbols. Now you can refactor, navigate and complete functions
+that are located in a different package file
+- Smart completion inside comments to insert symbols from file
+- Implementation of better local variable support. Especially, "With" supports now several declaration lists
+- Fixing "Go to related symbol". Finds all usages of a symbol and gives file, line and a snip of the code there. You can
+directly navigate to any of these places
+- Implemented "Go to Declaration" so that the user can navigate to all targets where a function is given a definition (
+I know that go to _declaration_ is misleading for Mathematica, but it is the easier short-cut and widely used.)
+- Heavy reimplementation of the core algorithms for resolving references.

config/copyright/MIT.xml

@@ -1,5 +1,5 @@
 <component name="CopyrightManager">
   <copyright>
-    <option name="notice" value="Copyright (c) &amp;#36;today.year Patrick Scheibe&#10;&#10; Permission is hereby granted, free of charge, to any person obtaining a copy&#10; of this software and associated documentation files (the &quot;Software&quot;), to deal&#10; in the Software without restriction, including without limitation the rights&#10; to use, copy, modify, merge, publish, distribute, sublicense, and/or sell&#10; copies of the Software, and to permit persons to whom the Software is&#10; furnished to do so, subject to the following conditions:&#10; &#10; The above copyright notice and this permission notice shall be included in&#10; all copies or substantial portions of the Software.&#10; &#10; THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR&#10; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,&#10; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE&#10; AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER&#10; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,&#10; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN&#10; THE SOFTWARE.&#10; " />
+    <option name="notice" value="Copyright (c) &amp;#36;today.year. Patrick Scheibe&#10;&#10;Permission is hereby granted, free of charge, to any person&#10;obtaining a copy of this software and associated documentation&#10;files (the “Software”), to deal in the Software without&#10;restriction, including without limitation the rights to use,&#10;copy, modify, merge, publish, distribute, sublicense, and/or sell&#10;copies of the Software, and to permit persons to whom the&#10;Software is furnished to do so, subject to the following&#10;conditions:&#10;&#10;The above copyright notice and this permission notice shall be&#10;included in all copies or substantial portions of the Software.&#10;&#10;THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,&#10;EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES&#10;OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND&#10;NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT&#10;HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,&#10;WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING&#10;FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR&#10;OTHER DEALINGS IN THE SOFTWARE." />
   </copyright>
 </component>

resources/de/halirutan/mathematica/MathematicaBundle.properties

@@ -23,6 +23,9 @@
 
 language.name=Mathematica
 language.description=The Mathematica/Wolfram language
+language.level.11.3=Mathematica Version 11.3
+language.level.11.2=Mathematica Version 11.2
+language.level.11.1=Mathematica Version 11.1
 language.level.11=Mathematica Version 11.0
 language.level.10.4=Mathematica Version 10.4
 language.level.10.3=Mathematica Version 10.3
@@ -54,3 +57,6 @@ structureview.sorter.by.appearance.text=Sort by Appearance
 structureview.sorter.by.appearance.description=Sorts the entries by appearance in the source file.
 library.new=Mathematica Library
 library.description=A Mathematica package directory that acts as library
+doc.navi.invalid=Cannot resolve symbol {0}
+doc.navi.navto=Navigate to definition of  {0}
+doc.navi.builtin=Built-in symbol <b>{0}</b>

src/de/halirutan/mathematica/documentation/MathematicaDocumentationProvider.java

@@ -32,20 +32,26 @@
 import com.intellij.psi.PsiFile;
 import com.intellij.psi.PsiManager;
 import com.intellij.psi.util.PsiTreeUtil;
+import de.halirutan.mathematica.MathematicaBundle;
 import de.halirutan.mathematica.lang.psi.LocalizationConstruct;
 import de.halirutan.mathematica.lang.psi.api.OperatorNameProvider;
 import de.halirutan.mathematica.lang.psi.api.Symbol;
 import de.halirutan.mathematica.lang.psi.impl.LightBuiltInSymbol;
 import de.halirutan.mathematica.lang.psi.impl.LightFileSymbol;
 import de.halirutan.mathematica.lang.psi.util.MathematicaPsiElementFactory;
+import de.halirutan.mathematica.lang.psi.util.UsageMessagesKt;
+import kotlin.Pair;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.io.InputStream;
+import java.util.List;
 import java.util.Scanner;
 import java.util.regex.Pattern;
 
 /**
+ * Provides documentation aka rendered usage messages for built-in functions, operators and user-defined functions
+ *
  * @author patrick (4/4/13)
  */
 public class MathematicaDocumentationProvider extends AbstractDocumentationProvider {
@@ -55,10 +61,13 @@ public class MathematicaDocumentationProvider extends AbstractDocumentationProvi
   private static final Pattern SLOT_SEQUENCE_PATTERN = Pattern.compile("##[0-9]*");
 
   /**
-   * Generates the documentation (if available) for element. This does two things, first it looks whether the element is
-   * a {@link Symbol}. If this is true it tries to load the usage message. If element is not a Symbol, it is possibly an
-   * operator. Then it tries to guess the usage message of the operator by converting the class name to a hopefully
-   * valid operator name.
+   * Generates the documentation (if available) for element. This does three things:
+   * <p>
+   * <ul>
+   * <li>it provides documentation if the symbol near the cursor is a built in function</li>
+   * <li>it provides documentation when it is called over operators like ++</li>
+   * <li>it checks if user functions have a usage message and presents this</li>
+   * </ul>
    *
    * @param element         Element which was possibly altered by {@link #getCustomDocumentationElement(Editor, PsiFile, PsiElement)} or by
    *                        {@link #getDocumentationElementForLookupItem(PsiManager, Object, PsiElement)} if the lookup was active
@@ -70,36 +79,68 @@ public class MathematicaDocumentationProvider extends AbstractDocumentationProvi
   @Override
   public String generateDoc(PsiElement element, @Nullable PsiElement originalElement) {
 
-    Symbol docElement;
-    if (element instanceof Symbol) {
-      docElement = (Symbol) element;
-    } else if (originalElement instanceof Symbol) {
-      docElement = (Symbol) originalElement;
-    } else {
+    if (!(element instanceof Symbol || element instanceof OperatorNameProvider)) {
       return null;
     }
 
+    String pathToHTMLDoc;
 
-    String context = docElement.getMathematicaContext();
-    context = context.equals("") ? "System`" : context;
-    String name = docElement.getSymbolName();
-    if (ALL_SLOT_PATTERN.matcher(name).matches()) {
-      if (SLOT_PATTERN.matcher(name).matches()) name = "Slot";
-      else if (SLOT_SEQUENCE_PATTERN.matcher(name).matches()) name = "SlotSequence";
+    if (element instanceof Symbol) {
+      Symbol docElement = (Symbol) element;
+      String context = docElement.getMathematicaContext();
+      context = context.equals("") ? "System`" : context;
+      String name = docElement.getSymbolName();
+      if (ALL_SLOT_PATTERN.matcher(name).matches()) {
+        if (SLOT_PATTERN.matcher(name).matches()) name = "Slot";
+        else if (SLOT_SEQUENCE_PATTERN.matcher(name).matches()) name = "SlotSequence";
+      }
+      pathToHTMLDoc = "usages/" + context.replace('`', '/') + name + ".html";
+    } else {
+      pathToHTMLDoc = "usages/System/" + ((OperatorNameProvider) element).getOperatorName() + ".html";
     }
-    String path = "usages/" + context.replace('`', '/') + name + ".html";
 
-    if (docElement instanceof OperatorNameProvider) {
-      path = "usages/System/" + ((OperatorNameProvider) docElement).getOperatorName() + ".html";
+    InputStream docFile = MathematicaDocumentationProvider.class.getResourceAsStream(pathToHTMLDoc);
+    if (docFile != null) {
+      final String usage = new Scanner(docFile, "UTF-8").useDelimiter("\\A").next();
+      if (!usage.isEmpty()) {
+        return usage;
+      }
     }
 
-    InputStream docFile = MathematicaDocumentationProvider.class.getResourceAsStream(path);
-    if (docFile != null) {
-      return new Scanner(docFile, "UTF-8").useDelimiter("\\A").next();
+    // Inject the usage message of functions that are declared inside the package
+    if (element instanceof Symbol) {
+      return renderCustomUsageMessage((Symbol) element);
     }
+
     return null;
   }
 
+  /**
+   * Provides a html form of the usage message for custom user functions.
+   * @param symbol a file symbol for which the usage message should be found and rendered
+   * @return the first found usage message
+   */
+  private String renderCustomUsageMessage(@NotNull Symbol symbol) {
+    final Pair<Symbol, List<String>> usages = UsageMessagesKt.extractUsageMessageString(symbol);
+    if (usages.component2().isEmpty()) {
+      return "";
+    }
+    final String fileName = usages.component1().getContainingFile().getName();
+    final String symbolName = symbol.getSymbolName();
+    StringBuilder result = new StringBuilder("<h3>");
+    result.append(symbolName);
+    result.append(" (");
+    result.append(fileName);
+    result.append(")</h3><ul>");
+    for (String usg : usages.component2()) {
+      result.append("<li>");
+      result.append(usg.replaceAll("("+symbolName+"(\\[.*])?)", "<b>$1</b>"));
+      result.append("</li>");
+    }
+    result.append("</ul>");
+    return result.toString();
+  }
+
   /**
    * Calculates the correct element for which the user wants documentation.
    *
@@ -137,9 +178,7 @@ public PsiElement getCustomDocumentationElement(@NotNull Editor editor, @NotNull
     // Determine if the contextElement is the operator sign of an operation.
     // See the doc to OperatorNameProviderImpl.
     if (docElement instanceof OperatorNameProvider) {
-//      if (((OperatorNameProvider) docElement).isOperatorSign(contextElement)) {
       return docElement;
-//      }
     }
     return null;
   }
@@ -161,7 +200,8 @@ public PsiElement getCustomDocumentationElement(@NotNull Editor editor, @NotNull
   @Override
   public PsiElement getDocumentationElementForLookupItem(PsiManager psiManager, Object object, PsiElement element) {
     if (element != null) {
-      final LookupEx activeLookup = LookupManager.getActiveLookup(FileEditorManager.getInstance(element.getProject()).getSelectedTextEditor());
+      final LookupEx activeLookup =
+          LookupManager.getActiveLookup(FileEditorManager.getInstance(element.getProject()).getSelectedTextEditor());
       if (activeLookup != null) {
         MathematicaPsiElementFactory elementFactory = new MathematicaPsiElementFactory(psiManager.getProject());
         try {
@@ -174,21 +214,27 @@ public PsiElement getDocumentationElementForLookupItem(PsiManager psiManager, Ob
     return null;
   }
 
+  /**
+   * Provides a quick info when the user hovers code with CTRL pressed
+   * @param element element to show quick navigation. This is the resolved element which means we can check which kind of light symbol it is
+   * @param originalElement the original symbol in file
+   * @return quick info what happens when the user performs a mouse click
+   */
   @Nullable
   @Override
   public String getQuickNavigateInfo(PsiElement element, PsiElement originalElement) {
     if (element instanceof LightBuiltInSymbol) {
-      return "Built-in symbol " + ((LightBuiltInSymbol) element).getName();
+      return MathematicaBundle.message("doc.navi.builtin", ((LightBuiltInSymbol) element).getName());
     }
     if (element instanceof LightFileSymbol) {
       if (originalElement instanceof Symbol &&
           ((Symbol) originalElement).getLocalizationConstruct() == LocalizationConstruct.MScope.NULL_SCOPE) {
-        return "Cannot resolve symbol " + ((LightFileSymbol) element).getName();
+        return MathematicaBundle.message("doc.navi.invalid", ((LightFileSymbol) element).getName());
       }
-      return "Navigate to definition of " + ((LightFileSymbol) element).getName();
+      return MathematicaBundle.message("doc.navi.navto", ((LightFileSymbol) element).getName());
     }
     if (element instanceof Symbol) {
-      return "Navigate to definition of " + ((Symbol) element).getFullSymbolName();
+      return MathematicaBundle.message("doc.navi.navto", ((Symbol) element).getFullSymbolName());
     }
     return super.getQuickNavigateInfo(element, originalElement);
   }

src/de/halirutan/mathematica/lang/psi/api/MessageName.java

@@ -36,4 +36,6 @@ public interface MessageName extends Expression {
 
   @Nullable
   public StringifiedSymbol getLang();
+
+  public boolean isUsageMessage();
 }

src/de/halirutan/mathematica/lang/psi/impl/MessageNameImpl.java

@@ -28,6 +28,7 @@
 import de.halirutan.mathematica.lang.psi.api.Expression;
 import de.halirutan.mathematica.lang.psi.api.MessageName;
 import de.halirutan.mathematica.lang.psi.api.StringifiedSymbol;
+import de.halirutan.mathematica.lang.psi.api.string.MString;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -83,4 +84,10 @@ public StringifiedSymbol getLang() {
     }
     return null;
   }
+
+  @Override
+  public boolean isUsageMessage() {
+    final StringifiedSymbol tag = getTag();
+    return tag != null && "usage".equals(tag.getText());
+  }
 }

src/de/halirutan/mathematica/lang/psi/util/UsageMessages.kt

@@ -0,0 +1,62 @@
+package de.halirutan.mathematica.lang.psi.util
+
+import com.intellij.openapi.progress.ProgressManager
+import com.intellij.openapi.project.DumbService
+import com.intellij.psi.search.searches.ReferencesSearch
+import com.intellij.psi.util.PsiTreeUtil
+import de.halirutan.mathematica.lang.psi.api.MessageName
+import de.halirutan.mathematica.lang.psi.api.Symbol
+import de.halirutan.mathematica.lang.psi.api.assignment.Set
+import de.halirutan.mathematica.lang.psi.api.string.MString
+
+/**
+ *
+ * @author patrick (02.12.17).
+ */
+
+fun extractUsageMessageString(symbol: Symbol): Pair<Symbol, List<String>> {
+  val resolve = symbol.resolve() ?: return Pair(symbol, emptyList())
+
+  if (resolve is Symbol) {
+    return Pair(resolve, doUsageMessageExtract(resolve))
+  }
+
+  var result: Pair<Symbol, List<String>> = Pair(symbol, emptyList())
+
+  DumbService.getInstance(symbol.project).runReadActionInSmartMode {
+    val elements = ReferencesSearch.search(resolve)
+    for (elm in elements) {
+      ProgressManager.checkCanceled()
+      if (elm != null && elm.element is Symbol) {
+        val sym = elm.element as Symbol
+        val r = doUsageMessageExtract(sym)
+        if (r.isNotEmpty()) {
+          result = Pair(sym, r)
+          break
+        }
+      }
+    }
+  }
+  return result
+}
+
+private fun doUsageMessageExtract(symbol: Symbol): List<String> {
+  if (symbol.parent is MessageName) {
+    val messageName = symbol.parent as MessageName
+    if (messageName.isUsageMessage) {
+      val set = messageName.parent
+      if (set is Set) {
+        var message = ""
+        when {
+          set.lastChild is MString -> message = set.lastChild.text.removeSurrounding("\"")
+          else -> {
+            val strings = PsiTreeUtil.findChildrenOfType(set.lastChild, MString::class.java)
+            strings.forEach { result -> message += result.text.removeSurrounding("\"") }
+          }
+        }
+        return message.replace("\\[Ellipsis]", "...").split("\\n")
+      }
+    }
+  }
+  return emptyList()
+}

src/de/halirutan/mathematica/lang/resolve/MathematicaGlobalResolveCache.java

@@ -67,7 +67,7 @@ public boolean containsSymbol(@NotNull Symbol symbol) {
     return containsBuildInSymbol(symbol) || containsFileSymbol(symbol) || containsExternalSymbol(symbol);
   }
 
-  private boolean containsFileSymbol(@NotNull Symbol symbol) {
+  public boolean containsFileSymbol(@NotNull Symbol symbol) {
     final LightFileSymbol lightFileSymbol = new LightFileSymbol(symbol);
     return myCachedFileSymbols.containsKey(lightFileSymbol);
   }
@@ -131,9 +131,19 @@ public ResolveResult getValue(Symbol symbol) {
     return myCachedExternalSymbols.get(new LightExternalSymbol(symbol));
   }
 
+  public List<SymbolResolveResult> getCachedFileSymbolResolves(@NotNull PsiFile containingFile) {
+    return myCachedFileSymbols
+        .values()
+        .parallelStream()
+        .filter(resolve -> containingFile.equals(resolve.getScopingElement()) &&
+            resolve.getElement() instanceof LightFileSymbol)
+        .collect(Collectors.toList());
+  }
+
   public List<String> getCachedFileSymbolNames(@NotNull PsiFile file) {
-    return myCachedFileSymbols.values().parallelStream().filter(
-        resolve -> file.equals(resolve.getScopingElement()) && resolve.getElement() instanceof LightFileSymbol).map(
-        resolve -> ((LightFileSymbol) resolve.getElement()).getName()).collect(Collectors.toList());
+    return getCachedFileSymbolResolves(file)
+        .stream()
+        .filter(resolve -> resolve.getElement() != null)
+        .map(resolve -> ((LightFileSymbol) resolve.getElement()).getName()).collect(Collectors.toList());
   }
 }