1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

// Copyright (c) The enable-ansi-support Contributors
// SPDX-License-Identifier: MIT

//! Enable ANSI code support on Windows 10 and above.
//!
//! This crate provides one function, `enable_ansi_support`, which allows [ANSI escape codes]
//! to work on Windows 10 and above.
//!
//! Call `enable_ansi_support` *once*, early on in `main()`, to enable ANSI escape codes generated
//! by crates like
//! [`ansi_term`](https://docs.rs/ansi_term) or [`owo-colors`](https://docs.rs/owo-colors)
//! to work on Windows just like they do on Unix platforms.
//!
//! ## Examples
//!
//! ```rust
//! fn main() {
//!     match enable_ansi_support::enable_ansi_support() {
//!         Ok(()) => {
//!             // ANSI escape codes were successfully enabled, or this is a non-Windows platform.
//!         }
//!         Err(_) => {
//!             // The operation was unsuccessful, typically because it's running on an older
//!             // version of Windows. The program may choose to disable ANSI color code output in
//!             // this case.
//!         }
//!     }
//!
//!     // Use your terminal color library of choice here.
//! }
//! ```
//!
//! ## How it works
//!
//! `enable_ansi_support` uses Windows API calls to alter the properties of the console that
//! the program is running in. See the
//! [Windows documentation](https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences)
//! for more information.
//!
//! On non-Windows platforms, `enable_ansi_support` is a no-op.
//!
//! [ANSI escape codes]: https://en.wikipedia.org/wiki/ANSI_escape_code
#![allow(clippy::needless_doctest_main)]

/// Enables ANSI code support on Windows 10.
///
/// Returns the Windows error code if unsuccessful.
///
/// On non-Windows platforms, this is a no-op that always returns `Ok(())`.
///
/// # Examples
///
/// See the [crate documentation](crate).
#[cfg(windows)]
pub fn enable_ansi_support() -> Result<(), u32> {
    // ref: https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences#EXAMPLE_OF_ENABLING_VIRTUAL_TERMINAL_PROCESSING @@ https://archive.is/L7wRJ#76%

    use std::{ffi::OsStr, iter::once, os::windows::ffi::OsStrExt, ptr::null_mut};
    use winapi::um::{
        consoleapi::{GetConsoleMode, SetConsoleMode},
        errhandlingapi::GetLastError,
        fileapi::{CreateFileW, OPEN_EXISTING},
        handleapi::INVALID_HANDLE_VALUE,
        winnt::{FILE_SHARE_WRITE, GENERIC_READ, GENERIC_WRITE},
    };

    const ENABLE_VIRTUAL_TERMINAL_PROCESSING: u32 = 0x0004;

    unsafe {
        // ref: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew
        // Using `CreateFileW("CONOUT$", ...)` to retrieve the console handle works correctly even if STDOUT and/or STDERR are redirected
        let console_out_name: Vec<u16> =
            OsStr::new("CONOUT$").encode_wide().chain(once(0)).collect();
        let console_handle = CreateFileW(
            console_out_name.as_ptr(),
            GENERIC_READ | GENERIC_WRITE,
            FILE_SHARE_WRITE,
            null_mut(),
            OPEN_EXISTING,
            0,
            null_mut(),
        );
        if console_handle == INVALID_HANDLE_VALUE {
            return Err(GetLastError());
        }

        // ref: https://docs.microsoft.com/en-us/windows/console/getconsolemode
        let mut console_mode: u32 = 0;
        if 0 == GetConsoleMode(console_handle, &mut console_mode) {
            return Err(GetLastError());
        }

        // VT processing not already enabled?
        if console_mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING == 0 {
            // https://docs.microsoft.com/en-us/windows/console/setconsolemode
            if 0 == SetConsoleMode(
                console_handle,
                console_mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING,
            ) {
                return Err(GetLastError());
            }
        }
    }

    Ok(())
}

/// Enables ANSI code support on Windows 10.
///
/// Returns the Windows error code if unsuccessful.
///
/// On non-Windows platforms, this is a no-op that always returns `Ok(())`.
///
/// # Examples
///
/// See the [crate documentation](crate).
#[cfg(not(windows))]
#[inline]
pub fn enable_ansi_support() -> Result<(), u32> {
    Ok(())
}