Contents

• Glorified Copy 'n' Paste
  • Preface
  • Usage
  • Templates
  • File templates
  • Directory templates
  • Project templates
  • Generic (snippet/template) special files
    • _gcnp.py
      • _gcnp_path
      • _gcnp_filters
      • _gcnp_tests
  • Template special files
    • _gcnp.meta, _gcnp_post.meta
  • Tags (extensions) basics
  • Generic (snippet/template) tags
    • field
    • field_get
    • field_set
    • meta
    • time
  • Directory/project template only tags
    • copy
    • directory
    • export
    • file
    • ignore
    • rename
  • Variables
    • __gcnp__
    • cache
    • field_get
    • field_set
    • file
    • path
    • project
  • Snippets
  • Commands
    • gcnp_browse_snippet
    • gcnp_browse_template
    • gcnp_snippet
    • gcnp_template
  • Settings
    • cache
    • common_path
    • destination_path
    • fields
    • file_open
    • project_open
    • snippet_path
    • strip_name_from_path
    • template_path

Glorified Copy 'n' Paste

Preface

Glorified Copy 'n' Paste is a Sublime Text 3 plugin which adds support for creating files, directories and projects from Jinja2 based templates. Additionally it has snippet functionality.

Before continuing, please consult Jinja2's Template Designer Documentation.

Usage

To see possible usage of GCnP you can check out repository with my own templates.

Templates

Templates for GCnP are stored in a directory specified by template_path option. Only direct descendants of that directory are considered to be templates and there are three types of them:

• File
• Directory
• Project

Files and directories starting with _ will be considered to be templates by GCnP but will be hidden from template selection.

For file and directory templates, destination directories are selected in order of:

• First, directory of currently open file
• If no file is open, then directory of currently open project
• Else, directory specified by destination_path option

For project templates, destination_path is used unconditionally.

File templates

File templates are what you'd expect - single file templates. They do not support some of tags added by GCnP, as it would not make much sense for them to do so.

Directory templates

Directory templates are collections of file templates and they are rendered recursively, that means a directory template can contain other directories (which won't be considered templates themselves).

Project templates

Project templates are special case of directory templates, as they have to contain a file named <template_name>.sublime-project in their root directory, where <template_name> is the name of the directory itself. For example, when there exist a file <template_path>/sometemplate/sometemplate.sublime-project, then sometemplate will be a project template. *.sublime-project files can be empty, but don't have to, also '.' will be added to project's folders when rendering as well as all fields set to be saved. SEE: _gcnp_path

Generic (snippet/template) special files

_gcnp.py

There can be a file named _gcnp.py directly in the both snippet_path and template_path, which will be imported and its public contents will be available in every snippet and template as context variables. This allows to create custom functions extending GCnP capabilities. SEE: cache variable

_gcnp_path

_gcnp_path is a special function which allows to modify destination path for project templates only:

_gcnp_path(destination, template)

destination is the destination_path option value.

template is the template name.

NOTE: It has to return a complete path.

_gcnp_filters

_gcnp_filters is a special dictionary containing additional filters for Jinja2 templates:

// 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 is a special dictionary containing additional tests for Jinja2 templates:

// 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 %}

Template special files

_gcnp.meta, _gcnp_post.meta

Each directory in template_path be it a template or a subdirectory of one, can contain a file named _gcnp.meta which is rendered by Jinja2 before any other and _gcnp_post.meta which is rendered in the end. Both files' output will be discarded.

Tags (extensions) basics

GCnP extends Jinja2 by adding few tags which allow for more control over template contents.

Generic (snippet/template) tags

field

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

name is an identifier of field.

label (optional) is a label to be displayed when asking user for input.

default (optional) is a default value, or a list of possible choices.

save (optional) controls whether field value will be saved in project.

multiple (optional) controls whether field can have multiple values.

Field tag allows to define fields used by field_get. When multiple is True and default is a list, then the user will be presented with a list of fields which allows toggling multiple values to be then passed as a list to the template. NOTE: Regardless of save's value, field's value will be reused during rendering of current template. SEE: field_get, field_set, field_get variable, field_set variable, fields.

Example:

{% 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 is an identifier of field.

ask (optional) controls whether user will be asked for input even when there's already a value for the field.

Field_get tag allows to ask user interactively for input. If ask is not True (default), previous value will be reused. NOTE: If ask is True and field is a single-value input, then previously entered value will be prefilled instead of the default one. If it is a multi-value selection, then previously selected values will be marked as such and can be unselected as desired. In case of multi-value input, entry box will be empty and values will be appended to those already stored, if you want them to be forgotten, use field_set with None argument.

Example:

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

field_set

{% field_set name, value %}

name is an identifier of field.

value is the value to be set or None to clear field and ask user for a value on next field_get.

Field_set tag allows to change value of a field, or clear previous entries for multi-value ones.

Example:

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

meta

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

post (optional) controls whether the block will be run after template was rendered to a file. NOTE: Setting post to True will not work in snippets, as it doesn't make any sense.

Meta tag parses all its children, but discards their output. Optionally it can be set to run after the template output was written to a file.

Example:

{% 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 is a strftime format.

Time tag outputs current time formatted according to format. NOTE: Timestamp is stored at the execution of Sublime's gcnp command, so it will not change between files.

Directory/project template only tags

copy

{% copy[ pattern] %}

pattern (optional) is a python's fnmatch glob pattern. If not specified, current file will be used, except for _gcnp.meta or _gcnp_post.meta in which case whole directory will be copied as-is.

Copy tag can be used to prevent Jinja2 from rendering a file or a directory, so that they will be copied as-is.

Example:

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

directory

{% directory template[, destination] %}

template is a template name. NOTE: In this case project templates are not considered to be directories.

destination (optional) is a destination name, if not specified, template name will be used. NOTE: This argument is a name, not a path.

Directory tag can be used to dynamically include a directory template in directory of current file.

Example:

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

export

{% export variable %}

variable is a name of variable from template.

Export tag can be used to export a variable for use in subsequent files.

Example:

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

file

{% file template[, destination] %}

template is a template name.

destination (optional) is a destination name, if not specified, template name will be used. NOTE: This argument is a name, not a path.

File tag can be used to dynamically include a file template in directory of current file.

Example:

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

ignore

{% ignore[ pattern] %}

pattern (optional) is a python's fnmatch glob pattern. If not specified, current file will be used, except for _gcnp.meta or _gcnp_post.meta in which case whole directory will be ignored.

Ignore tag can be used to ignore a file or directory completely.

Example:

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

rename

{% rename a[, b] %}

If b (optional) is not specified, a will be used as name for current file, or directory if current file is _gcnp.meta or _gcnp_post.meta. Otherwise a will be the file/directory to be renamed and b will be target name. NOTE: Target is a name, not a path.

Example:

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

Variables

GCnP also adds a few predefined variables to template context.

__gcnp__

__gcnp__ is an internal variable required for GCnP to function properly, do not modify it, or else...

cache

To work around Jinja2 immutability of the context, GCnP provides an empty dictionary which can be used in helper functions, to store any data for the duration of template rendering. SEE: _gcnp.py

Example:

@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 is an identifier of field.

Field is a function, which accepts only one argument and is equivalent to using field_get tag.

Example:

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

field_set

field_set(name, value)

name is an identifier of field.

value is the value to be set or None to clear field and ask user for a value on next field_get.

Field is a function, which accepts two arguments and is equivalent to using field_set tag.

Example:

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

file

File contains currently rendered file source path.

path

Path contains destination path of currently rendered file.

project

When rendering project template, project will contain its name.

Snippets

Snippets for GCnP are stored in subdirectories of a directory specified by snippet_path option. Subdirectories are selectors like source.python or text.restructuredtext, which are scored by Sublime and used in lowest to highest score order. That means if both source and source.python contain function snippet, then in a Python file snippet from source.python will be used. SEE: Generic (snippet/template) tags, Generic (snippet/template) special files

Commands

You can add your own command invocations to <package_path>/User/Glorified Copy 'n' Paste.sublime-commands.

gcnp_browse_snippet

gcnp_browse_snippet command opens snippet_path in file manager.

gcnp_browse_template

gcnp_browse_template command opens template_path in file manager.

gcnp_snippet

gcnp_snippet command asks user for snippet name and then renders the selected one.

gcnp_template

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

destination override destination path.

directory controls whether directory templates will be presented to user.

file controls whether file templates will be presented to user.

project controls whether project templates will be presented to user.

regex if specified is a regular expression. Only templates matching it will be shown.

gcnp_template command asks user for template name, and a destination path, then renders the selected one.

Example:

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

Settings

NOTE: destination_path and template_path can be:

• Absolute paths (/home/user/Templates)
• Paths relative to user's home directory if the first character is ~ (~/Templates)
• Paths relative to Sublime's package directory otherwise (User/Glorified Copy 'n' Paste)

cache

Cache option is for internal use of GCnP, do not modify it.

common_path

Common_path is used by both snippets and templates. NOTE: _gcnp.py in this directory is not treated in any special way, it's just a template file.

destination_path

Destination_path is the default destination path for new projects, or other templates when no file or project is open.

fields

Fields is an identifier:value mapping, which stores default values for fields.

Example:

"fields": {
    "name": "Michał Przybyś",
    "email": "michal@przybys.eu",
    "license": "BSD"
}

file_open

Controls whether new files should be opened after rendering.

project_open

Controls whether new projects should be opened after rendering.

snippet_path

Path to snippet directory.

strip_name_from_path

Remove the last element from destination path when querying user for it.

template_path

Path to template directory.