From b2824fc2bbc1d05a1bd8396cbbb3fc74aebfb4d9 Mon Sep 17 00:00:00 2001
From: codesoap <codesoap@mailbox.org>
Date: Thu, 3 Jun 2021 18:55:42 +0200
Subject: [PATCH] term: add examples for ReadPassword

These examples demonstrate how to use ReadPassword for interactive
password input from the terminal. They highlight how to use the
function, even if standard input is not a terminal (e.g. when it is a
pipe). The example for Windows is especially interesting, because there
seems to be a bug where CONIN$ cannot be used unless opened with the
write flag.
---
 read_password_test.go         | 21 +++++++++++++++++++++
 read_password_unix_test.go    | 30 ++++++++++++++++++++++++++++++
 read_password_windows_test.go | 31 +++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+)
 create mode 100644 read_password_test.go
 create mode 100644 read_password_unix_test.go
 create mode 100644 read_password_windows_test.go

diff --git a/read_password_test.go b/read_password_test.go
new file mode 100644
index 0000000..b1eb3cd
--- /dev/null
+++ b/read_password_test.go
@@ -0,0 +1,21 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package term_test
+
+import (
+	"fmt"
+	"os"
+
+	"golang.org/x/term"
+)
+
+func ExampleReadPassword() {
+	fmt.Print("Enter your password: ")
+	p, err := term.ReadPassword(int(os.Stdin.Fd()))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("\nYou entered '%s'\n", string(p))
+}
diff --git a/read_password_unix_test.go b/read_password_unix_test.go
new file mode 100644
index 0000000..82170bf
--- /dev/null
+++ b/read_password_unix_test.go
@@ -0,0 +1,30 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build !windows
+
+package term_test
+
+import (
+	"fmt"
+	"os"
+
+	"golang.org/x/term"
+)
+
+func ExampleReadPassword_unix() {
+	// If standard input is not bound to the terminal, a password can
+	// still be read from it.
+	tty, err := os.Open("/dev/tty")
+	if err != nil {
+		panic(err)
+	}
+	defer tty.Close()
+	fmt.Print("Enter your password: ")
+	p, err := term.ReadPassword(int(tty.Fd()))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("\nYou entered '%s'\n", string(p))
+}
diff --git a/read_password_windows_test.go b/read_password_windows_test.go
new file mode 100644
index 0000000..a7bca3d
--- /dev/null
+++ b/read_password_windows_test.go
@@ -0,0 +1,31 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build windows
+
+package term_test
+
+import (
+	"fmt"
+	"os"
+
+	"golang.org/x/term"
+)
+
+func ExampleReadPassword_windows() {
+	// If standard input is not bound to the terminal, a password can
+	// still be read from it. OpenFile must be used with the write flag
+	// for CONIN$.
+	tty, err := os.OpenFile("CONIN$", os.O_RDWR, 0)
+	if err != nil {
+		panic(err)
+	}
+	defer tty.Close()
+	fmt.Print("Enter your password: ")
+	p, err := term.ReadPassword(int(tty.Fd()))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("\nYou entered '%s'\n", string(p))
+}