platform/lang-api/src/com/intellij/psi/PsiLanguageInjectionHost.java

   1 /*
   2  * Copyright 2000-2007 JetBrains s.r.o.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package com.intellij.psi;
  18
  19 import com.intellij.openapi.editor.RangeMarker;
  20 import com.intellij.openapi.util.Pair;
  21 import com.intellij.openapi.util.ProperTextRange;
  22 import com.intellij.openapi.util.TextRange;
  23 import org.jetbrains.annotations.NotNull;
  24 import org.jetbrains.annotations.Nullable;
  25
  26 import java.util.List;
  27
  28 /**
  29  * Marks psi element as (potentially) containing text in other language.
  30  * Injected language PSI does not embed into the PSI tree of the hosting element,
  31  * but is used by IDEA for highlighting, completion and other code insight actions.
  32  * In order to do the injection, you have to
  33  * <ul>
  34  * <li>Implement {@link com.intellij.psi.LanguageInjector} to describe exact place where injection should occur.</li>
  35  * <li>Register injection in {@link com.intellij.psi.PsiManager#registerLanguageInjector(LanguageInjector)} .</li>
  36  * </ul>
  37  * Currently, language can be injected into string literals, XML tag contents and XML attributes.
  38  * You don't have to implement PsiLanguageInjectionHost by yourself, unless you want to inject something into your own custom PSI.
  39  * For all returned injected PSI elements, {@link PsiElement#getContext()} method returns PsiLanguageInjectionHost they were injected into.
  40  */
  41 public interface PsiLanguageInjectionHost extends PsiElement {
  42   /**
  43    * @return injected PSI element and text range inside host element where injection occurs.
  44    * For example, in string literals we might want to inject something inside double quotes.
  45    * To express this, use <code>return Pair.create(injectedPsi, new TextRange(1, textLength+1))</code>.
  46    * @see #processInjectedPsi(InjectedPsiVisitor) instead
  47    */
  48   @Nullable @Deprecated
  49   List<Pair<PsiElement,TextRange>> getInjectedPsi();
  50
  51   void processInjectedPsi(@NotNull InjectedPsiVisitor visitor);
  52
  53   PsiLanguageInjectionHost updateText(@NotNull String text);
  54
  55   @NotNull
  56   LiteralTextEscaper<? extends PsiLanguageInjectionHost> createLiteralTextEscaper();
  57
  58
  59   interface InjectedPsiVisitor {
  60     void visit(@NotNull PsiFile injectedPsi, @NotNull List<Shred> places);
  61   }
  62
  63   class Shred {
  64     public PsiLanguageInjectionHost host;
  65     private final RangeMarker relevantRangeInHost;
  66     public final TextRange range; // range in (decoded) PSI
  67     public final String prefix;
  68     public final String suffix;
  69
  70     public Shred(@NotNull PsiLanguageInjectionHost host, @NotNull RangeMarker relevantRangeInHost, @NotNull String prefix, @NotNull String suffix, @NotNull TextRange range) {
  71       this.host = host;
  72       this.relevantRangeInHost = relevantRangeInHost;
  73       this.prefix = prefix;
  74       this.suffix = suffix;
  75       this.range = range;
  76       assert isValid();
  77     }
  78
  79     public RangeMarker getHostRangeMarker() {
  80       return relevantRangeInHost;
  81     }
  82
  83     //@Nullable
  84     public TextRange getRangeInsideHost() {
  85       //if (!relevantRangeInHost.isValid()) return null;
  86       ProperTextRange textRange = new ProperTextRange(relevantRangeInHost.getStartOffset(), relevantRangeInHost.getEndOffset());
  87       TextRange result = textRange.shiftRight(-host.getTextRange().getStartOffset());
  88       assert host.getTextRange().contains(textRange);
  89       return result;
  90     }
  91
  92     @SuppressWarnings({"HardCodedStringLiteral"})
  93     public String toString() {
  94       return "Shred "+ host.getTextRange() + ": "+ host+
  95              " Inhost range: "+(relevantRangeInHost.isValid() ? "" : "!") + "(" + relevantRangeInHost.getStartOffset()+","+relevantRangeInHost.getEndOffset()+");" +
  96              " PSI range: "+range;
  97     }
  98
  99     public boolean isValid() {
 100       return relevantRangeInHost.isValid() && host.isValid();
 101     }
 102   }
 103 }