Merge pull request #70714 from Calinou/doc-os-stdin

Improve documentation for `OS.read_string_from_stdin()`

10 files changed, 19 insertions, 26 deletions

diff --git a/core/core_bind.cpp b/core/core_bind.cpp
index 0ed05a20a2..ab433bd8f1 100644
--- a/core/core_bind.cpp
+++ b/core/core_bind.cpp
@@ -257,8 +257,8 @@ Error OS::shell_open(String p_uri) {
 	return ::OS::get_singleton()->shell_open(p_uri);
 }
 
-String OS::read_string_from_stdin(bool p_block) {
-	return ::OS::get_singleton()->get_stdin_string(true);
+String OS::read_string_from_stdin() {
+	return ::OS::get_singleton()->get_stdin_string();
 }
 
 int OS::execute(const String &p_path, const Vector<String> &p_arguments, Array r_output, bool p_read_stderr, bool p_open_console) {
@@ -539,7 +539,7 @@ void OS::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("get_system_font_path", "font_name", "weight", "stretch", "italic"), &OS::get_system_font_path, DEFVAL(400), DEFVAL(100), DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("get_system_font_path_for_text", "font_name", "text", "locale", "script", "weight", "stretch", "italic"), &OS::get_system_font_path_for_text, DEFVAL(String()), DEFVAL(String()), DEFVAL(400), DEFVAL(100), DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("get_executable_path"), &OS::get_executable_path);
-	ClassDB::bind_method(D_METHOD("read_string_from_stdin", "block"), &OS::read_string_from_stdin, DEFVAL(true));
+	ClassDB::bind_method(D_METHOD("read_string_from_stdin"), &OS::read_string_from_stdin);
 	ClassDB::bind_method(D_METHOD("execute", "path", "arguments", "output", "read_stderr", "open_console"), &OS::execute, DEFVAL(Array()), DEFVAL(false), DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("create_process", "path", "arguments", "open_console"), &OS::create_process, DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("create_instance", "arguments"), &OS::create_instance);
diff --git a/core/core_bind.h b/core/core_bind.h
index e8c59866e3..7ef346d1c4 100644
--- a/core/core_bind.h
+++ b/core/core_bind.h
@@ -146,7 +146,7 @@ public:
 	String get_system_font_path(const String &p_font_name, int p_weight = 400, int p_stretch = 100, bool p_italic = false) const;
 	Vector<String> get_system_font_path_for_text(const String &p_font_name, const String &p_text, const String &p_locale = String(), const String &p_script = String(), int p_weight = 400, int p_stretch = 100, bool p_italic = false) const;
 	String get_executable_path() const;
-	String read_string_from_stdin(bool p_block = true);
+	String read_string_from_stdin();
 	int execute(const String &p_path, const Vector<String> &p_arguments, Array r_output = Array(), bool p_read_stderr = false, bool p_open_console = false);
 	int create_process(const String &p_path, const Vector<String> &p_arguments, bool p_open_console = false);
 	int create_instance(const Vector<String> &p_arguments);
diff --git a/core/os/os.h b/core/os/os.h
index 3c0c05f575..b80efa47b7 100644
--- a/core/os/os.h
+++ b/core/os/os.h
@@ -131,7 +131,7 @@ public:
 	void print_rich(const char *p_format, ...) _PRINTF_FORMAT_ATTRIBUTE_2_3;
 	void printerr(const char *p_format, ...) _PRINTF_FORMAT_ATTRIBUTE_2_3;
 
-	virtual String get_stdin_string(bool p_block = true) = 0;
+	virtual String get_stdin_string() = 0;
 
 	virtual Error get_entropy(uint8_t *r_buffer, int p_bytes) = 0; // Should return cryptographically-safe random bytes.
 
diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml
index ff4982e2fb..6dab7b4ebe 100644
--- a/doc/classes/OS.xml
+++ b/doc/classes/OS.xml
@@ -572,10 +572,9 @@
 		</method>
 		<method name="read_string_from_stdin">
 			<return type="String" />
-			<param index="0" name="block" type="bool" default="true" />
 			<description>
-				Reads a user input string from the standard input (usually the terminal).
-				[b]Note:[/b] This method is implemented on Linux, macOS and Windows. Non-blocking reads are not currently supported on any platform.
+				Reads a user input string from the standard input (usually the terminal). This operation is [i]blocking[/i], which causes the window to freeze if [method read_string_from_stdin] is called on the main thread. The thread calling [method read_string_from_stdin] will block until the program receives a line break in standard input (usually by the user pressing [kbd]Enter[/kbd]).
+				[b]Note:[/b] This method is implemented on Linux, macOS and Windows.
 			</description>
 		</method>
 		<method name="request_permission">
diff --git a/drivers/unix/os_unix.cpp b/drivers/unix/os_unix.cpp
index 2f3a78a689..c37b3d9c87 100644
--- a/drivers/unix/os_unix.cpp
+++ b/drivers/unix/os_unix.cpp
@@ -149,13 +149,9 @@ Vector<String> OS_Unix::get_video_adapter_driver_info() const {
 	return Vector<String>();
 }
 
-String OS_Unix::get_stdin_string(bool p_block) {
-	if (p_block) {
-		char buff[1024];
-		return String::utf8(fgets(buff, 1024, stdin));
-	}
-
-	return String();
+String OS_Unix::get_stdin_string() {
+	char buff[1024];
+	return String::utf8(fgets(buff, 1024, stdin));
 }
 
 Error OS_Unix::get_entropy(uint8_t *r_buffer, int p_bytes) {
diff --git a/drivers/unix/os_unix.h b/drivers/unix/os_unix.h
index 56c4d1747f..416311307c 100644
--- a/drivers/unix/os_unix.h
+++ b/drivers/unix/os_unix.h
@@ -51,7 +51,7 @@ public:
 
 	virtual Vector<String> get_video_adapter_driver_info() const override;
 
-	virtual String get_stdin_string(bool p_block) override;
+	virtual String get_stdin_string() override;
 
 	virtual Error get_entropy(uint8_t *r_buffer, int p_bytes) override;
 
diff --git a/platform/uwp/os_uwp.cpp b/platform/uwp/os_uwp.cpp
index 40c19056b3..38df68c764 100644
--- a/platform/uwp/os_uwp.cpp
+++ b/platform/uwp/os_uwp.cpp
@@ -680,7 +680,7 @@ bool OS_UWP::set_environment(const String &p_var, const String &p_value) const {
 	return false;
 }
 
-String OS_UWP::get_stdin_string(bool p_block) {
+String OS_UWP::get_stdin_string() {
 	return String();
 }
 
diff --git a/platform/uwp/os_uwp.h b/platform/uwp/os_uwp.h
index 02a81f1a47..153656add7 100644
--- a/platform/uwp/os_uwp.h
+++ b/platform/uwp/os_uwp.h
@@ -162,7 +162,7 @@ public:
 	HANDLE mouse_mode_changed;
 
 	virtual void alert(const String &p_alert, const String &p_title = "ALERT!");
-	String get_stdin_string(bool p_block);
+	String get_stdin_string();
 
 	void set_mouse_mode(MouseMode p_mode);
 	MouseMode get_mouse_mode() const;
diff --git a/platform/windows/os_windows.cpp b/platform/windows/os_windows.cpp
index 2a44a19085..bc74978f0b 100644
--- a/platform/windows/os_windows.cpp
+++ b/platform/windows/os_windows.cpp
@@ -1162,13 +1162,11 @@ bool OS_Windows::set_environment(const String &p_var, const String &p_value) con
 	return (bool)SetEnvironmentVariableW((LPCWSTR)(p_var.utf16().get_data()), (LPCWSTR)(p_value.utf16().get_data()));
 }
 
-String OS_Windows::get_stdin_string(bool p_block) {
-	if (p_block) {
-		WCHAR buff[1024];
-		DWORD count = 0;
-		if (ReadConsoleW(GetStdHandle(STD_INPUT_HANDLE), buff, 1024, &count, nullptr)) {
-			return String::utf16((const char16_t *)buff, count);
-		}
+String OS_Windows::get_stdin_string() {
+	WCHAR buff[1024];
+	DWORD count = 0;
+	if (ReadConsoleW(GetStdHandle(STD_INPUT_HANDLE), buff, 1024, &count, nullptr)) {
+		return String::utf16((const char16_t *)buff, count);
 	}
 
 	return String();
diff --git a/platform/windows/os_windows.h b/platform/windows/os_windows.h
index 9cb3977030..c33e0f6740 100644
--- a/platform/windows/os_windows.h
+++ b/platform/windows/os_windows.h
@@ -140,7 +140,7 @@ protected:
 
 	virtual void finalize() override;
 	virtual void finalize_core() override;
-	virtual String get_stdin_string(bool p_block) override;
+	virtual String get_stdin_string() override;
 
 	String _quote_command_line_argument(const String &p_text) const;