Documentation generation: argument mode, return SETOF (#99)

* Documentation generation: argument mode, return SETOF Co-authored-by: sergei sh <[email protected]>
zachasme · Nov 4, 2022 · 33b80e2 · 33b80e2
1 parent acd2409
commit 33b80e2
Show file tree

Hide file tree

Showing 3 changed files with 77 additions and 68 deletions.
diff --git a/.github/documentation/generate.py b/.github/documentation/generate.py
@@ -6,18 +6,21 @@
 
 
 class Function:
-    def __init__(self, name: str, arguments, returntype: str):
+    def __init__(self, name: str, arguments, returntype: str, returns_set: bool):
         self.name = name
         self.arguments = arguments
         self.returntype = returntype
+        self.returns_set = returns_set
 
     def __str__(self):
         if self.name.startswith("__"):
             return None
         if self.arguments is None:
             self.arguments = []
-        return "\n### {}({}) ⇒ `{}`".format(
-            self.name, ", ".join(self.arguments), self.returntype
+        return "\n### {}({}) ⇒ {}`{}`".format(
+            self.name, ", ".join(self.arguments),
+            "SETOF " if self.returns_set else "",
+            self.returntype
         )
 
 
@@ -87,6 +90,10 @@ def create_oper_opt(self, option, value=None):
         return [str(option), value]
 
     # -- CREATE FUNCTION -------------------------------------------------------
+    def create_fun_rettype(self, children):
+        # (returntype, returns_set)
+        return (children[1], children[0] is not None)
+
     @v_args(inline=True)
     def create_func_stmt(self, name: str, arguments, returntype, *opts):
         # skip internal functions
@@ -95,7 +102,7 @@ def create_func_stmt(self, name: str, arguments, returntype, *opts):
 
         # print("func")
 
-        return Function(name, arguments, returntype)
+        return Function(name, arguments, returntype[0], returntype[1])
 
     def argument_list(self, children):
         return children
@@ -136,12 +143,11 @@ def string(self, s):
     def fun_name(self, children):
         return children[1]
 
-    def datatype(self, children):
-        return children[0]
-
     @v_args(inline=True)
-    def argument(self, name, argtype, default=None):
+    def argument(self, argmode, name, argtype, default=None):
         out = ""
+        if argmode:
+            out += "{} ".format(argmode)
         if name:
             out += name + " "
         out += "`{}`".format(argtype)

diff --git a/.github/documentation/sql.lark b/.github/documentation/sql.lark
@@ -29,7 +29,7 @@ create_type_stmt: "CREATE" "TYPE" CNAME ("(" /([^\)])+/ ")")?
 
 // -----------------------------------------------------------------------------
 // CREATE CAST ...
-create_cast_stmt: "CREATE" "CAST" "(" datatype "AS" datatype ")" "WITH" "FUNCTION" CNAME "(" /([^\)])+/ ")"
+create_cast_stmt: "CREATE" "CAST" "(" DATATYPE "AS" DATATYPE ")" "WITH" "FUNCTION" CNAME "(" /([^\)])+/ ")"
 
 // -----------------------------------------------------------------------------
 // CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type
@@ -53,8 +53,8 @@ create_opcl_list: create_opcl_opts ("," create_opcl_opts)*
 // )
 create_oper_stmt: "CREATE" "OPERATOR" OPERATOR "(" create_oper_opts ")"
 create_oper_opt: /PROCEDURE/ "=" CNAME
-               | /LEFTARG/ "=" datatype
-               | /RIGHTARG/ "=" datatype
+               | /LEFTARG/ "=" DATATYPE
+               | /RIGHTARG/ "=" DATATYPE
                | /COMMUTATOR/ "=" OPERATOR
                | /NEGATOR/ "=" OPERATOR
                | /RESTRICT/ "=" CNAME
@@ -82,13 +82,14 @@ create_oper_opts: create_oper_opt ("," create_oper_opt)*
 //   } ...
 //     [ WITH ( attribute [, ...] ) ]
 create_func_stmt: "CREATE" ("OR" "REPLACE")? "FUNCTION" fun_name "(" [argument_list] ")" [create_fun_rets] create_fun_opts*
-?create_fun_rets: "RETURNS" ("SETOF")? datatype "[]"?
+?create_fun_rets: "RETURNS" create_fun_rettype
 create_fun_opts: "LANGUAGE" CNAME
               | ("IMMUTABLE" | "STABLE" | "VOLATILE" | ("NOT"? "LEAKPROOF"))
               | (("CALLED" "ON" "NULL" "INPUT") | ("RETURNS" "NULL" "ON" "NULL" "INPUT") | "STRICT")
               | ("PARALLEL" ("UNSAFE" | "RESTRICTED" | "SAFE"))
               | "AS" string ("," string)?
 argument_list: argument ("," argument)*
+!create_fun_rettype: ["SETOF"] DATATYPE
 
 // -----------------------------------------------------------------------------
 // COMMENT ON
@@ -102,32 +103,34 @@ argument_list: argument ("," argument)*
 //   ...
 // } IS 'text'
 comment_on_stmt: "COMMENT" "ON" comment_on_type "IS" string
-comment_on_type: "CAST" "(" datatype "AS" datatype ")" -> comment_on_cast
+comment_on_type: "CAST" "(" DATATYPE "AS" DATATYPE ")" -> comment_on_cast
                | "FUNCTION" fun_name "(" [argument_list] ")" -> comment_on_function
                | "OPERATOR" OPERATOR "(" argument "," argument ")" -> comment_on_operator
 
 // -----------------------------------------------------------------------------
 // SIMPLE RULES
-argument: "OUT"? [CNAME] datatype "[]"? ("DEFAULT" expr)?
-!datatype: "h3index"
+argument: [ARGMODE] [CNAME] DATATYPE "[]"? ("DEFAULT" expr)?
+ARGMODE.2: "IN" | "OUT" | "INOUT"
+DATATYPE_SCALAR: "h3index"
         | "bigint"
         | "boolean"
         | "cstring"
-        | "double" "precision"
+        | "double" WS "precision"
         | "float"
         | "geography"
         | "geometry"
         | "bytea"
-        | "int"
         | "int32"
         | "int8"
         | "integer"
         | "internal"
+        | "int"
         | "point"
         | "polygon"
         | "record"
         | "text"
         | "void"
+DATATYPE: DATATYPE_SCALAR "[]"?
 fun_name: [CNAME "."] CNAME
 ?expr: atom | string
 atom: SIGNED_NUMBER -> number
@@ -155,4 +158,4 @@ COMMAND: "\\" /([^\n])+/
 %ignore COMMAND
 %ignore MULTI_COMMENT
 %ignore SINGLE_COMMENT
-%ignore WS
+%ignore WS