Capstone B: errors a user can read

A message that says expected a number at 4 is correct and still hard to use: the reader has to count four characters to find the place. This lesson turns the position from a number in a message into a property of an exception, and the program prints the input, a caret under the character and the message under both. It also makes the program a command, so the status of a failed run is part of the answer.

An exception with a position

SyntaxException derives from FormatException, so a catch of the base type still takes it, and it adds one member: the position. Both the lexer and the parser throw it, and the message no longer repeats the number, because the caller has it. The whole program is one listing:

Console.WriteLine("calc 1.0"); var input = args.Length > 0 ? string.Join(' ', args) : "1 + * 2"; try { var value = Eval(Parse(Lex(input))); Console.WriteLine($"{input} = {value}"); return 0; } catch (SyntaxException ex) { Console.WriteLine(input); Console.WriteLine($"{new string(' ', ex.Position)}^"); Console.WriteLine($"error at {ex.Position}: {ex.Message}"); return 1; } static double Eval(Node node) => node switch { Number number => number.Value, Unary unary => -Eval(unary.Operand), Binary binary => binary.Op switch { '+' => Eval(binary.Left) + Eval(binary.Right), '-' => Eval(binary.Left) - Eval(binary.Right), '*' => Eval(binary.Left) * Eval(binary.Right), _ => Eval(binary.Left) / Eval(binary.Right), }, _ => throw new SyntaxException(0, "unknown node"), }; static List<Token> Lex(string text) { var tokens = new List<Token>(); var i = 0; while (i < text.Length) { var c = text[i]; if (char.IsWhiteSpace(c)) { i++; continue; } if (char.IsDigit(c) || c == '.') { var start = i; while (i < text.Length && (char.IsDigit(text[i]) || text[i] == '.')) { i++; } var number = text[start..i]; var value = double.Parse(number, System.Globalization.CultureInfo.InvariantCulture); tokens.Add(new Token(TokenKind.Number, value, start, number)); continue; } if (c is '+' or '-' or '*' or '/' or '(' or ')') { tokens.Add(new Token(TokenKind.Operator, 0, i, c.ToString())); i++; continue; } throw new SyntaxException(i, $"unexpected '{c}'"); } tokens.Add(new Token(TokenKind.End, 0, text.Length, "end")); return tokens; } static Node Parse(List<Token> tokens) => Parser.Parse(tokens); enum TokenKind { Number, Operator, End, } record Token(TokenKind Kind, double Value, int Position, string Text); sealed class SyntaxException(int position, string message) : FormatException(message) { public int Position { get; } = position; } abstract record Node; sealed record Number(double Value) : Node; sealed record Unary(char Op, Node Operand) : Node; sealed record Binary(char Op, Node Left, Node Right) : Node; sealed class Parser { private readonly List<Token> _tokens; private int _index; private Parser(List<Token> tokens) => _tokens = tokens; public static Node Parse(List<Token> tokens) => new Parser(tokens).Expression(); private Token Current => _tokens[_index]; private Node Expression() { var left = Term(); while (Current.Kind == TokenKind.Operator && Current.Text is "+" or "-") { var op = Current.Text[0]; _index++; left = new Binary(op, left, Term()); } return left; } private Node Term() { var left = Factor(); while (Current.Kind == TokenKind.Operator && Current.Text is "*" or "/") { var op = Current.Text[0]; _index++; left = new Binary(op, left, Factor()); } return left; } private Node Factor() { var token = Current; switch (token.Kind) { case TokenKind.Number: _index++; return new Number(token.Value); case TokenKind.Operator when token.Text == "-": _index++; return new Unary('-', Factor()); case TokenKind.Operator when token.Text == "(": _index++; var inner = Expression(); Expect(")"); return inner; default: throw new SyntaxException(token.Position, "expected a number"); } } private void Expect(string text) { if (Current.Kind != TokenKind.Operator || Current.Text != text) { throw new SyntaxException(Current.Position, $"expected '{text}'"); } _index++; } }

The program takes the expression from its arguments, so one build answers every case below. The default input is the broken one, which makes a bare dotnet run show the message the lesson is about:

dotnet run
echo "status: $?"

calc 1.0
1 + * 2
    ^
error at 4: expected a number
status: 1

The caret line

new string(' ', ex.Position) builds a string of spaces with the length of the position, and a ^ goes after it. The caret therefore points at dotnet run -- 2 * "(3 + 4)"
echo "status: $?"

calc 1.0
2 * (3 + 4) = 14
status: 0

The two remaining runs are the two errors of the previous lessons, now with the position marked. A missing closing parenthesis is an error one past the last character, so its caret stands after the text, where the character belongs:

dotnet run -- '1 + (2'
echo "status: $?"

calc 1.0
1 + (2
      ^
error at 6: expected ')'
status: 1

dotnet run -- '1 + $'
echo "status: $?"

calc 1.0
1 + $
    ^
error at 4: unexpected '$'
status: 1

The fourth run is a lexer error and not a parser error: the dollar sign never becomes a token. Both arrive at the same catch, because both throw the same exception with the same property, and the caret line is written once.

The exit status

A successful run returns zero and a failed one returns one, so a script or a make rule can tell without reading the text. The status is the value of the return statement of the top-level program, and the shell line in each command block is what printed it.

The next lesson puts the read of the line into a loop: a prompt, a result per line, a running total and :quit.

Exercises

  1. Give the caret line an underline of the length of the token instead of one character.
  2. Print the column number next to the caret and check that it is one more than the position, because a person counts from one.
  3. Catch FormatException instead of SyntaxException and report the position as unknown, then argue for one of the two catches.
  4. Return 2 for an empty input and leave 1 for a syntax error.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Why does SyntaxException carry the position as a property?

    Answer

    The caller can draw a caret without reading a number out of the message

    The caret line uses ex.Position directly.

  2. What does new string(' ', 4) create?

    Answer

    Four spaces

    The caret sits four characters to the right of the start of the line.

  3. What does this program print? var input = "1 + * 2"; Console.WriteLine($"{input.Length}");

    Answer

    7

    Seven characters including the spaces.

  4. Why does the catch of the program cover a lexer error and a parser error?

    Answer

    Both throw SyntaxException, which derives from FormatException

    One type, one catch, one caret line.

  5. What is the exit status of the default run?

    Answer

    1

    The measured status line of the failing run reads status: 1.

  6. What does this program print? var position = 3; Console.WriteLine(new string('-', position) + "^");

    Answer

    ---^

    Three copies of the character, then the caret.

  7. Why print the input line above the caret?

    Answer

    The message points into a line the reader can see

    A caret under a line that is no longer on screen says nothing.

  8. What does this program print? try { throw new FormatException("bad"); } catch (FormatException ex) { Console.WriteLine($"caught {ex.Message}"); }

    Answer

    caught bad

    The catch takes the exception and prints its message.

  9. What status does a successful run of the calculator return?

    Answer

    0

    The measured line for 2 * (3 + 4) = 14 ends with status: 0.

  10. What is the position of an error that needs a character at the end of the line?

    Answer

    The length of the line

    1 + (2 is six characters and the error is at six, where the parenthesis belongs.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev