Stream_support: add indenting and coloring stream wrappers

[lrineau]

Summary of Changes

Stream_support: add indenting and coloring stream wrappers

See the test examples.

Indenting

Example:

=== Basic Indenting Usage ===

1. Basic indentation with std::cout:
  This line is indented
  So is this one
  Multi-line output:
  Line 1
  Line 2
  Line 3
Back to normal indentation

2. Nested indentation levels:
| Level 1 indentation
| | Level 2 indentation
| | | Level 3 indentation
| | Back to level 2
| Back to level 1
Back to normal

3. Custom indentation string:
>>> Custom prefix on each line
>>> Works with multiple lines too
Normal output again

Coloring

Example:

Todo

• Write a paragraph in the User Manual

Release Management

• Affected package(s): Stream_support
• Feature/Small Feature (if any): TODO
• Link to compiled documentation (obligatory for small feature) wrong link name to be changed
• License and copyright ownership: unchanged

[Copilot]

Pull Request Overview

This PR adds new stream formatting capabilities to CGAL's Stream_support package, introducing automatic indentation and ANSI color support for output streams. The changes enhance debugging and logging functionality with RAII-based stream wrappers that automatically restore original state.

• Adds Basic_indenting_streambuf and Basic_color_streambuf classes that wrap existing streambufs to add indentation and color codes
• Implements RAII guard classes for scoped stream formatting with automatic restoration
• Includes automatic color terminal detection respecting NO_COLOR and CLICOLOR_FORCE environment variables

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
Stream_support/include/CGAL/IO/Indenting_ostream.h	New header implementing indenting streambuf wrapper and RAII guard class
Stream_support/include/CGAL/IO/Color_ostream.h	New header implementing color streambuf wrapper with ANSI color support and terminal detection
Stream_support/examples/Stream_support/indenting_ostream.cpp	Example demonstrating indenting stream functionality
Stream_support/examples/Stream_support/color_ostream.cpp	Example demonstrating color stream functionality
Stream_support/examples/Stream_support/CMakeLists.txt	Adds new example programs to build
Stream_support/doc/Stream_support/examples.txt	Registers new examples in documentation
Stream_support/doc/Stream_support/PackageDescription.txt	Documents new classes and functions in package reference
Installation/include/CGAL/config.h	Adds support for __STDC_WANT_LIB_EXT1__ for secure getenv_s

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lrineau]

/force-build:v1

[github-actions]

The documentation is built. It will be available, after a few minutes, here: https://cgal.github.io/9115/v1/Manual/index.html

[afabri]

Maybe even manipulators would be practical, but one then has the problem to distinguish from a color information to write.

[afabri]

Warning in testsuite CGAL-6.2-Ic-48CGAL-6.2-Ic-48

Color_ostream.h(149,30): warning C4996: 'getenv': This function or variable may be unsafe. Consider using _dupenv_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.

[afabri]

Is it necessary to document all classes? Isn't Basic_indenting_streambuf juxst an implementation detail?

[lrineau]

Is it necessary to document all classes? Isn't Basic_indenting_streambuf juxst an implementation detail?

That is right. I documented as the STL documented the stream classes. Should I hide the streambuf?

[afabri]

I would document what is needed from a user perspective, and I think as a user I would not need the stream buffer class.

[sloriot]

Successfully tested in CGAL-6.2-Ic-53