Add isinstance keyword, and allow isinstance(x,t) to be parsed - but not resolved

Note that we parse arbitrary type expressions on the RHS of isinstance, but
will be planning to limit the allowed types when resolving (in a follow-up).
Consider, for example, something like isinstance(x, list[int]) - we cannot
allow it because x may subsequently get a non-int element added to it.
By contrast, we may want to allow e.g. `isinstance(f, Callable[[str], bool])`
to test if f is a predicate on a string (note that Python doesn't, but in
Python this is an eval-time error, not a syntax error). And further consider
the possibility of `isinstance(x, T)` - where `T` is a type alias (and which
might well be an alias for something we don't want to allow). So we cannot
take the simple path of syntactically allowing only identifiers.

Also make a drive-by fix to `cast()`'s pretty-printer.

Working towards bazelbuild#27372 and isinstance().

PiperOrigin-RevId: 829638719
Change-Id: Iad1c4307fb4da262031b5e664f846662a081c210

Author: tetromino

src/main/java/net/starlark/java/eval/Eval.java

@@ -562,6 +562,9 @@ private static Object eval(StarlarkThread.Frame fr, Expression expr)
         return evalCall(fr, (CallExpression) expr);
       case CAST:
         return eval(fr, ((CastExpression) expr).getValue());
+      case ISINSTANCE:
+        fr.setErrorLocation(expr.getStartLocation());
+        throw new EvalException("isinstance() is not yet supported");
       case IDENTIFIER:
         return evalIdentifier(fr, (Identifier) expr);
       case INDEX:

src/main/java/net/starlark/java/syntax/BUILD

@@ -41,6 +41,7 @@ java_library(
         "IfStatement.java",
         "IndexExpression.java",
         "IntLiteral.java",
+        "IsInstanceExpression.java",
         "LambdaExpression.java",
         "Lexer.java",
         "ListExpression.java",

src/main/java/net/starlark/java/syntax/Expression.java

@@ -41,6 +41,7 @@ public enum Kind {
     IDENTIFIER,
     INDEX,
     INT_LITERAL,
+    ISINSTANCE,
     LAMBDA,
     LIST_EXPR,
     SLICE,

src/main/java/net/starlark/java/syntax/IsInstanceExpression.java

@@ -0,0 +1,66 @@
+// Copyright 2025 The Bazel Authors. All rights reserved.
+//
+// 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 net.starlark.java.syntax;
+
+/** Syntax node for isinstance() expressions. */
+public final class IsInstanceExpression extends Expression {
+  private final int startOffset;
+  private final Expression value;
+  private final Expression type;
+  private final int rparenOffset;
+
+  IsInstanceExpression(
+      FileLocations locs, int startOffset, Expression value, Expression type, int rparenOffset) {
+    super(locs, Kind.ISINSTANCE);
+    this.startOffset = startOffset;
+    this.value = value;
+    this.type = type;
+    this.rparenOffset = rparenOffset;
+  }
+
+  @Override
+  public int getStartOffset() {
+    return startOffset;
+  }
+
+  @Override
+  public int getEndOffset() {
+    return rparenOffset + 1;
+  }
+
+  public Expression getValue() {
+    return value;
+  }
+
+  public Expression getType() {
+    return type;
+  }
+
+  @Override
+  public String toString() {
+    StringBuilder buf = new StringBuilder();
+    buf.append("isinstance(");
+    buf.append(value);
+    buf.append(", ");
+    buf.append(type);
+    buf.append(')');
+    return buf.toString();
+  }
+
+  @Override
+  public void accept(NodeVisitor visitor) {
+    visitor.visit(this);
+  }
+}

src/main/java/net/starlark/java/syntax/Lexer.java

@@ -562,6 +562,9 @@ private void scanToNewline() {
 
   private static final Map<String, TokenKind> keywordMap = new HashMap<>();
 
+  /** Additional keywords that are only recognized if --experimental_starlark_type_syntax is set. */
+  private static final Map<String, TokenKind> typeSyntaxExtraKeywordMap = new HashMap<>();
+
   static {
     keywordMap.put("and", TokenKind.AND);
     keywordMap.put("as", TokenKind.AS);
@@ -594,6 +597,9 @@ private void scanToNewline() {
     keywordMap.put("while", TokenKind.WHILE);
     keywordMap.put("with", TokenKind.WITH);
     keywordMap.put("yield", TokenKind.YIELD);
+
+    typeSyntaxExtraKeywordMap.put("cast", TokenKind.CAST);
+    typeSyntaxExtraKeywordMap.put("isinstance", TokenKind.ISINSTANCE);
   }
 
   /**
@@ -606,16 +612,14 @@ private void identifierOrKeyword() {
     int oldPos = pos - 1;
     String id = identInterner.intern(scanIdentifier());
     TokenKind kind = keywordMap.get(id);
+    if (kind == null && options.allowTypeSyntax()) {
+      kind = typeSyntaxExtraKeywordMap.get(id);
+    }
     if (kind == null) {
-      if (options.allowTypeSyntax() && id.equals("cast")) {
-        // `cast` is treated as a keyword iff --experimental_starlark_type_syntax is enabled.
-        setToken(TokenKind.CAST, oldPos, pos);
-      } else {
-        setToken(TokenKind.IDENTIFIER, oldPos, pos);
-        // setValue allocates a new String for the raw text, but it's not retained so we don't
-        // bother interning it.
-        setValue(id);
-      }
+      setToken(TokenKind.IDENTIFIER, oldPos, pos);
+      // setValue allocates a new String for the raw text, but it's not retained so we don't
+      // bother interning it.
+      setValue(id);
     } else {
       setToken(kind, oldPos, pos);
     }

src/main/java/net/starlark/java/syntax/NodePrinter.java

@@ -405,9 +405,9 @@ private void printExpr(Expression expr, boolean canSkipParenthesis) {
         {
           CastExpression cast = (CastExpression) expr;
           buf.append("cast(");
-          printExpr(cast.getType());
+          printExpr(cast.getType(), /* canSkipParenthesis= */ true);
           buf.append(", ");
-          printExpr(cast.getValue());
+          printExpr(cast.getValue(), /* canSkipParenthesis= */ true);
           buf.append(')');
           break;
         }
@@ -438,6 +438,17 @@ private void printExpr(Expression expr, boolean canSkipParenthesis) {
           break;
         }
 
+      case ISINSTANCE:
+        {
+          IsInstanceExpression isinstance = (IsInstanceExpression) expr;
+          buf.append("isinstance(");
+          printExpr(isinstance.getValue(), /* canSkipParenthesis= */ true);
+          buf.append(", ");
+          printExpr(isinstance.getType(), /* canSkipParenthesis= */ true);
+          buf.append(')');
+          break;
+        }
+
       case FLOAT_LITERAL:
         {
           buf.append(((FloatLiteral) expr).getValue());

src/main/java/net/starlark/java/syntax/NodeVisitor.java

@@ -58,6 +58,10 @@ public void visit(CastExpression node) {
     visit(node.getValue());
   }
 
+  public void visit(IsInstanceExpression node) {
+    visit(node.getValue());
+  }
+
   public void visit(Ellipsis node) {}
 
   public void visit(Identifier node) {}

src/main/java/net/starlark/java/syntax/Parser.java

@@ -569,6 +569,21 @@ private Expression parseCastExpression() {
     return new CastExpression(locs, startOffset, typeExpr, valueExpr, rparenOffset);
   }
 
+  // isinstance_expression = 'isinstance' '(' expr ',' TypeExpr [','] ')'
+  private Expression parseIsInstanceExpression() {
+    checkAllowTypeSyntax(token.start, token.kind, token.value);
+    int startOffset = expect(TokenKind.ISINSTANCE);
+    expect(TokenKind.LPAREN);
+    Expression valueExpr = parseTest();
+    expect(TokenKind.COMMA);
+    Expression typeExpr = parseTypeExprWithFallback();
+    if (token.kind == TokenKind.COMMA) {
+      expect(TokenKind.COMMA);
+    }
+    int rparenOffset = expect(TokenKind.RPAREN);
+    return new IsInstanceExpression(locs, startOffset, valueExpr, typeExpr, rparenOffset);
+  }
+
   // Parse a list of call arguments.
   //
   // arg_list = ( (arg ',')* arg ','? )?
@@ -754,6 +769,9 @@ private Expression parsePrimary() {
       case CAST:
         return parseCastExpression();
 
+      case ISINSTANCE:
+        return parseIsInstanceExpression();
+
       case ELLIPSIS:
         if (!insideTypeExpr) {
           syntaxError("ellipsis ('...') is not allowed outside type expressions");

src/main/java/net/starlark/java/syntax/Resolver.java

@@ -804,6 +804,14 @@ public void visit(VarStatement node) {
     assign(node.getIdentifier());
   }
 
+  @Override
+  public void visit(IsInstanceExpression node) {
+    // TODO(b/350661266): restrict the types that can be used on the RHS of isinstance(); e.g.
+    // `list` or `list | tuple` (or aliases resolving to those!) are allowed, but `list[int]` isn't,
+    // since a list can subsequently be mutated to add a non-int element.
+    errorf(node, "isinstance() is not yet supported");
+  }
+
   @Override
   public void visit(TypeAliasStatement node) {
     if (!(locals.syntax instanceof StarlarkFile)) {

src/main/java/net/starlark/java/syntax/TokenKind.java

@@ -68,6 +68,8 @@ public enum TokenKind {
   INDENT("indent"),
   INT("integer literal"),
   IS("is"),
+  /** Emitted only if --experimental_starlark_type_syntax is enabled. */
+  ISINSTANCE("isinstance"),
   LAMBDA("lambda"),
   LBRACE("{"),
   LBRACKET("["),