放映师

转到其他文件以及更多。

功能

• 在测试和实现文件之间跳转
• 从侧边栏打开/跳转到其他文件
• .projections.json文件支持（包括JSON-schema验证）
• 内置对Elixir、Ruby和Sublime包开发的投影支持
• 为其他包使用提供公共API
• 适用于所有平台

安装

1. 如果您还没有安装，请安装Sublime Text 软件包控制包。
2. 打开命令面板，开始输入Package Control: 安装包。
3. 输入放映师。

用法

该软件包实现了由Tim Pope在他的vim-projectionist插件中最初引入的逻辑。主要思想是

提供使用“投影”进行粒度项目配置。

该软件包公开以下命令来处理投影

• projectionist_open_alternate - 为当前文件打开替代文件。
  在Sublime Text 4中，此命令支持"mode": "side_by_side"，以在侧边视图打开替代文件。此命令也可在命令面板（放映师：打开替代）以及侧边栏中使用。在侧边栏中，还有一个选项可以跳转（在侧边栏中显示）替代文件而不是打开它。

查看Default.sublime-commands以查看所有可用命令的列表。

什么是投影？

投影是从文件名和glob到描述文件的属性集合的映射。定义它们的最简单方法是创建一个位于项目根目录的.projections.json文件，但还有其他定义投影的方法（参见Sublime Text集成部分）。
该软件包附带了用于 .projections.json 文件的 JSON 架构，以提供验证和自动补全（需要 LSP-json 软件包）。

以下是一个 Maven 项目的简单示例

{
  "src/main/java/*.java": {
    "alternate": "src/test/java/{}.java",
  },
  "src/test/java/*.java": {
    "alternate": "src/main/java/{}.java",
  }
}

在属性值中，{} 将被匹配到的 * 通配符部分的值所替换。您还可以在花括号内部使用一个或多个转换，之间用竖线分隔，例如 {dot|hyphenate}。以下是可以使用的完整转换列表

从通配符的角度来看，* 实际上是 **/* 的占位符。对于更复杂的情况，可以显式包含两个 glob：例如，test/**/test_*.rb。在用 {} 展开 时，** 和 * 部分将用斜杠连接。如果需要，可以使用 dirname 和 basename 展开，将值拆分回原来的独立值。

目前，该软件包只支持原始实现中的一些属性，但未来将添加更多属性支持。以下是当前支持的属性列表

• alternate
  确定 projectionist_open_alternate 命令的目地。
  如果这是一列，将使用第一个可读的文件。也用作 related 的默认值。

• template
  用于创建新文件的行数组。

以下是目前尚未支持的属性

• console
  运行以启动 REPL 或其他交互式外壳的命令。
  这对于从 * 投影或简单的文件glob（例如，*.js）中设置非常有用。
  也用作 start 的默认值。
  展开是被shell转义过的。

• dispatch
  展开是被shell转义过的。

• make
  设置 makeprg。
  这对于从 * 投影中设置非常有用。
  展开是被shell转义过的。

• path
  附加到 path 的目录。
  可以是相对于项目根的相对路径或绝对路径。
  这在简单的文件 glob（例如，*.js）上设置时非常有用。

• related
  当在没有参数的情况下调用导航命令时，指示要搜索的文件，以找到默认的目的地。
  相关文件会递归搜索。

• start
  用于“启动”项目的命令。
  例如，包括 lein run、rails server 和 foreman start。
  这对于从 * 投影中设置非常有用。
  展开是被shell转义过的。

• type
  声明文件类型并为匹配 glob 的文件创建一组导航命令。

Sublime Text 集成

该软件包支持以下来源的投影

• local - 在项目配置文件中定义的投影（例如，MyProject.sublime-project）
• file - 定义在 .projections.json 文件中的投影
• global - 全球设置中定义的启发式投影
• builtin - 包含于该包内的内置启发式投影

查找顺序由 lookup_order 设置决定，它是

{
  "lookup_order": [
    "local", // first look in the project settings
    "file", // then, in the .projections.json file
    "global", // then, the `heuristic_projections` from the package settings
    "builtin" // and finally, he built-in heuristic projections
  ]
}

要避免评估来自某些源的投影，请从 lookup_order 设置中移除它们

{
  "lookup_order": ["local", "file"] // evaluate only local and .projections.json projections
}

lookup_order 设置中项目的顺序很重要，因此在数组中切换项将改变查找顺序

{
  "lookup_order": [
    "file", // first look in the .projections.json file
    "local", // then, in the project settings
    "builtin", // then, the built-in heuristic projections
    "global" // and finally, the `heuristic_projections` from the package settings
  ]
}

鉴于投影源的数量，该软件包提供了 projectionist_output_projections 命令（或命令面板中的 Projectionist: 输出投影）以将所有投影输出到 Sublime Text 控制台。

lookup_order 也会确定具有相同模式的投影的处理方式。因此，例如，如果多个源中定义了相同的模式，则将按照 lookup_order 设置中定义的顺序合并属性。
例如，如果有局部投影

{
  "lib/*.ex": {
    "alternate": "test/{}_test.exs",
    "prop2": "value2"
  }
}

以及内置投影

{
  "lib/*.ex": {
    "alternate": "spec/{}_spec.exs",
    "prop1": "value1"
  }
}

结果投影将是

{
  "lib/*.ex": {
    "alternate": "test/{}_test.exs",
    "prop1": "value1",
    "prop2": "value2"
  }
}

为了避免覆盖深层级别上定义的投影，可以使用 append/prepend 前缀，例如

{
  "lib/*.ex": {
    "prepend_alternate": "spec/{}_spec.exs",
    "prop1": "value1"
  }
}

将产生

{
  "lib/*.ex": {
    "alternate": [
      "spec/{}_spec.exs",
      "test/{}_test.exs"
    ],
    "prop1": "value1",
    "prop2": "value2"
  }
}

这对于微调定义在 .projections.json 文件中的投影非常有用，因为这个文件可以被其他编辑器（例如 VIM、VSCode）使用。

目前，只有 alternate 属性支持这些前缀。

局部投影

局部投影可以在项目设置中定义

{
  "folders": [
    {
      "path": ".",
    }
  ],
  "settings": {
    "Projectionist": {
      "projections": {
        "plugin/*.py": {
          "alternate": "tests/{dirname}/test_{basename}.py",
        },
        "tests/**/test_*.py": {
          "alternate": "plugin/{}.py",
        }
      }
    }
  }
}

启发式投影

启发式投影可以通过全球设置中的 heuristic_projections 变量定义，它们在以下字符串描述项目根目录和一组投影之间作为字典映射。字典的键是可以在一个项目根目录下找到的文件和目录，多个需求之间用 & 分隔，多个替代项之间用 | 分隔。
您还可以使用 ! 前缀来禁止而不是要求其存在。

在以下示例中，第一个键需要名为 mix.exs 的文件和一个名为 test/test_helper.exs 的文件。

{
  "heuristic_projections": {
    "mix.exs&test/test_helper.exs": {
      "lib/*.ex": {
        "alternate": "test/{}_test.exs",
        "template": [
          "defmodule {camelcase|capitalize|dot} do",
          "end"
        ]
      },
      "test/*_test.exs": {
        "alternate": "lib/{}.ex",
        "template": [
          "defmodule {camelcase|capitalize|dot}Test do",
          "  use ExUnit.Case",
          "",
          "  alias {camelcase|capitalize|dot}",
          "end",
        ]
      }
    }
  }
}

内置投影

该软件包提供了以下列表的内置投影，它们默认启用

• elixir
• ruby
• sublime

要禁用一些内置投影，请从 builtin_heuristic_projections 设置中移除

{
  "builtin_heuristic_projections": ["elixir", "ruby"] // disable the sublime projection
}

缓存

出于性能考虑，启发式投影（全局和内置）在每个项目中仅确定一次，然后缓存。同样的，对于 .projections.json 文件，它也是解析和按项目缓存。因此，在更改启发式投影或更新 .projections.json 文件后，清空缓存很重要。
可以使用 projectionist_clear_cache 命令或通过命令面板中的 Projectionist: 清空缓存 命令来清空缓存。

项目文件夹和子项目

软件包支持多个项目文件夹。当存在包含单独项目的嵌套文件夹时，这可能非常有用。软件包可以检测这种情况，并使用这些信息进行启发式投影计算和检测 .projections.json 文件。

处理嵌套项目的一种另一种方法是通过使用 subprojects 设置（通常在项目配置中）

{
  "folders": [
    {
      "path": ".",
    }
  ],
  "settings": {
    "Projectionist": {
      "subprojects": [
        "subfolder1/subfolder1_1",
        ["subfolder2", "subfolder2_1"]
      ]
    }
  }
}

子项目可以是字符串或字符串数组（在这种情况下将自动添加路径分隔符）。

公共API

为了允许其他软件包找到替代文件等，该软件包暴露了作为公共API的 projectionist 模块。
请检查 plugin/api.py 以获取实现细节，并查看 tests/test_api.py 以获取测试用例。

find_alternate_file

该功能允许为指定的文件和根目录找到一个替换文件。
返回一个元组 (exists, alternate)，其中 exists 是一个表示替换文件是否存在（布尔值），而 alternate 是替换文件的路径或者如果没有定义替换文件则为 None。

try:
    from projectionist import find_alternate_file

    root = "~/code/project"
    file = "~/code/project/folder1/file1.py"
    exists, alternate = find_alternate_file(root, file)

    if alternate is None:
        print("No alternate file defined")
    elif exists:
        print("Alternate file exists")
    else:
        print("Alternate file defined but does not exist")
except ImportError:
    print("Projectionist is not installed")

发展规划

• 支持更多原始的projectionist功能，如type、console、dispatch。

致谢

Projectionist 是vim-projectionist 插件的 Sublime Text 实现，因此所有的荣誉都归功于这个出色的 Vim 插件的作者和维护者。

演示