The ptemplate project has grown quite large, and as such some documentation is needed to facilitate hacking on it in the future, when I’ll have forgotten most details about internals, which this file tries to provide.
The snippet chain is a relatively small subsystem of ptemplate, around 150 lines as of writing (mainly due to docstrings) and is not dependent on the rest of ptemplate.
One feature, as stated in the README, is the interactive expansion of file snippets. This is facilitated with a “snippet chain”: it is a set of snippet files mapped to their targets. Pressing C-c C-c moves forward, … (see the README for that).
However, there is a problem: the snippet chain supports saving snippets for later and ptemplate must support expanding multiple templates at once, so the snippet alist (“snippet chain”) must be shared between buffers. This cannot be done with global variables however, as that would clash with ptemplate’s multiple-template expansion support.
The sharing is done by setting the same `ptemplate–snippet-chain` structure instance in each buffer, buffer-locally.
This is the core function that advances the snippet chain. It is responsible for running the finalize hook.
Starts a snippet chain. Since there is no snippet chain yet, this function
simply let-binds the snippet chain variables to the arguments, overriding their
current buffer-local values (nil, unless in a snippet chain buffer).
To support template inheritance elegantly, the state of some template needs to
be contained and merged. This is done using a copy context, which is a
structure containing all state needed to expand a template to some destination.
However, this isn’t enough to mean that a template could be loaded once and
expanded to multiple targets, because the :init block is not stored, but
executed directly instead.
In ptemplate, that context is contained within the ptemplate--copy-context
structure, the global instance of which is in ptemplate--cur-copy-context.
To allow multiple templates to be expanded at once, and to eliminate global
state, ptemplate--cur-copy-context is always let-bound before loading a
template in ptemplate--eval-template.
This macro is mainly useful in .ptemplate.el files. It transforms various :<foo>
blocks into code that modifies the global template variables, as defined above,
directly. Most keywords can be implemented using the existing copy context
fields and hooks, but sometimes new ones need to be added. See above for that.
The rest is taken care of by the ptemplate--define-copy-context macro.
- Various comments beginning with HACKING can be found in the source. They contain additional hints.