Merge pull request duckdb#3657 from Tishj/macro_overloads

Add documentation for macro overloads

Gemfile.lock

@@ -10,7 +10,7 @@ GIT
 
 GIT
   remote: https://github.com/duckdb/rouge.git
-  revision: e3747a4b14c3cc1676f3da2a96540fd08f13e8e1
+  revision: 97560470d9a6bb1ff8fd4ddc102496ccf9a752bd
   branch: duckdb
   specs:
     rouge (3.3823.1)

docs/sql/statements/create_macro.md

@@ -6,6 +6,7 @@ railroad: statements/createmacro.js
 
 The `CREATE MACRO` statement can create a scalar or table macro (function) in the catalog.
 A macro may only be a single `SELECT` statement (similar to a `VIEW`), but it has the benefit of accepting parameters.
+
 For a scalar macro, `CREATE MACRO` is followed by the name of the macro, and optionally parameters within a set of parentheses. The keyword `AS` is next, followed by the text of the macro. By design, a scalar macro may only return a single value.
 For a table macro, the syntax is similar to a scalar macro except `AS` is replaced with `AS TABLE`. A table macro may return a table of arbitrary size and shape.
 
@@ -99,6 +100,28 @@ CREATE TABLE users AS
 SELECT * FROM get_users([1, 5]);
 ```
 
+## Overloading
+
+It is possible to overload a macro based on the amount of parameters it takes, this works for both scalar and table macros.
+
+By providing overloads we can have both `add_x(a, b)` and `add_x(a, b, c)` with different function bodies.
+
+```sql
+CREATE MACRO add_x
+    (a, b) AS a + b,
+    (a, b, c) AS a + b + c;
+```
+
+```sql
+SELECT
+    add_x(21, 42) AS two_args,
+    add_x(21, 42, 21) AS three_args;
+```
+
+| two_args | three_args |
+|----------|------------|
+|    63    |     84     |
+
 ## Syntax
 
 <div id="rrdiagram"></div>
@@ -244,3 +267,7 @@ If a `MACRO` is defined as a subquery, it cannot be invoked in a table function.
 ```console
 Binder Error: Table function cannot contain subqueries
 ```
+
+### Overloads
+
+Overloads for macro functions have to be set at creation, it is not possible to define a macro by the same name twice without first removing the first definition.

js/statements/createmacro.js

@@ -15,21 +15,23 @@ function GenerateCreateMacro(options = {}) {
 				Keyword(".")
 			]), "skip"),
 			Expression("macro-name"),
-			Keyword("("),
-			ZeroOrMore(Sequence([
-				Expression("param-name"),
-				], "skip")
-			),
-			ZeroOrMore(Sequence([
-				Expression("param-name"),
-				Keyword(":="),
-				Expression("default-value")
-				], "skip")
-			),
-			Keyword(")"),
-			Keyword("AS"),
-			Optional("TABLE"),
-			Expression("expr")
+			OneOrMore(Sequence([
+				Keyword("("),
+				ZeroOrMore(Sequence([
+					Expression("param-name"),
+					], "skip")
+				),
+				ZeroOrMore(Sequence([
+					Expression("param-name"),
+					Keyword(":="),
+					Expression("default-value")
+					], "skip")
+				),
+				Keyword(")"),
+				Keyword("AS"),
+				Optional("TABLE"),
+				Expression("expr")
+			]), ",")
 		])
 	])
 }