PkgTemplates Developer Guide
PkgTemplates can be easily extended by adding new Plugins.
There are two types of plugins: Plugin and FilePlugin.
PkgTemplates.Plugin — TypePlugins are PkgTemplates' source of customization and extensibility. Add plugins to your Templates to enable extra pieces of repository setup.
When implementing a new plugin, subtype this type to have full control over its behaviour.
PkgTemplates.FilePlugin — TypeA simple plugin that, in general, creates a single file.
Template + Package Creation Pipeline
The Template constructor basically does this:
- extract values from keyword arguments
+Developer Guide · PkgTemplates.jl PkgTemplates Developer Guide
PkgTemplates can be easily extended by adding new Plugins.
There are two types of plugins: Plugin and FilePlugin.
PkgTemplates.Plugin — TypePlugins are PkgTemplates' source of customization and extensibility. Add plugins to your Templates to enable extra pieces of repository setup.
When implementing a new plugin, subtype this type to have full control over its behaviour.
sourcePkgTemplates.FilePlugin — TypeA simple plugin that, in general, creates a single file.
sourceTemplate + Package Creation Pipeline
The Template constructor basically does this:
- extract values from keyword arguments
- create a Template from the values
- for each plugin:
- - validate plugin against the template
The plugin validation step uses the validate function. It lets us catch mistakes before we try to generate packages.
PkgTemplates.validate — Functionvalidate(::Plugin, ::Template)
Perform any required validation for a Plugin.
It is preferred to do validation here instead of in prehook, because this function is called at Template construction time, whereas the prehook is only run at package generation time.
sourceThe package generation process looks like this:
- create empty directory for the package
+ - validate plugin against the template
The plugin validation step uses the validate function. It lets us catch mistakes before we try to generate packages.
PkgTemplates.validate — Functionvalidate(::Plugin, ::Template)
Perform any required validation for a Plugin.
It is preferred to do validation here instead of in prehook, because this function is called at Template construction time, whereas the prehook is only run at package generation time.
sourceThe package generation process looks like this:
- create empty directory for the package
- for each plugin, ordered by priority:
- run plugin prehook
- for each plugin, ordered by priority:
- run plugin hook
- for each plugin, ordered by priority:
- - run plugin posthook
As you can tell, plugins play a central role in setting up a package.
The three main entrypoints for plugins to do work are the prehook, the hook, and the posthook. As the names might imply, they basically mean "before the main stage", "the main stage", and "after the main stage", respectively.
Each stage is basically identical, since the functions take the exact same arguments. However, the multiple stages allow us to depend on artifacts of the previous stages. For example, the Git plugin uses posthook to commit all generated files, but it wouldn't make sense to do that before the files are generated.
But what about dependencies within the same stage? In this case, we have priority to define which plugins go when. The Git plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).
PkgTemplates.prehook — Functionprehook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 1 of the package generation process (the "before" stage, in general). At this point, pkg_dir is an empty directory that will eventually contain the package, and neither the hooks nor the posthooks have run.
Note pkg_dir only stays empty until the first plugin chooses to create a file. See also: priority.
sourcePkgTemplates.hook — Functionhook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 2 of the package generation pipeline (the "main" stage, in general). At this point, the prehooks have run, but not the posthooks.
pkg_dir is the directory in which the package is being generated (so basename(pkg_dir) is the package name).
Note You usually shouldn't implement this function for FilePlugins. If you do, it should probably invoke the generic method (otherwise, there's not much reason to subtype FilePlugin).
sourcePkgTemplates.posthook — Functionposthook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 3 of the package generation pipeline (the "after" stage, in general). At this point, both the prehooks and hooks have run.
sourcePkgTemplates.priority — Functionpriority(::Plugin, ::Union{typeof(prehook), typeof(hook), typeof(posthook)}) -> Int
Determines the order in which plugins are processed (higher goes first). The default priority (DEFAULT_PRIORITY), is 1000.
You can implement this function per-stage (by using ::typeof(hook), for example), or for all stages by simply using ::Function.
sourcePlugin Walkthrough
Concrete types that subtype Plugin directly are free to do almost anything. To understand how they're implemented, let's look at simplified versions of two plugins: Documenter to explore templating, and Git to further clarify the multi-stage pipeline.
Example: Documenter
@plugin struct Documenter <: Plugin
+ - run plugin posthook
As you can tell, plugins play a central role in setting up a package.
The three main entrypoints for plugins to do work are the prehook, the hook, and the posthook. As the names might imply, they basically mean "before the main stage", "the main stage", and "after the main stage", respectively.
Each stage is basically identical, since the functions take the exact same arguments. However, the multiple stages allow us to depend on artifacts of the previous stages. For example, the Git plugin uses posthook to commit all generated files, but it wouldn't make sense to do that before the files are generated.
But what about dependencies within the same stage? In this case, we have priority to define which plugins go when. The Git plugin also uses this function to lower its posthook's priority, so that even if other plugins generate files in their posthooks, they still get committed (provided that those plugins didn't set an even lower priority).
PkgTemplates.prehook — Functionprehook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 1 of the package generation process (the "before" stage, in general). At this point, pkg_dir is an empty directory that will eventually contain the package, and neither the hooks nor the posthooks have run.
Note pkg_dir only stays empty until the first plugin chooses to create a file. See also: priority.
sourcePkgTemplates.hook — Functionhook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 2 of the package generation pipeline (the "main" stage, in general). At this point, the prehooks have run, but not the posthooks.
pkg_dir is the directory in which the package is being generated (so basename(pkg_dir) is the package name).
Note You usually shouldn't implement this function for FilePlugins. If you do, it should probably invoke the generic method (otherwise, there's not much reason to subtype FilePlugin).
sourcePkgTemplates.posthook — Functionposthook(::Plugin, ::Template, pkg_dir::AbstractString)
Stage 3 of the package generation pipeline (the "after" stage, in general). At this point, both the prehooks and hooks have run.
sourcePkgTemplates.priority — Functionpriority(::Plugin, ::Union{typeof(prehook), typeof(hook), typeof(posthook)}) -> Int
Determines the order in which plugins are processed (higher goes first). The default priority (DEFAULT_PRIORITY), is 1000.
You can implement this function per-stage (by using ::typeof(hook), for example), or for all stages by simply using ::Function.
sourcePlugin Walkthrough
Concrete types that subtype Plugin directly are free to do almost anything. To understand how they're implemented, let's look at simplified versions of two plugins: Documenter to explore templating, and Git to further clarify the multi-stage pipeline.
Example: Documenter
@plugin struct Documenter <: Plugin
make_jl::String = default_file("docs", "make.jl")
index_md::String = default_file("docs", "src", "index.md")
end
@@ -55,7 +55,7 @@ end
Implementing @plugin Manually
Remember to add a method to the function belonging to PkgTemplates, rather than creating your own function that PkgTemplates won't see.
If your plugin's fields have no sane defaults, then you'll need to implement prompt appropriately instead.
PkgTemplates.default_file — Functiondefault_file(paths::AbstractString...) -> String
Return a path relative to the default template file directory (~/build/invenia/PkgTemplates.jl/templates).
sourceThe first method we implement for Documenter is gitignore, so that packages created with this plugin ignore documentation build artifacts.
PkgTemplates.gitignore — Functiongitignore(::Plugin) -> Vector{String}
Return patterns that should be added to .gitignore. These are used by the Git plugin.
By default, an empty list is returned.
sourceSecond, we implement badges to add a couple of badges to new packages' README files.
PkgTemplates.badges — Functionbadges(::Plugin) -> Union{Badge, Vector{Badge}}
Return a list of Badges, or just one, to be added to README.md. These are used by the Readme plugin to add badges to the README.
By default, an empty list is returned.
sourcePkgTemplates.Badge — TypeBadge(hover::AbstractString, image::AbstractString, link::AbstractString)
Container for Markdown badge data. Each argument can contain placeholders, which will be filled in with values from combined_view.
Arguments
hover::AbstractString: Text to appear when the mouse is hovered over the badge.image::AbstractString: URL to the image to display.link::AbstractString: URL to go to upon clicking the badge.
sourceThese two functions, gitignore and badges, are currently the only "special" functions for cross-plugin interactions. In other cases, you can still access the Template's plugins to depend on the presence/properties of other plugins via getplugin, although that's less powerful.
PkgTemplates.getplugin — Functiongetplugin(t::Template, ::Type{T<:Plugin}) -> Union{T, Nothing}
Get the plugin of type T from the template t, if it's present.
sourceThird, we implement view, which is used to fill placeholders in badges and rendered files.
PkgTemplates.view — Functionview(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
Return the view to be passed to the text templating engine for this plugin. pkg is the name of the package being generated.
For FilePlugins, this is used for both the plugin badges (see badges) and the template file (see source). For other Plugins, it is used only for badges, but you can always call it yourself as part of your hook implementation.
By default, an empty Dict is returned.
sourceFinally, we implement hook, which is the real workhorse for the plugin. Inside of this function, we generate a couple of files with the help of a few more text templating functions.
PkgTemplates.render_file — Functionrender_file(file::AbstractString view::Dict{<:AbstractString}, tags=nothing) -> String
Render a template file with the data in view. tags should be a tuple of two strings, which are the opening and closing delimiters, or nothing to use the default delimiters.
sourcePkgTemplates.render_text — Functionrender_text(text::AbstractString, view::Dict{<:AbstractString}, tags=nothing) -> String
Render some text with the data in view. tags should be a tuple of two strings, which are the opening and closing delimiters, or nothing to use the default delimiters.
sourcePkgTemplates.gen_file — Functiongen_file(file::AbstractString, text::AbstractString)
Create a new file containing some given text. Trailing whitespace is removed, and the file will end with a newline.
sourcePkgTemplates.combined_view — Functioncombined_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}
This function combines view and user_view for use in text templating. If you're doing manual file creation or text templating (i.e. writing Plugins that are not FilePlugins), then you should use this function rather than either of the former two.
sourcePkgTemplates.tags — Functiontags(::Plugin) -> Tuple{String, String}
Return the delimiters used for text templating. See the Citation plugin for a rare case where changing the tags is necessary.
By default, the tags are "{{" and "}}".
sourceFor more information on text templating, see the FilePlugin Walkthrough and the section on Custom Template Files.
Example: Git
struct Git <: Plugin end
+PkgTemplates.defaultkw(::Type{MyPlugin}, ::Val{:x}) = "my default"
Remember to add a method to the function belonging to PkgTemplates, rather than creating your own function that PkgTemplates won't see.
If your plugin's fields have no sane defaults, then you'll need to implement prompt appropriately instead.
source