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.

Author: codesoap

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))
+}

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))
+}

read_password_windows.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))
+}