Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorMartin Hořeňovský2022-04-07 12:40:46 +0200
committerMartin Hořeňovský2022-04-07 12:50:18 +0200
commit46b3f7ee5fa29c65e786abb180df15fff68ef1c1 (patch)
tree7bf5515b8fbb8465d19b93a5f657e8cb7e70f9da
parentf9f4e58dfbec1da8fee63383d72e07d2fab87eb7 (diff)
downloadcatch3-46b3f7ee5fa29c65e786abb180df15fff68ef1c1.tar.gz
Document magic %-prefixed streams
-rw-r--r--docs/command-line.md18
-rw-r--r--src/catch2/internal/catch_stream.hpp11
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 &lt;filename&gt;
</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 {