shellish_parse

这是一个Rust crate，用于进行"命令行解析"。不，我说的不是解析传递给程序的命令行 参数；为此，我推荐优秀的 Clap crate（启用 wrap_help 和 derive 功能）。这个crate所做的是读取一行文本，并像命令行一样解析它。换句话说，它解析shellish。

如果您正在实现任何需要用户能够输入命令的交互式系统，这将非常有用。

用法

将 shellish_parse 添加到您的 Cargo.toml

shellish_parse = "2.1"

使用 shellish_parse::parse 解析shellish

let line = "Hello World";
assert_eq!(shellish_parse::parse(line, false).unwrap(), &[
    "Hello", "World"
]);

第一个参数，一个 &str，是要解析的行。第二个参数，一个 bool，是不识别的转义序列是否为错误

let line = r#"In\mvalid"#; // note: raw string
assert_eq!(shellish_parse::parse(line, false).unwrap(), &[
    "In�valid"
]);
assert_eq!(shellish_parse::parse(line, true).unwrap_err(),
    shellish_parse::ParseError::UnrecognizedEscape("\\m".to_string()));

如果您在很多地方使用它，可以使用别名来使其更方便

use shellish_parse::parse as parse_shellish;
let line = "Hello World";
assert_eq!(parse_shellish(line, false).unwrap(), &[
    "Hello", "World"
]);

常规解析很棒，但有时您希望能够在同一行上链接多个命令。这就是 multiparse 发挥作用的地方

let line = "Hello World; How are you?";
assert_eq!(shellish_parse::multiparse(line, true, &[";"]).unwrap(), &[
    (vec!["Hello".to_string(), "World".to_string()], Some(0)),
    (vec!["How".to_string(), "are".to_string(), "you?".to_string()], None),
]);

(由于它返回一个元组向量，因此在测试中很难表达。)

您传递您想要使用的分隔符。一个单独的分号可能就足够了。如果您想要更复杂，可以添加任意数量的不同分隔符。每个返回的命令都带有终止它的分隔符的索引

let line = "test -f foo && pv foo | bar || echo no foo & echo wat";
assert_eq!(shellish_parse::multiparse(line, true, &["&&", "||", "&", "|",
                                                    ";"]).unwrap(), &[
    (vec!["test".to_string(), "-f".to_string(), "foo".to_string()], Some(0)),
    (vec!["pv".to_string(), "foo".to_string()], Some(3)),
    (vec!["bar".to_string()], Some(1)),
    (vec!["echo".to_string(), "no".to_string(), "foo".to_string()], Some(2)),
    (vec!["echo".to_string(), "wat".to_string()], None),
]);

由于分隔符是按照传递的顺序进行检查的，所以将较长的分隔符放在较短的分隔符之前。如果在上述调用中 "&" 在 "&&" 之前，那么 "&" 总会被识别，而 "&&" 则永远不会被识别。

此crate的范围不包括极其shellish的东西，如重定向或使用括号分组命令。如果您想要这些功能，您可能正在编写一个实际的shell，而不仅仅是shellish。

语法

语法深受UNIX Bourne shell的影响。引号的使用方式与该shell完全相同。反斜杠也可以用于转义（以及更高级的用法，更类似于Rust字符串而非shell字符串）。与真正的Bourne shell不同，parse_shellish不包含任何形式的变量替换。

空白字符

元素之间通过一个或多个空白字符分隔。

let line = "Hello there!";
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "Hello", "there!",
])

空白字符包括空格、制表符或换行符。命令行前后空白字符将被忽略。元素之间的任何组合和数量的空白字符都等同于单个空格。

let line = "\tHello\n\t  there!    \n\n";
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "Hello", "there!",
])

反斜杠转义

（本节中所有示例输入字符串均作为原始字符串给出。您在其中看到的反斜杠和引号都是字面意思。）

您可以使用反斜杠来转义任何字符。

反斜杠后跟ASCII字母（从'A'到'Z'和从'a'到'z'的26个字母）或数字（从'0'到'9'）具有特殊含义。

• 'n'：换行符（U+000A 行馈送）
• 't'：制表符（U+0009 字符制表）
• 任何其他字母（和任何数字）将插入一个替换字符（U+FFFD），或者根据传递给parse的第二个参数的值引发解析错误。

let line = r#"General\t Kenobi\n"#;
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "General\t", "Kenobi\n",
])

反斜杠后跟换行符，再跟任意数量的未转义的制表符或空格将不会产生任何效果，就像在Rust字符串中一样。例如，您可以通过在行中断处前加反斜杠来继续命令行到另一行。

let line = r#"You will die br\
              aver than most."#;
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "You", "will", "die", "braver", "than", "most."
])

反斜杠后跟任何其他字符将给出该字符，忽略它可能具有的任何特殊含义。

let line = r#"Four\-score\ and\ seven \"years\" ago"#;
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "Four-score and seven", "\"years\"", "ago"
])

未来版本可能添加更多特殊字符。这些特殊字符仅由字母或数字表示。对于所有其他字符，反斜杠的处理方式保证不会改变。

引号

（本节中所有示例输入字符串均作为原始字符串给出。您在其中看到的反斜杠和引号都是字面意思。）

您可以引号部分命令行。引号中的文本将放入同一个元素。

let line = r#"cp "Quotation Mark Test" "Quotation Mark Test Backup""#;
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "cp", "Quotation Mark Test", "Quotation Mark Test Backup"
])

引号本身不会创建新的元素。

let line = r#"I Probably Should Have"Added A Space!""#;
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "I", "Probably", "Should", "HaveAdded A Space!"
])

有两种类型的引号。双引号字符串将解释反斜杠转义，包括\"。

let line = r#"movie recommend "\"Swing it\" magistern""#;
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "movie", "recommend", "\"Swing it\" magistern"
])

单引号字符串不会解释反斜杠转义，甚至不包括\'！

let line = r#"addendum 'and then he said "But I haven'\''t seen it, I \
just searched for '\''movies with quotes in their titles'\'' on IMDB and \
saw that it was popular"'"#;
assert_eq!(shellish_parse::parse(line, true).unwrap(), &[
    "addendum", "and then he said \"But I haven't seen it, I just \
searched for 'movies with quotes in their titles' on IMDB and saw that it \
was popular\""
])

续行符

parse在失败时返回Err(ParseResult::...)。解析可以以三种方式失败

1. 悬挂反斜杠：like this\
2. 未结束的字符串：like "this
3. 未识别的转义序列：like this\m

在前两种情况下，如果只有更多的输入需要读取，解析可能成功。因此，您可以通过提示更多输入，将其添加到字符串末尾，并再次尝试来处理这些错误。《code>needs_continuation方法来自助《code>ParseResult。

// note: raw strings
let input_lines = [r#"This is not a very \"#,
                   r#"long line, so why did \"#,
                   r#"we choose to 'force "#,
                   r#"continuation'?"#];
let mut input_iter = input_lines.into_iter();
let mut buf = input_iter.next().unwrap().to_string();
let result = loop {
    match shellish_parse::parse(&buf, true) {
        Err(x) if x.needs_continuation() => {
            buf.push('\n'); // don't forget this part!
            buf.push_str(input_iter.next().unwrap())
        },
        x => break x,
    }
};
assert_eq!(result.unwrap(), &[
    "This", "is", "not", "a", "very", "long", "line,", "so", "why", "did",
    "we", "choose", "to", "force \ncontinuation?"
]);

法律声明

shellish_parse版权所有2022年，Solra Bizna，并许可以下之一：

• Apache License，版本2.0（《a href="https://github.com/solrabizna/shellish_parse/blob/bd93fe9656b6a6a744f6fbc6d932746815bb325f/LICENSE-APACHE" rel="noopener ugc nofollow">LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可证（《a href="https://github.com/solrabizna/shellish_parse/blob/bd93fe9656b6a6a744f6fbc6d932746815bb325f/LICENSE-MIT" rel="noopener ugc nofollow">LICENSE-MIT或https://open-source.org.cn/licenses/MIT）

任选其一。

除非您明确表示，否则根据Apache-2.0许可证定义的，您有意提交并包含在《code>shellish_parsecrate中的任何贡献，将如上双许可，不附加任何额外的条款或条件。

许可证：MIT OR Apache-2.0