<htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><title>Plugin Development · PkgTemplates.jl</title><linkhref="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"rel="stylesheet"type="text/css"/><linkhref="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"rel="stylesheet"type="text/css"/><linkhref="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"rel="stylesheet"type="text/css"/><script>documenterBaseURL=".."</script><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"data-main="../assets/documenter.js"></script><scriptsrc="../siteinfo.js"></script><scriptsrc="../../versions.js"></script><linkhref="../assets/documenter.css"rel="stylesheet"type="text/css"/></head><body><navclass="toc"><h1>PkgTemplates.jl</h1><selectid="version-selector"onChange="window.location.href=this.value"style="visibility: hidden"></select><formclass="search"action="../search.html"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../index.html">Home</a></li><li><aclass="toctext"href="package_generation.html">Package Generation</a></li><li><aclass="toctext"href="plugins.html">Plugins</a></li><liclass="current"><aclass="toctext"href="plugin_development.html">Plugin Development</a><ulclass="internal"><li><aclass="toctext"href="#Generic-Plugins-1">Generic Plugins</a></li><li><aclass="toctext"href="#Custom-Plugins-1">Custom Plugins</a></li><li><aclass="toctext"href="#Helper-Types/Functions-1">Helper Types/Functions</a></li></ul></li><li><aclass="toctext"href="licenses.html">Licenses</a></li><li><aclass="toctext"href="index.html">Index</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref="plugin_development.html">Plugin Development</a></li></ul><aclass="edit-page"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/docs/src/pages/plugin_development.md#L{line}"><spanclass="fa"></span> Edit on GitHub</a></nav><hr/><divid="topbar"><span>Plugin Development</span><aclass="fa fa-bars"href="#"></a></div></header><h1><aclass="nav-anchor"id="Plugin-Development-1"href="#Plugin-Development-1">Plugin Development</a></h1><p>The best and easiest way to contribute to <code>PkgTemplates</code> is to write new plugins.</p><p>There are two types of plugins: <ahref="plugin_development.html#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a>s and <ahref="plugin_development.html#PkgTemplates.CustomPlugin"><code>CustomPlugin</code></a>s.</p><h2><aclass="nav-anchor"id="Generic-Plugins-1"href="#Generic-Plugins-1">Generic Plugins</a></h2><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.GenericPlugin"href="#PkgTemplates.GenericPlugin"><code>PkgTemplates.GenericPlugin</code></a> — <spanclass="docstring-category">Type</span>.</div><div><p>Generic plugins are plugins that add any number of patterns to the generated package's <code>.gitignore</code>, and have at most one associated file to generate.</p><p><strong>Attributes</strong></p><ul><li><p><code>gitignore::Vector{AbstractString}</code>: Array of patterns to be added to the <code>.gitignore</code> of generated packages that use this plugin.</p></li><li><p><code>src::Nullable{AbstractString}</code>: Path to the file that will be copied into the generated package repository. If set to <code>nothing</code>, no file will be generated. When this defaults to an empty string, there should be a default file in <code>defaults</code> that will be copied. That file's name is usually the same as the plugin's name, except in all lowercase and with the <code>.yml</code> extension. If this is not the case, an <code>interactive</code> method needs to be implemented to call <code>interactive(; file="file.
interactive(plugin_type::Type{MyPlugin}) = interactive(plugin_type; file="my-plugin.toml")</code></pre><p>The above plugin ignores files ending with <code>.mgp</code>, copies <code>defaults/my-plugin.toml</code> by default, and creates a badge that links to the project on its own site, using the default substitutions with one addition: <code>{{YEAR}} => Dates.year(Dates.today())</code>. Since the default config template file doesn't follow the generic naming convention, we added another <code>interactive</code> method to correct the assumed filename.</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/plugin.jl#LL1-L65">source</a><br/></section><h2><aclass="nav-anchor"id="Custom-Plugins-1"href="#Custom-Plugins-1">Custom Plugins</a></h2><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.CustomPlugin"href="#PkgTemplates.CustomPlugin"><code>PkgTemplates.CustomPlugin</code></a> — <spanclass="docstring-category">Type</span>.</div><div><p>Custom plugins are plugins whose behaviour does not follow the <ahref="plugin_development.html#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a> pattern. They can implement <ahref="plugin_development.html#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <ahref="plugin_development.html#PkgTemplates.badges"><code>badges</code></a>, and <ahref="plugin_development.html#PkgTemplates.interactive"><code>interactive</code></a> in any way they choose.</p><p><strong>Attributes</strong></p><ul><li><p><code>gitignore::Vector{AbstractString}</code>: Array of patterns to be added to the <code>.gitignore</code> of generated packages that use this plugin.</p></li></ul><p><strong>Example</strong></p><pre><codeclass="language-julia">@auto_hash_equals struct MyPlugin <: CustomPlugin
interactive(plugin_type::Type{MyPlugin}) = MyPlugin()</code></pre><p>This plugin doesn't do much, but it demonstrates how <ahref="plugin_development.html#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <ahref="plugin_development.html#PkgTemplates.badges"><code>badges</code></a> and <ahref="plugin_development.html#PkgTemplates.interactive"><code>interactive</code></a> can be implemented using <ahref="plugin_development.html#PkgTemplates.substitute"><code>substitute</code></a>, <ahref="plugin_development.html#PkgTemplates.gen_file"><code>gen_file</code></a>, <ahref="plugin_development.html#PkgTemplates.Badge"><code>Badge</code></a>, and <ahref="plugin_development.html#PkgTemplates.format"><code>format</code></a>.</p><p><strong>Defining Template Files</strong></p><p>Often, the contents of the config file that your plugin generates depends on variables like the package name, the user's username, etc. Template files (which are stored in <code>defaults</code>) can use <ahref="https://github.com/jverzani/Mustache.jl">here</a>'s syntax to define replacements.</p><p><strong>Note</strong>: Due to a bug in <code>Mustache</code>, conditionals can insert undesired newlines (more detail <ahref="https://github.com/jverzani/Mustache.jl/issues/47">here</a>).</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/plugin.jl#LL68-L135">source</a><br/></section><h3><aclass="nav-anchor"id="CustomPlugin-Required-Methods-1"href="#CustomPlugin-Required-Methods-1"><code>CustomPlugin</code> Required Methods</a></h3><h4><aclass="nav-anchor"id="gen_plugin-1"href="#gen_plugin-1"><code>gen_plugin</code></a></h4><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.gen_plugin"href="#PkgTemplates.gen_plugin"><code>PkgTemplates.gen_plugin</code></a> — <spanclass="docstring-category">Function</span>.</div><div><pre><codeclass="language-none">gen_plugin(
) -> Vector{String}</code></pre><p>Generate any files associated with a plugin.</p><p><strong>Arguments</strong></p><ul><li><p><code>plugin::Plugin</code>: Plugin whose files are being generated.</p></li><li><p><code>template::Template</code>: Template configuration.</p></li><li><p><code>dir::AbstractString</code>: The directory in which the files will be generated. Note that this will be joined to <code>pkg_name</code>.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li></ul><p>Returns an array of generated file/directory names.</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/plugin.jl#LL161-L179">source</a><br/></section><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.interactive"href="#PkgTemplates.interactive"><code>PkgTemplates.interactive</code></a> — <spanclass="docstring-category">Function</span>.</div><div><pre><codeclass="language-none">interactive(
) -> Plugin</code></pre><p>Interactively create a plugin of type <code>plugin_type</code>, where <code>file</code> is the plugin type's default config template with a non-standard name (for <code>MyPlugin</code>, this is anything but "myplugin.yml").</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/plugin.jl#LL229-L238">source</a><br/></section><p><strong>Note</strong>: <ahref="plugin_development.html#PkgTemplates.interactive"><code>interactive</code></a> is not strictly required, however without it, your custom plugin will not be available when creating templates with <ahref="package_generation.html#PkgTemplates.interactive_template"><code>interactive_template</code></a>.</p><h4><aclass="nav-anchor"id="badges-1"href="#badges-1"><code>badges</code></a></h4><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.badges"href="#PkgTemplates.badges"><code>PkgTemplates.badges</code></a> — <spanclass="docstring-category">Function</span>.</div><div><pre><codeclass="language-none">badges(plugin::Plugin, user::AbstractString, pkg_name::AbstractString) -> Vector{String}</code></pre><p>Generate Markdown badges for the plugin.</p><p><strong>Arguments</strong></p><ul><li><p><code>plugin::Plugin</code>: Plugin whose badges we are generating.</p></li><li><p><code>user::AbstractString</code>: Username of the package creator.</p></li><li><p><code>pkg_name::AbstractString</code>: Name of the package.</p></li></ul><p>Returns an array of Markdown badges.</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/plugin.jl#LL209-L220">source</a><br/></section><h2><aclass="nav-anchor"id="Helper-Types/Functions-1"href="#Helper-Types/Functions-1">Helper Types/Functions</a></h2><h4><aclass="nav-anchor"id="gen_file-1"href="#gen_file-1"><code>gen_file</code></a></h4><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.gen_file"href="#PkgTemplates.gen_file"><code>PkgTemplates.gen_file</code></a> — <spanclass="docstring-category">Function</span>.</div><div><pre><codeclass="language-none">gen_file(file_path::AbstractString, text::AbstractString) -> Int</code></pre><p>Create a new file containing some given text. Always ends the file with a newline.</p><p><strong>Arguments</strong></p><ul><li><p><code>file::AbstractString</code>: Path to the file to be created.</p></li><li><p><code>text::AbstractString</code>: Text to write to the file.</p></li></ul><p>Returns the number of bytes written to the file.</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL344-L354">source</a><br/></section><h4><aclass="nav-anchor"id="substitute-1"href="#substitute-1"><code>substitute</code></a></h4><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.substitute"href="#PkgTemplates.substitute"><code>PkgTemplates.substitute</code></a> — <spanclass="docstring-category">Function</span>.</div><div><pre><codeclass="language-none">substitute(template::AbstractString, view::Dict{String, Any}) -> String</code></pre><p>Replace placeholders in <code>template</code> with values in <code>view</code> via <ahref="https://github.com/jverzani/Mustache.jl"><code>Mustache</code></a>. <code>template</code> is not modified.</p><p>For information on how to structure <code>template</code>, see "Defining Template Files" section in <ahref="plugin_development.html#Custom-Plugins-1">Custom Plugins</a>.</p><p><strong>Note</strong>: Conditionals in <code>template</code> without a corresponding key in <code>view</code> won't error, but will simply be evaluated as false.</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4ca
) -> String</code></pre><p>Replace placeholders in <code>template</code>, using some default replacements based on the <code>pkg_template</code> and additional ones in <code>view</code>. <code>template</code> is not modified.</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL398-L407">source</a><br/></section><h4><aclass="nav-anchor"id="Badge-1"href="#Badge-1"><code>Badge</code></a></h4><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.Badge"href="#PkgTemplates.Badge"><code>PkgTemplates.Badge</code></a> — <spanclass="docstring-category">Type</span>.</div><div><pre><codeclass="language-none">Badge(hover::AbstractString, image::AbstractString, link::AbstractString) -> Badge</code></pre><p>A <code>Badge</code> contains the data necessary to generate a Markdown badge.</p><p><strong>Arguments</strong></p><ul><li><p><code>hover::AbstractString</code>: Text to appear when the mouse is hovered over the badge.</p></li><li><p><code>image::AbstractString</code>: URL to the image to display.</p></li><li><p><code>link::AbstractString</code>: URL to go to upon clicking the badge.</p></li></ul></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/plugin.jl#LL138-L147">source</a><br/></section><h4><aclass="nav-anchor"id="format-1"href="#format-1"><code>format</code></a></h4><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.format"href="#PkgTemplates.format"><code>PkgTemplates.format</code></a> — <spanclass="docstring-category">Function</span>.</div><div><pre><codeclass="language-none">format(b::Badge)</code></pre><p>Return <code>badge</code>'s data formatted as a Markdown string.</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/plugin.jl#LL154-L158">source</a><br/></section><h4><aclass="nav-anchor"id="version_floor-1"href="#version_floor-1"><code>version_floor</code></a></h4><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.version_floor"href="#PkgTemplates.version_floor"><code>PkgTemplates.version_floor</code></a> — <spanclass="docstring-category">Function</span>.</div><div><pre><codeclass="language-none">version_floor(v::VersionNumber=VERSION) -> String</code></pre><p>Format the given Julia version.</p><p><strong>Keyword arguments</strong></p><ul><li><p><code>v::VersionNumber=VERSION</code>: Version to floor.</p></li></ul><p>Returns "major.minor" for the most recent release version relative to v. For prereleases with v.minor == v.patch == 0, returns "major.minor-".</p></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/ca8788d2d41b2ddc27d26eba4cac02f9de09bf0d/src/generate.jl#LL365-L375">source</a><br/></section><footer><hr/><aclass="previous"href="plugins.html"><spanclass="direction">Previous</span><spanclass="title">Plugins</span></a><aclass="next"href="licenses.html"><spanclass="direction">Next</span><spanclass="title">Licenses</span></a></footer></article></body></html>
