c4dplugwiz is a command line tool and a template system that was written originally to help with creating the neccesary files and folders for a fresh CINEMA 4D plugin. It works by copying pre-existing folder structures from a template data repository to a destination specified by the user. Its usefulness comes from a token and rules based search and replace system that works on file and folder names as well as the contents of any file.
A wizard or assistant is defined to be any process that is helpful in some creational undertaking, providing means to a customizable starting point and easing the user into the steps towards some goal.
Here, the goal is the creation of Python plugins, and the means are blueprint folder structures. The files of which, embed within their contents special text that is utilized from a magic token and rules based templating system.
A blueprint folder structure is defined to be a collection of directories and files representing one type of plugin that can be created, e.g. tag plugin, command plugin, etc... While there usually is a predetermined layout of directories and subdirectories for each plugin type (see Py4D docs), the contents of any enclosed files can be determined by the user.
The source repository is defined to be the path to the parent folder that contains all blueprint folder structures.
The user supplies the following data:
- plugin ID
- plugin name
- destination path(s)
- author name (optional - see CLI args)
- org name (optional - see CLI args)
Processing is then divided into 3 main steps:
- Copy blueprint folder structure to destination
- Perform text replacements in file and directory names
- Perform text replacements in file contents
1) First, copy the blueprint folder structure corresponding to the specified plugin type from the source repository to a destination folder (there can be multiple destinations).
2) Then, loop through the directories and files of the copied folder structure and perform text replacements of magic tokens and search terms found within the file and directory names.
3) Finally, parse the contents of each file within the copied folder structure and perform magic token and rule based text replacements.
There are two systems for replacing text:
- magic tokens
- search/replace rules
A magic token is denoted by the syntax %!Datum!%, where Datum is a variable term referring to one piece of data, called a datum point. Datum points are generally concerned with project relevant metadata (who, what, when - plugin id/name, author/org, date/time).
Magic tokens can also have alternate forms, which insert a variation of the replacement text. The syntax for this is %!DatumAsForm!%. Note the adverb As (case sensitive!), which is used as a separator between the datum point and its form.
For example, if the datum point %!PluginName!% is found it will be replaced by the name of the plugin as supplied by the user. If the alternate form %!PluginNameAsID!% is found, the name of the plugin as entered by the user will be sanitized for illegal characters and transformed to CamelCase format.
There are a fixed number of variations per datum point and to find out about those, pass the -l/--list-tokens flag to the CLI.
Currently, the following datum points can be used:
- ID supplied by user with a CLI argument
- PluginName supplied by user with a CLI argument
- AuthorName supplied by user with a CLI option, or an environment variable
- OrgName supplied by user with a CLI option, or an environment variable
- Date constructed from time.strftime()
- Time constructed from time.strftime()
- DateTime constructed from time.strftime()
Note: datum point names are case sensitive!
If a datum point is used but the corresponding value can’t be retrieved, an exception is raised to avoid continuing with false information. To ensure a value is found for author and organization names, you can pass the relevant values per the CLI or set the environment variables C4DPLUGWIZ_AUTHORNAME and C4DPLUGWIZ_ORGNAME respectively.
Search and replace rules are read from a file called rules.py.
There can be multiple rules.py files at different locations, but one location will take precendence over the others as indicated in the following listing:
(with decreasing precedence)
- arbitrary file path, passed with -r/--rules-file CLI argument
- at the root level of each blueprint folder structure (plugin type local)
- at the root level of the data source repository (repository global)
Since rules.py is just a plain old Python script you can write any valid Python code but you must have a dictionary called RULES somewhere in that file, the keys of which will serve as search terms and the values as replacement terms.
Also, if you expect to make full use of non-ASCII characters, such as accented e’s or umlauts, keep in mind that you must define them in rules.py as unicode string (u'...') and set an encoding comment at the very beginning (e.g. # coding: utf-8). The same goes for strings in template Python scripts where the unicode value should be inserted: these must be unicode strings too and the file also needs a coding comment at the top.
| author: | André Berg |
|---|---|
| copyright: | 2013 Iris VFX. All rights reserved. |
| license: | Licensed under the Apache License, Version 2.0 (the “License”);n you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
| contact: |
Contents: