yyc12345/YYCCommonplace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: add documentation for ConsoleHelper

Browse Source
This commit is contained in:
yyc12345 2024-07-16 10:41:09 +08:00
parent 81fe72c425
commit b13bb445e4
3 changed files with 182 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
doc/src/console_helper.dox Normal file
View File

@ -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 <TT>"Light Red Text"</TT> to be shown in light red color.
And for second line, it will make <TT>"Light Red"</TT> to be shown in light red color,
but <TT>"I am "</TT> 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.
*/

2
doc/src/index.dox
View File

@ -39,6 +39,8 @@
\li \subpage parser_helper \li \subpage parser_helper
\li \subpage console_helper
\li \subpage io_helper \li \subpage io_helper
\li \subpage fs_path_patch \li \subpage fs_path_patch

55
src/ConsoleHelper.hpp
View File

@ -7,60 +7,7 @@
/** /**
* @brief The namespace providing universal Console visiting functions like C-Sharp Console class. * @brief The namespace providing universal Console visiting functions like C-Sharp Console class.
* @details * @details
* \par Why this Namespace * \ref console_helper
* 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.
*/ */
namespace YYCC::ConsoleHelper { namespace YYCC::ConsoleHelper {