内容

• 美化复制粘贴
  • 前言
  • 用法
  • 模板
  • 文件模板
  • 目录模板
  • 项目模板
  • 通用（代码片段/模板）特殊文件
    • _gcnp.py
      • _gcnp_path
      • _gcnp_filters
      • _gcnp_tests
  • 模板特殊文件
    • _gcnp.meta, _gcnp_post.meta
  • 标签（扩展）基础
  • 通用（代码片段/模板）标签
    • field
    • field_get
    • field_set
    • meta
    • time
  • 目录/项目模板专有标签
    • copy
    • directory
    • export
    • file
    • ignore
    • rename
  • 变量
    • __gcnp__
    • cache
    • field_get
    • field_set
    • file
    • path
    • project
  • 代码片段
  • 命令
    • gcnp_browse_snippet
    • gcnp_browse_template
    • gcnp_snippet
    • gcnp_template
  • 设置
    • cache
    • common_path
    • destination_path
    • fields
    • file_open
    • project_open
    • snippet_path
    • strip_name_from_path
    • template_path

美化复制粘贴

前言

美化复制粘贴是 Sublime Text 3 插件，它添加了从 Jinja2 基础模板创建文件、目录和项目支持。此外，它还具备代码片段功能。

在继续之前，请参考 Jinja2 的 模板设计文档。

用法

要查看 GCnP 的可能用法，您可以查看带有 我自己的模板 的存储库。

模板

GCnP 的模板存储在由 template_path 选项指定的目录中。只有该目录的直接子目录被视为模板，并且存在三种类型的模板：

• 文件
• 目录
• 项目

以 _ 开头的文件和目录将被 GCnP 视为模板，但将隐藏在模板选择中。

对于文件和目录模板，目标目录的排序顺序为

• 首先，当前打开文件的目录
• 如果没有打开文件，则为当前打开项目的目录。
• 否则，使用 destination_path 选项指定的目录。

对于项目模板，无条件使用 destination_path。

文件模板

文件模板就是您所期望的单个文件模板。它们不支持GCnP添加的一些标签，这样做意义不大。

目录模板

目录模板是文件模板的集合，并且它们是递归渲染的，这意味着目录模板可以包含其他目录（这些目录本身不会被视为模板）。

项目模板

项目模板是目录模板的特殊情况，因为它们必须在根目录中包含一个名为 <template_name>.sublime-project 的文件，其中 <template_name> 是目录自身的名称。例如，当存在一个文件 <template_path>/sometemplate/sometemplate.sublime-project 时，那么 sometemplate 将是一个项目模板。 *.sublime-project 文件可以是空的，但不必是空的，此外在渲染为项目时也会添加 '.' ，以及所有设置的字段都保存在项目中。 SEE: _gcnp_path

通用（代码片段/模板）特殊文件

_gcnp.py

可以直接在 snippet_path 和 template_path 中有一个名为 _gcnp.py 的文件，它将被导入，并且其公共内容将作为上下文变量在所有片段和模板中可用。这允许创建扩展GCnP功能的自定义函数。 SEE: 缓存变量

_gcnp_path

_gcnp_path 是一个特殊函数，只能修改 项目模板 的目标路径。

_gcnp_path(destination, template)

destination 是 destination_path 选项的值。

template 是模板名称。

NOTE: 它必须返回一个完整的路径。

_gcnp_filters

_gcnp_filters 是一个特殊字典，包含Jinja2模板的额外过滤器。

// In _gcnp.py
_gcnp_filters = {
    'repr': repr
}
// In a template
{% field 'version', 'Module version', '0.1.0.dev0' %}
__version__ = {{ field('version') | repr }}

_gcnp_tests

_gcnp_tests 是一个特殊字典，包含Jinja2模板的额外测试。

// In _gcnp.py
_gcnp_tests = {
    'the_answer': lambda x: x == '42'
}
// In a template
{% field 'answer', 'Your answer' %}
{% if field('answer') is the_answer %}
Yeah!
{% else %}
Lolwut?
{% endif %}

模板特殊文件

_gcnp.meta, _gcnp_post.meta

template_path 中的每个目录，无论是模板还是某个子目录，都可以包含一个名为 _gcnp.meta 的文件，它是由Jinja2在渲染其他任何内容之前执行的，以及 _gcnp_post.meta 文件，它是在最后渲染的。这两个文件的输出都将被丢弃。

标签（扩展）基础

GCnP通过添加一些允许对模板内容进行更多控制的标签来扩展Jinja2。

通用（代码片段/模板）标签

field

{% field name[, label, default, save, multiple] %}

name 是字段的一个标识符。

label （可选）在请求用户输入时显示的标签。

default （可选）默认值或可能的选项列表。

save （可选）控制字段值是否将保存到项目中。

multiple （可选）控制字段是否可以有多重值。

字段标签允许为 field_get 定义字段。当 multiple 为 True 且 default 是一个列表时，用户将看到一个允许切换多个值的字段列表，然后作为一个 list 传递给模板。 NOTE: 无视 save 的值，字段值会在当前模板的渲染过程中被重复使用。 SEE: field_get, field_set, field_get 变量, field_set 变量, 字段。

示例

{% field 'name', 'Your full name', none, true %}
Your name is: {% field_get 'name' %}.
{% field 'license', 'License', ('BSD', 'MIT', 'WTFPL'), true %}
You chose: {{ field_get('license') }} license.

field_get

{% field_get name[, ask] %}

name 是字段的一个标识符。

ask （可选）控制当字段已有值时用户是否会被询问。

Field_get 标签允许以交互方式向用户请求输入。如果 ask 不可用 True（默认情况），将重新使用先前值。 注意：如果 ask 为 True 并且字段是单个值的输入，则之前输入的值将自动填充，而不是默认值。如果是多值选择，则之前选择的值将被标记并可选择取消选择。在多值输入的情况下，输入框将留空，值将附加到已存储的值。如果您想忘记这些值，请使用带有 None 参数的 field_set。

示例

{% field 'name', 'Your full name', none, true %}
Your name is: {% field_get 'name' %}.

field_set

{% field_set name, value %}

name 是字段的一个标识符。

value 是要设置的值，或 None 以清除字段并表示在下一次 field_get 时请求值。

Field_set 标签允许更改字段的值，或者清除多值的先前条目。

示例

{% field 'python_version', 'Python version', ('2.7', '3.4'), true %}
{% field_set 'python_version', ['2.7'] %}

meta

{% meta [post] %}{% endmeta %}

post （可选） 控制是否在将模板渲染成文件之后运行此块。 注意：将 post 设置为 True 在片段中不会起作用，因为这不合逻辑。

Meta 标签解析其所有子节点，但忽略了它们的输出。可选地，它可以在将模板输出写入文件后运行。

示例

{% meta %}
    {% field 'name', 'Your name' %}
    {% field 'email', 'Your email' %}
    {% field 'city', 'City where you live' %}
    {# Ask now to ensure consistent querying order regardless of the order further down the road #}
    {% field_get 'city' %}
    {% field_get 'email' %}
    {% field_get 'name' %}
{% endmeta %}

time

{% time format %}

format 是一个 strftime 格式。

Time 标签输出当前时间，格式遵循 format。 注意：时间戳在 Sublime 的 gcnp 命令执行时存储，因此在不同文件之间不会变化。

目录/项目模板专有标签

copy

{% copy[ pattern] %}

pattern （可选） 是 python 的 fnmatch glob 模式。如果未指定，将使用当前文件，除非为 _gcnp.meta 或 _gcnp_post.meta，在这种情况下将按原样复制整个目录。

Copy 标签可以用来防止 Jinja2 渲染文件或目录，以便它们被按原样复制。

示例

{% copy %}
{% copy 'static' %}

directory

{% directory template[, destination] %}

template 是模板名称。 注意：在本例中，项目模板不被视为目录。

destination （可选） 是目标名称，如果不指定，则使用模板名称。 注意：此参数是一个名称，而不是路径。

Directory 标签可用于在当前文件的目录中动态包含目录模板。

示例

{% directory 'static' %}
{% directory 'python_package', field('package') %}

export

{% export variable %}

variable 是模板中的变量名称。

Export 标签可用于将变量导出供后续文件使用。

示例

// In _gcnp.meta
{% set something = 12345 %}
{% export 'something' %}
// In file.txt
{{ something }}

file

{% file template[, destination] %}

template 是模板名称。

destination （可选） 是目标名称，如果不指定，则使用模板名称。 注意：此参数是一个名称，而不是路径。

File 标签可用于在当前文件的目录中动态包含文件模板。

示例

{% file 'LICENSE' %}
{% file 'module.py', '__init__.py' %}

ignore

{% ignore[ pattern] %}

pattern （可选） 是 python 的 fnmatch glob 模式。如果未指定，将使用当前文件，除非为 _gcnp.meta 或 _gcnp_post.meta，在这种情况下将忽略整个目录。

Ignore 标签可用于完全忽略文件或目录。

示例

{% ignore %}
{% ignore 'somedirectory' %}
{% ignore '*.tmp' %}

rename

{% rename a[, b] %}

如果未指定 b （可选），则 a 将用作当前文件或目录的名称，如果当前文件是 _gcnp.meta 或 _gcnp_post.meta，则将使用目录。否则 a 将是要重命名的文件/目录，而 b 将为目标名称。 注意：目标是名称，而不是路径。

示例

{% rename 'ihaveanewname' %}
{% rename 'thisguy', 'hasanewname' %}

变量

GCnP 还向模板上下文添加了一些预定义的变量。

__gcnp__

__gcnp__ 是 GCnP 正确运行的必要内部变量，请不要修改它，否则...

cache

为了解决 Jinja2 上下 text 不可变的问题，GCnP 提供了一个空字典，可以在辅助函数中使用，以在模板渲染期间存储任何数据。 参见： _gcnp.py

示例

@jinja2.contextfunction
def increment(context):
    if 'increment' not in context['cache']:
        context['cache']['increment'] = 1

    context['cache']['increment'] += 1

    return context['cache']['increment']

field_get

field_get(name)

name 是字段的一个标识符。

Field 是一个函数，它只接受一个参数，与使用 field_get 标签时的作用相同。

示例

{% field 'name', 'Your full name', none, true %}
{{ field_get('name') }}

field_set

field_set(name, value)

name 是字段的一个标识符。

value 是要设置的值，或 None 以清除字段并表示在下一次 field_get 时请求值。

Field 是一个函数，它接受两个参数，与使用 field_set 标签时的作用相同。

示例

{% field 'name', 'Your full name', none, true %}
{{ field_set('name', 'John Doe') }}

file

File 包含当前渲染的文件源路径。

path

路径包含正在渲染文件的目标路径。

project

当渲染项目模板时，项目将包含其名称。

代码片段

GCnP片段存储在由snippet_path选项指定的目录的子目录中。子目录是选择器，如source.python或text.restructuredtext，由Sublime进行评分，并按从低到高的顺序使用。这意味着如果source和source.python都包含function片段，那么在Python文件中将会使用来自source.python的片段。参见： 通用（片段/模板）标签，通用（片段/模板）特殊文件

命令

您可以将自己的命令调用添加到<package_path>/User/Glorified Copy 'n' Paste.sublime-commands中。

gcnp_browse_snippet

gcnp_browse_snippet命令在文件管理器中打开snippet_path。

gcnp_browse_template

gcnp_browse_template命令在文件管理器中打开template_path。

gcnp_snippet

gcnp_snippet命令会询问用户片段名称，然后渲染所选片段。

gcnp_template

{
    "command": "gcnp_template",
    "args": {
        "destination": none,
        "directory": false,
        "file": false,
        "project": false,
        "regex": none
    }
}

目标覆盖目标路径。

目录控制是否将目录模板呈现给用户。

文件控制是否将文件模板呈现给用户。

项目控制是否将项目模板呈现给用户。

正则表达式如果指定，则是一个正则表达式。只有匹配它的模板将显示。

gcnp_template命令会询问用户模板名称和目标路径，然后渲染所选模板。

示例

{
    "caption": "Glorified Copy 'n' Paste: Python files",
    "command": "gcnp_template",
    "args": {
        "file": true,
        "regex": "[.]py$"
    }
}

设置

注意： destination_path和template_path可以是

• 绝对路径 (/home/user/Templates)
• 如果第一个字符是~,则相对于用户的主目录的路径 (~/Templates)
• 否则，相对于Sublime的包目录的路径 (User/Glorified Copy 'n' Paste)

cache

Cache选项是GCnP的内部使用，请不要修改它。

common_path

Common_path既用于片段，也用于模板。注意：此目录中的_gcnp.py没有特殊处理，只是一个模板文件。

destination_path

Destination_path是新建项目或其他模板的默认目标路径，在没有文件或项目打开的情况下。

fields

Fields是一个标识符：值映射，它存储字段的默认值。

示例

"fields": {
    "name": "Michał Przybyś",
    "email": "[email protected]",
    "license": "BSD"
}

file_open

控制渲染后是否应该打开新文件。

project_open

控制渲染后是否应该打开新项目。

snippet_path

片段目录的路径。

strip_name_from_path

当询问用户目标路径时，从目标路径中删除最后一个元素。

template_path

模板目录的路径。