SublimeText解惑

SublimeText是我的主力编辑器，虽然已经使用几年了，还是有不少疑惑的、不甚明白的地方，例如目录结构里的道理、一些报错信息没有解决消除，个别插件使用有些问题等等，开发一些小插件时经常还要模仿着来，所以最近阅读了一些文档和博文，整理成笔记备忘。

分享我放在GitHub上的一些小插件：sublime-text-small-plugins

一些概念

buffer

Data of a loaded file and additional metadata, associated with one or more views. The distinction between buffer and view is technical. Most of the time, both terms can be used interchangeably.

view

Graphical display of a buffer. Multiple views can show the same buffer.

plugin

A feature implemented in Python, which can consist of a single command or multiple commands. It can be contained in one .py file or many .py files.

package

This term is ambiguous in the context of Sublime Text, because it can refer to a Python package (unlikely), a folder inside Packages or a .sublime-package file. Most of the time, it means a folder inside Packages containing resources that belong together, which build a new feature or provide support for a programming or markup language.

panel

An input/output widget, such as a search panel or the output panel.

overlay

An input widget of a special kind. For example, Goto Anything is an overlay.

file type

In the context of Sublime Text, file type refers to the type of file as determined by the applicable .tmLanguage syntax definition. However, this is an ambiguous term, and in some instances it could also be used with the broader meaning it has in technical texts.

Scope

Syntax definitions make Sublime Text aware of programming and markup languages. Most noticeably, they work together with colors to provide syntax highlighting. Syntax definitions define scopes that divide the text in a buffer into named regions. Several editing features in Sublime Text make extensive use of this fine-grained contextual information.

Scopes are a key concept in Sublime Text. Essentially, they are named text regions in a buffer. They don’t do anything by themselves, but Sublime Text peeks at them when it needs contextual information.

scopeName

The topmost scope for this syntax definition. It takes the form source.<lang_name> or text.<lang_name>. For programming languages, use source. For markup and everything else, use text.

Anatomy of a Command

Commands have a name separated by underscores (snake_case) like hot_exit, and can take a dictionary of arguments whose keys must be strings and whose values must be JSON types. Here are a few examples of commands run from the Python console:

view.run_command("goto_line", {"line": 10})
view.run_command('insert_snippet', {"contents": "<$SELECTION>"})
view.window().run_command("prompt_select_project")

项目与空间

项目

There is always an active project, even if you haven’t created or opened one. In this situation, you are working with an anonymous project, which has limited functionality. New windows always use an anonymous project when they first open.

Project metadata is stored in JSON files with a .sublime-project extension. Wherever there’s a .sublime-project file, you will find an ancillary .sublime-workspace file too. The .sublime-workspace file contains session data that you should never edit. (More on workspaces later.)

空间

A project can have multiple workspaces.

A common use case for workspaces is to work on different features within the same project, where each feature requires a different set of files to be open, and you want to switch between features quickly. In this case you’ll want to have a second workspace available. Writing tests could be an example for this.

You should never commit .sublime-workspace files into a source code repository. They may contain sensitive information.

插件开发

插件函数中使用的变量的来源

每一个TextCommand对应一个view，可以通过self.view访问view对象。同理WindowCommand对应一个window对象，应该根据需要选择相应的command类型。

插件的保存位置、文件命名

… …
Now save the file inside of the Prefixr folder as Prefixr.py. It doesn’t actually matter what the filename is, just that it ends in .py. However, by convention we will use the name of the plugin for the filename.

Sublime will take any class that extends one of the sublime_plugin classes (TextCommand, WindowCommand or ApplicationCommand), remove the suffix Command and then convert the CamelCaseinto underscore_notation for the command name.

Where to Store Plugins

Sublime Text will look for plugins only in these places:

• Installed Packages (only .sublime-package files)
• Packages
• Packages/<pkg_name>/
  As a consequence, any plugin nested deeper in Packages won’t be loaded.

常用的代码片段

获取当前view的内容：

self.view.substr(sublime.Region(0, self.view.size()))

检测当前view的文件扩展名，录入检测markdown：

def is_visible(self):
    return self.view.file_name() is not None and (
        self.view.file_name()[-3:] == ".md" or
        self.view.file_name()[-3:] == ".MD")

包管理

几个存放包的位置的优先位序

Interactions Between Packages with The Same Name
If two packages with the same name exist in both Installed Packages and Shipped Packages, the one in Installed Packages will be used and the one in Shipped Packages will be ignored.

Any file in Packages/PackageName takes precedence over an identically named file in Installed Packages/PackageName.sublime-package or Shipped Packages/PackageName.sublime-package.

如何修改/覆写已打包[压缩]的插件

To create an override package, create a new folder under Packages and name it after the .sublime-package file you want to override, excluding the extension. Any file you create in this package will take precedence over any identically named file in the original package.

包的加载顺序

Sublime Text loads packages in this order:

• Packages/Default;
• shipped packages in lexicographical order;
• installed packages in lexicographical order;
• all remaining user packages, except for Packages/User, that did not override anything, in lexicographical order;
• Packages/User

其它

Windows版本和数据保存位置

Portable or Not Portable?
Sublime Text comes in two flavors for Windows: normal, and portable. Most users should be better served by a normal installation. Use the portable version only if you know you need it.

Normal installations separate data between two folders: the installation folder proper, and the data directory (user-specific directory for data; explained later in this guide). Normal installations also integrate Sublime Text with File Explorer.

Portable installations keep all files needed by Sublime Text in a single folder. This folder can be moved around and the editor will still work.
Windows: %APPDATA%\Sublime Text 3

If you’re using the portable version (Windows only), look for Application/Data. Here, Application refers to the directory to which you’ve extracted the compressed portable files and where the executable resides.

Note that the Data directory only exists with that name in the portable version. In full installations, it is one of the locations indicated above.

所用的python版本

Your System’s Python vs the Sublime Text 3 Embedded Python

Sublime Text 3 comes with its own Python interpreter that’s separate from your system’s Python interpreter (if available).

The embedded interpreter is only intended to interact with the plugin API, not for general development.

快捷键

好用但易忘的快捷键

侧栏快捷键

These are common keyboard shortcuts related to the side bar:

面板布局/分栏分格快捷键

Main keyboard shortcuts related to panes:

资源

Build System

非官方英文文档 – Build Systems – Configuration

非官方翻译文档 – 构建系统

官方文档 – DOCUMENTATION Build Systems

API文档

API Reference V2

Sublime插件API手册 V2

DOCUMENTATION API Reference

开发插件的入门/参考文档

为sublime text 3开发插件

编写你的第一个sublime插件

How to Create a Sublime Text 2 Plugin

Docs » Extending Sublime Text » Plugins

参考资料

• http://docs.sublimetext.info/en/latest/index.html

-- EOF --

本文最后修改于6年前 (2019-06-07)