External_Programs for Sublime Text 3

将外部程序集成到Sublime Text 3中的插件，作为文本命令和窗口命令。

程序调用不交互；如果每个调用都需要编辑命令行，希望使用Sublime Text的解释器或完整功能的程序调用选项，请使用文中提到的三个替代方案之一。

• 摘要
• 安装
• external_program 文本命令
• 理由
• 许可证

摘要

提供 external_program，一个运行外部程序的命令，可应用于以下之一：

• 当前文件；
• 文件URI（带/不带字符位置/范围片段标识符）；
• 当前选择（如果没有选择，则为整个缓冲区）；
• 无。

通过以下方式将数据传递给程序：

• 单个参数；
• 标准输入流；
• 临时文件；
• 无（当参数为无时有意义）。

将程序的标准输出（或可选的临时文件）的结果写回，可以：

• 在光标处插入；
• 替换选定的文本（如果没有选择，则为整个缓冲区）；
• 到输出面板；
• 到Sublime Text的幽灵；
• 无。

“选择”表示单个选择，不是多选。如果没有选择，则插件会拿整个缓冲区，无论它是否已保存到文件中。

如果发生错误，消息将被写入状态条。如果调用的程序将其文本发送到标准错误流，它将在错误输出面板中显示。注意：这并非插件自身的错误消息所在的之处，包括程序返回的状态码（当非零时），这总是显示在状态条上。

从命令面板中提供两个命令以显示错误和输出面板：“外部程序：显示错误”和“外部程序：显示输出”。

外部程序以异步方式执行。

安装

可以使用Package Control，或手动使用源存档。在Packages/中进行手动安装，插件应安装为External_Programs，因为使用其他名称将破坏文件引用。

external_program 文本命令

将外部程序与简单调用（无复杂命令行）集成，主要作为文本命令。

本命令文档的部分内容可在摘要中找到。

提供了两个辅助命令

• external_program_show_errors;
• external_program_show_output.

这些命令可在命令面板中找到：

• “外部程序：显示错误”;
• “外部程序：显示输出”。

创建一个命令

以下是从*.sublime-commands文件中提供的示例用法

{
    "caption": "Text: Format",
    "command": "external_program",
    "args": {
        "source": "selected_text",
        "through": "stdin",
      "executable": "format-text",
      // "executable": ["format-text", "--file", "$file"],
      "output": "stdout",
        "destination": "insert_replace",
        "panels": "reset"
    }
}

以下图表显示了主要参数及其选项

"source"     -->     "through"      -->  "executable" (*) -->     "output"     -->  "destination"
---------------     -----------------       ----------------     ----------------     ----------------
"selected_text"          "stdin"              string|array         "stdout" (d)       "insert_replace"
 "file_name"        "single_argument"                            "temporary_file"      "output_panel"
  "file_uri"        "temporary_file"                                                     "phantom"
  "text_uri"

                                *: required
                                d: default

以及附加参数

• panels: [enum] reset（默认值）| accumulate;

只有一个参数是必需的，即 executable。如果您省略了一个没有默认值的参数，则该功能将不会被使用。

如果没有为 executable 提供任何参数，则可以将其表示为字符串。否则，它可以是包含所有参数的数组（请参阅上面的示例）。此外，如果 executable 参数为数组，它可能包含一些特殊变量。这些是 Sublime Text 在其构建系统中使用的相同变量。以下是列表

如果正在运行的命令启动了 GUI 应用程序，请不要设置 destination 参数。如果设置了 destination，则插件将等待命令的 stdout 和返回码。这通常以超时错误结束，该错误适用于预期长时间运行的城市GUI应用程序。

当 destination 为 insert_replace 时，更改选择或缓冲区将终止显示结果的命令（实际程序不会被终止）。

当 panels 为 accumulate 时，意味着新内容将被附加到输出和错误面板的先前面板内容。

关于through参数，当需要将选择字符串发送给只接受文件参数且不支持stdin的命令时，temporary_file选项非常有用。它会将选择保存到临时文件（位于Packages文件夹中），然后将文件路径作为参数发送给命令。执行完成后，临时文件将自动删除。如果您想从同一临时文件（而不是stdout）读取输出，请将output参数设置为temporary_file。

更多关于source

• selected_text：当选择不是多选时，选择的文本；如果没有选择，则使用整个缓冲区；
• file_name：简单文件名，即带扩展名的基名（注意工作目录是文件的目录）；
• file_uri：具有file:协议和绝对路径的URI，必要时进行百分号编码；
• text_uri：具有文本位置或范围片段标识符的文件URI，根据RFC 5147，仅使用char方案，其中选择不是多选（当没有选择时，这与file_uri相同）。

设置

命令使用这些设置

• errors_panel_name，默认值为errors；
• output_panel_name，默认值为output；
• timeout_delay，默认值为3（秒，不是毫秒）；

如果找不到设置，则使用上述默认值。

更改errors_panel_name和output_panel_name设置，实际上需要重新启动以应用（这可能在未来的版本中更改）。

注意：要使用Sublime Text命令显示面板，面板名称必须以output.（注意点）为前缀。例如：output.output，为输出面板或output.errors为错误面板。在这些面板中没有写入内容之前，这两个面板都不存在。

面板将使用相应的Sublime Text首选项中的颜色方案进行显示，并且当更改此首选项时，面板将切换颜色方案。

理由

程序调用是故意简单的。此插件提供我认为应该是编辑器核心部分的功能，并且这不是编辑器的目的，即成为一个外壳或提供命令行编辑功能（这是插件的目的）。因此，从来不会超过单个参数传递或通过标准输入流传递。

此插件用于调用外部特别定制的简单命令作为外部程序或包装脚本（这是一种便利的策略，因为它允许以简单的方式在这些命令之间以及在编辑器之间进行重用）

• 如果需要从Sublime Text运行外壳或解释器，请最好使用External REPL来完成此操作。
• 如果需要以交互式方式运行外部命令，或者可能异步运行长时间运行的过程，还有一个：External Command。
• 如果需要全面的功能选项，请使用Commando。

此软件包与前面的两个软件包可以一起安装，因为它们的功能不重叠（我正在使用External_Programs的补丁版本与External Command一起使用）。如果有人想要一个故意简化的程序调用永远不会提供的功能，第三个将替代此软件包。

许可证

请参阅LICENSE文件。