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

summaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorMartin Hořeňovský2022-03-27 23:35:41 +0200
committerMartin Hořeňovský2022-03-28 13:10:13 +0200
commit1a8a793178d50b74b0f9a0adb3eec937b61039a9 (patch)
tree2a8cadf3fa4478f1a11548485a4a0389d4920d2d /docs
parenta4e4e82474f894d56cbe86e13a2d23bb1b46744d (diff)
downloadcatch3-1a8a793178d50b74b0f9a0adb3eec937b61039a9.tar.gz
Refactor colour handling to prepare for per-reporter colour modes
This includes always compiling the ANSI and None colour implementations, as they don't need to touch any platform specific APIs, and removing their respective compile-time configuration options. Because the Win32 colour implementation requires Win32-specific APIs, it is still hidden behind a compile-time toggle, `CATCH_CONFIG_COLOUR_WIN32` (renamed from `..._COLOUR_WINDOWS`). The commandline options for colours were also changed. The option now uses different name, and allows to select between different implementations, rather than changing whether the compiled-in colour implementation is used through "yes/no/default" options.
Diffstat (limited to 'docs')
-rw-r--r--docs/command-line.md26
-rw-r--r--docs/configuration.md17
-rw-r--r--docs/release-notes.md7
3 files changed, 33 insertions, 17 deletions
diff --git a/docs/command-line.md b/docs/command-line.md
index 7ace0530..29e6a365 100644
--- a/docs/command-line.md
+++ b/docs/command-line.md
@@ -67,7 +67,7 @@ Click one of the following links to take you straight to that option - or scroll
<a href="#benchmark-confidence-interval"> ` --benchmark-confidence-interval`</a><br />
<a href="#benchmark-no-analysis"> ` --benchmark-no-analysis`</a><br />
<a href="#benchmark-warmup-time"> ` --benchmark-warmup-time`</a><br />
-<a href="#use-colour"> ` --use-colour`</a><br />
+<a href="#colour-mode"> ` --colour-mode`</a><br />
<a href="#test-sharding"> ` --shard-count`</a><br />
<a href="#test-sharding"> ` --shard-index`</a><br />
<a href=#no-tests-override> ` --allow-running-no-tests`</a><br />
@@ -457,16 +457,26 @@ filename it is found in, with any extension stripped, prefixed with the `#` char
So, for example, tests within the file `~\Dev\MyProject\Ferrets.cpp` would be tagged `[#Ferrets]`.
-<a id="use-colour"></a>
+<a id="colour-mode"></a>
## Override output colouring
-<pre>--use-colour &lt;yes|no|auto&gt;</pre>
+<pre>--colour-mode &lt;ansi|win32|none|default&gt;</pre>
-Catch colours output for terminals, but omits colouring when it detects that
-output is being sent to a pipe. This is done to avoid interfering with automated
-processing of output.
+Catch2 support two different ways of colouring terminal output, and by
+default it attempts to make a good guess on which implementation to use
+(and whether to even use it, e.g. Catch2 tries to avoid writing colour
+codes when writing the results into a file).
+
+`--colour-mode` allows the user to explicitly select what happens.
+
+* `--colour-mode ansi` tells Catch2 to always use ANSI colour codes, even
+when writing to a file
+* `--colour-mode win32` tells Catch2 to use colour implementation based
+ on Win32 terminal API
+* `--colour-mode none` tells Catch2 to disable colours completely
+* `--colour-mode default` lets Catch2 decide
+
+`--colour-mode default` is the default setting.
-`--use-colour yes` forces coloured output, `--use-colour no` disables coloured
-output. The default behaviour is `--use-colour auto`.
<a id="test-sharding"></a>
## Test Sharding
diff --git a/docs/configuration.md b/docs/configuration.md
index a7db4b13..5105f6d9 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -31,19 +31,18 @@ To keep test code clean and uncluttered Catch uses short macro names (e.g. ```TE
## Terminal colour
- CATCH_CONFIG_COLOUR_NONE // completely disables all text colouring
- CATCH_CONFIG_COLOUR_WINDOWS // forces the Win32 console API to be used
- CATCH_CONFIG_COLOUR_ANSI // forces ANSI colour codes to be used
+ CATCH_CONFIG_COLOUR_WIN32 // Force enables compiling colouring impl based on Win32 console API
+ CATCH_CONFIG_NO_COLOUR_WIN32 // Force disables ...
-Yes, I am English, so I will continue to spell "colour" with a 'u'.
+Yes, Catch2 uses the british spelling of colour.
-When sending output to the terminal, if it detects that it can, Catch will use colourised text. On Windows the Win32 API, ```SetConsoleTextAttribute```, is used. On POSIX systems ANSI colour escape codes are inserted into the stream.
+Catch2 attempts to autodetect whether the Win32 console colouring API,
+`SetConsoleTextAttribute`, is available, and if it is available it compiles
+in a console colouring implementation that uses it.
-For finer control you can define one of the above identifiers (these are mutually exclusive - but that is not checked so may behave unexpectedly if you mix them):
+This option can be used to override Catch2's autodetection and force the
+compilation either ON or OFF.
-Note that when ANSI colour codes are used "unistd.h" must be includable - along with a definition of ```isatty()```
-
-Typically you should place the ```#define``` before #including "catch.hpp" in your main source file - but if you prefer you can define it for your whole project by whatever your IDE or build system provides for you to do so.
## Console width
diff --git a/docs/release-notes.md b/docs/release-notes.md
index 60f38b77..ca64106e 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -179,6 +179,13 @@ v3 releases.
* To support this, the `-r`, `--reporter` flag now also accepts optional output destination
* For full overview of the semantics of using multiple reporters, look into the reporter documentation
* To enable the new syntax, reporter names can no longer contain `::`.
+* Console colour support has been rewritten and significantly improved
+ * The colour implementation based on ANSI colour codes is always available
+ * Colour implementations respect their associated stream
+ * previously e.g. Win32 impl would change console colour even if Catch2 was writing to a file
+ * The colour API is resilient against changing evaluation order of expressions
+ * The associated CLI flag and compile-time configuration options have changed
+ * For details see the docs for command-line and compile-time Catch2 configuration
### Fixes