README
¶
terminal
import "github.com/gechr/x/terminal"
Package terminal provides terminal detection and size queries.
Index
- func Height(f *os.File) int
- func Is(f *os.File) bool
- func IsDark() (bool, bool)
- func IsLight() (bool, bool)
- func Size(f *os.File) (int, int)
- func SupportsTrueColor() bool
- func Width(f *os.File) int
func Height
func Height(f *os.File) int
Height returns the height of the terminal connected to f, or 0 if f is nil or not a terminal.
Example
Height returns 0 when the file is nil or not connected to a terminal.
fmt.Println(terminal.Height(nil))
Output:
0
func Is
func Is(f *os.File) bool
Is returns true if the given file is a terminal. Returns false for nil files.
Example
A pipe is not a terminal, and nil files are always reported as non-terminals.
r, w, err := os.Pipe()
if err != nil {
panic(err)
}
defer r.Close()
defer w.Close()
fmt.Println(terminal.Is(r))
fmt.Println(terminal.Is(w))
fmt.Println(terminal.Is(nil))
Output:
false
false
false
func IsDark
func IsDark() (bool, bool)
IsDark reports (dark, ok) for the controlling terminal. It performs terminal I/O on the first call, returning as soon as the terminal has answered and waiting no longer than half a second for one that never does. The result, including no response, is cached for the process. ok is false if no standard stream is a terminal or the terminal does not respond, in which case the first result is meaningless.
Example
IsDark reports ok=false when no standard stream is connected to a terminal, since there is no background to query.
dark, ok := terminal.IsDark()
switch {
case !ok:
fmt.Println("no terminal detected")
case dark:
fmt.Println("dark")
default:
fmt.Println("light")
}
Output:
no terminal detected
func IsLight
func IsLight() (bool, bool)
IsLight reports (light, ok) for the controlling terminal. Like IsDark, it performs terminal I/O on the first call and caches the result for the process. ok is false if no standard stream is a terminal or the terminal does not respond, in which case the first result is meaningless.
func Size
func Size(f *os.File) (int, int)
Size returns the (width, height) of the terminal connected to f in cells, or (0, 0) if f is nil or not a terminal.
Example
Size returns (0, 0) when the file is nil or not connected to a terminal.
w, h := terminal.Size(nil)
fmt.Println(w, h)
Output:
0 0
func SupportsTrueColor
func SupportsTrueColor() bool
SupportsTrueColor reports whether the terminal supports 24-bit "true color" output.
Detection reads COLORTERM, TERM, the terminfo Tc and RGB capabilities and, inside tmux, tmux info - tmux does not forward COLORTERM, so only its own capabilities settle the question there. TERM alone is not trusted for capability: the ubiquitous TERM=xterm-256color advertises only 256 colors even on terminals that render 24-bit, which is precisely why COLORTERM exists.
This reports capability, not preference: NO_COLOR and CLICOLOR are ignored and a redirected stream is still measured against the terminal, so honoring either is left to the caller. The first call detects, and the result is cached for the process.
func Width
func Width(f *os.File) int
Width returns the width of the terminal connected to f. Returns 0 if f is nil or not a terminal.
Example
Width returns 0 when the file is nil or not connected to a terminal.
fmt.Println(terminal.Width(nil))
Output:
0
Documentation
¶
Overview ¶
Package terminal provides terminal detection and size queries.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Height ¶
Height returns the height of the terminal connected to `f`, or 0 if `f` is nil or not a terminal.
Example ¶
Height returns 0 when the file is nil or not connected to a terminal.
package main
import (
"fmt"
"github.com/gechr/x/terminal"
)
func main() {
fmt.Println(terminal.Height(nil))
}
Output: 0
func Is ¶
Is returns true if the given file is a terminal. Returns false for nil files.
Example ¶
A pipe is not a terminal, and nil files are always reported as non-terminals.
package main
import (
"fmt"
"os"
"github.com/gechr/x/terminal"
)
func main() {
r, w, err := os.Pipe()
if err != nil {
panic(err)
}
defer r.Close()
defer w.Close()
fmt.Println(terminal.Is(r))
fmt.Println(terminal.Is(w))
fmt.Println(terminal.Is(nil))
}
Output: false false false
func IsDark ¶ added in v0.3.4
IsDark reports (dark, ok) for the controlling terminal. It performs terminal I/O on the first call, returning as soon as the terminal has answered and waiting no longer than half a second for one that never does. The result, including no response, is cached for the process. `ok` is false if no standard stream is a terminal or the terminal does not respond, in which case the first result is meaningless.
Example ¶
IsDark reports ok=false when no standard stream is connected to a terminal, since there is no background to query.
package main
import (
"fmt"
"github.com/gechr/x/terminal"
)
func main() {
dark, ok := terminal.IsDark()
switch {
case !ok:
fmt.Println("no terminal detected")
case dark:
fmt.Println("dark")
default:
fmt.Println("light")
}
}
Output: no terminal detected
func IsLight ¶ added in v0.3.4
IsLight reports (light, ok) for the controlling terminal. Like IsDark, it performs terminal I/O on the first call and caches the result for the process. `ok` is false if no standard stream is a terminal or the terminal does not respond, in which case the first result is meaningless.
func Size ¶
Size returns the (width, height) of the terminal connected to `f` in cells, or (0, 0) if `f` is nil or not a terminal.
Example ¶
Size returns (0, 0) when the file is nil or not connected to a terminal.
package main
import (
"fmt"
"github.com/gechr/x/terminal"
)
func main() {
w, h := terminal.Size(nil)
fmt.Println(w, h)
}
Output: 0 0
func SupportsTrueColor ¶ added in v0.5.0
func SupportsTrueColor() bool
SupportsTrueColor reports whether the terminal supports 24-bit "true color" output.
Detection reads COLORTERM, TERM, the terminfo Tc and RGB capabilities and, inside tmux, `tmux info` - tmux does not forward COLORTERM, so only its own capabilities settle the question there. TERM alone is not trusted for capability: the ubiquitous TERM=xterm-256color advertises only 256 colors even on terminals that render 24-bit, which is precisely why COLORTERM exists.
This reports capability, not preference: NO_COLOR and CLICOLOR are ignored and a redirected stream is still measured against the terminal, so honoring either is left to the caller. The first call detects, and the result is cached for the process.
func Width ¶
Width returns the width of the terminal connected to `f`. Returns 0 if `f` is nil or not a terminal.
Example ¶
Width returns 0 when the file is nil or not connected to a terminal.
package main
import (
"fmt"
"github.com/gechr/x/terminal"
)
func main() {
fmt.Println(terminal.Width(nil))
}
Output: 0
Types ¶
This section is empty.
Source Files
Directories