From e25ce086c993bdab606c320367bc90271c9ce3f8 Mon Sep 17 00:00:00 2001
From: James Wrigley <JamesWrigley@users.noreply.github.com>
Date: Wed, 1 May 2024 14:31:59 +0200
Subject: [PATCH] Make Base.shell_escape() and Base.shell_split() public
 (#53510)

`Base.shell_escape()` is particularly useful since it's the only way
(AFAICT) to properly convert a `Cmd` to a string.
---
 base/public.jl       | 11 +++++++++++
 base/shell.jl        | 12 +++++++-----
 base/strings/io.jl   |  2 +-
 doc/src/base/base.md |  6 ++++++
 4 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/base/public.jl b/base/public.jl
index 912953795c801..4e5a9947a5661 100644
--- a/base/public.jl
+++ b/base/public.jl
@@ -84,6 +84,17 @@ public
     @locals,
     @propagate_inbounds,
 
+# External processes
+    shell_escape,
+    shell_split,
+    shell_escape_posixly,
+    shell_escape_csh,
+    shell_escape_wincmd,
+    escape_microsoft_c_args,
+
+# Strings
+    escape_raw_string,
+
 # IO
     # types
     BufferStream,
diff --git a/base/shell.jl b/base/shell.jl
index 137150b585d86..e07fff128acfe 100644
--- a/base/shell.jl
+++ b/base/shell.jl
@@ -219,9 +219,9 @@ print_shell_escaped(io::IO; special::String="") = nothing
 """
     shell_escape(args::Union{Cmd,AbstractString...}; special::AbstractString="")
 
-The unexported `shell_escape` function is the inverse of the unexported `shell_split` function:
+The unexported `shell_escape` function is the inverse of the unexported [`Base.shell_split()`](@ref) function:
 it takes a string or command object and escapes any special characters in such a way that calling
-`shell_split` on it would give back the array of words in the original command. The `special`
+[`Base.shell_split()`](@ref) on it would give back the array of words in the original command. The `special`
 keyword argument controls what characters in addition to whitespace, backslashes, quotes and
 dollar signs are considered to be special (default: none).
 
@@ -284,6 +284,8 @@ The unexported `shell_escape_posixly` function
 takes a string or command object and escapes any special characters in such a way that
 it is safe to pass it as an argument to a posix shell.
 
+See also: [`Base.shell_escape()`](@ref)
+
 # Examples
 ```jldoctest
 julia> Base.shell_escape_posixly("cat", "/foo/bar baz", "&&", "echo", "done")
@@ -316,7 +318,7 @@ a backslash.
 This function should also work for a POSIX shell, except if the input
 string contains a linefeed (`"\\n"`) character.
 
-See also: [`shell_escape_posixly`](@ref)
+See also: [`Base.shell_escape_posixly()`](@ref)
 """
 function shell_escape_csh(io::IO, args::AbstractString...)
     first = true
@@ -414,7 +416,7 @@ run(setenv(`cmd /C echo %cmdargs%`, "cmdargs" => cmdargs))
 With an I/O stream parameter `io`, the result will be written there,
 rather than returned as a string.
 
-See also [`escape_microsoft_c_args`](@ref), [`shell_escape_posixly`](@ref).
+See also [`Base.escape_microsoft_c_args()`](@ref), [`Base.shell_escape_posixly()`](@ref).
 
 # Examples
 ```jldoctest
@@ -468,7 +470,7 @@ It joins command-line arguments to be passed to a Windows
 C/C++/Julia application into a command line, escaping or quoting the
 meta characters space, TAB, double quote and backslash where needed.
 
-See also [`shell_escape_wincmd`](@ref), [`escape_raw_string`](@ref).
+See also [`Base.shell_escape_wincmd()`](@ref), [`Base.escape_raw_string()`](@ref).
 """
 function escape_microsoft_c_args(io::IO, args::AbstractString...)
     # http://daviddeley.com/autohotkey/parameters/parameters.htm#WINCRULES
diff --git a/base/strings/io.jl b/base/strings/io.jl
index ba577b5e3eaaf..9204310129729 100644
--- a/base/strings/io.jl
+++ b/base/strings/io.jl
@@ -615,7 +615,7 @@ string literals. (It also happens to be the escaping convention
 expected by the Microsoft C/C++ compiler runtime when it parses a
 command-line string into the argv[] array.)
 
-See also [`escape_string`](@ref).
+See also [`Base.escape_string()`](@ref).
 """
 function escape_raw_string(io::IO, str::AbstractString, delim::Char='"')
     total = 0
diff --git a/doc/src/base/base.md b/doc/src/base/base.md
index 739ee97d1dd43..3e171485a974f 100644
--- a/doc/src/base/base.md
+++ b/doc/src/base/base.md
@@ -338,6 +338,12 @@ Base.Cmd
 Base.setenv
 Base.addenv
 Base.withenv
+Base.shell_escape
+Base.shell_split
+Base.shell_escape_posixly
+Base.shell_escape_csh
+Base.shell_escape_wincmd
+Base.escape_microsoft_c_args
 Base.setcpuaffinity
 Base.pipeline(::Any, ::Any, ::Any, ::Any...)
 Base.pipeline(::Base.AbstractCmd)