<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"id="search-form"action="../../search/"><inputid="search-query"name="q"type="text"placeholder="Search docs"/></form><ul><li><aclass="toctext"href="../../">Home</a></li><li><aclass="toctext"href="../package_generation/">Package Generation</a></li><li><aclass="toctext"href="../plugins/">Plugins</a></li><liclass="current"><aclass="toctext"href>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/">Licenses</a></li><li><aclass="toctext"href="../">Index</a></li></ul></nav><articleid="docs"><header><nav><ul><li><ahref>Plugin Development</a></li></ul><aclass="edit-page"href="https://github.com/invenia/PkgTemplates.jl/blob/master/docs/src/pages/plugin_development.md#L"><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><sectionclass="docstring"><divclass="docstring-header"><aclass="docstring-binding"id="PkgTemplates.Plugin"href="#PkgTemplates.Plugin"><code>PkgTemplates.Plugin</code></a> — <spanclass="docstring-category">Type</span>.</div><div><div><p>A plugin to be added to a <ahref="../package_generation/#PkgTemplates.Template"><code>Template</code></a>, which adds some functionality or integration. New plugins should almost always extend <ahref="#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a> or <ahref="#PkgTemplates.CustomPlugin"><code>CustomPlugin</code></a>.</p></div></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/PkgTemplates.jl#LL29-L32">source</a></section><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><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><code>gitignore::Vector{AbstractString}</code>: Array of patterns to be added to the <code>.gitignore</code> of generated packages that use this plugin.</li><li><code>src::Union{AbstractString, Nothing}</code>: Path to the file that will be copied in
interactive(::Type{MyPlugin}) = interactive(MyPlugin; 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}} => year(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></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/plugin.jl#LL1-L67">source</a></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><div><p>Custom plugins are plugins whose behaviour does not follow the <ahref="#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a> pattern. They can implement <ahref="#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <ahref="#PkgTemplates.badges"><code>badges</code></a>, and <ahref="#PkgTemplates.interactive"><code>interactive</code></a> in any way they choose, as long as they conform to the usual type signature.</p><p><strong>Attributes</strong></p><ul><li><code>gitignore::Vector{AbstractString}</code>: Array of patterns to be added to the <code>.gitignore</code> of generated packages that use this plugin.</li></ul><p><strong>Example</strong></p><pre><codeclass="language-julia">@auto_hash_equals struct MyPlugin <: CustomPlugin
interactive(:Type{MyPlugin}) = MyPlugin()</code></pre><p>This plugin doesn't do much, but it demonstrates how <ahref="#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <ahref="#PkgTemplates.badges"><code>badges</code></a> and <ahref="#PkgTemplates.interactive"><code>interactive</code></a> can be implemented using <ahref="#PkgTemplates.substitute"><code>substitute</code></a>, <ahref="#PkgTemplates.gen_file"><code>gen_file</code></a>, <ahref="#PkgTemplates.Badge"><code>Badge</code></a>, and <ahref="#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></div></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/plugin.jl#LL87-L142">source</a></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><div><pre><codeclass="language-none">gen_plugin(p::Plugin, t::Template, pkg_name::AbstractString) -> Vector{String}</code></pre><p>Generate any files associated with a plugin.</p><p><strong>Arguments</strong></p><ul><li><code>p::Plugin</code>: Plugin whose files are being generated.</li><li><code>t::Template</code>: Template configuration.</li><li><code>pkg_name::AbstractString</code>: Name of the package.</li></ul><p>Returns an array of generated file/directory names.</p></div></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/plugin.jl#LL168-L179">source</a></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><div><pre><codeclass="language-none">interactive(T::Type{<:Plugin}; file::Union{AbstractString, Nothing}="") -> Plugin</code></pre><p>Interactively create a plugin of type <code>T</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></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/plugin.jl#LL215-L221">source</a></section><p><strong>Note</strong>: <ahref="#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/#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><div><pre><codeclass="language-none">badges(p::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><code>p::Plugin</code>: Plugin whose badges we are generating.</li><li><code>user::AbstractString</code>: Use
) -> 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. If <code>pkg_template</code> is supplied, some default replacements are also performed.</p><p>For information on how to structure <code>template</code>, see "Defining Template Files" section in <ahref="#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></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/generate.jl#LL309-L326">source</a></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><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><code>hover::AbstractString</code>: Text to appear when the mouse is hovered over the badge.</li><li><code>image::AbstractString</code>: URL to the image to display.</li><li><code>link::AbstractString</code>: URL to go to upon clicking the badge.</li></ul></div></div><aclass="source-link"target="_blank"href="https://github.com/JuliaLang/julia/blob/099e826241fca365a120df9bac9a9fede6e7bae4/base/#L0-L9">source</a></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><div><pre><codeclass="language-none">format(b::Badge) -> String</code></pre><p>Return <code>badge</code>'s data formatted as a Markdown string.</p></div></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/plugin.jl#LL161-L165">source</a></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><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><code>v::VersionNumber=VERSION</code>: Version to floor.</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></div><aclass="source-link"target="_blank"href="https://github.com/invenia/PkgTemplates.jl/blob/f3761d54580f9c2389d838baf895948284268a99/src/generate.jl#LL290-L300">source</a></section><footer><hr/><aclass="previous"href="../plugins/"><spanclass="direction">Previous</span><spanclass="title">Plugins</span></a><aclass="next"href="../licenses/"><spanclass="direction">Next</span><spanclass="title">Licenses</span></a></footer></article></body></html>
