Handle formatting errors
Control how Smart Strings react to invalid format strings and unformattable values, and track the failures that occur.
Read time 2 minutesLast updated 5 days ago
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 , of type .
ParserSettings.ErrorActionParseErrorActionThe formatter error action is , of type .
FormatterSettings.ErrorActionFormatErrorActionBoth enums define the same four values in the same order, and both default to .
ThrowErrorValue | What it does |
|---|---|
| Raises an exception. This is the default. Use this while debugging so that errors surface immediately. |
| Writes the error message into the formatted result instead of throwing. |
| Skips the error and continues, producing no output for the failed item. |
| 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 events. This event raises a that reports the text, the within the format string, and , which is when the error action is anything other than .
SmartFormatter.OnFormattingFailureFormattingErrorEventArgsPlaceholderErrorIndexIgnoreErrortrueThrowErrorTo track failures in the parser, subscribe to events. This event raises a that reports the parsing and , which is when the parser error action is . Reach the parser through .
Parser.OnParsingFailureParsingErrorEventArgsErrorsThrowsExceptiontrueThrowErrorSmart.Default.ParserSmart.Default.OnFormattingFailure += (sender, e) => Debug.LogWarning($"Smart String failed at {e.ErrorIndex}: {e.Placeholder}");
When the error action is , a formatting failure throws a . It exposes:
ThrowErrorFormattingExceptionMember | Description |
|---|---|
| A description of the error. |
| The base format string that caused the error. |
| The index inside the format string where the error occurred. |
| The |