The R Project SVN R

Rev

Rev 68948 | Rev 80623 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 68948 Rev 69810
Line 8... Line 8...
8 
\title{Quote Strings for Use in OS Shells}
 8 
\title{Quote Strings for Use in OS Shells}
9 
\description{
 9 
\description{
10 
  Quote a string to be passed to an operating system shell.
 10 
  Quote a string to be passed to an operating system shell.
11 
}
 11 
}
12 
\usage{
 12 
\usage{
13 
shQuote(string, type = c("sh", "csh", "cmd"))
 13 
shQuote(string, type = c("sh", "csh", "cmd", "cmd2"))
14 
}
 14 
}
15 
\arguments{
 15 
\arguments{
16 
  \item{string}{a character vector, usually of length one.}
 16 
  \item{string}{a character vector, usually of length one.}
17 
  \item{type}{character: the type of shell.  Partial matching is
 17 
  \item{type}{character: the type of shell quoting.  Partial matching is
18 
    supported.  \code{"cmd"} refers to the Windows NT shell, and is the
 18 
    supported.  \code{"cmd"} and \code{"cmd2"} refer to the Windows shell.
19 
    default under Windows.}
 19 
    \code{"cmd"} is the default under Windows.}
20 
}
 20 
}
21 
\details{
 21 
\details{
22 
  The default type of quoting supported under Unix-alikes is that for
 22 
  The default type of quoting supported under Unix-alikes is that for
23 
  the Bourne shell \code{sh}.  If the string does not contain single
 23 
  the Bourne shell \code{sh}.  If the string does not contain single
24 
  quotes, we can just surround it with single quotes.  Otherwise, the
 24 
  quotes, we can just surround it with single quotes.  Otherwise, the
Line 34... Line 34...
34 
  contain single quotes, we can use double quotes provided it does not
 34 
  contain single quotes, we can use double quotes provided it does not
35 
  contain dollar or backquote (and we need to escape backslash,
 35 
  contain dollar or backquote (and we need to escape backslash,
36 
  exclamation mark and double quote).  As a last resort, we need to
 36 
  exclamation mark and double quote).  As a last resort, we need to
37 
  split the string into pieces not containing single quotes and surround
 37 
  split the string into pieces not containing single quotes and surround
38 
  each with single quotes, and the single quotes with double quotes.
 38 
  each with single quotes, and the single quotes with double quotes.
39 
 
 39
40 
#ifdef windows
 40 
  In Windows, command line interpretation is done by the application
41 
  The Windows shell supports only double quoting.  All this
 41 
  as well as the shell.  It may depend on the compiler used:
42 
  implementation does is to surround the string by double quotes and
 42 
  Microsoft's rules for the C run-time are given at
- 
 
 43 
  \url{https://msdn.microsoft.com/library/ms880421}. It may depend on
43 
  escape internal double quotes by a backslash.  As Windows path names
 44 
  the whim of the programmer of the application: check its
44 
  cannot contain double quotes, this makes \code{shQuote} safe for use
 45 
  documentation.  The \code{type = "cmd"} quoting surrounds the string
45 
  with file paths in \code{\link{system}}, and with \code{\link{shell}}
 46 
  by double quotes and escapes internal double quotes by a backslash.
46 
  if the default shell is used.
 47 
  As Windows path names cannot contain double quotes, this makes
47 
 
 - 
 
48 
  It will usually be safe to use \code{shQuote} to quote arguments of a
 48 
  \code{shQuote} safe for use with many applications when used with
49 
  command, but because \code{\link{system}} does not use a shell,
 49 
  \code{\link{system}} or \code{\link{system2}}.  The Windows
- 
 
 50 
  \command{cmd.exe} shell (used by default with \code{\link{shell}})
50 
  interpretation of quoted arguments is done by the run-time code of the
 51 
  uses \code{type = "cmd2"} quoting:  special characters are prefixed
51 
  executable.  This may depend on the compiler used: Microsoft's rules
 52 
  with \code{"^"}.  In some cases, two types of quoting should be
52 
  for the C run-time are given at
 53 
  used:  first for the application, and then \code{type = "cmd2"}
53 
  \url{https://msdn2.microsoft.com/en-us/library/ms880421.aspx}.
 54 
  for \command{cmd.exe}.  See the examples below.
54 
#endif
 - 
 
55 
}
 55 
}
56 
\references{
 56
57 
  Loukides, M. \emph{et al} (2002)
 57 
\references{ Loukides, M. \emph{et al} (2002) \emph{Unix Power Tools}
58 
  \emph{Unix Power Tools} Third Edition.  O'Reilly.  Section 27.12.
 58 
  Third Edition. O'Reilly.  Section 27.12.
- 
 
 59
- 
 
 60 
  Discussion in \PR{16636}.
59 
 
 61 
 
60 
% gone in Jan 2015
62 
% gone in Jan 2015
61 
% \url{http://www.mhuffman.com/Notes/dos/bash_cmd.htm}
 63 
% \url{http://www.mhuffman.com/Notes/dos/bash_cmd.htm}
62 
}
 64 
}
63 
\seealso{
 65 
\seealso{
64 
  \code{Quotes} for quoting \R code.
 66 
  \link{Quotes} for quoting \R code.
65 
 
 67 
 
66 
  \code{\link{sQuote}} for quoting English text.
 68 
  \code{\link{sQuote}} for quoting English text.
67 
}
 69 
}
68 
\examples{
 70 
\examples{
69 
test <- "abc$def`gh`i\\\\j"
 71 
test <- "abc$def`gh`i\\\\j"
Line 75... Line 77...
75 
tryit <- paste("use the", sQuote("-c"), "switch\nlike this")
 77 
tryit <- paste("use the", sQuote("-c"), "switch\nlike this")
76 
cat(shQuote(tryit), "\n")
 78 
cat(shQuote(tryit), "\n")
77 
\dontrun{system(paste("echo", shQuote(tryit)))}
 79 
\dontrun{system(paste("echo", shQuote(tryit)))}
78 
cat(shQuote(tryit, type = "csh"), "\n")
 80 
cat(shQuote(tryit, type = "csh"), "\n")
79 
 
 81 
 
80 
## Windows-only example.
 82 
## Windows-only example, assuming cmd.exe:
81 
perlcmd <- 'print "Hello World\\n";'
 83 
perlcmd <- 'print "Hello World\\\\n";'
- 
 
 84 
\dontrun{
- 
 
 85 
shell(shQuote(paste("perl -e",
82 
\dontrun{shell(paste("perl -e", shQuote(perlcmd, type = "cmd")))}
 86 
                    shQuote(perlcmd, type = "cmd")),
- 
 
 87 
              type = "cmd2"))
- 
 
 88 
}
83 
}
 89 
}
84 
\keyword{utilities}
 90 
\keyword{utilities}