/*
* Copyright 2000-2012 JetBrains s.r.o.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.intellij.psi;
import com.intellij.lang.Language;
import com.intellij.openapi.editor.Document;
import com.intellij.openapi.fileTypes.FileType;
import com.intellij.openapi.util.UserDataHolder;
import com.intellij.openapi.vfs.VirtualFile;
import com.intellij.testFramework.LightVirtualFile;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.List;
import java.util.Set;
/**
* Manages language-specific access to PSI for a single file.
* <p/>
* Custom providers are registered via {@link FileViewProviderFactory}.
* <p/>
* Please see <a href="http://confluence.jetbrains.net/display/IDEADEV/IntelliJ+IDEA+Architectural+Overview">IntelliJ IDEA Architectural Overview </a>
* for high-level overview.
*
* @see PsiFile#getViewProvider()
* @see PsiManager#findViewProvider(VirtualFile)
*/
public interface FileViewProvider extends Cloneable, UserDataHolder {
/**
* @return this project's PsiManager
*/
@NotNull
PsiManager getManager();
/**
* @return the document corresponding to this file. Can be null for binary or files without events enabled.
*
* @see FileType#isBinary()
* @see PsiBinaryFile
* @see #isEventSystemEnabled()
*/
@Nullable
Document getDocument();
/**
* @return the contents of this file view provider, which are parsed into PSI trees. May or may not be equal
* to the contents of the corresponding document. The latter happens for non-committed documents.
* If the document is modified but not yet committed, the result is equivalent to {@link PsiDocumentManager#getLastCommittedText(Document)}.
*
* @see #getDocument()
* @see PsiDocumentManager#isUncommited(Document)
*/
@NotNull
CharSequence getContents();
/**
* @return the virtual file corresponding to this view provider. Physical or an instance of {@link LightVirtualFile} for most non-physical files.
*/
@NotNull
VirtualFile getVirtualFile();
/**
* @return the language of the main PSI tree (or the only one in a single-tree view providers). Used when returning a PsiFile from
* {@link PsiManager#findFile(VirtualFile)},
* {@link PsiDocumentManager#getPsiFile(Document)} etc.
*/
@NotNull
Language getBaseLanguage();
/**
* @return all languages this file supports, in no particular order.
*
* @see #getPsi(com.intellij.lang.Language)
*/
@NotNull
Set<Language> getLanguages();
/**
* @param target target language
* @return PsiFile for given language, or {@code null} if the language not present
*/
PsiFile getPsi(@NotNull Language target);
/**
* @return all PSI files for this view provider. In most cases, just one main file. For multi-root languages, several files. The files' languages
* should be the same as {@link #getLanguages()}. The main file which corresponds to {@link #getBaseLanguage()}, should be the first one. Otherwise
* the order is non-deterministic and should not be relied upon.
*/
@NotNull
List<PsiFile> getAllFiles();
/**
* @return whether PSI events are fired when changes occur inside PSI in this view provider. True for physical files and for some non-physical as well.
*
* @see PsiTreeChangeListener
* @see PsiFileFactory#createFileFromText(String, FileType, CharSequence, long, boolean)
* @see PsiFile#isPhysical()
*/
boolean isEventSystemEnabled();
/**
* @return whether this file corresponds to a file on a disk. For such files, {@link PsiFile#getVirtualFile()} returns non-null.
* Not to be confused with {@link PsiFile#isPhysical()} which (for historical reasons) returns {@code getViewProvider().isEventSystemEnabled()}
*
* @see #isEventSystemEnabled()
* @see PsiFile#isPhysical()
*/
boolean isPhysical();
/**
* @return a number to quickly check if contents of this view provider have diverged from the corresponding {@link VirtualFile} or {@link Document}.
* If a document is modified but not yet committed, the result is the same as {@link PsiDocumentManager#getLastCommittedStamp(Document)}
*
* @see VirtualFile#getModificationStamp()
* @see Document#getModificationStamp()
*/
long getModificationStamp();
/**
* @param rootLanguage one of the root languages
* @return whether the PSI file with the specified root language supports incremental reparse.
*
* @see #getLanguages()
*/
boolean supportsIncrementalReparse(@NotNull Language rootLanguage);
/**
* Invoked when any PSI change happens in any of the PSI files corresponding to this view provider.
* @param psiFile the file where PSI has just been changed.
*/
void rootChanged(@NotNull PsiFile psiFile);
/**
* Invoked before document or VFS changes are processed that affect PSI inside the corresponding file.
*/
void beforeContentsSynchronized();
/**
* Invoked after PSI in the corresponding file is synchronized with the corresponding document, which can happen
* after VFS, document or PSI changes.<p/>
*
* Multi-language file view providers may override this method to recalculate template data languages.
*
* @see #getLanguages()
*/
void contentsSynchronized();
/**
* @return a copy of this view provider, built on a {@link LightVirtualFile}, not physical and with PSI events disabled.
*
* @see #isPhysical()
* @see #isEventSystemEnabled()
* @see #createCopy(VirtualFile)
*/
FileViewProvider clone();
/**
* @param offset an offset in the file
* @return the deepest (leaf) PSI element in the main PSI tree at the specified offset.
*
* @see #getBaseLanguage()
* @see #findElementAt(int, Class)
* @see #findElementAt(int, com.intellij.lang.Language)
* @see PsiFile#findElementAt(int)
*/
@Nullable
PsiElement findElementAt(int offset);
/**
* @param offset an offset in the file
* @return a reference in the main PSI tree at the specified offset.
*
* @see #getBaseLanguage()
* @see PsiFile#findReferenceAt(int)
* @see #findReferenceAt(int, com.intellij.lang.Language)
*/
@Nullable
PsiReference findReferenceAt(int offset);
/**
* @param offset an offset in the file
* @return the deepest (leaf) PSI element in the PSI tree with the specified root language at the specified offset.
*
* @see #getBaseLanguage()
* @see #findElementAt(int)
*/
@Nullable
PsiElement findElementAt(int offset, @NotNull Language language);
/**
* @param offset an offset in the file
* @return the deepest (leaf) PSI element in the PSI tree with the specified root language class at the specified offset.
*
* @see #getBaseLanguage()
* @see #findElementAt(int)
*/
@Nullable
PsiElement findElementAt(int offset, @NotNull Class<? extends Language> lang);
/**
* @param offsetInElement an offset in the file
* @return a reference in the PSI tree with the specified root language at the specified offset.
*
* @see #getBaseLanguage()
* @see PsiFile#findReferenceAt(int)
* @see #findReferenceAt(int)
*/
@Nullable
PsiReference findReferenceAt(int offsetInElement, @NotNull Language language);
/**
* Creates a copy of this view provider linked with the give (typically light) file.
* The result provider is required to be NOT event-system-enabled.
*
* @see LightVirtualFile
* @see #isEventSystemEnabled()
*/
@NotNull
FileViewProvider createCopy(@NotNull VirtualFile copy);
/**
* @return the PSI root for which stubs are to be built if supported. By default it's the main root.
*
* @see #getBaseLanguage()
*/
@NotNull
PsiFile getStubBindingRoot();
/**
* @return the same as {@code getVirtualFile().getFileType()}, but cached.
*/
@NotNull
FileType getFileType();
}