Repository: edgedb/edgedb

Issue:
Rename some string handling functions and deprecate the old versions.
From discussion in Slack a point was raised:
> Just noticed something now of an engineering nature though:
> https://edgedb.com/docs/edgeql/funcops/string#function::std::str_lpad
> This reminded me of similar methods in Rust that were eventually deprecated in favour of calling them "start" and "end" instead of "right" and "left" due to languages that write right to left (and even up to down):
> https://doc.rust-lang.org/std/primitive.str.html#method.trim_left
> The new methods did the exact same thing but were just given different names, while the old method names were left alone to accommodate legacy code.

This means that we want to rename string handling functions to use "start" and "end" such as `std::str_trim_start`, etc. The old functions should remain for some time, but they need to be marked as deprecated. To this end we also introduce a `deprecated` annotation which can mark deprecated items as well as provide a useful note like what should be used instead.

The documentation needs to include deprecated functions, but they should also be clearly labeled as such.


Discussion:

Resolving patch:
diff --git a/edb/edgeql/pygments/meta.py b/edb/edgeql/pygments/meta.py
--- a/edb/edgeql/pygments/meta.py
+++ b/edb/edgeql/pygments/meta.py
@@ -106,6 +106,7 @@ class EdgeQL:
         "cardinality",
         "cast",
         "config",
+        "conflict",
         "constraint",
         "current",
         "database",
@@ -139,13 +140,17 @@ class EdgeQL:
         "oids",
         "on",
         "only",
+        "onto",
         "operator",
         "overloaded",
+        "owned",
         "postfix",
         "prefix",
         "property",
+        "proposed",
         "pseudo",
         "read",
+        "reject",
         "rename",
         "repeatable",
         "required",
@@ -169,6 +174,7 @@ class EdgeQL:
         "to",
         "transaction",
         "type",
+        "unless",
         "using",
         "verbose",
         "view",
@@ -285,12 +291,16 @@ class EdgeQL:
         "str_lower",
         "str_lpad",
         "str_ltrim",
+        "str_pad_end",
+        "str_pad_start",
         "str_repeat",
         "str_rpad",
         "str_rtrim",
         "str_split",
         "str_title",
         "str_trim",
+        "str_trim_end",
+        "str_trim_start",
         "str_upper",
         "sum",
         "time_get",


Test patch:
diff --git a/tests/test_edgeql_functions.py b/tests/test_edgeql_functions.py
--- a/tests/test_edgeql_functions.py
+++ b/tests/test_edgeql_functions.py
@@ -3520,63 +3520,74 @@ async def test_edgeql_functions_str_case_01(self):
 
     async def test_edgeql_functions_str_pad_01(self):
         await self.assert_query_result(
-            r'''SELECT str_lpad('Hello', 20);''',
+            r'''SELECT str_pad_start('Hello', 20);''',
             {'               Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_lpad('Hello', 20, '>');''',
+            r'''SELECT str_pad_start('Hello', 20, '>');''',
             {'>>>>>>>>>>>>>>>Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_lpad('Hello', 20, '-->');''',
+            r'''SELECT str_pad_start('Hello', 20, '-->');''',
             {'-->-->-->-->-->Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rpad('Hello', 20);''',
+            r'''SELECT str_pad_end('Hello', 20);''',
             {'Hello               '},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rpad('Hello', 20, '<');''',
+            r'''SELECT str_pad_end('Hello', 20, '<');''',
             {'Hello<<<<<<<<<<<<<<<'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rpad('Hello', 20, '<--');''',
+            r'''SELECT str_pad_end('Hello', 20, '<--');''',
             {'Hello<--<--<--<--<--'},
         )
 
+        # Call deprecated functions, too.
+        await self.assert_query_result(
+            r'''SELECT str_lpad('Hello', 20);''',
+            {'               Hello'},
+        )
+
+        await self.assert_query_result(
+            r'''SELECT str_rpad('Hello', 20);''',
+            {'Hello               '},
+        )
+
     async def test_edgeql_functions_str_pad_02(self):
         await self.assert_query_result(
-            r'''SELECT str_lpad('Hello', 2);''',
+            r'''SELECT str_pad_start('Hello', 2);''',
             {'He'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_lpad('Hello', 2, '>');''',
+            r'''SELECT str_pad_start('Hello', 2, '>');''',
             {'He'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_lpad('Hello', 2, '-->');''',
+            r'''SELECT str_pad_start('Hello', 2, '-->');''',
             {'He'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rpad('Hello', 2);''',
+            r'''SELECT str_pad_end('Hello', 2);''',
             {'He'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rpad('Hello', 2, '<');''',
+            r'''SELECT str_pad_end('Hello', 2, '<');''',
             {'He'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rpad('Hello', 2, '<--');''',
+            r'''SELECT str_pad_end('Hello', 2, '<--');''',
             {'He'},
         )
 
@@ -3584,7 +3595,7 @@ async def test_edgeql_functions_str_pad_03(self):
         await self.assert_query_result(
             r'''
                 WITH l := {0, 2, 10, 20}
-                SELECT len(str_lpad('Hello', l)) = l;
+                SELECT len(str_pad_start('Hello', l)) = l;
             ''',
             [True, True, True, True],
         )
@@ -3592,7 +3603,7 @@ async def test_edgeql_functions_str_pad_03(self):
         await self.assert_query_result(
             r'''
                 WITH l := {0, 2, 10, 20}
-                SELECT len(str_rpad('Hello', l)) = l;
+                SELECT len(str_pad_end('Hello', l)) = l;
             ''',
             [True, True, True, True],
         )
@@ -3603,6 +3614,17 @@ async def test_edgeql_functions_str_trim_01(self):
             {'Hello'},
         )
 
+        await self.assert_query_result(
+            r'''SELECT str_trim_start('    Hello    ');''',
+            {'Hello    '},
+        )
+
+        await self.assert_query_result(
+            r'''SELECT str_trim_end('    Hello    ');''',
+            {'    Hello'},
+        )
+
+        # Call deprecated functions, too.
         await self.assert_query_result(
             r'''SELECT str_ltrim('    Hello    ');''',
             {'Hello    '},
@@ -3615,32 +3637,32 @@ async def test_edgeql_functions_str_trim_01(self):
 
     async def test_edgeql_functions_str_trim_02(self):
         await self.assert_query_result(
-            r'''SELECT str_ltrim('               Hello', ' <->');''',
+            r'''SELECT str_trim_start('               Hello', ' <->');''',
             {'Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_ltrim('>>>>>>>>>>>>>>>Hello', ' <->');''',
+            r'''SELECT str_trim_start('>>>>>>>>>>>>>>>Hello', ' <->');''',
             {'Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_ltrim('-->-->-->-->-->Hello', ' <->');''',
+            r'''SELECT str_trim_start('-->-->-->-->-->Hello', ' <->');''',
             {'Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rtrim('Hello               ', ' <->');''',
+            r'''SELECT str_trim_end('Hello               ', ' <->');''',
             {'Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rtrim('Hello<<<<<<<<<<<<<<<', ' <->');''',
+            r'''SELECT str_trim_end('Hello<<<<<<<<<<<<<<<', ' <->');''',
             {'Hello'},
         )
 
         await self.assert_query_result(
-            r'''SELECT str_rtrim('Hello<--<--<--<--<--', ' <->');''',
+            r'''SELECT str_trim_end('Hello<--<--<--<--<--', ' <->');''',
             {'Hello'},
         )