From b13bb445e4f7885fd3bab965f8fb7c105ce3fab8 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Tue, 16 Jul 2024 10:41:09 +0800 Subject: [PATCH] doc: add documentation for ConsoleHelper --- doc/src/console_helper.dox | 179 +++++++++++++++++++++++++++++++++++++ doc/src/index.dox | 2 + src/ConsoleHelper.hpp | 55 +----------- 3 files changed, 182 insertions(+), 54 deletions(-) create mode 100644 doc/src/console_helper.dox diff --git a/doc/src/console_helper.dox b/doc/src/console_helper.dox new file mode 100644 index 0000000..461485d --- /dev/null +++ b/doc/src/console_helper.dox @@ -0,0 +1,179 @@ +/** + +\page console_helper Console Helper + +This helper provide console related stuff. +This helper includes 2 parts. +First part is console color. +It was constituted by a bunch of macros. +The second part is universal console IO function because Windows is lacking in UTF8 console IO. +All of these parts will be introduced in following content. + +\section console_helper__color Console Color + +YYCC::ConsoleHelper provide a bunch of macros which can allow you output colorful text in terminal. +Supported color is limited in 16 colors, +because these color is implemented by ASCII Escape Code: https://en.wikipedia.org/wiki/ANSI_escape_code . +So if your terminal do not support this, such as default Windows terminal, or teletypewriter, +you will see some unrecognised characters surrounding with your output. +That's ASCII Escape Code. + +\subsection console_helper__color__enable_win_color Enable Color in Windows Console + +As we introduced in above, +you may know Windows console does not support ASCII Escape Code color in default. +However YYCC::ConsoleHelper::EnableColorfulConsole can fix this issue. + +YYCC::ConsoleHelper::EnableColorfulConsole will forcely enable ASCII Escape Code support in Windows console if possible. +Thus you can write colorful text in Windows console freely. +We suggest you to call this function at the beginning of program. + +Considering most Linux console supports ASCII Escape Code very well, +this function does nothing in non-Windows platform. +So it is not essential that brack this function calling with Windows-only \#if. + +\subsection console_helper__color__common Common Usage + +For common scenarios, you can use macro like this: + +\code +YYCC::ConsoleHelper::WriteLine(YYCC_U8(YYCC_COLOR_LIGHT_RED("Light Red Text"))); +YYCC::ConsoleHelper::WriteLine(YYCC_U8("I am " YYCC_COLOR_LIGHT_RED("Light Red"))); +\endcode + +In first line, it will make "Light Red Text" to be shown in light red color. +And for second line, it will make "Light Red" to be shown in light red color, +but "I am " will keep default console font color. + +You also may notice this macro is used with YYCC_U8 macro. +Because YYCC::ConsoleHelper::WriteLine only accept UTF8 argument. +So please note if you use console color macro with YYCC_U8, +please make YYCC_U8 always is located the outside. +Otherwise, YYCC_U8 will fail to make the whole become UTF8 stirng as we introduced in \ref library_encoding. +Because console color macro is implemented by string literal concatenation internally. + +YYCC_COLOR_LIGHT_RED is a member in YYCC_COLOR macro family. +YYCC_COLOR macro family has 16 members for 16 different colors: + +\li YYCC_COLOR_BLACK +\li YYCC_COLOR_RED +\li YYCC_COLOR_GREEN +\li YYCC_COLOR_YELLOW +\li YYCC_COLOR_BLUE +\li YYCC_COLOR_MAGENTA +\li YYCC_COLOR_CYAN +\li YYCC_COLOR_WHITE +\li YYCC_COLOR_LIGHT_BLACK +\li YYCC_COLOR_LIGHT_RED +\li YYCC_COLOR_LIGHT_GREEN +\li YYCC_COLOR_LIGHT_YELLOW +\li YYCC_COLOR_LIGHT_BLUE +\li YYCC_COLOR_LIGHT_MAGENTA +\li YYCC_COLOR_LIGHT_CYAN +\li YYCC_COLOR_LIGHT_WHITE + +\subsection console_helper__color__embedded Embedded Usgae + +In some cases, you want change console at some time point and reset it in another time point. +You can use color macros like following example: + +\code +YYCC::ConsoleHelper::WriteLine(YYCC_U8(YYCC_COLORHDR_LIGHT_BLUE)); + +// Write as much as you liked +YYCC::ConsoleHelper::WriteLine(YYCC_U8("some string")); +YYCC::ConsoleHelper::WriteLine(YYCC_U8("another string")); + +YYCC::ConsoleHelper::WriteLine(YYCC_U8(YYCC_COLORTAIL)); +\endcode + +At first line, we output YYCC_COLORHDR_LIGHT_BLUE which is in YYCC_COLORHDR macro family. +It is colorful text ASCII Escape Code head. +It will make all following output become light blue color, +until the last line we output YYCC_COLORTAIL to reset console color to original color. + +Same as YYCC_COLOR macro family, +YYCC_COLORHDR macro family also has 16 members for 16 different colors: + +\li YYCC_COLORHDR_BLACK +\li YYCC_COLORHDR_RED +\li YYCC_COLORHDR_GREEN +\li YYCC_COLORHDR_YELLOW +\li YYCC_COLORHDR_BLUE +\li YYCC_COLORHDR_MAGENTA +\li YYCC_COLORHDR_CYAN +\li YYCC_COLORHDR_WHITE +\li YYCC_COLORHDR_LIGHT_BLACK +\li YYCC_COLORHDR_LIGHT_RED +\li YYCC_COLORHDR_LIGHT_GREEN +\li YYCC_COLORHDR_LIGHT_YELLOW +\li YYCC_COLORHDR_LIGHT_BLUE +\li YYCC_COLORHDR_LIGHT_MAGENTA +\li YYCC_COLORHDR_LIGHT_CYAN +\li YYCC_COLORHDR_LIGHT_WHITE + +However YYCC_COLORTAIL is YYCC_COLORTAIL. +There is no other variant for different colors. +Because all tail of colorful ASCII Escape Code is same. + +\section console_helper__universal_io Universal IO Function + +\subsection console_helper__universal_io__why Why? + +Windows console doesn't support UTF8 very well. +The standard input output functions can not work properly with UTF8 on Windows. +So we create this namespace and provide various console-related functions +to patch Windows console and let it more like the console in other platforms. + +The function provided in this function can be called in any platforms. +In Windows, the implementation will use Windows native function, +and in other platform, the implementation will redirect request to standard C function like \c std::fputs and etc. +So the programmer do not need to be worried about which function should they use, +and don't need to use macro to use different IO function in different platforms. +It is just enough that fully use the functions provided in this namespace. + +All IO functions this namespace provided are UTF8-based. +It also means that input output string should always be UTF8 encoded. + +\subsection console_helper__universal_io__input Input Functions + +Please note that EOL will automatically converted into LF on Windows platform, not CRLF. +This action actually is removing all CR chars in result string. +This behavior affect nothing in most cases but it still is possible break something in some special case. + +Due to implementation, if you decide to use this function, +you should give up using any other function to read stdin stream, +such as \c std::gets() and \c std::cin. +Because this function may read chars which is more than needed. +These extra chars will be stored in this function and can be used next calling. +But these chars can not be visited by stdin again. +This behavior may cause bug. +So if you decide using this function, stick on it and do not change. + +Due to implementation, this function do not support hot switch of stdin. +It means that stdin can be redirected before first calling of this function, +but it should not be redirected during program running. +The reason is the same one introduced above. + +\subsection console_helper__universal_io__output Output Functions + +In current implementation, EOL will not be converted automatically to CRLF. +This is different with other stream read functions provided in this namespace. + +Comparing with other stream read functions provided in this namespace, +stream write function support hot switch of stdout and stderr. +Because they do not have internal buffer storing something. + +In this namespace, there are various stream write function. +There is a list telling you how to choose one from them for using: + +\li Functions with leading "Err" will write data into stderr, +otherwise they will write data into stdout. +\li Functions with embedded "Format" are output functions with format feature +like \c std::fprintf(), otherwise the functions with embedded "Write" will +only write plain string like \c std::fputs(). +\li Functions with trailing "Line" will write extra EOL to break current line. +This is commonly used, otherwise functions will only write the text provided by arguments, +without adding something. + +*/ \ No newline at end of file diff --git a/doc/src/index.dox b/doc/src/index.dox index 67895cc..65276e7 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -39,6 +39,8 @@ \li \subpage parser_helper + \li \subpage console_helper + \li \subpage io_helper \li \subpage fs_path_patch diff --git a/src/ConsoleHelper.hpp b/src/ConsoleHelper.hpp index 5e7eb35..18df6ed 100644 --- a/src/ConsoleHelper.hpp +++ b/src/ConsoleHelper.hpp @@ -7,60 +7,7 @@ /** * @brief The namespace providing universal Console visiting functions like C-Sharp Console class. * @details - * \par Why this Namespace - * Windows console doesn't support UTF8 very well. - * The standard input output functions can not work properly on Windows with UTF8. - * So we create this namespace and provide various console-related functions - * to patch Windows console and let it more like the console in other platforms. - * \par - * The function provided in this function can be called in any platforms. - * In Windows, the implementation will use Windows native function, - * and in other platform, the implementation will redirect request to standard C function - * like std::fputs and etc. - * So the programmer do not need to be worried about which function should they use, - * and don't need to use macro to use different IO function in different platforms. - * It is just enough that fully use the functions provided in this namespace. - * \par - * All IO functions this namespace provided are UTF8-based. - * It also means that input output string should always be UTF8 encoded. - * - * \par Input Functions - * Please note that EOL will automatically converted into LF on Windows platform, not CRLF. - * This action actually is removing all CR chars in result string. - * This behavior affect nothing in most cases but it still is possible break something in some special case. - * \par - * Due to implementation, if you decide to use this function, - * you should give up using any other function to read stdin stream, - * such as std::gets() and std::cin. - * Because this function may read chars which is more than needed. - * These extra chars will be stored in this function and can be used next calling. - * But these chars can not be visited by stdin again. - * This behavior may cause bug. - * So if you decide using this function, stick on it and do not change. - * \par - * Due to implementation, this function do not support hot switch of stdin. - * It means that stdin can be redirected before first calling of this function, - * but it should not be redirected during program running. - * The reason is the same one introduced above. - * - * \par Output Functions - * In current implementation, EOL will not be converted automatically to CRLF. - * This is different with other stream read functions provided in this namespace. - * \par - * Comparing with other stream read functions provided in this namespace, - * stream write function support hot switch of stdout and stderr. - * Because they do not have internal buffer storing something. - * \par - * In this namespace, there are various stream write function. - * There is a list telling you how to choose one from them for using: - * \li Functions with leading "Err" will write data into stderr, - * otherwise they will write data into stdout. - * \li Functions with embedded "Format" are output functions with format feature - * like std::fprintf(), otherwise the functions with embedded "Write" will - * only write plain string like std::fputs(). - * \li Functions with trailing "Line" will write extra EOL to break current line. - * This is commonly used, otherwise functions will only write the text provided by arguments, - * without adding something. + * \ref console_helper */ namespace YYCC::ConsoleHelper {