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).

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_test.go

@@ -0,0 +1,40 @@
+// 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"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+	"golang.org/x/term"
+)
+
+func ExampleReadPassword_windows() {
+	// If standard input is not bound to the terminal, a password can
+	// still be read from it.
+
+	path, err := windows.UTF16PtrFromString("CONIN$")
+	if err != nil {
+		panic(err)
+	}
+	var sa windows.SecurityAttributes
+	sa.Length = uint32(unsafe.Sizeof(sa))
+	sa.InheritHandle = 1
+	tty, err := windows.CreateFile(path, windows.GENERIC_READ|windows.GENERIC_WRITE, windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE, &sa, windows.OPEN_EXISTING, 0, 0)
+	if err != nil {
+		panic(err)
+	}
+	defer windows.CloseHandle(tty)
+
+	fmt.Print("Enter your password: ")
+	p, err := term.ReadPassword(int(tty))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("\nYou entered '%s'\n", string(p))
+}