python/psi-api/src/com/jetbrains/python/psi/PyElementGenerator.java

   1 /*
   2  * Copyright 2000-2014 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 package com.jetbrains.python.psi;
  17
  18 import com.intellij.lang.ASTNode;
  19 import com.intellij.openapi.components.ServiceManager;
  20 import com.intellij.openapi.project.Project;
  21 import com.intellij.psi.PsiElement;
  22 import com.intellij.psi.PsiFile;
  23 import com.intellij.util.IncorrectOperationException;
  24 import org.jetbrains.annotations.NotNull;
  25 import org.jetbrains.annotations.Nullable;
  26
  27 public abstract class PyElementGenerator {
  28   public static PyElementGenerator getInstance(Project project) {
  29     return ServiceManager.getService(project, PyElementGenerator.class);
  30   }
  31
  32   public abstract ASTNode createNameIdentifier(String name, LanguageLevel languageLevel);
  33
  34   /**
  35    * str must have quotes around it and be fully escaped.
  36    */
  37   public abstract PyStringLiteralExpression createStringLiteralAlreadyEscaped(String str);
  38
  39
  40   /**
  41    * Creates a string literal, adding appropriate quotes, properly escaping characters inside.
  42    *
  43    * @param destination where the literal is destined to; used to determine the encoding.
  44    * @param unescaped   the string
  45    * @param preferUTF8 try to use UTF8 (would use ascii if false)
  46    * @return a newly created literal
  47    */
  48   public abstract PyStringLiteralExpression createStringLiteralFromString(@Nullable PsiFile destination, String unescaped,
  49                                                                           boolean preferUTF8);
  50
  51   public abstract PyStringLiteralExpression createStringLiteralFromString(@NotNull String unescaped);
  52
  53   public abstract PyStringLiteralExpression createStringLiteral(@NotNull PyStringLiteralExpression oldElement, @NotNull String unescaped);
  54
  55   public abstract PyListLiteralExpression createListLiteral();
  56
  57   public abstract ASTNode createComma();
  58
  59   public abstract ASTNode createDot();
  60
  61   public abstract PyBinaryExpression createBinaryExpression(String s, PyExpression expr, PyExpression listLiteral);
  62
  63   /**
  64    * @param text the text to create an expression from
  65    * @return the expression
  66    * @deprecated use the overload with language level specified
  67    */
  68   public abstract PyExpression createExpressionFromText(String text);
  69
  70   public abstract PyExpression createExpressionFromText(final LanguageLevel languageLevel, String text);
  71
  72   /**
  73    * Adds elements to list inserting required commas.
  74    * Method is like {@link #insertItemIntoList(PyElement, PyExpression, PyExpression)} but does not add unneeded commas.
  75    *
  76    * @param list      where to add
  77    * @param afterThis after which element it should be added (null for add to the head)
  78    * @param toInsert  what to insert
  79    * @return newly inserted element
  80    */
  81   @NotNull
  82   public abstract PsiElement insertItemIntoListRemoveRedundantCommas(
  83     @NotNull PyElement list,
  84     @Nullable PyExpression afterThis,
  85     @NotNull PyExpression toInsert);
  86
  87   public abstract PsiElement insertItemIntoList(PyElement list, @Nullable PyExpression afterThis, PyExpression toInsert)
  88     throws IncorrectOperationException;
  89
  90   @NotNull
  91   public abstract PyCallExpression createCallExpression(final LanguageLevel langLevel, String functionName);
  92
  93   public abstract PyImportElement createImportElement(final LanguageLevel languageLevel, String name);
  94
  95   public abstract PyFunction createProperty(final LanguageLevel languageLevel,
  96                                             String propertyName,
  97                                             String fieldName,
  98                                             AccessDirection accessDirection);
  99
 100   @NotNull
 101   public abstract <T> T createFromText(LanguageLevel langLevel, Class<T> aClass, final String text);
 102
 103   @NotNull
 104   public abstract <T> T createPhysicalFromText(LanguageLevel langLevel, Class<T> aClass, final String text);
 105
 106   /**
 107    * Creates an arbitrary PSI element from text, by creating a bigger construction and then cutting the proper subelement.
 108    * Will produce all kinds of exceptions if the path or class would not match the PSI tree.
 109    *
 110    * @param langLevel the language level to use for parsing the text
 111    * @param aClass    class of the PSI element; may be an interface not descending from PsiElement, as long as target node can be cast to it
 112    * @param text      text to parse
 113    * @param path      a sequence of numbers, each telling which child to select at current tree level; 0 means first child, etc.
 114    * @return the newly created PSI element
 115    */
 116   @NotNull
 117   public abstract <T> T createFromText(LanguageLevel langLevel, Class<T> aClass, final String text, final int[] path);
 118
 119   public abstract PyNamedParameter createParameter(@NotNull String name, @Nullable String defaultValue, @Nullable String annotation,
 120                                                    @NotNull LanguageLevel level);
 121
 122   public abstract PyNamedParameter createParameter(@NotNull String name);
 123
 124   public abstract PyKeywordArgument createKeywordArgument(LanguageLevel languageLevel, String keyword, String value);
 125
 126   public abstract PsiFile createDummyFile(LanguageLevel langLevel, String contents);
 127
 128   public abstract PyExpressionStatement createDocstring(String content);
 129
 130   public abstract PyPassStatement createPassStatement();
 131
 132   @NotNull
 133   public abstract PyDecoratorList createDecoratorList(@NotNull final String... decoratorTexts);
 134
 135   /**
 136    * Creates new line whitespace
 137    */
 138   @NotNull
 139   public abstract PsiElement createNewLine();
 140
 141   /**
 142    * Creates import statement of form {@code from qualifier import name as alias}.
 143    *
 144    * @param languageLevel language level for created element
 145    * @param qualifier     from where {@code name} will be imported (module name)
 146    * @param name          text of the reference in import element
 147    * @param alias         optional alias for {@code as alias} part
 148    * @return created {@link com.jetbrains.python.psi.PyFromImportStatement}
 149    */
 150   @NotNull
 151   public abstract PyFromImportStatement createFromImportStatement(@NotNull LanguageLevel languageLevel,
 152                                                                   @NotNull String qualifier,
 153                                                                   @NotNull String name,
 154                                                                   @Nullable String alias);
 155
 156   /**
 157    * Creates import statement of form {@code import name as alias}.
 158    *
 159    * @param languageLevel language level for created element
 160    * @param name          text of the reference in import element (module name)
 161    * @param alias         optional alias for {@code as alias} part
 162    * @return created {@link com.jetbrains.python.psi.PyImportStatement}
 163    */
 164   @NotNull
 165   public abstract PyImportStatement createImportStatement(@NotNull LanguageLevel languageLevel,
 166                                                           @NotNull String name,
 167                                                           @Nullable String alias);
 168 }