Rename isStdout => isConsole and add doccomment

src/catch2/internal/catch_console_colour.cpp

@@ -97,7 +97,7 @@ namespace {
             // Win32 text colour APIs can only be used on console streams
             // We cannot check that the output hasn't been redirected,
             // so we just check that the original stream is console stream.
-            return stream.isStdout();
+            return stream.isConsole();
         }
 
     private:
@@ -164,7 +164,7 @@ namespace {
             // only want to use the colours if we are writing to console.
             // However, console might be redirected, so we make an attempt at
             // checking for that on platforms where we know how to do that.
-            bool useColour = stream.isStdout();
+            bool useColour = stream.isConsole();
 #if defined( CATCH_INTERNAL_HAS_ISATTY ) && \
     !( defined( __DJGPP__ ) && defined( __STRICT_ANSI__ ) )
             ErrnoGuard _; // for isatty

src/catch2/internal/catch_stream.cpp

@@ -99,7 +99,7 @@ namespace Detail {
 
         public: // IStream
             std::ostream& stream() const override { return m_os; }
-            bool isStdout() const override { return true; }
+            bool isConsole() const override { return true; }
         };
 
         class CerrStream : public IStream {
@@ -113,7 +113,7 @@ namespace Detail {
 
         public: // IStream
             std::ostream& stream() const override { return m_os; }
-            bool isStdout() const override { return true; }
+            bool isConsole() const override { return true; }
         };
 
         ///////////////////////////////////////////////////////////////////////////

src/catch2/internal/catch_stream.hpp

@@ -26,9 +26,18 @@ namespace Catch {
     public:
         virtual ~IStream(); // = default
         virtual std::ostream& stream() const = 0;
-        // Win32 colour supports requires us to identify whether a stream
+        /**
-        // is backed by stdout (so we can colour it) or not (and we can't).
+         * Best guess on whether the instance is writing to a console (e.g. via stdout/stderr)
-        virtual bool isStdout() const { return false;  }
+         *
+         * This is useful for e.g. Win32 colour support, because the Win32
+         * API manipulates console directly, unlike POSIX escape codes,
+         * that can be written anywhere.
+         *
+         * Due to variety of ways to change where the stdout/stderr is
+         * _actually_ being written, users should always assume that
+         * the answer might be wrong.
+         */
+        virtual bool isConsole() const { return false; }
     };
 
     auto makeStream( std::string const& filename ) -> Detail::unique_ptr<IStream const>;

tests/SelfTest/Baselines/compact.sw.approved.txt

@@ -479,7 +479,7 @@ Generators.tests.cpp:<line number>: passed: elem % 2 == 1 for: 1 == 1
 Generators.tests.cpp:<line number>: passed: elem % 2 == 1 for: 1 == 1
 Generators.tests.cpp:<line number>: passed: call_count == 1 for: 1 == 1
 Generators.tests.cpp:<line number>: passed: make_data().size() == test_count for: 6 == 6
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "-" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "-" )->isConsole() for: true
 Exception.tests.cpp:<line number>: failed: unexpected exception with message: 'custom exception - not std'; expression was: throwCustom()
 Exception.tests.cpp:<line number>: failed: unexpected exception with message: 'custom exception - not std'; expression was: throwCustom(), std::exception
 Exception.tests.cpp:<line number>: failed: unexpected exception with message: 'custom std exception'
@@ -490,7 +490,7 @@ ToString.tests.cpp:<line number>: passed: enumInfo->lookup(1) == "Value2" for: V
 ToString.tests.cpp:<line number>: passed: enumInfo->lookup(3) == "{** unexpected enum value **}" for: {** unexpected enum value **}
 ==
 "{** unexpected enum value **}"
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "" )->isConsole() for: true
 Tag.tests.cpp:<line number>: passed: Catch::TestCaseInfo( "", { "fake test name", "[]" }, dummySourceLineInfo )
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), EndsWith( "Substring" ) for: "this string contains 'abc' as a substring" ends with: "Substring"
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), EndsWith( "this", Catch::CaseSensitive::No ) for: "this string contains 'abc' as a substring" ends with: "this" (case insensitive)
@@ -2368,8 +2368,8 @@ ToStringGeneral.tests.cpp:<line number>: passed: Catch::Detail::stringify( set )
 ToStringPair.tests.cpp:<line number>: passed: ::Catch::Detail::stringify( pr ) == "{ { \"green\", 55 } }" for: "{ { "green", 55 } }"
 ==
 "{ { "green", 55 } }"
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stderr" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stderr" )->isConsole() for: true
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stdout" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stdout" )->isConsole() for: true
 ToStringWhich.tests.cpp:<line number>: passed: ::Catch::Detail::stringify(streamable_range{}) == "op<<(streamable_range)" for: "op<<(streamable_range)"
 ==
 "op<<(streamable_range)"

tests/SelfTest/Baselines/compact.sw.multi.approved.txt

@@ -477,7 +477,7 @@ Generators.tests.cpp:<line number>: passed: elem % 2 == 1 for: 1 == 1
 Generators.tests.cpp:<line number>: passed: elem % 2 == 1 for: 1 == 1
 Generators.tests.cpp:<line number>: passed: call_count == 1 for: 1 == 1
 Generators.tests.cpp:<line number>: passed: make_data().size() == test_count for: 6 == 6
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "-" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "-" )->isConsole() for: true
 Exception.tests.cpp:<line number>: failed: unexpected exception with message: 'custom exception - not std'; expression was: throwCustom()
 Exception.tests.cpp:<line number>: failed: unexpected exception with message: 'custom exception - not std'; expression was: throwCustom(), std::exception
 Exception.tests.cpp:<line number>: failed: unexpected exception with message: 'custom std exception'
@@ -488,7 +488,7 @@ ToString.tests.cpp:<line number>: passed: enumInfo->lookup(1) == "Value2" for: V
 ToString.tests.cpp:<line number>: passed: enumInfo->lookup(3) == "{** unexpected enum value **}" for: {** unexpected enum value **}
 ==
 "{** unexpected enum value **}"
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "" )->isConsole() for: true
 Tag.tests.cpp:<line number>: passed: Catch::TestCaseInfo( "", { "fake test name", "[]" }, dummySourceLineInfo )
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), EndsWith( "Substring" ) for: "this string contains 'abc' as a substring" ends with: "Substring"
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), EndsWith( "this", Catch::CaseSensitive::No ) for: "this string contains 'abc' as a substring" ends with: "this" (case insensitive)
@@ -2360,8 +2360,8 @@ ToStringGeneral.tests.cpp:<line number>: passed: Catch::Detail::stringify( set )
 ToStringPair.tests.cpp:<line number>: passed: ::Catch::Detail::stringify( pr ) == "{ { \"green\", 55 } }" for: "{ { "green", 55 } }"
 ==
 "{ { "green", 55 } }"
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stderr" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stderr" )->isConsole() for: true
-Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stdout" )->isStdout() for: true
+Stream.tests.cpp:<line number>: passed: Catch::makeStream( "%stdout" )->isConsole() for: true
 ToStringWhich.tests.cpp:<line number>: passed: ::Catch::Detail::stringify(streamable_range{}) == "op<<(streamable_range)" for: "op<<(streamable_range)"
 ==
 "op<<(streamable_range)"

tests/SelfTest/Baselines/console.sw.approved.txt

@@ -3812,7 +3812,7 @@ Stream.tests.cpp:<line number>
 ...............................................................................
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "-" )->isStdout() )
+  REQUIRE( Catch::makeStream( "-" )->isConsole() )
 with expansion:
   true
 
@@ -3894,7 +3894,7 @@ Stream.tests.cpp:<line number>
 ...............................................................................
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "" )->isStdout() )
+  REQUIRE( Catch::makeStream( "" )->isConsole() )
 with expansion:
   true
 
@@ -16859,12 +16859,12 @@ Stream.tests.cpp:<line number>
 ...............................................................................
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "%stderr" )->isStdout() )
+  REQUIRE( Catch::makeStream( "%stderr" )->isConsole() )
 with expansion:
   true
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "%stdout" )->isStdout() )
+  REQUIRE( Catch::makeStream( "%stdout" )->isConsole() )
 with expansion:
   true
 

tests/SelfTest/Baselines/console.sw.multi.approved.txt

@@ -3810,7 +3810,7 @@ Stream.tests.cpp:<line number>
 ...............................................................................
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "-" )->isStdout() )
+  REQUIRE( Catch::makeStream( "-" )->isConsole() )
 with expansion:
   true
 
@@ -3892,7 +3892,7 @@ Stream.tests.cpp:<line number>
 ...............................................................................
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "" )->isStdout() )
+  REQUIRE( Catch::makeStream( "" )->isConsole() )
 with expansion:
   true
 
@@ -16851,12 +16851,12 @@ Stream.tests.cpp:<line number>
 ...............................................................................
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "%stderr" )->isStdout() )
+  REQUIRE( Catch::makeStream( "%stderr" )->isConsole() )
 with expansion:
   true
 
 Stream.tests.cpp:<line number>: PASSED:
-  REQUIRE( Catch::makeStream( "%stdout" )->isStdout() )
+  REQUIRE( Catch::makeStream( "%stdout" )->isConsole() )
 with expansion:
   true
 

tests/SelfTest/Baselines/tap.sw.approved.txt

@@ -957,7 +957,7 @@ ok {test-number} - call_count == 1 for: 1 == 1
 # Copy and then generate a range
 ok {test-number} - make_data().size() == test_count for: 6 == 6
 # Cout stream properly declares it writes to stdout
-ok {test-number} - Catch::makeStream( "-" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "-" )->isConsole() for: true
 # Custom exceptions can be translated when testing for nothrow
 not ok {test-number} - unexpected exception with message: 'custom exception - not std'; expression was: throwCustom()
 # Custom exceptions can be translated when testing for throwing as something else
@@ -975,7 +975,7 @@ ok {test-number} - enumInfo->lookup(1) == "Value2" for: Value2 == "Value2"
 # Directly creating an EnumInfo
 ok {test-number} - enumInfo->lookup(3) == "{** unexpected enum value **}" for: {** unexpected enum value **} == "{** unexpected enum value **}"
 # Empty stream name opens cout stream
-ok {test-number} - Catch::makeStream( "" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "" )->isConsole() for: true
 # Empty tag is not allowed
 ok {test-number} - Catch::TestCaseInfo( "", { "fake test name", "[]" }, dummySourceLineInfo )
 # EndsWith string matcher
@@ -4245,9 +4245,9 @@ ok {test-number} - Catch::Detail::stringify( set ) == "{ \"abc\", \"def\", \"ghi
 # std::vector<std::pair<std::string,int> > -> toString
 ok {test-number} - ::Catch::Detail::stringify( pr ) == "{ { \"green\", 55 } }" for: "{ { "green", 55 } }" == "{ { "green", 55 } }"
 # stdout and stderr streams have %-starting name
-ok {test-number} - Catch::makeStream( "%stderr" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "%stderr" )->isConsole() for: true
 # stdout and stderr streams have %-starting name
-ok {test-number} - Catch::makeStream( "%stdout" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "%stdout" )->isConsole() for: true
 # stringify ranges
 ok {test-number} - ::Catch::Detail::stringify(streamable_range{}) == "op<<(streamable_range)" for: "op<<(streamable_range)" == "op<<(streamable_range)"
 # stringify ranges

tests/SelfTest/Baselines/tap.sw.multi.approved.txt

@@ -955,7 +955,7 @@ ok {test-number} - call_count == 1 for: 1 == 1
 # Copy and then generate a range
 ok {test-number} - make_data().size() == test_count for: 6 == 6
 # Cout stream properly declares it writes to stdout
-ok {test-number} - Catch::makeStream( "-" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "-" )->isConsole() for: true
 # Custom exceptions can be translated when testing for nothrow
 not ok {test-number} - unexpected exception with message: 'custom exception - not std'; expression was: throwCustom()
 # Custom exceptions can be translated when testing for throwing as something else
@@ -973,7 +973,7 @@ ok {test-number} - enumInfo->lookup(1) == "Value2" for: Value2 == "Value2"
 # Directly creating an EnumInfo
 ok {test-number} - enumInfo->lookup(3) == "{** unexpected enum value **}" for: {** unexpected enum value **} == "{** unexpected enum value **}"
 # Empty stream name opens cout stream
-ok {test-number} - Catch::makeStream( "" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "" )->isConsole() for: true
 # Empty tag is not allowed
 ok {test-number} - Catch::TestCaseInfo( "", { "fake test name", "[]" }, dummySourceLineInfo )
 # EndsWith string matcher
@@ -4237,9 +4237,9 @@ ok {test-number} - Catch::Detail::stringify( set ) == "{ \"abc\", \"def\", \"ghi
 # std::vector<std::pair<std::string,int> > -> toString
 ok {test-number} - ::Catch::Detail::stringify( pr ) == "{ { \"green\", 55 } }" for: "{ { "green", 55 } }" == "{ { "green", 55 } }"
 # stdout and stderr streams have %-starting name
-ok {test-number} - Catch::makeStream( "%stderr" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "%stderr" )->isConsole() for: true
 # stdout and stderr streams have %-starting name
-ok {test-number} - Catch::makeStream( "%stdout" )->isStdout() for: true
+ok {test-number} - Catch::makeStream( "%stdout" )->isConsole() for: true
 # stringify ranges
 ok {test-number} - ::Catch::Detail::stringify(streamable_range{}) == "op<<(streamable_range)" for: "op<<(streamable_range)" == "op<<(streamable_range)"
 # stringify ranges

tests/SelfTest/Baselines/xml.sw.approved.txt

@@ -4208,7 +4208,7 @@ Nor would this
   <TestCase name="Cout stream properly declares it writes to stdout" tags="[streams]" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "-" )->isStdout()
+        Catch::makeStream( "-" )->isConsole()
       </Original>
       <Expanded>
         true
@@ -4301,7 +4301,7 @@ Nor would this
   <TestCase name="Empty stream name opens cout stream" tags="[streams]" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "" )->isStdout()
+        Catch::makeStream( "" )->isConsole()
       </Original>
       <Expanded>
         true
@@ -19885,7 +19885,7 @@ loose text artifact
   <TestCase name="stdout and stderr streams have %-starting name" tags="[streams]" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "%stderr" )->isStdout()
+        Catch::makeStream( "%stderr" )->isConsole()
       </Original>
       <Expanded>
         true
@@ -19893,7 +19893,7 @@ loose text artifact
     </Expression>
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "%stdout" )->isStdout()
+        Catch::makeStream( "%stdout" )->isConsole()
       </Original>
       <Expanded>
         true

tests/SelfTest/Baselines/xml.sw.multi.approved.txt

@@ -4208,7 +4208,7 @@ Nor would this
   <TestCase name="Cout stream properly declares it writes to stdout" tags="[streams]" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "-" )->isStdout()
+        Catch::makeStream( "-" )->isConsole()
       </Original>
       <Expanded>
         true
@@ -4301,7 +4301,7 @@ Nor would this
   <TestCase name="Empty stream name opens cout stream" tags="[streams]" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "" )->isStdout()
+        Catch::makeStream( "" )->isConsole()
       </Original>
       <Expanded>
         true
@@ -19884,7 +19884,7 @@ There is no extra whitespace here
   <TestCase name="stdout and stderr streams have %-starting name" tags="[streams]" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "%stderr" )->isStdout()
+        Catch::makeStream( "%stderr" )->isConsole()
       </Original>
       <Expanded>
         true
@@ -19892,7 +19892,7 @@ There is no extra whitespace here
     </Expression>
     <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/Stream.tests.cpp" >
       <Original>
-        Catch::makeStream( "%stdout" )->isStdout()
+        Catch::makeStream( "%stdout" )->isConsole()
       </Original>
       <Expanded>
         true

tests/SelfTest/IntrospectiveTests/Stream.tests.cpp

@@ -11,16 +11,16 @@
 #include <catch2/internal/catch_stream.hpp>
 
 TEST_CASE( "Cout stream properly declares it writes to stdout", "[streams]" ) {
-    REQUIRE( Catch::makeStream( "-" )->isStdout() );
+    REQUIRE( Catch::makeStream( "-" )->isConsole() );
 }
 
 TEST_CASE( "Empty stream name opens cout stream", "[streams]" ) {
-    REQUIRE( Catch::makeStream( "" )->isStdout() );
+    REQUIRE( Catch::makeStream( "" )->isConsole() );
 }
 
 TEST_CASE( "stdout and stderr streams have %-starting name", "[streams]" ) {
-    REQUIRE( Catch::makeStream( "%stderr" )->isStdout() );
+    REQUIRE( Catch::makeStream( "%stderr" )->isConsole() );
-    REQUIRE( Catch::makeStream( "%stdout" )->isStdout() );
+    REQUIRE( Catch::makeStream( "%stdout" )->isConsole() );
 }
 
 TEST_CASE( "request an unknown %-starting stream fails", "[streams]" ) {