python/psi-api/src/com/jetbrains/python/psi/PyAssignmentStatement.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.openapi.util.Pair;
  19 import org.jetbrains.annotations.NotNull;
  20 import org.jetbrains.annotations.Nullable;
  21
  22 import java.util.List;
  23
  24 /**
  25  * Describes an assignment statement.
  26  */
  27 public interface PyAssignmentStatement extends PyStatement, PyNamedElementContainer {
  28
  29   /**
  30    * @return the left-hand side of the statement; each item may consist of many elements.
  31    */
  32   PyExpression[] getTargets();
  33
  34   /**
  35    * Return all expressions which are considered assignment targets (to the left of the last = sign in the statement).
  36    * Doesn't unpack tuples, parentheses or anything.
  37    *
  38    * @return the list of assignment target expressions
  39    */
  40   @NotNull
  41   PyExpression[] getRawTargets();
  42
  43
  44   /**
  45    * @return right-hand side of the statement; may as well consist of many elements.
  46    */
  47   @Nullable
  48   PyExpression getAssignedValue();
  49
  50   /**
  51    * Applies a visitor to every element of left-hand side. Tuple elements are flattened down to their most nested
  52    * parts. E.g. if the target is <tt>a, b[1], (c(2).d, e.f)</tt>, then expressions
  53    * <tt>a</tt>, <tt>b[1]</tt>, <tt>c(2).d</tt>, <tt>e.f</tt> will be visited.
  54    * Order of visiting is not guaranteed.
  55    * @param visitor its {@link PyElementVisitor#visitPyExpression} method will be called for each elementary target expression
  56    */
  57   //void visitElementaryTargets(PyElementVisitor visitor);
  58
  59
  60   /**
  61    * Maps target expressions to assigned values, unpacking tuple expressions.
  62    * For "{@code a, (b, c) = 1, (2, 'foo')}" the result will be [(a,1), (b:2), (c:'foo')].
  63    * <br/>
  64    * If there's a number of LHS targets, the RHS expression is mapped to every target.
  65    * For "{@code a = b = c = 1}" the result will be [(a,1), (b,1), (c,1)].
  66    * <br/>
  67    * Elements of tuples and tuples themselves may get interspersed in complex mappings.
  68    * For "{@code a = b,c = 1,2}" the result will be [(a,(1,2)), (b,1), (c,2)].
  69    * <br/>
  70    * If RHS and LHS are mis-balanced, certain target or value expressions may be null.
  71    * If source is severely incorrect, the returned mapping is empty.
  72    * @return a list of [target, value] pairs; either part of a pair may be null, but not both.
  73    */
  74   @NotNull
  75   List<Pair<PyExpression, PyExpression>> getTargetsToValuesMapping();
  76
  77   @Nullable
  78   PyExpression getLeftHandSideExpression();
  79
  80   boolean isAssignmentTo(@NotNull String name);
  81
  82 }