#2876 #2873 Better handling of async/await syntax

hurricup · hurricup · commit d0fbcca4832a · 2024-08-18T14:51:46.000+04:00
- `await` is now parsed as an unary named operator - `async`/`await` are now implicitly declared and auto-imported as subs from the package, making completion and quickdoc work as expected Fixes #2876 #2873 See also: #2878 #2877 #2875
diff --git a/plugin/core/grammar/Perl.flex b/plugin/core/grammar/Perl.flex
@@ -134,7 +134,7 @@ TYPES_TINY = "ArrayRef"|"ConsumerOf"|"CycleTuple"|"Dict"|"Enum"|"HasMethods"|"Ha
 READONLY="Readonly"
 
 // auto-generated by handlesubs.pl
-NAMED_UNARY_OPERATORS = "umask"|"srand"|"sleep"|"setservent"|"setprotoent"|"setnetent"|"sethostent"|"reset"|"readline"|"rand"|"prototype"|"localtime"|"gmtime"|"getsockname"|"getpwuid"|"getpwnam"|"getprotobyname"|"getpgrp"|"getpeername"|"getnetbyname"|"gethostbyname"|"getgrnam"|"getgrgid"|"exists"|"caller"
+NAMED_UNARY_OPERATORS = "umask"|"srand"|"sleep"|"setservent"|"setprotoent"|"setnetent"|"sethostent"|"reset"|"readline"|"rand"|"prototype"|"localtime"|"gmtime"|"getsockname"|"getpwuid"|"getpwnam"|"getprotobyname"|"getpgrp"|"getpeername"|"getnetbyname"|"gethostbyname"|"getgrnam"|"getgrgid"|"exists"|"caller"|"await"
 BARE_HANDLE_ACCEPTORS = "truncate"|"syswrite"|"sysseek"|"sysread"|"sysopen"|"stat"|"select"|"seekdir"|"seek"|"read"|"opendir"|"open"|"lstat"|"ioctl"|"flock"|"fcntl"|"binmode"
 NAMED_UNARY_BARE_HANDLE_ACCEPTORS = "write"|"telldir"|"tell"|"rewinddir"|"readdir"|"getc"|"fileno"|"eof"|"closedir"|"close"|"chdir"
 LIST_OPERATORS = "warn"|"waitpid"|"vec"|"utime"|"untie"|"tied"|"tie"|"system"|"syscall"|"symlink"|"substr"|"sprintf"|"socketpair"|"socket"|"shutdown"|"shmwrite"|"shmread"|"shmget"|"shmctl"|"setsockopt"|"setpriority"|"setpgrp"|"send"|"semop"|"semget"|"semctl"|"rindex"|"rename"|"recv"|"pipe"|"pack"|"msgsnd"|"msgrcv"|"msgget"|"msgctl"|"lock"|"listen"|"link"|"kill"|"join"|"index"|"getsockopt"|"getservbyport"|"getservbyname"|"getprotobynumber"|"getpriority"|"getnetbyaddr"|"gethostbyaddr"|"formline"|"exec"|"dump"|"die"|"dbmopen"|"dbmclose"|"crypt"|"connect"|"chown"|"chmod"|"bind"|"atan2"|"accept"
diff --git a/plugin/core/src/main/gen/com/perl5/lang/perl/lexer/PerlLexer.java b/plugin/core/src/main/gen/com/perl5/lang/perl/lexer/PerlLexer.java
diff --git a/plugin/core/src/main/java/com/perl5/lang/perl/extensions/futureAsyncAwait/FutureAsyncAwaitImplicitDeclarationsProvider.java b/plugin/core/src/main/java/com/perl5/lang/perl/extensions/futureAsyncAwait/FutureAsyncAwaitImplicitDeclarationsProvider.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2015-2024 Alexandr Evstigneev
+ *
+ * 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 com.perl5.lang.perl.extensions.futureAsyncAwait;
+
+import com.perl5.lang.perl.psi.references.PerlImplicitDeclarationsProvider;
+import org.jetbrains.annotations.NotNull;
+
+public class FutureAsyncAwaitImplicitDeclarationsProvider extends PerlImplicitDeclarationsProvider {
+  @Override
+  public @NotNull String getDataFileName() {
+    return "perlData/FutureAsyncAwait.xml";
+  }
+}
diff --git a/plugin/core/src/main/java/com/perl5/lang/perl/extensions/futureAsyncAwait/FutureAsyncAwaitPackageProcessor.java b/plugin/core/src/main/java/com/perl5/lang/perl/extensions/futureAsyncAwait/FutureAsyncAwaitPackageProcessor.java
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2015-2024 Alexandr Evstigneev
+ *
+ * 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 com.perl5.lang.perl.extensions.futureAsyncAwait;
+
+import com.perl5.lang.perl.extensions.packageprocessor.PerlPackageOptionsProvider;
+import com.perl5.lang.perl.extensions.packageprocessor.PerlPackageProcessorBase;
+import com.perl5.lang.perl.psi.impl.PerlUseStatementElement;
+import org.jetbrains.annotations.NotNull;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+public class FutureAsyncAwaitPackageProcessor extends PerlPackageProcessorBase implements PerlPackageOptionsProvider {
+  /**
+   * These are actually keywords, but to avoid writing custom code for documentation/completion, we treat them here as exported methods
+   * and lexer handles the rest.
+   */
+  private static final List<String> METHODS = List.of("async", "await");
+
+  @Override
+  public void addExports(@NotNull PerlUseStatementElement useStatement,
+                         @NotNull Set<? super String> export,
+                         @NotNull Set<? super String> exportOk) {
+    export.addAll(METHODS);
+    exportOk.addAll(METHODS);
+  }
+
+  @Override
+  public @NotNull Map<String, String> getOptions() {
+    return Collections.emptyMap();
+  }
+
+  @Override
+  public @NotNull Map<String, String> getOptionsBundles() {
+    return Collections.emptyMap();
+  }
+}
diff --git a/plugin/core/src/main/resources/perlData/FutureAsyncAwait.xml b/plugin/core/src/main/resources/perlData/FutureAsyncAwait.xml
@@ -0,0 +1,27 @@
+<!--
+  ~ Copyright 2015-2020 Alexandr Evstigneev
+  ~
+  ~ 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.
+  -->
+<xml>
+  <package name="Future::AsyncAwait">
+    <!-- This is actually a keyword used for async subs declarations -->
+    <sub name="async"/>
+    <!-- This is actually a keyword behaving like unary named operator -->
+    <sub name="await">
+      <arguments>
+        <argument name="future" type="$"/>
+      </arguments>
+    </sub>
+  </package>
+</xml>
diff --git a/plugin/src/main/resources/META-INF/plugin.xml b/plugin/src/main/resources/META-INF/plugin.xml
@@ -169,6 +169,8 @@
                       implementationClass="com.perl5.lang.perl.extensions.packageprocessor.impl.FileSpecFunctionsProcessor"/>
     <packageProcessor key="Log::Log4perl"
                       implementationClass="com.perl5.lang.perl.extensions.log4perl.Log4PerlPackageProcessor"/>
+    <packageProcessor key="Future::AsyncAwait"
+                      implementationClass="com.perl5.lang.perl.extensions.futureAsyncAwait.FutureAsyncAwaitPackageProcessor"/>
 
     <parserExtension implementation="com.perl5.lang.perl.parser.PerlSwitchParserExtensionImpl"/>
     <parserExtension implementation="com.perl5.lang.perl.parser.MooseParserExtension"/>
@@ -191,6 +193,7 @@
     <implicitSubsProvider implementation="com.perl5.lang.perl.extensions.readonly.ReadonlyImplicitDeclarationsProvider"/>
     <implicitSubsProvider implementation="com.perl5.lang.perl.extensions.log4perl.Log4PerlImplicitDeclarationsProvider"/>
     <implicitSubsProvider implementation="com.perl5.lang.perl.extensions.moo.MooImplicitSubsProvider"/>
+    <implicitSubsProvider implementation="com.perl5.lang.perl.extensions.futureAsyncAwait.FutureAsyncAwaitImplicitDeclarationsProvider"/>
   </extensions>
 
   <extensions defaultExtensionNs="com.intellij">
diff --git a/plugin/src/test/java/completion/PerlCompletionTest.java b/plugin/src/test/java/completion/PerlCompletionTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2015-2023 Alexandr Evstigneev
+ * Copyright 2015-2024 Alexandr Evstigneev
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -36,6 +36,14 @@ protected String getBaseDataPath() {
     return "completion/perl";
   }
 
+  @Test
+  public void testAsyncAwait() { doTestFuture(); }
+
+  private void doTestFuture() {
+    withFuture();
+    doTestWithTypeText();
+  }
+
   @Test
   public void testUseCGISubs() { doTestCgi(); }
 
diff --git a/plugin/src/test/java/documentation/PerlQuickDocTest.java b/plugin/src/test/java/documentation/PerlQuickDocTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2015-2023 Alexandr Evstigneev
+ * Copyright 2015-2024 Alexandr Evstigneev
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -56,21 +56,28 @@ public void testIsaOperator() {
   }
 
   @Test
-  public void testAsyncSub() {
+  public void testAwaitSub() {
+    doTestFuture();
+  }
+
+  private void doTestFuture() {
     withFuture();
     doTest528();
   }
 
+  @Test
+  public void testAsyncSub() {
+    doTestFuture();
+  }
+
   @Test
   public void testAsyncSubExpr() {
-    withFuture();
-    doTest528();
+    doTestFuture();
   }
 
   @Test
   public void testAsyncMethod() {
-    withFuture();
-    doTest528();
+    doTestFuture();
   }
 
   @Test
diff --git a/plugin/src/test/java/unit/perl/parser/PerlParserLikeTest.java b/plugin/src/test/java/unit/perl/parser/PerlParserLikeTest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2015-2023 Alexandr Evstigneev
+ * Copyright 2015-2024 Alexandr Evstigneev
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,6 +29,9 @@ protected String getBaseDataPath() {
   @Test
   public void testSubSignatureDefault() { doTest(); }
 
+  @Test
+  public void testAsyncAwait() { doTest(); }
+
   @Test
   public void testUndefHash() { doTest(); }
 
diff --git a/plugin/src/test/resources/completion/perl/asyncAwait.code b/plugin/src/test/resources/completion/perl/asyncAwait.code
@@ -0,0 +1,2 @@
+use Future::AsyncAwait;
+a<caret>
diff --git a/plugin/src/test/resources/completion/perl/asyncAwait.pl.txt b/plugin/src/test/resources/completion/perl/asyncAwait.pl.txt
@@ -0,0 +1,18 @@
+Text: af; Tail: null; Type: after statement; Icon: /template.svg; Type Icon: null
+	Lookups: af
+	Live template: Perl5: Moose/af
+Text: ar; Tail: null; Type: around statement; Icon: /template.svg; Type Icon: null
+	Lookups: ar
+	Live template: Perl5: Moose/ar
+Text: as; Tail: null; Type: async sub definition; Icon: /template.svg; Type Icon: null
+	Lookups: as
+	Live template: Perl5/as
+Text: async; Tail: null; Type: Future::AsyncAwait; Icon: /subroutine_gutter_icon.png; Type Icon: null
+	Lookups: async
+	PsiElement: Implicit sub: async()
+Text: au; Tail: null; Type: augment statement; Icon: /template.svg; Type Icon: null
+	Lookups: au
+	Live template: Perl5: Moose/au
+Text: await; Tail: ($future); Type: Future::AsyncAwait; Icon: /subroutine_gutter_icon.png; Type Icon: null
+	Lookups: await
+	PsiElement: Implicit sub: await($future)($future)
diff --git a/plugin/src/test/resources/documentation/perl/quickdoc/awaitSub.code b/plugin/src/test/resources/documentation/perl/quickdoc/awaitSub.code
@@ -0,0 +1,2 @@
+use Future::AsyncAwait;
+say aw<caret>ait something();
diff --git a/plugin/src/test/resources/documentation/perl/quickdoc/awaitSub.txt b/plugin/src/test/resources/documentation/perl/quickdoc/awaitSub.txt
@@ -0,0 +1,47 @@
+<p><a href="psi_element://Future%3A%3AAsyncAwait">Future::AsyncAwait</a>: <a href="psi_element://Future%3A%3AAsyncAwait%2FDESCRIPTION">DESCRIPTION</a></p><h2><code>await</code></h2><p style="padding-bottom: 10px;">The <code>await</code> keyword forms an expression which takes a <code>Future</code> instance as
+an operand and yields the eventual result of it. Superficially it can be
+thought of similar to invoking the <code>get</code> method on the future.</p>
+<div style="padding-bottom: 10px;"><pre><code>   my $result = await $f;
+
+   my $result = $f-&gt;get;</code></pre></div>
+<p style="padding-bottom: 10px;">However, the key difference (and indeed the entire reason for being a new
+syntax keyword) is the behaviour when the future is still pending and is not
+yet complete. Whereas the simple <code>get</code> method would block until the future is
+complete, the <code>await</code> keyword causes its entire containing function to become
+suspended, making it return a new (pending) future instance. It waits in this
+state until the future it was waiting on completes, at which point it wakes up
+and resumes execution from the point of the <code>await</code> expression. When the
+now-resumed function eventually finishes (either by returning a value or
+throwing an exception), this value is set as the result of the future it had
+returned earlier.</p>
+<p style="padding-bottom: 10px;"><code>await</code> provides scalar context to its controlling expression.</p>
+<div style="padding-bottom: 10px;"><pre><code>   async sub func {
+      # this function is invoked in scalar context
+   }
+
+   await func();</code></pre></div>
+<p style="padding-bottom: 10px;">Because the <code>await</code> keyword may cause its containing function to suspend
+early, returning a pending future instance, it is only allowed inside
+<code>async</code>-marked subs.</p>
+<p style="padding-bottom: 10px;">The converse is not true; just because a function is marked as <code>async</code> does
+not require it to make use of the <code>await</code> expression. It is still useful to
+turn the result of that function into a future, entirely without <code>await</code>ing
+on any itself.</p>
+<p style="padding-bottom: 10px;">Any function that doesn't actually await anything, and just returns immediate
+futures can be neatened by this module too.</p>
+<p style="padding-bottom: 10px;">Instead of writing</p>
+<div style="padding-bottom: 10px;"><pre><code>   sub imm
+   {
+      ...
+      return Future-&gt;done( @result );
+   }</code></pre></div>
+<p style="padding-bottom: 10px;">you can now simply write</p>
+<div style="padding-bottom: 10px;"><pre><code>   async sub imm
+   {
+      ...
+      return @result;
+   }</code></pre></div>
+<p style="padding-bottom: 10px;">with the added side-benefit that any exceptions thrown by the elided code will
+be turned into an immediate-failed <code>Future</code> rather than making the call
+itself propagate the exception, which is usually what you wanted when dealing
+with futures.</p>
diff --git a/plugin/src/test/resources/highlighting/perl/syntax/asyncAwait.pl.txt b/plugin/src/test/resources/highlighting/perl/syntax/asyncAwait.pl.txt
diff --git a/plugin/src/test/resources/unit/perl/parser/asyncAwait.code b/plugin/src/test/resources/unit/perl/parser/asyncAwait.code
diff --git a/plugin/src/test/resources/unit/perl/parser/asyncAwait.txt b/plugin/src/test/resources/unit/perl/parser/asyncAwait.txt

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+use Future::AsyncAwait;`
	`2`	`+a<caret>`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+use Future::AsyncAwait;`
	`2`	`+say aw<caret>ait something();`