-
+# atty
-
+> are you or are you not a tty?
-As of Rust 1.70, most users should use the [`IsTerminal`] trait in the Rust
-standard library instead of this crate.
-On Unix platforms, this crate now uses libc, so that the implementation
-matches what's in std. Users wishing to use the rustix-based implementation
-can use the [rustix-is-terminal] crate instead.
+## install
-[rustix-is-terminal]: https://crates.io/crates/rustix-is-terminal
+Add the following to your `Cargo.toml`
-is-terminal
+# atty
- - Test whether a given stream is a terminal -
+[](https://travis-ci.org/softprops/atty) [](https://ci.appveyor.com/project/softprops/atty) [](https://coveralls.io/github/softprops/atty?branch=master) [](https://crates.io/crates/atty) [](http://docs.rs/atty) [](https://softprops.github.io/atty) -
- 
- 
- 
-
- -is-terminal is a simple utility that answers one question: - -> Is this a terminal? - -A "terminal", also known as a "tty", is an I/O device which may be interactive -and may support color and other special features. This crate doesn't provide -any of those features; it just answers this one question. - -On Unix-family platforms, this is effectively the same as the [`isatty`] -function for testing whether a given stream is a terminal, though it accepts -high-level stream types instead of raw file descriptors. - -On Windows, it uses a variety of techniques to determine whether the given -stream is a terminal. - -This crate is derived from [the atty crate] with [PR \#51] bug fix and -[PR \#54] port to windows-sys applied. The only additional difference is that -the atty crate only accepts stdin, stdout, or stderr, while this crate accepts -any stream. In particular, this crate does not access any stream that is not -passed to it, in accordance with [I/O safety]. - -[PR \#51]: https://github.com/softprops/atty/pull/51 -[PR \#54]: https://github.com/softprops/atty/pull/54 +```toml +[dependencies] +atty = "0.2" +``` -## Example +## usage ```rust -use is_terminal::IsTerminal; +use atty::Stream; fn main() { - if std::io::stdout().is_terminal() { - println!("Stdout is a terminal"); - } else { - println!("Stdout is not a terminal"); - } + if atty::is(Stream::Stdout) { + println!("I'm a terminal"); + } else { + println!("I'm not"); + } } ``` -## Testing +## testing + +This library has been unit tested on both unix and windows platforms (via appveyor). + -This library is tested on both Unix-family and Windows platforms. +A simple example program is provided in this repo to test various tty's. By default. -To test it on a platform manually, use the provided `stdio` example program. -When run normally, it prints this: +It prints ```bash -$ cargo run --example stdio -stdin? true +$ cargo run --example atty stdout? true stderr? true +stdin? true ``` -To test stdin, pipe some text to the program: +To test std in, pipe some text to the program ```bash -$ cat | cargo run --example stdio -stdin? false +$ echo "test" | cargo run --example atty stdout? true stderr? true +stdin? false ``` -To test stdout, pipe the program to something: +To test std out, pipe the program to something ```bash -$ cargo run --example stdio | cat -stdin? true +$ cargo run --example atty | grep std stdout? false stderr? true +stdin? true ``` -To test stderr, pipe the program to something redirecting stderr: +To test std err, pipe the program to something redirecting std err ```bash -$ cargo run --example stdio 2>&1 | cat -stdin? true +$ cargo run --example atty 2>&1 | grep std stdout? false stderr? false +stdin? true ``` -# Minimum Supported Rust Version (MSRV) - -This crate currently works on the version of [Rust on Debian stable], which is -currently Rust 1.63. This policy may change in the future, in minor version -releases, so users using a fixed version of Rust should pin to a specific -version of this crate. - -[`isatty`]: https://man7.org/linux/man-pages/man3/isatty.3.html -[the atty crate]: https://crates.io/crates/atty -[I/O safety]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md -[Rust on Debian stable]: https://packages.debian.org/stable/rust/rustc -[`IsTerminal`]: https://doc.rust-lang.org/stable/std/io/trait.IsTerminal.html +Doug Tangren (softprops) 2015-2019 diff --git a/appveyor.yml b/appveyor.yml new file mode 100644 index 0000000..d7fb127 --- /dev/null +++ b/appveyor.yml @@ -0,0 +1,16 @@ +environment: + matrix: + - TARGET: nightly-x86_64-pc-windows-msvc + - TARGET: nightly-i686-pc-windows-msvc + - TARGET: nightly-x86_64-pc-windows-gnu + - TARGET: nightly-i686-pc-windows-gnu +install: + - ps: Start-FileDownload "https://static.rust-lang.org/dist/rust-${env:TARGET}.exe" -FileName "rust-install.exe" + - ps: .\rust-install.exe /VERYSILENT /NORESTART /DIR="C:\rust" | Out-Null + - ps: $env:PATH="$env:PATH;C:\rust\bin" + - call "%VCVARS%" || ver>nul + - rustc -vV + - cargo -vV +build: false +test_script: + - cargo build diff --git a/examples/atty.rs b/examples/atty.rs new file mode 100644 index 0000000..3b3635e --- /dev/null +++ b/examples/atty.rs @@ -0,0 +1,9 @@ +extern crate atty; + +use atty::{is, Stream}; + +fn main() { + println!("stdout? {}", is(Stream::Stdout)); + println!("stderr? {}", is(Stream::Stderr)); + println!("stdin? {}", is(Stream::Stdin)); +} diff --git a/examples/stdio.rs b/examples/stdio.rs deleted file mode 100644 index f895635..0000000 --- a/examples/stdio.rs +++ /dev/null @@ -1,7 +0,0 @@ -use is_terminal::IsTerminal; - -fn main() { - println!("stdin? {}", std::io::stdin().is_terminal()); - println!("stdout? {}", std::io::stdout().is_terminal()); - println!("stderr? {}", std::io::stderr().is_terminal()); -} diff --git a/rustfmt.toml b/rustfmt.toml new file mode 100644 index 0000000..899a094 --- /dev/null +++ b/rustfmt.toml @@ -0,0 +1,4 @@ +# https://github.com/rust-lang/rustfmt/blob/master/Configurations.md#fn_args_layout +fn_args_layout = "Vertical" +# https://github.com/rust-lang/rustfmt/blob/master/Configurations.md#merge_imports +merge_imports = true \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index fda959c..418f617 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,154 +1,126 @@ -//! is-terminal is a simple utility that answers one question: +//! atty is a simple utility that answers one question +//! > is this a tty? //! -//! > Is this a terminal? +//! usage is just as simple //! -//! A "terminal", also known as a "tty", is an I/O device which may be -//! interactive and may support color and other special features. This crate -//! doesn't provide any of those features; it just answers this one question. -//! -//! On Unix-family platforms, this is effectively the same as the [`isatty`] -//! function for testing whether a given stream is a terminal, though it -//! accepts high-level stream types instead of raw file descriptors. -//! -//! On Windows, it uses a variety of techniques to determine whether the -//! given stream is a terminal. -//! -//! # Example -//! -//! ```rust -//! use is_terminal::IsTerminal; -//! -//! if std::io::stdout().is_terminal() { -//! println!("stdout is a terminal") +//! ``` +//! if atty::is(atty::Stream::Stdout) { +//! println!("i'm a tty") //! } //! ``` //! -//! [`isatty`]: https://man7.org/linux/man-pages/man3/isatty.3.html +//! ``` +//! if atty::isnt(atty::Stream::Stdout) { +//! println!("i'm not a tty") +//! } +//! ``` -#![cfg_attr( - not(any( - unix, - windows, - target_os = "wasi", - target_os = "hermit", - target_os = "unknown" - )), - no_std -)] +#![cfg_attr(unix, no_std)] -#[cfg(target_os = "wasi")] -use std::os::fd::{AsFd, AsRawFd}; -#[cfg(target_os = "hermit")] -use std::os::hermit::io::AsFd; #[cfg(unix)] -use std::os::unix::io::{AsFd, AsRawFd}; +extern crate libc; #[cfg(windows)] -use std::os::windows::io::{AsHandle, AsRawHandle, BorrowedHandle}; +extern crate windows_sys; + #[cfg(windows)] -use windows_sys::Win32::Foundation::HANDLE; +use windows_sys::Win32::System::Console::STD_HANDLE; -/// Extension trait to check whether something is a terminal. -pub trait IsTerminal { - /// Returns true if this is a terminal. - /// - /// # Example - /// - /// ``` - /// use is_terminal::IsTerminal; - /// - /// if std::io::stdout().is_terminal() { - /// println!("stdout is a terminal") - /// } - /// ``` - fn is_terminal(&self) -> bool; +/// possible stream sources +#[derive(Clone, Copy, Debug)] +pub enum Stream { + Stdout, + Stderr, + Stdin, } -/// Returns `true` if `this` is a terminal. -/// -/// This is equivalent to calling `this.is_terminal()` and exists only as a -/// convenience to calling the trait method [`IsTerminal::is_terminal`] -/// without importing the trait. -/// -/// # Example -/// -/// ``` -/// if is_terminal::is_terminal(&std::io::stdout()) { -/// println!("stdout is a terminal") -/// } -/// ``` -pub fn is_terminal