Specify usable escape sequences in Exception#detailed_message

An error message is primarily rendered in a terminal emulator, but is
also shown in a browser by converting it to a HTML fragment.
However, the conversion would be unreasonably difficult if the message
includes any escape sequence (such as cursor move or screen clear).

This change adds a guideline about escape sequences in
`Exception#detailed_message`:

* Use widely-supported escape sequences: bold, underline, and basic
  eight foreground colors (except white and black).
* Make the message readable if all escape sequences are ignored.
This commit is contained in:
Yusuke Endoh 2022-07-12 13:50:04 +09:00
Родитель 1052ad4e48
Коммит 1fe6c92603
1 изменённых файлов: 22 добавлений и 0 удалений

22
error.c
Просмотреть файл

@ -1385,6 +1385,28 @@ exc_message(VALUE exc)
*
* This method is overridden by did_you_mean and error_highlight to add
* their information.
*
* A user-defined exception class can also define their own
* +detailed_message+ method to add supplemental information.
* When +highlight+ is true, it can return a string containing escape
* sequences, but use widely-supported ones. It is recommended to limit
* the following codes:
*
* - Reset (+\e[0m+)
* - Bold (+\e[1m+)
* - Underline (+\e[4m+)
* - Foreground color except white and black
* - Red (+\e[31m+)
* - Green (+\e[32m+)
* - Yellow (+\e[33m+)
* - Blue (+\e[34m+)
* - Magenta (+\e[35m+)
* - Cyan (+\e[36m+)
*
* Use escape sequeunces carefully even if +highlight+ is true.
* Do not use escape sequences to express essential information;
* the message should be readable even if all escape sequences are
* ignored.
*/
static VALUE