From 136cee71c27ed96f94f9b04834e593a537af210a 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).
---
 read_password_test.go         | 21 ++++++++++++++++++
 read_password_unix_test.go    | 30 ++++++++++++++++++++++++++
 read_password_windows_test.go | 40 +++++++++++++++++++++++++++++++++++
 3 files changed, 91 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..a28af27
--- /dev/null
+++ b/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))
+}