PY-20744 Parse PEP-526 variable annotations
[idea/community.git] / 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, PyAnnotationOwner {
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 }