diff options
| author | Martin Hořeňovský | 2022-04-07 12:40:46 +0200 |
|---|---|---|
| committer | Martin Hořeňovský | 2022-04-07 12:50:18 +0200 |
| commit | 46b3f7ee5fa29c65e786abb180df15fff68ef1c1 (patch) | |
| tree | 7bf5515b8fbb8465d19b93a5f657e8cb7e70f9da | |
| parent | f9f4e58dfbec1da8fee63383d72e07d2fab87eb7 (diff) | |
| download | catch3-46b3f7ee5fa29c65e786abb180df15fff68ef1c1.tar.gz | |
Document magic %-prefixed streams
| -rw-r--r-- | docs/command-line.md | 18 | ||||
| -rw-r--r-- | src/catch2/internal/catch_stream.hpp | 11 |
2 files changed, 26 insertions, 3 deletions
diff --git a/docs/command-line.md b/docs/command-line.md index ec129159..f8ac6374 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -218,12 +218,24 @@ similar information. <pre>-o, --out <filename> </pre> -Use this option to send all output to a file. By default output is sent to stdout (note that uses of stdout and stderr *from within test cases* are redirected and included in the report - so even stderr will effectively end up on stdout). - -Using `-` as the filename sends the output to stdout. +Use this option to send all output to a file, instead of stdout. You can +use `-` as the filename to explicitly send the output to stdout (this is +useful e.g. when using multiple reporters). > Support for `-` as the filename was introduced in Catch2 X.Y.Z +Filenames starting with "%" (percent symbol) are reserved by Catch2 for +meta purposes, e.g. using `%debug` as the filename opens stream that +writes to platform specific debugging/logging mechanism. + +Catch2 currently recognizes 3 meta streams: + +* `%debug` - writes to platform specific debugging/logging output +* `%stdout` - writes to stdout +* `%stderr` - writes to stderr + +> Support for `%stdout` and `%stderr` was introduced in Catch2 X.Y.Z + <a id="naming-a-test-run"></a> ## Naming a test run diff --git a/src/catch2/internal/catch_stream.hpp b/src/catch2/internal/catch_stream.hpp index ba0a3876..41c1fef0 100644 --- a/src/catch2/internal/catch_stream.hpp +++ b/src/catch2/internal/catch_stream.hpp @@ -40,6 +40,17 @@ namespace Catch { virtual bool isConsole() const { return false; } }; + /** + * Creates a stream wrapper that writes to specific file. + * + * Also recognizes 4 special filenames + * * `-` for stdout + * * `%stdout` for stdout + * * `%stderr` for stderr + * * `%debug` for platform specific debugging output + * + * \throws if passed an unrecognized %-prefixed stream + */ auto makeStream( std::string const& filename ) -> Detail::unique_ptr<IStream const>; class ReusableStringStream : Detail::NonCopyable { |