90 lines
20 KiB
HTML
90 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Plugin Development · PkgTemplates.jl</title><link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css" rel="stylesheet" type="text/css"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link href="../assets/documenter.css" rel="stylesheet" type="text/css"/></head><body><nav class="toc"><h1>PkgTemplates.jl</h1><select id="version-selector" onChange="window.location.href=this.value" style="visibility: hidden"></select><form class="search" action="../search.html"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../index.html">Home</a></li><li><a class="toctext" href="package_generation.html">Package Generation</a></li><li><a class="toctext" href="plugins.html">Plugins</a></li><li class="current"><a class="toctext" href="plugin_development.html">Plugin Development</a><ul class="internal"><li><a class="toctext" href="#Generic-Plugins-1">Generic Plugins</a></li><li><a class="toctext" href="#Custom-Plugins-1">Custom Plugins</a></li><li><a class="toctext" href="#Helper-Types/Functions-1">Helper Types/Functions</a></li></ul></li><li><a class="toctext" href="licenses.html">Licenses</a></li><li><a class="toctext" href="index.html">Index</a></li></ul></nav><article id="docs"><header><nav><ul><li><a href="plugin_development.html">Plugin Development</a></li></ul><a class="edit-page" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/docs/src/pages/plugin_development.md#L{line}"><span class="fa"></span> Edit on GitHub</a></nav><hr/><div id="topbar"><span>Plugin Development</span><a class="fa fa-bars" href="#"></a></div></header><h1><a class="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: <a href="plugin_development.html#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a>s and <a href="plugin_development.html#PkgTemplates.CustomPlugin"><code>CustomPlugin</code></a>s.</p><h2><a class="nav-anchor" id="Generic-Plugins-1" href="#Generic-Plugins-1">Generic Plugins</a></h2><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.GenericPlugin" href="#PkgTemplates.GenericPlugin"><code>PkgTemplates.GenericPlugin</code></a> — <span class="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.ext")</code>.</p></li><li><p><code>dest::AbstractString</code>: Path to the generated file, relative to the root of the generated package repository.</p></li><li><p><code>badges::Vector{Badge}</code>: Array of <a href="plugin_development.html#PkgTemplates.Badge"><code>Badge</code></a>s containing information used to create Markdown-formatted badges from the plugin. Entries will be run through <a href="plugin_development.html#PkgTemplates.substitute"><code>substitute</code></a>, so they may contain placeholder values.</p></li><li><p><code>view::Dict{String, Any}</code>: Additional substitutions to make in both the plugin's badges and its associated file. See <a href="plugin_development.html#PkgTemplates.substitute"><code>substitute</code></a> for details.</p></li></ul><p><strong>Example</strong></p><pre><code class="language-julia">@auto_hash_equals struct MyPlugin <: GenericPlugin
|
|
gitignore::Vector{AbstractString}
|
|
src::Nullable{AbstractString}
|
|
dest::AbstractString
|
|
badges::Vector{Badge}
|
|
view::Dict{String, Any}
|
|
|
|
function MyPlugin(; config_file::Union{AbstractString, Void}="")
|
|
if config_file != nothing
|
|
if isempty(config_file)
|
|
config_file = joinpath(DEFAULTS_DIR, "my-plugin.toml")
|
|
elseif !isfile(config_file)
|
|
throw(ArgumentError(
|
|
"File $(abspath(config_file)) does not exist"
|
|
))
|
|
end
|
|
end
|
|
new(
|
|
["*.mgp"],
|
|
config_file,
|
|
".myplugin.yml",
|
|
[
|
|
Badge(
|
|
"My Plugin",
|
|
"https://myplugin.com/badge-{{YEAR}}.png",
|
|
"https://myplugin.com/{{USER}}/{{PKGNAME}}.jl",
|
|
),
|
|
],
|
|
Dict{String, Any}("YEAR" => Dates.year(Dates.today())),
|
|
)
|
|
end
|
|
end
|
|
|
|
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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/plugin.jl#LL1-L65">source</a><br/></section><h2><a class="nav-anchor" id="Custom-Plugins-1" href="#Custom-Plugins-1">Custom Plugins</a></h2><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.CustomPlugin" href="#PkgTemplates.CustomPlugin"><code>PkgTemplates.CustomPlugin</code></a> — <span class="docstring-category">Type</span>.</div><div><p>Custom plugins are plugins whose behaviour does not follow the <a href="plugin_development.html#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a> pattern. They can implement <a href="plugin_development.html#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <a href="plugin_development.html#PkgTemplates.badges"><code>badges</code></a>, and <a href="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><code class="language-julia">@auto_hash_equals struct MyPlugin <: CustomPlugin
|
|
gitignore::Vector{AbstractString}
|
|
lucky::Bool
|
|
|
|
MyPlugin() = new([], rand() > 0.8)
|
|
|
|
function gen_plugin(
|
|
plugin::MyPlugin,
|
|
template::Template,
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString
|
|
)
|
|
if plugin.lucky
|
|
text = substitute(
|
|
"You got lucky with {{PKGNAME}}, {{USER}}!",
|
|
template,
|
|
)
|
|
gen_file(joinpath(dir, ".myplugin.yml"), text)
|
|
else
|
|
println("Maybe next time.")
|
|
end
|
|
end
|
|
|
|
function badges(
|
|
plugin::MyPlugin,
|
|
user::AbstractString,
|
|
pkg_name::AbstractString,
|
|
)
|
|
if plugin.lucky
|
|
return [
|
|
format(Badge(
|
|
"You got lucky!",
|
|
"https://myplugin.com/badge.png",
|
|
"https://myplugin.com/$user/$pkg_name.jl",
|
|
)),
|
|
]
|
|
else
|
|
return String[]
|
|
end
|
|
end
|
|
end
|
|
|
|
interactive(plugin_type::Type{MyPlugin}) = MyPlugin()</code></pre><p>This plugin doesn't do much, but it demonstrates how <a href="plugin_development.html#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <a href="plugin_development.html#PkgTemplates.badges"><code>badges</code></a> and <a href="plugin_development.html#PkgTemplates.interactive"><code>interactive</code></a> can be implemented using <a href="plugin_development.html#PkgTemplates.substitute"><code>substitute</code></a>, <a href="plugin_development.html#PkgTemplates.gen_file"><code>gen_file</code></a>, <a href="plugin_development.html#PkgTemplates.Badge"><code>Badge</code></a>, and <a href="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 <a href="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 <a href="https://github.com/jverzani/Mustache.jl/issues/47">here</a>).</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/plugin.jl#LL68-L136">source</a><br/></section><h3><a class="nav-anchor" id="CustomPlugin-Required-Methods-1" href="#CustomPlugin-Required-Methods-1"><code>CustomPlugin</code> Required Methods</a></h3><h4><a class="nav-anchor" id="gen_plugin-1" href="#gen_plugin-1"><code>gen_plugin</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_plugin" href="#PkgTemplates.gen_plugin"><code>PkgTemplates.gen_plugin</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">gen_plugin(
|
|
plugin::Plugin,
|
|
template::Template,
|
|
dir::AbstractString,
|
|
pkg_name::AbstractString
|
|
) -> 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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/plugin.jl#LL162-L180">source</a><br/></section><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.interactive" href="#PkgTemplates.interactive"><code>PkgTemplates.interactive</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">interactive(
|
|
plugin_type::Type{P <: Plugin};
|
|
file::Union{AbstractString, Void}="",
|
|
) -> 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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/plugin.jl#LL230-L239">source</a><br/></section><p><strong>Note</strong>: <a href="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 <a href="package_generation.html#PkgTemplates.interactive_template"><code>interactive_template</code></a>.</p><h4><a class="nav-anchor" id="badges-1" href="#badges-1"><code>badges</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.badges" href="#PkgTemplates.badges"><code>PkgTemplates.badges</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/plugin.jl#LL210-L221">source</a><br/></section><h2><a class="nav-anchor" id="Helper-Types/Functions-1" href="#Helper-Types/Functions-1">Helper Types/Functions</a></h2><h4><a class="nav-anchor" id="gen_file-1" href="#gen_file-1"><code>gen_file</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.gen_file" href="#PkgTemplates.gen_file"><code>PkgTemplates.gen_file</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/generate.jl#LL296-L306">source</a><br/></section><h4><a class="nav-anchor" id="substitute-1" href="#substitute-1"><code>substitute</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.substitute" href="#PkgTemplates.substitute"><code>PkgTemplates.substitute</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="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 <a href="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 <a href="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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/generate.jl#LL336-L347">source</a><br/><div><pre><code class="language-none">substitute(
|
|
template::AbstractString,
|
|
pkg_template::Template;
|
|
view::Dict{String, Any}=Dict{String, Any}(),
|
|
) -> 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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/generate.jl#LL350-L359">source</a><br/></section><h4><a class="nav-anchor" id="Badge-1" href="#Badge-1"><code>Badge</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.Badge" href="#PkgTemplates.Badge"><code>PkgTemplates.Badge</code></a> — <span class="docstring-category">Type</span>.</div><div><pre><code class="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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/plugin.jl#LL139-L148">source</a><br/></section><h4><a class="nav-anchor" id="format-1" href="#format-1"><code>format</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.format" href="#PkgTemplates.format"><code>PkgTemplates.format</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="language-none">format(b::Badge)</code></pre><p>Return <code>badge</code>'s data formatted as a Markdown string.</p></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/plugin.jl#LL155-L159">source</a><br/></section><h4><a class="nav-anchor" id="version_floor-1" href="#version_floor-1"><code>version_floor</code></a></h4><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.version_floor" href="#PkgTemplates.version_floor"><code>PkgTemplates.version_floor</code></a> — <span class="docstring-category">Function</span>.</div><div><pre><code class="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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/063ce773ac62deace27c237c1ca3d0feacb07921/src/generate.jl#LL317-L327">source</a><br/></section><footer><hr/><a class="previous" href="plugins.html"><span class="direction">Previous</span><span class="title">Plugins</span></a><a class="next" href="licenses.html"><span class="direction">Next</span><span class="title">Licenses</span></a></footer></article></body></html>
|