| % File src/library/base/man/shQuote.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2021 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{shQuote} |
| \alias{shQuote} |
| \title{Quote Strings for Use in OS Shells} |
| \description{ |
| Quote a string to be passed to an operating system shell. |
| } |
| \usage{ |
| shQuote(string, type = c("sh", "csh", "cmd", "cmd2")) |
| } |
| \arguments{ |
| \item{string}{a character vector, usually of length one.} |
| \item{type}{character: the type of shell quoting. Partial matching is |
| supported. \code{"cmd"} and \code{"cmd2"} refer to the Windows shell. |
| \code{"cmd"} is the default under Windows.} |
| } |
| \details{ |
| The default type of quoting supported under Unix-alikes is that for |
| the Bourne shell \code{sh}. If the string does not contain single |
| quotes, we can just surround it with single quotes. Otherwise, the |
| string is surrounded in double quotes, which suppresses all special |
| meanings of metacharacters except dollar, backquote and backslash, so |
| these (and of course double quote) are preceded by backslash. This |
| type of quoting is also appropriate for \code{bash}, \code{ksh} and |
| \code{zsh}. |
| |
| The other type of quoting is for the C-shell (\code{csh} and |
| \code{tcsh}). Once again, if the string does not contain single |
| quotes, we can just surround it with single quotes. If it does |
| contain single quotes, we can use double quotes provided it does not |
| contain dollar or backquote (and we need to escape backslash, |
| exclamation mark and double quote). As a last resort, we need to |
| split the string into pieces not containing single quotes (some may be |
| empty) and surround each with single quotes, and the single quotes |
| with double quotes. |
| |
| In Windows, command line interpretation is done by the application as well |
| as the shell. It may depend on the compiler used: Microsoft's rules for |
| the C run-time are given at |
| \url{https://docs.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments?view=msvc-160}. |
| It may depend on the whim of the programmer of the application: check its |
| documentation. The \code{type = "cmd"} prepares the string for parsing as |
| an argument by the Microsoft's rules and makes \code{shQuote} safe for use |
| with many applications when used with \code{\link{system}} or |
| \code{\link{system2}}. It surrounds the string by double quotes and |
| escapes internal double quotes by a backslash. Any trailing backslashes |
| and backslashes that were originally before double quotes are doubled. |
| |
| The Windows |
| \command{cmd.exe} shell (used by default with \code{\link{shell}}) |
| uses \code{type = "cmd2"} quoting: special characters are prefixed |
| with \code{"^"}. In some cases, two types of quoting should be |
| used: first for the application, and then \code{type = "cmd2"} |
| for \command{cmd.exe}. See the examples below. |
| } |
| \value{ |
| A character vector of the same length as \code{string}. |
| } |
| \references{ Loukides, M. \emph{et al} (2002) \emph{Unix Power Tools} |
| Third Edition. O'Reilly. Section 27.12. |
| |
| Discussion in \PR{16636}. |
| |
| % gone in Jan 2015 |
| % \url{http://www.mhuffman.com/Notes/dos/bash_cmd.htm} |
| } |
| \seealso{ |
| \link{Quotes} for quoting \R code. |
| |
| \code{\link{sQuote}} for quoting English text. |
| } |
| \examples{ |
| test <- "abc$def`gh`i\\\\j" |
| cat(shQuote(test), "\n") |
| \dontrun{system(paste("echo", shQuote(test)))} |
| test <- "don't do it!" |
| cat(shQuote(test), "\n") |
| |
| tryit <- paste("use the", sQuote("-c"), "switch\nlike this") |
| cat(shQuote(tryit), "\n") |
| \dontrun{system(paste("echo", shQuote(tryit)))} |
| cat(shQuote(tryit, type = "csh"), "\n") |
| |
| ## Windows-only example, assuming cmd.exe: |
| perlcmd <- 'print "Hello World\\\\n";' |
| \dontrun{ |
| shell(shQuote(paste("perl -e", |
| shQuote(perlcmd, type = "cmd")), |
| type = "cmd2")) |
| } |
| } |
| \keyword{utilities} |