diff --git a/doc/src/carton/console_helper.dox b/doc/src/carton/console_helper.dox deleted file mode 100644 index c6cc627..0000000 --- a/doc/src/carton/console_helper.dox +++ /dev/null @@ -1,181 +0,0 @@ -namespace YYCC::ConsoleHelper { -/** - -\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 #EnableColorfulConsole can fix this issue. - -#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 \c \#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 #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/carton/csconsole.dox b/doc/src/carton/csconsole.dox new file mode 100644 index 0000000..c322fad --- /dev/null +++ b/doc/src/carton/csconsole.dox @@ -0,0 +1,74 @@ +namespace YYCC::ConsoleHelper { +/** + +\page csconsole Universal IO Function + +This namespace provide universal console IO function which is more like C\# provided, +because Windows is lacking in UTF8 console IO. + +\section csconsole__deprecation Deprecation Notes + +This namespace, or thie module is deprecated. +It provided functions are too aggressive and can not cover all use scenarios. +So it is suggested not to use this namespace. +Programmers should handle Windows UTF8 issues on their own. + +\section csconsole__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. + +\section csconsole__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. + +\section csconsole__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 "e" (like eformat, ewrite) will write data into stderr, +otherwise they will write data into stdout. +\li Functions with embedded "format" (format, format_line, eformat, eformat_line) are output functions with format feature like \c std::fprintf(), +otherwise the functions with embedded "write" in the name (write, write_line, ewrite, ewrite_line) will only write plain string like \c std::fputs(). +\li Functions with trailing "line" (format_line, write_line, eformat_line, ewrite_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 1e589cb..2fd591c 100644 --- a/doc/src/index.dox +++ b/doc/src/index.dox @@ -52,14 +52,14 @@ \li \subpage termcolor + \li \subpage csconsole +