[ruby/yarp] Extract error messages into diagnostic.c and use canonical message IDs

The parser now passes around `yp_diagnostic_id_t` for diagnostic
messages instead of character strings, and we rely on the function
`diagnostic_message()` to resolve that to a string.

In addition, many messages were edited so that the parser expresses
coordinate ideas in similar form [1] using consistent voice and
typographic conventions.

Closes https://github.com/ruby/yarp/pull/1379, and makes progress on #941.

  [1] Strunk & White rule 19

https://github.com/ruby/yarp/commit/0b6dd85bf1

1 files changed, 108 insertions, 108 deletions

diff --git a/test/yarp/errors_test.rb b/test/yarp/errors_test.rb
index 608af07795..61955d612f 100644
--- a/test/yarp/errors_test.rb
+++ b/test/yarp/errors_test.rb
@@ -8,8 +8,8 @@ module YARP
 
     def test_constant_path_with_invalid_token_after
       assert_error_messages "A::$b", [
-        "Expected identifier or constant after '::'",
-        "Expected a newline or semicolon after statement."
+        "Expected a constant after the `::` operator",
+        "Expected a newline or semicolon after the statement"
       ]
     end
 
@@ -26,7 +26,7 @@ module YARP
       )
 
       assert_errors expected, "module Parent module end", [
-        ["Expected to find a module name after `module`.", 20..20]
+        ["Expected a constant name after `module`", 20..20]
       ]
     end
 
@@ -42,7 +42,7 @@ module YARP
       )
 
       assert_errors expected, "for in 1..10\ni\nend", [
-        ["Expected index after for.", 0..0]
+        ["Expected an index after `for`", 0..0]
       ]
     end
 
@@ -58,9 +58,9 @@ module YARP
       )
 
       assert_errors expected, "for end", [
-        ["Expected index after for.", 0..0],
-        ["Expected keyword in.", 3..3],
-        ["Expected collection.", 3..3]
+        ["Expected an index after `for`", 0..0],
+        ["Expected an `in` after the index in a `for` statement", 3..3],
+        ["Expected a collection after the `in` in a `for` statement", 3..3]
       ]
     end
 
@@ -73,7 +73,7 @@ module YARP
       )
 
       assert_errors expected, "BEGIN 1 }", [
-        ["Expected '{' after 'BEGIN'.", 5..5]
+        ["Expected a `{` after `BEGIN`", 5..5]
       ]
     end
 
@@ -98,37 +98,37 @@ module YARP
       )
 
       assert_errors expected, "BEGIN { 1 + }", [
-        ["Expected a value after the operator.", 11..11]
+        ["Expected an expression after the operator", 11..11]
       ]
     end
 
     def test_unterminated_embdoc
       assert_errors expression("1"), "1\n=begin\n", [
-        ["Unterminated embdoc", 2..9]
+        ["Could not find a terminator for the embedded document", 2..9]
       ]
     end
 
     def test_unterminated_i_list
       assert_errors expression("%i["), "%i[", [
-        ["Expected a closing delimiter for a `%i` list.", 3..3]
+        ["Expected a closing delimiter for the `%i` list", 3..3]
       ]
     end
 
     def test_unterminated_w_list
       assert_errors expression("%w["), "%w[", [
-        ["Expected a closing delimiter for a `%w` list.", 3..3]
+        ["Expected a closing delimiter for the `%w` list", 3..3]
       ]
     end
 
     def test_unterminated_W_list
       assert_errors expression("%W["), "%W[", [
-        ["Expected a closing delimiter for a `%W` list.", 3..3]
+        ["Expected a closing delimiter for the `%W` list", 3..3]
       ]
     end
 
     def test_unterminated_regular_expression
       assert_errors expression("/hello"), "/hello", [
-        ["Expected a closing delimiter for a regular expression.", 1..1]
+        ["Expected a closing delimiter for the regular expression", 1..1]
       ]
     end
 
@@ -136,178 +136,178 @@ module YARP
       source = "<<-END + /b\nEND\n"
 
       assert_errors expression(source), source, [
-        ["Expected a closing delimiter for a regular expression.", 10..10]
+        ["Expected a closing delimiter for the regular expression", 10..10]
       ]
     end
 
     def test_unterminated_xstring
       assert_errors expression("`hello"), "`hello", [
-        ["Expected a closing delimiter for an xstring.", 1..1]
+        ["Expected a closing delimiter for the `%x` or backtick string", 1..1]
       ]
     end
 
     def test_unterminated_string
       assert_errors expression('"hello'), '"hello', [
-        ["Expected a closing delimiter for an interpolated string.", 1..1]
+        ["Expected a closing delimiter for the interpolated string", 1..1]
       ]
     end
 
     def test_unterminated_s_symbol
       assert_errors expression("%s[abc"), "%s[abc", [
-        ["Expected a closing delimiter for a dynamic symbol.", 3..3]
+        ["Expected a closing delimiter for the dynamic symbol", 3..3]
       ]
     end
 
     def test_unterminated_parenthesized_expression
       assert_errors expression('(1 + 2'), '(1 + 2', [
-        ["Expected to be able to parse an expression.", 6..6],
-        ["Expected a closing parenthesis.", 6..6]
+        ["Cannot parse the expression", 6..6],
+        ["Expected a matching `)`", 6..6]
       ]
     end
 
     def test_unterminated_argument_expression
       assert_errors expression('a %'), 'a %', [
-        ["Unexpected end of input", 2..3],
-        ["Expected a value after the operator.", 3..3],
+        ["Invalid `%` token", 2..3],
+        ["Expected an expression after the operator", 3..3],
       ]
     end
 
     def test_cr_without_lf_in_percent_expression
       assert_errors expression("%\r"), "%\r", [
-        ["Invalid %% token", 0..2],
+        ["Invalid `%` token", 0..2],
       ]
     end
 
     def test_1_2_3
       assert_errors expression("(1, 2, 3)"), "(1, 2, 3)", [
-        ["Expected to be able to parse an expression.", 2..2],
-        ["Expected a closing parenthesis.", 2..2],
-        ["Expected a newline or semicolon after statement.", 2..2],
-        ["Expected to be able to parse an expression.", 2..2],
-        ["Expected a newline or semicolon after statement.", 5..5],
-        ["Expected to be able to parse an expression.", 5..5],
-        ["Expected a newline or semicolon after statement.", 8..8],
-        ["Expected to be able to parse an expression.", 8..8],
+        ["Cannot parse the expression", 2..2],
+        ["Expected a matching `)`", 2..2],
+        ["Expected a newline or semicolon after the statement", 2..2],
+        ["Cannot parse the expression", 2..2],
+        ["Expected a newline or semicolon after the statement", 5..5],
+        ["Cannot parse the expression", 5..5],
+        ["Expected a newline or semicolon after the statement", 8..8],
+        ["Cannot parse the expression", 8..8],
       ]
     end
 
     def test_return_1_2_3
       assert_error_messages "return(1, 2, 3)", [
-        "Expected to be able to parse an expression.",
-        "Expected a closing parenthesis.",
-        "Expected a newline or semicolon after statement.",
-        "Expected to be able to parse an expression."
+        "Cannot parse the expression",
+        "Expected a matching `)`",
+        "Expected a newline or semicolon after the statement",
+        "Cannot parse the expression",
       ]
     end
 
     def test_return_1
       assert_errors expression("return 1,;"), "return 1,;", [
-        ["Expected to be able to parse an argument.", 9..9]
+        ["Expected an argument", 9..9]
       ]
     end
 
     def test_next_1_2_3
       assert_errors expression("next(1, 2, 3)"), "next(1, 2, 3)", [
-        ["Expected to be able to parse an expression.", 6..6],
-        ["Expected a closing parenthesis.", 6..6],
-        ["Expected a newline or semicolon after statement.", 12..12],
-        ["Expected to be able to parse an expression.", 12..12]
+        ["Cannot parse the expression", 6..6],
+        ["Expected a matching `)`", 6..6],
+        ["Expected a newline or semicolon after the statement", 12..12],
+        ["Cannot parse the expression", 12..12],
       ]
     end
 
     def test_next_1
       assert_errors expression("next 1,;"), "next 1,;", [
-        ["Expected to be able to parse an argument.", 7..7]
+        ["Expected an argument", 7..7]
       ]
     end
 
     def test_break_1_2_3
       assert_errors expression("break(1, 2, 3)"), "break(1, 2, 3)", [
-        ["Expected to be able to parse an expression.", 7..7],
-        ["Expected a closing parenthesis.", 7..7],
-        ["Expected a newline or semicolon after statement.", 13..13],
-        ["Expected to be able to parse an expression.", 13..13],
+        ["Cannot parse the expression", 7..7],
+        ["Expected a matching `)`", 7..7],
+        ["Expected a newline or semicolon after the statement", 13..13],
+        ["Cannot parse the expression", 13..13],
       ]
     end
 
     def test_break_1
       assert_errors expression("break 1,;"), "break 1,;", [
-        ["Expected to be able to parse an argument.", 8..8]
+        ["Expected an argument", 8..8]
       ]
     end
 
     def test_argument_forwarding_when_parent_is_not_forwarding
       assert_errors expression('def a(x, y, z); b(...); end'), 'def a(x, y, z); b(...); end', [
-        ["unexpected ... when parent method is not forwarding.", 18..21]
+        ["Unexpected `...` when the parent method is not forwarding", 18..21]
       ]
     end
 
     def test_argument_forwarding_only_effects_its_own_internals
       assert_errors expression('def a(...); b(...); end; def c(x, y, z); b(...); end'),
         'def a(...); b(...); end; def c(x, y, z); b(...); end', [
-          ["unexpected ... when parent method is not forwarding.", 43..46]
+          ["Unexpected `...` when the parent method is not forwarding", 43..46]
         ]
     end
 
     def test_top_level_constant_with_downcased_identifier
       assert_error_messages "::foo", [
-        "Expected a constant after ::.",
-        "Expected a newline or semicolon after statement."
+        "Expected a constant after the `::` operator",
+        "Expected a newline or semicolon after the statement"
       ]
     end
 
     def test_top_level_constant_starting_with_downcased_identifier
       assert_error_messages "::foo::A", [
-        "Expected a constant after ::.",
-        "Expected a newline or semicolon after statement."
+        "Expected a constant after the `::` operator",
+        "Expected a newline or semicolon after the statement"
       ]
     end
 
     def test_aliasing_global_variable_with_non_global_variable
       assert_errors expression("alias $a b"), "alias $a b", [
-        ["Expected a global variable.", 9..10]
+        ["Invalid argument being passed to `alias`; expected a bare word, symbol, constant, or global variable", 9..10]
       ]
     end
 
     def test_aliasing_non_global_variable_with_global_variable
       assert_errors expression("alias a $b"), "alias a $b", [
-        ["Expected a bare word or symbol argument.", 8..10]
+        ["Invalid argument being passed to `alias`; expected a bare word, symbol, constant, or global variable", 8..10]
       ]
     end
 
     def test_aliasing_global_variable_with_global_number_variable
       assert_errors expression("alias $a $1"), "alias $a $1", [
-        ["Can't make alias for number variables.", 9..11]
+        ["Invalid argument being passed to `alias`; expected a bare word, symbol, constant, or global variable", 9..11]
       ]
     end
 
     def test_def_with_expression_receiver_and_no_identifier
       assert_errors expression("def (a); end"), "def (a); end", [
-        ["Expected '.' or '::' after receiver", 7..7]
+        ["Expected a `.` or `::` after the receiver in a method definition", 7..7]
       ]
     end
 
     def test_def_with_multiple_statements_receiver
       assert_errors expression("def (\na\nb\n).c; end"), "def (\na\nb\n).c; end", [
-        ["Expected closing ')' for receiver.", 7..7],
-        ["Expected '.' or '::' after receiver", 7..7],
-        ["Expected to be able to parse an expression.", 10..10],
-        ["Expected to be able to parse an expression.", 11..11]
+        ["Expected a matching `)`", 7..7],
+        ["Expected a `.` or `::` after the receiver in a method definition", 7..7],
+        ["Cannot parse the expression", 10..10],
+        ["Cannot parse the expression", 11..11]
       ]
     end
 
     def test_def_with_empty_expression_receiver
       assert_errors expression("def ().a; end"), "def ().a; end", [
-        ["Expected to be able to parse receiver.", 5..5]
+        ["Expected a receiver for the method definition", 5..5]
       ]
     end
 
     def test_block_beginning_with_brace_and_ending_with_end
       assert_error_messages "x.each { x end", [
-        "Expected a newline or semicolon after statement.",
-        "Expected to be able to parse an expression.",
-        "Expected to be able to parse an expression.",
-        "Expected block beginning with '{' to end with '}'."
+        "Expected a newline or semicolon after the statement",
+        "Cannot parse the expression",
+        "Cannot parse the expression",
+        "Expected a block beginning with `{` to end with `}`"
       ]
     end
 
@@ -328,7 +328,7 @@ module YARP
       )
 
       assert_errors expected, "a(**kwargs, *args)", [
-        ["Unexpected splat argument after double splat.", 12..17]
+        ["Unexpected `*` splat argument after a `**` keyword splat argument", 12..17]
       ]
     end
 
@@ -349,15 +349,15 @@ module YARP
       )
 
       assert_errors expected, "a(&block, foo)", [
-        ["Unexpected argument after block argument.", 10..13]
+        ["Unexpected argument after a block argument", 10..13]
       ]
     end
 
     def test_arguments_binding_power_for_and
       assert_error_messages "foo(*bar and baz)", [
-        "Expected a ')' to close the argument list.",
-        "Expected a newline or semicolon after statement.",
-        "Expected to be able to parse an expression."
+        "Expected a `)` to close the arguments",
+        "Expected a newline or semicolon after the statement",
+        "Cannot parse the expression"
       ]
     end
 
@@ -384,7 +384,7 @@ module YARP
       )
 
       assert_errors expected, "a(foo: bar, *args)", [
-        ["Unexpected splat argument after double splat.", 12..17]
+        ["Unexpected `*` splat argument after a `**` keyword splat argument", 12..17]
       ]
     end
 
@@ -405,7 +405,7 @@ module YARP
       )
 
       assert_errors expected, "def foo;module A;end;end", [
-        ["Module definition in method body", 8..14]
+        ["Unexpected module definition in a method body", 8..14]
       ]
     end
 
@@ -443,7 +443,7 @@ module YARP
         Location()
       )
 
-      assert_errors expected, <<~RUBY, [["Module definition in method body", 21..27]]
+      assert_errors expected, <<~RUBY, [["Unexpected module definition in a method body", 21..27]]
         def foo
           bar do
             module Foo;end
@@ -480,7 +480,7 @@ module YARP
       )
 
       assert_errors expected, "def foo;class A;end;end", [
-        ["Class definition in method body", 8..13]
+        ["Unexpected class definition in a method body", 8..13]
       ]
     end
 
@@ -506,10 +506,10 @@ module YARP
       )
 
       assert_errors expected, "def foo(A, @a, $A, @@a);end", [
-        ["Formal argument cannot be a constant", 8..9],
-        ["Formal argument cannot be an instance variable", 11..13],
-        ["Formal argument cannot be a global variable", 15..17],
-        ["Formal argument cannot be a class variable", 19..22],
+        ["Invalid formal argument; formal argument cannot be a constant", 8..9],
+        ["Invalid formal argument; formal argument cannot be an instance variable", 11..13],
+        ["Invalid formal argument; formal argument cannot be a global variable", 15..17],
+        ["Invalid formal argument; formal argument cannot be a class variable", 19..22],
       ]
     end
 
@@ -540,15 +540,15 @@ module YARP
       end
       RUBY
       assert_errors expected, source, [
-        ["reserved for numbered parameter", 8..10],
-        ["reserved for numbered parameter", 14..16],
-        ["reserved for numbered parameter", 20..22],
-        ["reserved for numbered parameter", 26..28],
-        ["reserved for numbered parameter", 32..34],
-        ["reserved for numbered parameter", 40..42],
-        ["reserved for numbered parameter", 46..48],
-        ["reserved for numbered parameter", 52..54],
-        ["reserved for numbered parameter", 58..60],
+        ["Token reserved for a numbered parameter", 8..10],
+        ["Token reserved for a numbered parameter", 14..16],
+        ["Token reserved for a numbered parameter", 20..22],
+        ["Token reserved for a numbered parameter", 26..28],
+        ["Token reserved for a numbered parameter", 32..34],
+        ["Token reserved for a numbered parameter", 40..42],
+        ["Token reserved for a numbered parameter", 46..48],
+        ["Token reserved for a numbered parameter", 52..54],
+        ["Token reserved for a numbered parameter", 58..60],
       ]
     end
 
@@ -577,7 +577,7 @@ module YARP
       )
 
       assert_errors expected, "def foo(a,b,c,);end", [
-        ["Unexpected ','.", 13..14]
+        ["Unexpected `,` in parameters", 13..14]
       ]
     end
 
@@ -596,7 +596,7 @@ module YARP
         nil
       )
       assert_errors expected, "-> (a, b, ) {}", [
-        ["Unexpected ','.", 8..9]
+        ["Unexpected `,` in parameters", 8..9]
       ]
     end
 
@@ -604,13 +604,13 @@ module YARP
       expected = StringNode(Location(), Location(), nil, "\u0001\u0002")
 
       assert_errors expected, '?\u{0001 0002}', [
-        ["Multiple codepoints at single character literal", 9..12]
+        ["Invalid Unicode escape sequence; multiple codepoints are not allowed in a character literal", 9..12]
       ]
     end
 
     def test_invalid_hex_escape
       assert_errors expression('"\\xx"'), '"\\xx"', [
-        ["Invalid hex escape.", 1..3],
+        ["Invalid hexadecimal escape sequence", 1..3],
       ]
     end
 
@@ -618,7 +618,7 @@ module YARP
       expected = StringNode(Location(), Location(), Location(), "\u0001")
 
       assert_errors expected, '"\u{0000001}"', [
-        ["invalid Unicode escape.", 4..11],
+        ["Invalid Unicode escape sequence; maximum length is 6 digits", 4..11],
       ]
     end
 
@@ -626,13 +626,13 @@ module YARP
       expected = StringNode(Location(), Location(), Location(), "\u0000z}")
 
       assert_errors expected, '"\u{000z}"', [
-        ["unterminated Unicode escape", 7..7],
+        ["Invalid Unicode escape sequence", 7..7],
       ]
     end
 
     def test_unterminated_unicode_brackets_should_be_a_syntax_error
       assert_errors expression('?\\u{3'), '?\\u{3', [
-        ["invalid Unicode escape.", 1..5],
+        ["Invalid Unicode escape sequence; needs closing `}`", 1..5],
       ]
     end
 
@@ -923,7 +923,7 @@ module YARP
       )
 
       assert_errors expected, "case :a\nelse\nend", [
-        ["Unexpected else without no when clauses in case statement.", 8..12]
+        ["Unexpected `else` in `case` statement; a `when` clause must precede `else`", 8..12]
       ]
     end
 
@@ -944,7 +944,7 @@ module YARP
       )
 
       assert_errors expected, "def a=() = 42", [
-        ["Setter method cannot be defined in an endless method definition", 4..6]
+        ["Invalid method name; a setter method cannot be defined in an endless method definition", 4..6]
       ]
     end
 
@@ -959,7 +959,7 @@ module YARP
       )
 
       assert_errors expected, "->(...) {}", [
-        ["Unexpected ...", 3..6]
+        ["Unexpected `...` when the parent method is not forwarding", 3..6]
       ]
     end
 
@@ -983,7 +983,7 @@ module YARP
       )
 
       assert_errors expected, "a {|...|}", [
-        ["Unexpected ...", 4..7]
+        ["Unexpected `...` when the parent method is not forwarding", 4..7]
       ]
     end
 
@@ -1000,7 +1000,7 @@ module YARP
       )
 
       assert_errors expected, "class A; return; end", [
-        ["Invalid return in class/module body", 15..16]
+        ["Invalid `return` in a class or module body", 15..16]
       ]
     end
 
@@ -1015,7 +1015,7 @@ module YARP
       )
 
       assert_errors expected, "module A; return; end", [
-        ["Invalid return in class/module body", 16..17]
+        ["Invalid `return` in a class or module body", 16..17]
       ]
     end
 
@@ -1033,8 +1033,8 @@ module YARP
       )
 
       assert_errors expected, "begin\n$+ = nil\n$1466 = nil\nend", [
-        ["Can't set variable", 6..8],
-        ["Can't set variable", 15..20]
+        ["Immutable variable as a write target", 6..8],
+        ["Immutable variable as a write target", 15..20]
       ]
     end
 
@@ -1058,7 +1058,7 @@ module YARP
         )
 
         assert_errors expected, "def foo(a,b,a);end", [
-          ["Duplicated parameter name.", 12..13]
+          ["Repeated parameter name", 12..13]
         ]
       end
 
@@ -1078,7 +1078,7 @@ module YARP
       )
 
       assert_errors expected, "def foo(a,b,*a);end", [
-        ["Duplicated parameter name.", 13..14]
+        ["Repeated parameter name", 13..14]
       ]
 
       expected = DefNode(
@@ -1097,7 +1097,7 @@ module YARP
       )
 
       assert_errors expected, "def foo(a,b,**a);end", [
-        ["Duplicated parameter name.", 14..15]
+        ["Repeated parameter name", 14..15]
       ]
 
       expected = DefNode(
@@ -1116,7 +1116,7 @@ module YARP
       )
 
       assert_errors expected, "def foo(a,b,&a);end", [
-        ["Duplicated parameter name.", 13..14]
+        ["Repeated parameter name", 13..14]
       ]
 
       expected = DefNode(
@@ -1134,12 +1134,12 @@ module YARP
         Location()
       )
 
-      assert_errors expected, "def foo(a = 1,b,*c);end", [["Unexpected parameter *", 16..17]]
+      assert_errors expected, "def foo(a = 1,b,*c);end", [["Unexpected parameter `*`", 16..17]]
     end
 
     def test_unterminated_global_variable
       assert_errors expression("$"), "$", [
-        ["Invalid global variable.", 0..1]
+        ["Invalid global variable", 0..1]
       ]
     end