Handle formatting errors

Control how Smart Strings react to invalid format strings and unformattable values, and track the failures that occur.

Smart Strings can fail at two stages: when the Parser reads the format string, and when the SmartFormatter evaluates a placeholder. Each stage has its own error action that decides whether a failure raises an exception, appears in the output, is skipped, or leaves the placeholder unchanged.

Error actions

The parser error action is ParserSettings.ErrorAction, of type ParseErrorAction.

The formatter error action is FormatterSettings.ErrorAction, of type FormatErrorAction.

Both enums define the same four values in the same order, and both default to ThrowError.

Value	What it does
`ThrowError`	Raises an exception. This is the default. Use this while debugging so that errors surface immediately.
`OutputErrorInResult`	Writes the error message into the formatted result instead of throwing.
`Ignore`	Skips the error and continues, producing no output for the failed item.
`MaintainTokens`	Leaves the offending token unchanged in the output, so the original placeholder text is preserved.

Set the error actions

Set the error actions in the editor or in code:

In the editor, open Edit > Project Settings > Smart Strings and use the Error Action dropdown under the Parser and Formatter sections. Refer to Smart Strings settings reference.
In code, set them on the active formatter’s settings:

Smart.Default.Settings.Parser.ErrorAction = ParseErrorAction.OutputErrorInResult;
Smart.Default.Settings.Formatter.ErrorAction = FormatErrorAction.Ignore;

Note: Settings are intended to be applied during initialization. Change the error actions before the formatter and parser process any Smart String.

Track failures

To observe failures without changing the error action, subscribe to the failure events. Both events fire whether or not an exception is thrown.

To track failures in the formatter, subscribe to SmartFormatter.OnFormattingFailure events. This event raises a FormattingErrorEventArgs that reports the Placeholder text, the ErrorIndex within the format string, and IgnoreError, which is true when the error action is anything other than ThrowError.

To track failures in the parser, subscribe to Parser.OnParsingFailure events. This event raises a ParsingErrorEventArgs that reports the parsing Errors and ThrowsException, which is true when the parser error action is ThrowError. Reach the parser through Smart.Default.Parser.

Smart.Default.OnFormattingFailure += (sender, e) =>
    Debug.LogWarning($"Smart String failed at {e.ErrorIndex}: {e.Placeholder}");

When the error action is ThrowError, a formatting failure throws a FormattingException. It exposes:

Member	Description
`Issue`	A description of the error.
`Format`	The base format string that caused the error.
`Index`	The index inside the format string where the error occurred.
`ErrorItem`	The `FormatItem` that caused the error.

Additional resources

Smart Strings settings reference

Smart Strings performance