Add HINT listing valid encodings to encode() and decode() errors.

This commit updates encode() and decode() so that when an invalid encoding
is specified, their error message includes a HINT listing all valid encodings.
This helps users quickly see which encodings are supported without needing
to consult the documentation.

Author: Shinya Sugamoto <shinya34892@gmail.com>
Reviewed-by: Chao Li <lic@highgo.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Reviewed-by: Masahiko Sawada <sawada.mshk@gmail.com>
Reviewed-by: Peter Eisentraut <peter@eisentraut.org>
Reviewed-by: Nathan Bossart <nathandbossart@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/CAAe3y+99sfPv8UDF1VM-rC1i5HBdqxUh=2HrbJJFm2+i=1OwOw@mail.gmail.com

diff --git a/src/backend/utils/adt/encode.c b/src/backend/utils/adt/encode.c
index aabe9913eee3c00e50366a47965ff0724df0bcad..c813ee1258b7ff4cb3dfcf76a06fd94edde3eda0 100644 (file)
--- a/src/backend/utils/adt/encode.c
+++ b/src/backend/utils/adt/encode.c
@@ -64,7 +64,9 @@ binary_encode(PG_FUNCTION_ARGS)
    if (enc == NULL)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
-                errmsg("unrecognized encoding: \"%s\"", namebuf)));
+                errmsg("unrecognized encoding: \"%s\"", namebuf),
+                errhint("Valid encodings are \"%s\", \"%s\", \"%s\", and \"%s\".",
+                        "base64", "base64url", "escape", "hex")));
 
    dataptr = VARDATA_ANY(data);
    datalen = VARSIZE_ANY_EXHDR(data);
@@ -112,7 +114,9 @@ binary_decode(PG_FUNCTION_ARGS)
    if (enc == NULL)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
-                errmsg("unrecognized encoding: \"%s\"", namebuf)));
+                errmsg("unrecognized encoding: \"%s\"", namebuf),
+                errhint("Valid encodings are \"%s\", \"%s\", \"%s\", and \"%s\".",
+                        "base64", "base64url", "escape", "hex")));
 
    dataptr = VARDATA_ANY(data);
    datalen = VARSIZE_ANY_EXHDR(data);

diff --git a/src/test/regress/expected/strings.out b/src/test/regress/expected/strings.out
index b9dc08d5f617ea5ce06d0276dc2ec6b150e19f10..727304f60e740ac0cffca57099016163f89b262b 100644 (file)
--- a/src/test/regress/expected/strings.out
+++ b/src/test/regress/expected/strings.out
@@ -2575,6 +2575,13 @@ SELECT decode(encode('\x1234567890abcdef00', 'escape'), 'escape');
  \x1234567890abcdef00
 (1 row)
 
+-- report an error with a hint listing valid encodings when an invalid encoding is specified
+SELECT encode('\x01'::bytea, 'invalid');  -- error
+ERROR:  unrecognized encoding: "invalid"
+HINT:  Valid encodings are "base64", "base64url", "escape", and "hex".
+SELECT decode('00', 'invalid');           -- error
+ERROR:  unrecognized encoding: "invalid"
+HINT:  Valid encodings are "base64", "base64url", "escape", and "hex".
 --
 -- base64url encoding/decoding
 --

diff --git a/src/test/regress/sql/strings.sql b/src/test/regress/sql/strings.sql
index a2a915234040ce6b16378de6698edaa96d146abc..88aa4c2983ba9459634cc361dc95e1fc977727b2 100644 (file)
--- a/src/test/regress/sql/strings.sql
+++ b/src/test/regress/sql/strings.sql
@@ -815,6 +815,10 @@ SELECT decode(encode(('\x' || repeat('1234567890abcdef0001', 7))::bytea,
 SELECT encode('\x1234567890abcdef00', 'escape');
 SELECT decode(encode('\x1234567890abcdef00', 'escape'), 'escape');
 
+-- report an error with a hint listing valid encodings when an invalid encoding is specified
+SELECT encode('\x01'::bytea, 'invalid');  -- error
+SELECT decode('00', 'invalid');           -- error
+
 --
 -- base64url encoding/decoding
 --