From 77da4c87a31d3c434280e4778d73fb6de9f128fb Mon Sep 17 00:00:00 2001
From: Pranjal Raihan <praihan@meta.com>
Date: Mon, 23 Dec 2024 12:37:42 -0800
Subject: [PATCH] Update spec to have named arguments in functions

Summary:
In practice, we want to be explicit about arguments in whisker since there is no type checking nor autocomplete.

This diff updates the grammar to have keyword arguments [like Python](https://docs.python.org/3.13/glossary.html#term-argument) and [matches the syntax in Handlebars](https://handlebarsjs.com/guide/builtin-helpers.html#if). Notice that the change to the grammar is purely additive in nature and does not break any existing code.

When user-defined functions are implemented in Whisker, I expect both positional and named arguments will be supported on day 1. That's why the spec change should happen as early as possible :) Now, everything is in place to go and implement it.

I've also added a small example of `expression`s.

Reviewed By: createdbysk

Differential Revision: D67586812

fbshipit-source-id: 1e7e945bdbb54f8f76bddff551b995fa328f50ac
---
 .../src/thrift/doc/contributions/whisker.md   | 36 +++++++++++++++++--
 .../thrift/src/thrift/website/yarn.lock       |  2 +-
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/third-party/thrift/src/thrift/doc/contributions/whisker.md b/third-party/thrift/src/thrift/doc/contributions/whisker.md
index dad1816bba0db..cfbbcb80eed08 100644
--- a/third-party/thrift/src/thrift/doc/contributions/whisker.md
+++ b/third-party/thrift/src/thrift/doc/contributions/whisker.md
@@ -155,7 +155,7 @@ partial-apply → { <see below> }
 
 </Grammar>
 
-### Interpolations
+### Interpolations & Expressions
 
 An `interpolation` causes the result of an `expression` to be rendered into the output at the position of the enclosing `{{ ... }}`.
 
@@ -190,6 +190,29 @@ Whisker includes a set of *keywords* that are reserved. These cannot be used as
 
 Every `expression` produces an `object`. However, not all `object`s are *printable*. The top-level `expression` in a `template` **must** be *printable*. `expression`s passed as arguments in a function call do **not** need be *printable*. See the [*data model*](#data-model) for details.
 
+<Example>
+
+```handlebars title=example.whisker
+{{foo.bar}}
+{{! scoped property access }}
+
+{{ (not true) }}
+{{! `false` }}
+
+{{ (uppercase "Hello") }}
+{{! "HELLO" }}
+
+{{ (int-to-string 16 format="hex")}}
+{{! "0x10" }}
+
+{{!--
+  Named arguments (like `format="hex"`) must follow after all
+  positional arguments (like `16`).
+}}
+```
+
+</Example>
+
 <Grammar>
 
 ```
@@ -198,7 +221,7 @@ expression    → { literal | variable | function-call }
 
 literal             → { string-literal | i64-literal | boolean-literal | null-literal }
 variable            → { "." | (identifier ~ ("." ~ identifier)*) }
-function-call       → { "(" ~ ((variable ~ expression*) | builtin-call) ~ ")" }
+function-call       → { "(" ~ (builtin-call | user-defined-call) ~ ")" }
 
 string-literal  → { <see above> }
 i64-literal     → { <see above> }
@@ -235,6 +258,15 @@ id_suffix → { alpha | digits | '_' | '$' | '-' | '+' | ':' | '?' | '/' }
 builtin-call → {
   ("not" ~ expression) |
   (("and" | "or") ~ expression ~ expression+) }
+
+user-defined-call → {
+  user-defined-call-lookup ~
+  positional-argument* ~
+  named-argument* }
+
+user-defined-call-lookup → { variable }
+positional-argument      → { expression }
+named-argument           → { identifier ~ "=" ~ expression }
 ```
 
 </Grammar>
diff --git a/third-party/thrift/src/thrift/website/yarn.lock b/third-party/thrift/src/thrift/website/yarn.lock
index 05a1e96ebdd3d..77a2bd9602ef0 100644
--- a/third-party/thrift/src/thrift/website/yarn.lock
+++ b/third-party/thrift/src/thrift/website/yarn.lock
@@ -5125,7 +5125,7 @@ exenv@^1.2.0:
   resolved "https://registry.yarnpkg.com/exenv/-/exenv-1.2.2.tgz#2ae78e85d9894158670b03d47bec1f03bd91bb9d"
   integrity sha512-Z+ktTxTwv9ILfgKCk32OX3n/doe+OcLTRtqK9pcL+JsP3J1/VW8Uvl4ZjLlKqeW4rzK4oesDOGMEMRIZqtP4Iw==
 
-express@^4.17.3, express@^4.19.2, express@^4.21.1:
+express@^4.17.3, express@^4.19.2:
   version "4.21.2"
   resolved "https://registry.yarnpkg.com/express/-/express-4.21.2.tgz#cf250e48362174ead6cea4a566abef0162c1ec32"
   integrity sha512-28HqgMZAmih1Czt9ny7qr6ek2qddF4FclbMzwhCREB6OFfH+rXAnuNCwo1/wFvrtbgsQDb4kSbX9de9lFbrXnA==