SONARPY-914 Match / case statement: support sequence patterns (#983)

Author: andrea-guarino-sonarsource

python-frontend/src/main/java/org/sonar/plugins/python/api/tree/BaseTreeVisitor.java

@@ -505,4 +505,14 @@ public void visitGuard(Guard guard) {
   public void visitCapturePattern(CapturePattern capturePattern) {
     scan(capturePattern.name());
   }
+
+  @Override
+  public void visitSequencePattern(SequencePattern sequencePattern) {
+    scan(sequencePattern.elements());
+  }
+
+  @Override
+  public void visitStarPattern(StarPattern starPattern) {
+    scan(starPattern.capturePattern());
+  }
 }

python-frontend/src/main/java/org/sonar/plugins/python/api/tree/CapturePattern.java

@@ -19,6 +19,16 @@
  */
 package org.sonar.plugins.python.api.tree;
 
+/**
+ * Capture Pattern
+ *
+ * <pre>
+ *   case x:
+ *     ...
+ * </pre>
+ *
+ * See https://docs.python.org/3/reference/compound_stmts.html#capture-patterns
+ */
 public interface CapturePattern extends Pattern {
 
   Name name();

python-frontend/src/main/java/org/sonar/plugins/python/api/tree/SequencePattern.java

@@ -0,0 +1,41 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2021 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.plugins.python.api.tree;
+
+import java.util.List;
+
+/**
+ * Sequence Pattern
+ *
+ * <pre>
+ *   case [x, y, z]:
+ *     ...
+ *   case (x, y, z):
+ *     ...
+ *   case x, y, z:
+ *     ...
+ * </pre>
+ *
+ * See https://docs.python.org/3/reference/compound_stmts.html#sequence-patterns
+ */
+public interface SequencePattern extends Pattern {
+
+  List<Pattern> elements();
+}

python-frontend/src/main/java/org/sonar/plugins/python/api/tree/StarPattern.java

@@ -0,0 +1,36 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2021 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.plugins.python.api.tree;
+
+/**
+ * Star Pattern
+ * Only used inside sequence patterns
+ *
+ * <pre>
+ *   case [x, y, *others]:
+ *     ...
+ * </pre>
+ *
+ * See https://docs.python.org/3/reference/compound_stmts.html#grammar-token-python-grammar-star_pattern
+ */
+public interface StarPattern extends Pattern {
+
+  CapturePattern capturePattern();
+}

python-frontend/src/main/java/org/sonar/plugins/python/api/tree/Tree.java

@@ -138,10 +138,14 @@ enum Kind {
 
     RETURN_STMT(ReturnStatement.class),
 
+    SEQUENCE_PATTERN(SequencePattern.class),
+
     SET_LITERAL(SetLiteral.class),
 
     STATEMENT_LIST(StatementList.class),
 
+    STAR_PATTERN(StarPattern.class),
+
     STRING_LITERAL(StringLiteral.class),
 
     STRING_ELEMENT(StringElement.class),

python-frontend/src/main/java/org/sonar/plugins/python/api/tree/TreeVisitor.java

@@ -184,4 +184,8 @@ public interface TreeVisitor {
   void visitGuard(Guard guard);
 
   void visitCapturePattern(CapturePattern capturePattern);
+
+  void visitSequencePattern(SequencePattern sequencePattern);
+
+  void visitStarPattern(StarPattern starPattern);
 }

python-frontend/src/main/java/org/sonar/python/api/PythonGrammar.java

@@ -154,11 +154,17 @@ public enum PythonGrammar implements GrammarRuleKey {
   CASE_BLOCK,
   GUARD,
 
+  PATTERNS,
   PATTERN,
   AS_PATTERN,
   CLOSED_PATTERN,
   LITERAL_PATTERN,
   CAPTURE_PATTERN,
+  SEQUENCE_PATTERN,
+  STAR_PATTERN,
+  MAYBE_STAR_PATTERN,
+  MAYBE_SEQUENCE_PATTERN,
+  OPEN_SEQUENCE_PATTERN,
 
   SIGNED_NUMBER,
   COMPLEX_NUMBER,
@@ -455,14 +461,25 @@ public static void compoundStatements(LexerfulGrammarBuilder b) {
 
     b.rule(MATCH_STMT).is("match", SUBJECT_EXPR, ":", NEWLINE, INDENT, b.oneOrMore(CASE_BLOCK), DEDENT);
     b.rule(SUBJECT_EXPR).is(STAR_NAMED_EXPRESSIONS);
-    b.rule(CASE_BLOCK).is("case", PATTERN, b.optional(GUARD), ":", SUITE);
+    b.rule(CASE_BLOCK).is("case", PATTERNS, b.optional(GUARD), ":", SUITE);
     b.rule(GUARD).is("if", NAMED_EXPR_TEST);
 
+    b.rule(PATTERNS).is(b.firstOf(OPEN_SEQUENCE_PATTERN, PATTERN));
     b.rule(PATTERN).is(b.firstOf(AS_PATTERN, CLOSED_PATTERN));
-    b.rule(CLOSED_PATTERN).is(b.firstOf(LITERAL_PATTERN, CAPTURE_PATTERN));
+    b.rule(CLOSED_PATTERN).is(b.firstOf(LITERAL_PATTERN, CAPTURE_PATTERN, SEQUENCE_PATTERN));
     b.rule(AS_PATTERN).is(CLOSED_PATTERN, "as", CAPTURE_PATTERN);
     b.rule(CAPTURE_PATTERN).is(NAME);
 
+    b.rule(SEQUENCE_PATTERN).is(b.firstOf(
+      b.sequence("[", b.optional(MAYBE_SEQUENCE_PATTERN) , "]"),
+      b.sequence("(", b.optional(OPEN_SEQUENCE_PATTERN), ")")
+    ));
+    b.rule(OPEN_SEQUENCE_PATTERN).is(MAYBE_STAR_PATTERN, ",", b.optional(MAYBE_SEQUENCE_PATTERN));
+    b.rule(MAYBE_SEQUENCE_PATTERN).is(MAYBE_STAR_PATTERN, b.zeroOrMore(",", MAYBE_STAR_PATTERN), b.optional(","));
+    b.rule(MAYBE_STAR_PATTERN).is(b.firstOf(STAR_PATTERN, PATTERN));
+    // TODO: ADD wildcard pattern for "*_"
+    b.rule(STAR_PATTERN).is("*", CAPTURE_PATTERN);
+
     b.rule(LITERAL_PATTERN).is(b.firstOf(
       COMPLEX_NUMBER,
       SIGNED_NUMBER,

python-frontend/src/main/java/org/sonar/python/tree/PythonTreeMaker.java

@@ -81,8 +81,10 @@
 import org.sonar.plugins.python.api.tree.RaiseStatement;
 import org.sonar.plugins.python.api.tree.RegularArgument;
 import org.sonar.plugins.python.api.tree.ReturnStatement;
+import org.sonar.plugins.python.api.tree.SequencePattern;
 import org.sonar.plugins.python.api.tree.SliceItem;
 import org.sonar.plugins.python.api.tree.SliceList;
+import org.sonar.plugins.python.api.tree.StarPattern;
 import org.sonar.plugins.python.api.tree.Statement;
 import org.sonar.plugins.python.api.tree.StatementList;
 import org.sonar.plugins.python.api.tree.StringElement;
@@ -805,7 +807,8 @@ public MatchStatement matchStatement(AstNode matchStmt) {
 
   public CaseBlock caseBlock(AstNode caseBlock) {
     Token caseKeyword = toPyToken(caseBlock.getTokens().get(0));
-    Pattern pattern = pattern(caseBlock.getFirstChild(PythonGrammar.PATTERN).getFirstChild());
+    AstNode patternOrSequence = caseBlock.getFirstChild(PythonGrammar.PATTERNS).getFirstChild();
+    Pattern pattern = patternOrSequence.is(PythonGrammar.PATTERN) ? pattern(patternOrSequence.getFirstChild()) : sequencePattern(patternOrSequence);
     Guard guard = null;
     AstNode guardNode = caseBlock.getFirstChild(PythonGrammar.GUARD);
     if (guardNode != null) {
@@ -843,8 +846,62 @@ private static Pattern closedPattern(AstNode closedPattern) {
       return literalPattern(astNode);
     } else if (astNode.is(PythonGrammar.CAPTURE_PATTERN)) {
       return new CapturePatternImpl(name(astNode.getFirstChild()));
+    } else if (astNode.is(PythonGrammar.SEQUENCE_PATTERN)) {
+      return sequencePattern(astNode);
+    }
+    throw new IllegalStateException(String.format("Pattern %s not recognized.", astNode.getName()));
+  }
+
+  private static SequencePattern sequencePattern(AstNode sequencePattern) {
+    AstNode leftDelimiter = sequencePattern.getFirstChild(PythonPunctuator.LPARENTHESIS, PythonPunctuator.LBRACKET);
+    AstNode rightDelimiter = sequencePattern.getFirstChild(PythonPunctuator.RPARENTHESIS, PythonPunctuator.RBRACKET);
+    List<Token> commas = new ArrayList<>();
+    List<Pattern> patterns = new ArrayList<>();
+    if (leftDelimiter == null) {
+      // sequence patterns without neither parenthesis nor square brackets.
+      // In this case there needs to be at least one comma
+      addPatternsAndCommasFromSequencePattern(sequencePattern, commas, patterns);
+      return new SequencePatternImpl(null, patterns, commas, null);
+    }
+    if (leftDelimiter.is(PythonPunctuator.LPARENTHESIS)) {
+      // we need to treat differently when delimiters are parenthesis '(' ')' because there needs to be at least one comma
+      // e.g. '(x)' is not a sequence pattern but a group pattern instead, while '(x,)' is a sequence pattern
+      AstNode openSequencePattern = sequencePattern.getFirstChild(PythonGrammar.OPEN_SEQUENCE_PATTERN);
+      if (openSequencePattern != null) {
+        addPatternsAndCommasFromSequencePattern(openSequencePattern, commas, patterns);
+      }
+    } else {
+      addPatternsAndCommasFromMaybeSequencePattern(sequencePattern.getFirstChild(PythonGrammar.MAYBE_SEQUENCE_PATTERN), patterns, commas);
+    }
+    return new SequencePatternImpl(toPyToken(leftDelimiter.getToken()), patterns, commas, toPyToken(rightDelimiter.getToken()));
+  }
+
+  private static void addPatternsAndCommasFromSequencePattern(AstNode sequencePattern, List<Token> commas, List<Pattern> patterns) {
+    commas.add(toPyToken(sequencePattern.getFirstChild(PythonPunctuator.COMMA).getToken()));
+    patterns.add(maybeStarPattern(sequencePattern.getFirstChild(PythonGrammar.MAYBE_STAR_PATTERN)));
+    addPatternsAndCommasFromMaybeSequencePattern(sequencePattern.getFirstChild(PythonGrammar.MAYBE_SEQUENCE_PATTERN), patterns, commas);
+  }
+
+  private static void addPatternsAndCommasFromMaybeSequencePattern(@Nullable AstNode maybeSequencePattern,List<Pattern> patterns, List<Token> commas) {
+    if (maybeSequencePattern == null) {
+      return;
+    }
+    patterns.addAll(maybeSequencePattern.getChildren(PythonGrammar.MAYBE_STAR_PATTERN).stream().map(PythonTreeMaker::maybeStarPattern).collect(Collectors.toList()));
+    commas.addAll(punctuators(maybeSequencePattern, PythonPunctuator.COMMA));
+  }
+
+  private static Pattern maybeStarPattern(AstNode maybeStarPattern) {
+    AstNode astNode = maybeStarPattern.getFirstChild();
+    if (astNode.is(PythonGrammar.STAR_PATTERN)) {
+      return starPattern(astNode);
     }
-    throw new IllegalStateException(String.format("Pattern %s not recognized.", closedPattern.getName()));
+    return pattern(astNode.getFirstChild());
+  }
+
+  private static StarPattern starPattern(AstNode starPattern) {
+    Token starToken = toPyToken(starPattern.getFirstChild(PythonPunctuator.MUL).getToken());
+    AstNode capturePattern = starPattern.getFirstChild(PythonGrammar.CAPTURE_PATTERN);
+    return new StarPatternImpl(starToken, new CapturePatternImpl(name(capturePattern.getFirstChild())));
   }
 
   private static LiteralPattern literalPattern(AstNode literalPattern) {

python-frontend/src/main/java/org/sonar/python/tree/SequencePatternImpl.java

@@ -0,0 +1,81 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2021 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.python.tree;
+
+import java.util.ArrayList;
+import java.util.List;
+import javax.annotation.Nullable;
+import org.sonar.plugins.python.api.tree.Pattern;
+import org.sonar.plugins.python.api.tree.SequencePattern;
+import org.sonar.plugins.python.api.tree.Token;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.tree.TreeVisitor;
+
+public class SequencePatternImpl extends PyTree implements SequencePattern {
+
+  @Nullable
+  private final Token leftDelimiter; // might be '(' or '['
+  private final List<Pattern> elements;
+  private final List<Token> commas;
+  @Nullable
+  private final Token rightDelimiter; // might be ')' or ']'
+
+  public SequencePatternImpl(@Nullable Token leftDelimiter, List<Pattern> elements, List<Token> commas, @Nullable Token rightDelimiter) {
+    this.leftDelimiter = leftDelimiter;
+    this.elements = elements;
+    this.commas = commas;
+    this.rightDelimiter = rightDelimiter;
+  }
+
+  @Override
+  public List<Pattern> elements() {
+    return elements;
+  }
+
+  @Override
+  public void accept(TreeVisitor visitor) {
+    visitor.visitSequencePattern(this);
+  }
+
+  @Override
+  public Kind getKind() {
+    return Kind.SEQUENCE_PATTERN;
+  }
+
+  @Override
+  List<Tree> computeChildren() {
+    List<Tree> children = new ArrayList<>();
+    if (leftDelimiter != null) {
+      children.add(leftDelimiter);
+    }
+    int i = 0;
+    for (Pattern element : elements) {
+      children.add(element);
+      if (i < commas.size()) {
+        children.add(commas.get(i));
+      }
+      i++;
+    }
+    if (rightDelimiter != null) {
+      children.add(rightDelimiter);
+    }
+    return children;
+  }
+}