From 27edd158c145b7ebe11c717f9ae1ac5f1e816eaa Mon Sep 17 00:00:00 2001 From: Laurent Rineau Date: Wed, 29 Oct 2025 17:34:57 +0100 Subject: [PATCH] self-review helped by Copilot --- .../doc/Stream_support/PackageDescription.txt | 16 +++ .../doc/Stream_support/examples.txt | 2 + .../include/CGAL/IO/Color_ostream.h | 132 ++++++++++-------- .../include/CGAL/IO/Indenting_ostream.h | 43 ++++-- 4 files changed, 124 insertions(+), 69 deletions(-) diff --git a/Stream_support/doc/Stream_support/PackageDescription.txt b/Stream_support/doc/Stream_support/PackageDescription.txt index 2d97d36e3c1..8e2c6762e41 100644 --- a/Stream_support/doc/Stream_support/PackageDescription.txt +++ b/Stream_support/doc/Stream_support/PackageDescription.txt @@ -65,9 +65,22 @@ the printing mode. \cgalCRPSection{Enum} - \link PkgStreamSupportEnumRef `CGAL::IO::Mode` \endlink +- `CGAL::IO::Ansi_color` \cgalCRPSection{Classes} - `CGAL::IO::Color` +- `CGAL::IO::Basic_color_streambuf` +- `CGAL::IO::Color_streambuf` +- `CGAL::IO::Color_wstreambuf` +- `CGAL::IO::Basic_color_stream_guard` +- `CGAL::IO::Color_stream_guard` +- `CGAL::IO::Color_wstream_guard` +- `CGAL::IO::Basic_indenting_streambuf` +- `CGAL::IO::Indenting_streambuf` +- `CGAL::IO::Indenting_wstreambuf` +- `CGAL::IO::Basic_indenting_stream_guard` +- `CGAL::IO::Indenting_stream_guard` +- `CGAL::IO::Indenting_wstream_guard` - `CGAL::Istream_iterator` - `CGAL::Ostream_iterator` - `CGAL::Verbose_ostream` @@ -75,6 +88,9 @@ the printing mode. - `CGAL::Output_rep` \cgalCRPSection{Functions} +- `CGAL::IO::make_color_guards()` +- `CGAL::IO::stream_supports_color()` +- `CGAL::IO::make_indenting_guards()` - `CGAL::IO::get_mode()` - `CGAL::IO::is_ascii()` - `CGAL::IO::is_binary()` diff --git a/Stream_support/doc/Stream_support/examples.txt b/Stream_support/doc/Stream_support/examples.txt index b8fd39550b6..5dac2ab70fc 100644 --- a/Stream_support/doc/Stream_support/examples.txt +++ b/Stream_support/doc/Stream_support/examples.txt @@ -1,4 +1,6 @@ /*! +\example Stream_support/color_ostream.cpp +\example Stream_support/indenting_ostream.cpp \example Stream_support/Linestring_WKT.cpp \example Stream_support/Point_WKT.cpp \example Stream_support/Polygon_WKT.cpp diff --git a/Stream_support/include/CGAL/IO/Color_ostream.h b/Stream_support/include/CGAL/IO/Color_ostream.h index af0b71a3982..d8fd7414558 100644 --- a/Stream_support/include/CGAL/IO/Color_ostream.h +++ b/Stream_support/include/CGAL/IO/Color_ostream.h @@ -13,6 +13,8 @@ // // // Author(s) : Laurent Rineau +// +// Documentation partially generated by Github Copilot #ifndef CGAL_IO_COLOR_OSTREAM_H #define CGAL_IO_COLOR_OSTREAM_H @@ -39,6 +41,7 @@ #endif #if defined(__STDC_LIB_EXT1__) && defined(_WIN32) +# include # include // for getenv_s # define CGAL_USE_GETENV_S 1 #endif @@ -47,58 +50,58 @@ namespace CGAL { namespace IO { /** - * \ingroup PkgStreamSupportRef + * \ingroup PkgStreamSupportEnumRef * * ANSI color codes for terminal output. */ enum class Ansi_color { - Reset = 0, - Bold = 1, - Dim = 2, - Underline = 4, - Blink = 5, - Reverse = 7, - Hidden = 8, + Reset = 0, ///< Reset all attributes to default + Bold = 1, ///< Bold or increased intensity + Dim = 2, ///< Faint or decreased intensity + Underline = 4, ///< Underlined text + Blink = 5, ///< Blinking text + Reverse = 7, ///< Swap foreground and background colors + Hidden = 8, ///< Hidden or invisible text // Foreground colors - Black = 30, - Red = 31, - Green = 32, - Yellow = 33, - Blue = 34, - Magenta = 35, - Cyan = 36, - White = 37, + Black = 30, ///< Black foreground color + Red = 31, ///< Red foreground color + Green = 32, ///< Green foreground color + Yellow = 33, ///< Yellow foreground color + Blue = 34, ///< Blue foreground color + Magenta = 35, ///< Magenta foreground color + Cyan = 36, ///< Cyan foreground color + White = 37, ///< White foreground color // Bright foreground colors - BrightBlack = 90, - BrightRed = 91, - BrightGreen = 92, - BrightYellow = 93, - BrightBlue = 94, - BrightMagenta = 95, - BrightCyan = 96, - BrightWhite = 97, + BrightBlack = 90, ///< Bright black (gray) foreground color + BrightRed = 91, ///< Bright red foreground color + BrightGreen = 92, ///< Bright green foreground color + BrightYellow = 93, ///< Bright yellow foreground color + BrightBlue = 94, ///< Bright blue foreground color + BrightMagenta = 95, ///< Bright magenta foreground color + BrightCyan = 96, ///< Bright cyan foreground color + BrightWhite = 97, ///< Bright white foreground color // Background colors - BgBlack = 40, - BgRed = 41, - BgGreen = 42, - BgYellow = 43, - BgBlue = 44, - BgMagenta = 45, - BgCyan = 46, - BgWhite = 47, + BgBlack = 40, ///< Black background color + BgRed = 41, ///< Red background color + BgGreen = 42, ///< Green background color + BgYellow = 43, ///< Yellow background color + BgBlue = 44, ///< Blue background color + BgMagenta = 45, ///< Magenta background color + BgCyan = 46, ///< Cyan background color + BgWhite = 47, ///< White background color // Bright background colors - BgBrightBlack = 100, - BgBrightRed = 101, - BgBrightGreen = 102, - BgBrightYellow = 103, - BgBrightBlue = 104, - BgBrightMagenta = 105, - BgBrightCyan = 106, - BgBrightWhite = 107 + BgBrightBlack = 100, ///< Bright black (gray) background color + BgBrightRed = 101, ///< Bright red background color + BgBrightGreen = 102, ///< Bright green background color + BgBrightYellow = 103, ///< Bright yellow background color + BgBrightBlue = 104, ///< Bright blue background color + BgBrightMagenta = 105, ///< Bright magenta background color + BgBrightCyan = 106, ///< Bright cyan background color + BgBrightWhite = 107 ///< Bright white background color }; /** @@ -110,18 +113,21 @@ enum class Ansi_color { * * \tparam CharT Character type (typically `char` or `wchar_t`) * \tparam Traits Character traits type + * + * \sa Basic_color_stream_guard + * \sa make_color_guards */ template > class Basic_color_streambuf : public std::basic_streambuf, protected Traits { public: - using char_type = CharT; - using traits_type = Traits; - using int_type = typename traits_type::int_type; - using pos_type = typename traits_type::pos_type; - using off_type = typename traits_type::off_type; - using streambuf_type = std::basic_streambuf; - using string = std::basic_string; + using char_type = CharT; ///< Character type + using traits_type = Traits; ///< Character traits type + using int_type = typename traits_type::int_type; ///< Integer type for character representation + using pos_type = typename traits_type::pos_type; ///< Position type for stream positioning + using off_type = typename traits_type::off_type; ///< Offset type for stream positioning + using streambuf_type = std::basic_streambuf; ///< Type of the wrapped streambuf + using string = std::basic_string; ///< String type matching character type private: streambuf_type* wrapped_buf_; @@ -425,9 +431,11 @@ protected: } }; +/// \ingroup PkgStreamSupportRef /// Type alias for `Basic_color_streambuf` using Color_streambuf = Basic_color_streambuf; +/// \ingroup PkgStreamSupportRef /// Type alias for `Basic_color_streambuf` using Color_wstreambuf = Basic_color_streambuf; @@ -440,16 +448,20 @@ using Color_wstreambuf = Basic_color_streambuf; * It provides a convenient way to add colors to output streams within a specific scope. * * \tparam StreamT The stream type (e.g., `std::ostream`, `std::wostream`) + * + * \sa Basic_color_streambuf + * \sa make_color_guards */ template class Basic_color_stream_guard { +public: + using char_type = typename StreamT::char_type; ///< Character type + using traits_type = typename StreamT::traits_type; ///< Character traits type + using streambuf_type = Basic_color_streambuf; ///< Type of the color streambuf + using wrapped_streambuf_type = std::basic_streambuf; ///< Type of the wrapped streambuf + using string = std::basic_string; ///< String type matching character type private: - using char_type = typename StreamT::char_type; - using traits_type = typename StreamT::traits_type; - using streambuf_type = Basic_color_streambuf; - using wrapped_streambuf_type = std::basic_streambuf; - using string = std::basic_string; StreamT& stream_; wrapped_streambuf_type* original_buf_; string original_color_code_; @@ -526,9 +538,11 @@ public: } }; +/// \ingroup PkgStreamSupportRef /// Type alias for `Basic_color_stream_guard` using Color_stream_guard = Basic_color_stream_guard; +/// \ingroup PkgStreamSupportRef /// Type alias for `Basic_color_stream_guard` using Color_wstream_guard = Basic_color_stream_guard; @@ -547,9 +561,11 @@ using Color_wstream_guard = Basic_color_stream_guard; * \param streams The streams to apply colors to * \return A tuple of Basic_color_stream_guard objects * + * \sa Basic_color_stream_guard + * * Example usage: * \code - * auto guards = CGAL::make_color_guards(Color::Red, std::cout, std::cerr); + * auto guards = CGAL::IO::make_color_guards(CGAL::IO::Ansi_color::Red, std::cout, std::cerr); * std::cout << "Red output\n"; * std::cerr << "Red error\n"; * \endcode @@ -570,6 +586,8 @@ auto make_color_guards(Ansi_color color, Streams&... streams) { * \param colors Vector of colors to combine * \param streams The streams to apply colors to * \return A tuple of Basic_color_stream_guard objects + * + * \sa Basic_color_stream_guard */ template auto make_color_guards(const std::vector& colors, Streams&... streams) { @@ -587,7 +605,7 @@ auto make_color_guards(const std::vector& colors, Streams&... stream * 1. Verifies the stream is attached to a TTY device using `isatty()` * 2. Checks if the `TERM` environment variable indicates color support * 3. Respects the `NO_COLOR` environment variable (if set, colors are disabled) - * 4. On Windows, also checks for `ANSICON` environment variable + * 4. Respects the `CLICOLOR_FORCE` environment variable (if set, colors are enabled) * * \param stream The output stream to check (e.g., `std::cout`, `std::cerr`) * \return `true` if the stream supports color output, `false` otherwise @@ -596,10 +614,12 @@ auto make_color_guards(const std::vector& colors, Streams&... stream * never return false positives (it won't report color support where * it doesn't exist). * + * \sa Basic_color_streambuf + * * Example usage: * \code - * if(CGAL::stream_supports_color(std::cout)) { - * CGAL::Color_stream_guard guard(std::cout, CGAL::Ansi_color::Red); + * if(CGAL::IO::stream_supports_color(std::cout)) { + * CGAL::IO::Color_stream_guard guard(std::cout, CGAL::IO::Ansi_color::Red); * std::cout << "This text is red!\n"; * } else { * std::cout << "Plain text output\n"; diff --git a/Stream_support/include/CGAL/IO/Indenting_ostream.h b/Stream_support/include/CGAL/IO/Indenting_ostream.h index f3b8c38f4ef..bff5f78a985 100644 --- a/Stream_support/include/CGAL/IO/Indenting_ostream.h +++ b/Stream_support/include/CGAL/IO/Indenting_ostream.h @@ -13,6 +13,8 @@ // // // Author(s) : Laurent Rineau +// +// Documentation partially generated by Github Copilot #ifndef CGAL_IO_INDENTING_OSTREAM_H #define CGAL_IO_INDENTING_OSTREAM_H @@ -36,18 +38,21 @@ namespace IO { * * \tparam CharT Character type (typically `char` or `wchar_t`) * \tparam Traits Character traits type + * + * \sa Basic_indenting_stream_guard + * \sa make_indenting_guards */ template > class Basic_indenting_streambuf : public std::basic_streambuf, protected Traits { public: - using char_type = CharT; - using traits_type = Traits; - using int_type = typename traits_type::int_type; - using pos_type = typename traits_type::pos_type; - using off_type = typename traits_type::off_type; - using streambuf_type = std::basic_streambuf; - using string = std::basic_string; + using char_type = CharT; ///< Character type + using traits_type = Traits; ///< Character traits type + using int_type = typename traits_type::int_type; ///< Integer type for character representation + using pos_type = typename traits_type::pos_type; ///< Position type for stream positioning + using off_type = typename traits_type::off_type; ///< Offset type for stream positioning + using streambuf_type = std::basic_streambuf; ///< Type of the wrapped streambuf + using string = std::basic_string; ///< String type matching character type private: streambuf_type* wrapped_buf_; @@ -180,9 +185,11 @@ protected: } }; +/// \ingroup PkgStreamSupportRef /// Type alias for `Basic_indenting_streambuf` using Indenting_streambuf = Basic_indenting_streambuf; +/// \ingroup PkgStreamSupportRef /// Type alias for `Basic_indenting_streambuf` using Indenting_wstreambuf = Basic_indenting_streambuf; @@ -195,16 +202,20 @@ using Indenting_wstreambuf = Basic_indenting_streambuf; * It provides a convenient way to add indentation to output streams within a specific scope. * * \tparam StreamT The stream type (e.g., `std::ostream`, `std::wostream`) + * + * \sa Basic_indenting_streambuf + * \sa make_indenting_guards */ template class Basic_indenting_stream_guard { +public: + using char_type = typename StreamT::char_type; ///< Character type + using traits_type = typename StreamT::traits_type; ///< Character traits type + using streambuf_type = Basic_indenting_streambuf; ///< Type of the indenting streambuf + using wrapped_streambuf_type = std::basic_streambuf; ///< Type of the wrapped streambuf + using string = std::basic_string; ///< String type matching character type private: - using char_type = typename StreamT::char_type; - using traits_type = typename StreamT::traits_type; - using streambuf_type = Basic_indenting_streambuf; - using wrapped_streambuf_type = std::basic_streambuf; - using string = std::basic_string; StreamT& stream_; wrapped_streambuf_type* original_buf_; string original_indent_string_; @@ -273,9 +284,11 @@ public: } }; +/// \ingroup PkgStreamSupportRef /// Type alias for `basic_indenting_stream_guard` using Indenting_stream_guard = Basic_indenting_stream_guard; +/// \ingroup PkgStreamSupportRef /// Type alias for `basic_indenting_stream_guard` using Indenting_wstream_guard = Basic_indenting_stream_guard; @@ -294,9 +307,11 @@ using Indenting_wstream_guard = Basic_indenting_stream_guard; * \param streams The streams to apply indentation to * \return A tuple of Basic_indenting_stream_guard objects * + * \sa Basic_indenting_stream_guard + * * Example usage: * \code - * auto guards = CGAL::make_indenting_guards(2, std::cout, std::cerr); + * auto guards = CGAL::IO::make_indenting_guards(2, std::cout, std::cerr); * std::cout << "Indented output\n"; * std::cerr << "Indented error\n"; * \endcode @@ -318,6 +333,8 @@ auto make_indenting_guards(int spaces_per_level, Streams&... streams) { * \param indent_string The indentation string to use * \param streams The streams to apply indentation to * \return A tuple of Basic_indenting_stream_guard objects + * + * \sa Basic_indenting_stream_guard */ template auto make_indenting_guards(const std::string& indent_string, Streams&... streams) {