├── .gitignore ├── Cargo.toml ├── LICENSE-APACHE ├── LICENSE-MIT ├── README.md ├── rustfmt.toml └── src └── lib.rs /.gitignore: -------------------------------------------------------------------------------- 1 | /target 2 | **/*.rs.bk 3 | Cargo.lock 4 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "shell-words" 3 | version = "1.1.0" 4 | authors = ["Tomasz Miąsko "] 5 | license = "MIT/Apache-2.0" 6 | repository = "https://github.com/tmiasko/shell-words" 7 | description = "Process command line according to parsing rules of UNIX shell" 8 | readme = "README.md" 9 | keywords = [ 10 | "quote", 11 | "shell", 12 | "split", 13 | "unix", 14 | "words", 15 | ] 16 | 17 | [features] 18 | default = ["std"] 19 | std = [] 20 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | Copyright (c) 2016 Tomasz Miąsko 2 | 3 | Permission is hereby granted, free of charge, to any 4 | person obtaining a copy of this software and associated 5 | documentation files (the "Software"), to deal in the 6 | Software without restriction, including without 7 | limitation the rights to use, copy, modify, merge, 8 | publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software 10 | is furnished to do so, subject to the following 11 | conditions: 12 | 13 | The above copyright notice and this permission notice 14 | shall be included in all copies or substantial portions 15 | of the Software. 16 | 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 18 | ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 19 | TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 20 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 21 | SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 22 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 23 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 24 | IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 | DEALINGS IN THE SOFTWARE. 26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # shell-words 2 | 3 | Process command line according to parsing rules of Unix shell. 4 | 5 | ## Usage 6 | 7 | Add this to Cargo.toml: 8 | ```toml 9 | [dependencies] 10 | shell-words = "1.0.0" 11 | ``` 12 | 13 | Add this to your crate: 14 | ```rust 15 | extern crate shell_words; 16 | ``` 17 | 18 | ## Examples 19 | 20 | ### Split 21 | 22 | Compiling C source code into an executable as in default build rule found in GNU Make: 23 | 24 | ```rust 25 | extern crate shell_words; 26 | 27 | use std::env::var; 28 | use std::process::Command; 29 | 30 | fn main() { 31 | let cc = var("CC").unwrap_or_else(|_| "cc".to_owned()); 32 | 33 | let cflags = var("CFLAGS").unwrap_or_else(|_| String::new()); 34 | let cflags = shell_words::split(&cflags).expect("failed to parse CFLAGS"); 35 | 36 | let cppflags = var("CPPFLAGS").unwrap_or_else(|_| String::new()); 37 | let cppflags = shell_words::split(&cppflags).expect("failed to parse CPPFLAGS"); 38 | 39 | Command::new(cc) 40 | .args(cflags) 41 | .args(cppflags) 42 | .args(&["-c", "a.c", "-o", "a.out"]) 43 | .spawn() 44 | .expect("failed to start subprocess") 45 | .wait() 46 | .expect("failed to wait for subprocess"); 47 | } 48 | ``` 49 | 50 | ### Join 51 | 52 | Logging executed commands in format that can be readily copied and pasted to a shell: 53 | 54 | ```rust 55 | extern crate shell_words; 56 | 57 | fn main() { 58 | let argv = &["python", "-c", "print('Hello world!')"]; 59 | 60 | println!("Executing: {}", shell_words::join(argv)); 61 | 62 | std::process::Command::new(&argv[0]) 63 | .args(&argv[1..]) 64 | .spawn() 65 | .expect("failed to start subprocess") 66 | .wait() 67 | .expect("failed to wait for subprocess"); 68 | } 69 | ``` 70 | 71 | ## Bugs 72 | 73 | Please report any issues at https://github.com/tmiasko/shell-words/issues. 74 | 75 | ## License 76 | 77 | Licensed under either of 78 | 79 | * Apache License, Version 2.0 80 | ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) 81 | * MIT license 82 | ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) 83 | 84 | at your option. 85 | 86 | ## Contribution 87 | 88 | Unless you explicitly state otherwise, any contribution intentionally submitted 89 | for inclusion in the work by you, as defined in the Apache-2.0 license, shall be 90 | dual licensed as above, without any additional terms or conditions. 91 | -------------------------------------------------------------------------------- /rustfmt.toml: -------------------------------------------------------------------------------- 1 | wrap_comments = true 2 | -------------------------------------------------------------------------------- /src/lib.rs: -------------------------------------------------------------------------------- 1 | // Copyright 2018 Tomasz Miąsko 2 | // 3 | // Licensed under the Apache License, Version 2.0 4 | // or the MIT license , at your option. 5 | // 6 | //! Process command line according to parsing rules of Unix shell as specified 7 | //! in [Shell Command Language in POSIX.1-2008][posix-shell]. 8 | //! 9 | //! [posix-shell]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html 10 | 11 | #![cfg_attr(not(feature = "std"), no_std)] 12 | #![forbid(unsafe_code)] 13 | 14 | #[cfg(feature = "std")] 15 | extern crate core; 16 | 17 | use core::fmt; 18 | use core::mem; 19 | 20 | #[cfg(not(feature = "std"))] 21 | #[macro_use] 22 | extern crate alloc; 23 | 24 | #[cfg(not(feature = "std"))] 25 | use alloc::string::String; 26 | #[cfg(not(feature = "std"))] 27 | use alloc::vec::Vec; 28 | 29 | #[cfg(not(feature = "std"))] 30 | use alloc::borrow::Cow; 31 | #[cfg(feature = "std")] 32 | use std::borrow::Cow; 33 | 34 | /// An error returned when shell parsing fails. 35 | #[derive(Clone, Copy, Debug, PartialEq, Eq)] 36 | pub struct ParseError; 37 | 38 | impl fmt::Display for ParseError { 39 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 40 | f.write_str("missing closing quote") 41 | } 42 | } 43 | 44 | #[cfg(feature = "std")] 45 | impl std::error::Error for ParseError {} 46 | 47 | enum State { 48 | /// Within a delimiter. 49 | Delimiter, 50 | /// After backslash, but before starting word. 51 | Backslash, 52 | /// Within an unquoted word. 53 | Unquoted, 54 | /// After backslash in an unquoted word. 55 | UnquotedBackslash, 56 | /// Within a single quoted word. 57 | SingleQuoted, 58 | /// Within a double quoted word. 59 | DoubleQuoted, 60 | /// After backslash inside a double quoted word. 61 | DoubleQuotedBackslash, 62 | /// Inside a comment. 63 | Comment, 64 | } 65 | 66 | /// Splits command line into separate arguments, in much the same way Unix shell 67 | /// would, but without many of expansion the shell would perform. 68 | /// 69 | /// The split functionality is compatible with behaviour of Unix shell, but with 70 | /// word expansions limited to quote removal, and without special token 71 | /// recognition rules for operators. 72 | /// 73 | /// The result is exactly the same as one obtained from Unix shell as long as 74 | /// those unsupported features are not present in input: no operators, no 75 | /// variable assignments, no tilde expansion, no parameter expansion, no command 76 | /// substitution, no arithmetic expansion, no pathname expansion. 77 | /// 78 | /// In case those unsupported shell features are present, the syntax that 79 | /// introduce them is interpreted literally. 80 | /// 81 | /// # Errors 82 | /// 83 | /// When input contains unmatched quote, an error is returned. 84 | /// 85 | /// # Compatibility with other implementations 86 | /// 87 | /// It should be fully compatible with g_shell_parse_argv from GLib, except that 88 | /// in GLib it is an error not to have any words after tokenization. 89 | /// 90 | /// It is also very close to shlex.split available in Python standard library, 91 | /// when used in POSIX mode with support for comments. Though, shlex 92 | /// implementation diverges from POSIX, and from implementation contained herein 93 | /// in three aspects. First, it doesn't support line continuations. 94 | /// Second, inside double quotes, the backslash characters retains its special 95 | /// meaning as an escape character only when followed by \\ or \", whereas POSIX 96 | /// specifies that it should retain its special meaning when followed by: $, \`, 97 | /// \", \\, or a newline. Third, it treats carriage return as one of delimiters. 98 | /// 99 | /// # Examples 100 | /// 101 | /// Building an executable using compiler obtained from CC environment variable 102 | /// and compiler flags from both CFLAGS and CPPFLAGS. Similar to default build 103 | /// rule for C used in GNU Make: 104 | /// 105 | /// ```rust,no_run 106 | /// use std::env::var; 107 | /// use std::process::Command; 108 | /// 109 | /// let cc = var("CC").unwrap_or_else(|_| "cc".to_owned()); 110 | /// 111 | /// let cflags_str = var("CFLAGS").unwrap_or_else(|_| String::new()); 112 | /// let cflags = shell_words::split(&cflags_str).expect("failed to parse CFLAGS"); 113 | /// 114 | /// let cppflags_str = var("CPPFLAGS").unwrap_or_else(|_| String::new()); 115 | /// let cppflags = shell_words::split(&cppflags_str).expect("failed to parse CPPFLAGS"); 116 | /// 117 | /// Command::new(cc) 118 | /// .args(cflags) 119 | /// .args(cppflags) 120 | /// .args(&["-c", "a.c", "-o", "a.out"]) 121 | /// .spawn() 122 | /// .expect("failed to start subprocess") 123 | /// .wait() 124 | /// .expect("failed to wait for subprocess"); 125 | /// ``` 126 | pub fn split(s: &str) -> Result, ParseError> { 127 | use State::*; 128 | 129 | let mut words = Vec::new(); 130 | let mut word = String::new(); 131 | let mut chars = s.chars(); 132 | let mut state = Delimiter; 133 | 134 | loop { 135 | let c = chars.next(); 136 | state = match state { 137 | Delimiter => match c { 138 | None => break, 139 | Some('\'') => SingleQuoted, 140 | Some('\"') => DoubleQuoted, 141 | Some('\\') => Backslash, 142 | Some('\t') | Some(' ') | Some('\n') => Delimiter, 143 | Some('#') => Comment, 144 | Some(c) => { 145 | word.push(c); 146 | Unquoted 147 | } 148 | }, 149 | Backslash => match c { 150 | None => { 151 | word.push('\\'); 152 | words.push(mem::replace(&mut word, String::new())); 153 | break; 154 | } 155 | Some('\n') => Delimiter, 156 | Some(c) => { 157 | word.push(c); 158 | Unquoted 159 | } 160 | }, 161 | Unquoted => match c { 162 | None => { 163 | words.push(mem::replace(&mut word, String::new())); 164 | break; 165 | } 166 | Some('\'') => SingleQuoted, 167 | Some('\"') => DoubleQuoted, 168 | Some('\\') => UnquotedBackslash, 169 | Some('\t') | Some(' ') | Some('\n') => { 170 | words.push(mem::replace(&mut word, String::new())); 171 | Delimiter 172 | } 173 | Some(c) => { 174 | word.push(c); 175 | Unquoted 176 | } 177 | }, 178 | UnquotedBackslash => match c { 179 | None => { 180 | word.push('\\'); 181 | words.push(mem::replace(&mut word, String::new())); 182 | break; 183 | } 184 | Some('\n') => Unquoted, 185 | Some(c) => { 186 | word.push(c); 187 | Unquoted 188 | } 189 | }, 190 | SingleQuoted => match c { 191 | None => return Err(ParseError), 192 | Some('\'') => Unquoted, 193 | Some(c) => { 194 | word.push(c); 195 | SingleQuoted 196 | } 197 | }, 198 | DoubleQuoted => match c { 199 | None => return Err(ParseError), 200 | Some('\"') => Unquoted, 201 | Some('\\') => DoubleQuotedBackslash, 202 | Some(c) => { 203 | word.push(c); 204 | DoubleQuoted 205 | } 206 | }, 207 | DoubleQuotedBackslash => match c { 208 | None => return Err(ParseError), 209 | Some('\n') => DoubleQuoted, 210 | Some(c @ '$') | Some(c @ '`') | Some(c @ '"') | Some(c @ '\\') => { 211 | word.push(c); 212 | DoubleQuoted 213 | } 214 | Some(c) => { 215 | word.push('\\'); 216 | word.push(c); 217 | DoubleQuoted 218 | } 219 | }, 220 | Comment => match c { 221 | None => break, 222 | Some('\n') => Delimiter, 223 | Some(_) => Comment, 224 | }, 225 | } 226 | } 227 | 228 | Ok(words) 229 | } 230 | 231 | enum EscapeStyle { 232 | /// No escaping. 233 | None, 234 | /// Wrap in single quotes. 235 | SingleQuoted, 236 | /// Single quotes combined with backslash. 237 | Mixed, 238 | } 239 | 240 | /// Determines escaping style to use. 241 | fn escape_style(s: &str) -> EscapeStyle { 242 | if s.is_empty() { 243 | return EscapeStyle::SingleQuoted; 244 | } 245 | 246 | let mut special = false; 247 | let mut newline = false; 248 | let mut single_quote = false; 249 | 250 | for c in s.chars() { 251 | match c { 252 | '\n' => { 253 | newline = true; 254 | special = true; 255 | } 256 | '\'' => { 257 | single_quote = true; 258 | special = true; 259 | } 260 | '|' | '&' | ';' | '<' | '>' | '(' | ')' | '$' | '`' | '\\' | '"' | ' ' | '\t' | '*' 261 | | '?' | '[' | '#' | '~' | '=' | '%' => { 262 | special = true; 263 | } 264 | _ => continue, 265 | } 266 | } 267 | 268 | if !special { 269 | EscapeStyle::None 270 | } else if newline && !single_quote { 271 | EscapeStyle::SingleQuoted 272 | } else { 273 | EscapeStyle::Mixed 274 | } 275 | } 276 | 277 | /// Escapes special characters in a string, so that it will retain its literal 278 | /// meaning when used as a part of command in Unix shell. 279 | /// 280 | /// It tries to avoid introducing any unnecessary quotes or escape characters, 281 | /// but specifics regarding quoting style are left unspecified. 282 | pub fn quote(s: &str) -> Cow { 283 | // We are going somewhat out of the way to provide 284 | // minimal amount of quoting in typical cases. 285 | match escape_style(s) { 286 | EscapeStyle::None => s.into(), 287 | EscapeStyle::SingleQuoted => format!("'{}'", s).into(), 288 | EscapeStyle::Mixed => { 289 | let mut quoted = String::new(); 290 | quoted.push('\''); 291 | for c in s.chars() { 292 | if c == '\'' { 293 | quoted.push_str("'\\''"); 294 | } else { 295 | quoted.push(c); 296 | } 297 | } 298 | quoted.push('\''); 299 | quoted.into() 300 | } 301 | } 302 | } 303 | 304 | /// Joins arguments into a single command line suitable for execution in Unix 305 | /// shell. 306 | /// 307 | /// Each argument is quoted using [`quote`] to preserve its literal meaning when 308 | /// parsed by Unix shell. 309 | /// 310 | /// Note: This function is essentially an inverse of [`split`]. 311 | /// 312 | /// # Examples 313 | /// 314 | /// Logging executed commands in format that can be easily copied and pasted 315 | /// into an actual shell: 316 | /// 317 | /// ```rust,no_run 318 | /// fn execute(args: &[&str]) { 319 | /// use std::process::Command; 320 | /// println!("Executing: {}", shell_words::join(args)); 321 | /// Command::new(&args[0]) 322 | /// .args(&args[1..]) 323 | /// .spawn() 324 | /// .expect("failed to start subprocess") 325 | /// .wait() 326 | /// .expect("failed to wait for subprocess"); 327 | /// } 328 | /// 329 | /// execute(&["python", "-c", "print('Hello world!')"]); 330 | /// ``` 331 | /// 332 | /// [`quote`]: fn.quote.html 333 | /// [`split`]: fn.split.html 334 | pub fn join(words: I) -> String 335 | where 336 | I: IntoIterator, 337 | S: AsRef, 338 | { 339 | let mut line = words.into_iter().fold(String::new(), |mut line, word| { 340 | let quoted = quote(word.as_ref()); 341 | line.push_str(quoted.as_ref()); 342 | line.push(' '); 343 | line 344 | }); 345 | line.pop(); 346 | line 347 | } 348 | 349 | #[cfg(test)] 350 | mod tests { 351 | use super::*; 352 | 353 | fn split_ok(cases: &[(&str, &[&str])]) { 354 | for &(input, expected) in cases { 355 | match split(input) { 356 | Err(actual) => { 357 | panic!( 358 | "After split({:?})\nexpected: Ok({:?})\n actual: Err({:?})\n", 359 | input, expected, actual 360 | ); 361 | } 362 | Ok(actual) => { 363 | assert!( 364 | expected == actual.as_slice(), 365 | "After split({:?}).unwrap()\nexpected: {:?}\n actual: {:?}\n", 366 | input, 367 | expected, 368 | actual 369 | ); 370 | } 371 | } 372 | } 373 | } 374 | 375 | #[test] 376 | fn split_empty() { 377 | split_ok(&[("", &[])]); 378 | } 379 | 380 | #[test] 381 | fn split_initial_whitespace_is_removed() { 382 | split_ok(&[ 383 | (" a", &["a"]), 384 | ("\t\t\t\tbar", &["bar"]), 385 | ("\t \nc", &["c"]), 386 | ]); 387 | } 388 | 389 | #[test] 390 | fn split_trailing_whitespace_is_removed() { 391 | split_ok(&[ 392 | ("a ", &["a"]), 393 | ("b\t", &["b"]), 394 | ("c\t \n \n \n", &["c"]), 395 | ("d\n\n", &["d"]), 396 | ]); 397 | } 398 | 399 | #[test] 400 | fn split_carriage_return_is_not_special() { 401 | split_ok(&[("c\ra\r'\r'\r", &["c\ra\r\r\r"])]); 402 | } 403 | 404 | #[test] 405 | fn split_single_quotes() { 406 | split_ok(&[ 407 | (r#"''"#, &[r#""#]), 408 | (r#"'a'"#, &[r#"a"#]), 409 | (r#"'\'"#, &[r#"\"#]), 410 | (r#"' \ '"#, &[r#" \ "#]), 411 | (r#"'#'"#, &[r#"#"#]), 412 | ]); 413 | } 414 | 415 | #[test] 416 | fn split_double_quotes() { 417 | split_ok(&[ 418 | (r#""""#, &[""]), 419 | (r#""""""#, &[""]), 420 | (r#""a b c' d""#, &["a b c' d"]), 421 | (r#""\a""#, &["\\a"]), 422 | (r#""$""#, &["$"]), 423 | (r#""\$""#, &["$"]), 424 | (r#""`""#, &["`"]), 425 | (r#""\`""#, &["`"]), 426 | (r#""\"""#, &["\""]), 427 | (r#""\\""#, &["\\"]), 428 | ("\"\n\"", &["\n"]), 429 | ("\"\\\n\"", &[""]), 430 | ]); 431 | } 432 | 433 | #[test] 434 | fn split_unquoted() { 435 | split_ok(&[ 436 | (r#"\|\&\;"#, &[r#"|&;"#]), 437 | (r#"\<\>"#, &[r#"<>"#]), 438 | (r#"\(\)"#, &[r#"()"#]), 439 | (r#"\$"#, &[r#"$"#]), 440 | (r#"\`"#, &[r#"`"#]), 441 | (r#"\""#, &[r#"""#]), 442 | (r#"\'"#, &[r#"'"#]), 443 | ("\\\n", &[]), 444 | (" \\\n \n", &[]), 445 | ("a\nb\nc", &["a", "b", "c"]), 446 | ("a\\\nb\\\nc", &["abc"]), 447 | ("foo bar baz", &["foo", "bar", "baz"]), 448 | (r#"\🦉"#, &[r"🦉"]), 449 | ]); 450 | } 451 | 452 | #[test] 453 | fn split_trailing_backslash() { 454 | split_ok(&[("\\", &["\\"]), (" \\", &["\\"]), ("a\\", &["a\\"])]); 455 | } 456 | 457 | #[test] 458 | fn split_errors() { 459 | assert_eq!(split("'abc"), Err(ParseError)); 460 | assert_eq!(split("\""), Err(ParseError)); 461 | assert_eq!(split("'\\"), Err(ParseError)); 462 | assert_eq!(split("'\\"), Err(ParseError)); 463 | } 464 | 465 | #[test] 466 | fn split_comments() { 467 | split_ok(&[ 468 | (r#" x # comment "#, &["x"]), 469 | (r#" w1#w2 "#, &["w1#w2"]), 470 | (r#"'not really a # comment'"#, &["not really a # comment"]), 471 | (" a # very long comment \n b # another comment", &["a", "b"]), 472 | ]); 473 | } 474 | 475 | #[test] 476 | fn test_quote() { 477 | assert_eq!(quote(""), "''"); 478 | assert_eq!(quote("'"), "''\\'''"); 479 | assert_eq!(quote("abc"), "abc"); 480 | assert_eq!(quote("a \n b"), "'a \n b'"); 481 | assert_eq!(quote("X'\nY"), "'X'\\''\nY'"); 482 | assert_eq!(quote("~root"), "'~root'"); 483 | } 484 | 485 | #[test] 486 | fn test_join() { 487 | assert_eq!(join(&["a", "b", "c"]), "a b c"); 488 | assert_eq!(join(&[" ", "$", "\n"]), "' ' '$' '\n'"); 489 | } 490 | 491 | #[test] 492 | fn join_followed_by_split_is_identity() { 493 | let cases: Vec<&[&str]> = vec![ 494 | &["a"], 495 | &["python", "-c", "print('Hello world!')"], 496 | &["echo", " arg with spaces ", "arg \' with \" quotes"], 497 | &["even newlines are quoted correctly\n", "\n", "\n\n\t "], 498 | &["$", "`test`"], 499 | &["cat", "~user/log*"], 500 | &["test", "'a \"b", "\"X'"], 501 | &["empty", "", "", ""], 502 | ]; 503 | for argv in cases { 504 | let args = join(argv); 505 | assert_eq!(split(&args).unwrap(), argv); 506 | } 507 | } 508 | } 509 | --------------------------------------------------------------------------------