75 lines
19 KiB
HTML
75 lines
19 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" id="search-form" action="../../search/"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../../">Home</a></li><li><a class="toctext" href="../package_generation/">Package Generation</a></li><li><a class="toctext" href="../plugins/">Plugins</a></li><li class="current"><a class="toctext" href>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/">Licenses</a></li><li><a class="toctext" href="../">Index</a></li></ul></nav><article id="docs"><header><nav><ul><li><a href>Plugin Development</a></li></ul><a class="edit-page" href="https://github.com/invenia/PkgTemplates.jl/blob/master/docs/src/pages/plugin_development.md#L"><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><section class="docstring"><div class="docstring-header"><a class="docstring-binding" id="PkgTemplates.Plugin" href="#PkgTemplates.Plugin"><code>PkgTemplates.Plugin</code></a> — <span class="docstring-category">Type</span>.</div><div><div><p>A plugin to be added to a <a href="../package_generation/#PkgTemplates.Template"><code>Template</code></a>, which adds some functionality or integration. New plugins should almost always extend <a href="#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a> or <a href="#PkgTemplates.CustomPlugin"><code>CustomPlugin</code></a>.</p></div></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/PkgTemplates.jl#LL29-L32">source</a></section><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><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
|
||
|
|
gitignore::Vector{AbstractString}
|
||
|
|
src::Union{AbstractString, Nothing}
|
||
|
|
dest::AbstractString
|
||
|
|
badges::Vector{Badge}
|
||
|
|
view::Dict{String, Any}
|
||
|
|
|
||
|
|
function MyPlugin(; config_file::Union{AbstractString, Nothing}="")
|
||
|
|
if config_file != nothing
|
||
|
|
config_file = if isempty(config_file)
|
||
|
|
joinpath(DEFAULTS_DIR, "my-plugin.toml")
|
||
|
|
elseif isfile(config_file)
|
||
|
|
abspath(config_file)
|
||
|
|
else
|
||
|
|
throw(ArgumentError(
|
||
|
|
"File $(abspath(config_file)) does not exist"
|
||
|
|
))
|
||
|
|
end
|
||
|
|
end
|
||
|
|
new(
|
||
|
|
["*.mgp"],
|
||
|
|
config_file,
|
||
|
|
".my-plugin.toml",
|
||
|
|
[
|
||
|
|
Badge(
|
||
|
|
"My Plugin",
|
||
|
|
"https://myplugin.com/badge-{{YEAR}}.png",
|
||
|
|
"https://myplugin.com/{{USER}}/{{PKGNAME}}.jl",
|
||
|
|
),
|
||
|
|
],
|
||
|
|
Dict{String, Any}("YEAR" => year(today())),
|
||
|
|
)
|
||
|
|
end
|
||
|
|
end
|
||
|
|
|
||
|
|
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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/plugin.jl#LL1-L67">source</a></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><div><p>Custom plugins are plugins whose behaviour does not follow the <a href="#PkgTemplates.GenericPlugin"><code>GenericPlugin</code></a> pattern. They can implement <a href="#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <a href="#PkgTemplates.badges"><code>badges</code></a>, and <a href="#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><code class="language-julia">@auto_hash_equals struct MyPlugin <: CustomPlugin
|
||
|
|
gitignore::Vector{AbstractString}
|
||
|
|
lucky::Bool
|
||
|
|
|
||
|
|
MyPlugin() = new([], rand() > 0.8)
|
||
|
|
|
||
|
|
function gen_plugin(p::MyPlugin, t::Template, pkg_name::AbstractString)
|
||
|
|
return if p.lucky
|
||
|
|
text = substitute("You got lucky with {{PKGNAME}}, {{USER}}!", t)
|
||
|
|
gen_file(joinpath(t.dir, pkg_name, ".myplugin.yml"), text)
|
||
|
|
[".myplugin.yml"]
|
||
|
|
else
|
||
|
|
println("Maybe next time.")
|
||
|
|
String[]
|
||
|
|
end
|
||
|
|
end
|
||
|
|
|
||
|
|
function badges(p::MyPlugin, user::AbstractString, pkg_name::AbstractString)
|
||
|
|
return if p.lucky
|
||
|
|
[
|
||
|
|
format(Badge(
|
||
|
|
"You got lucky!",
|
||
|
|
"https://myplugin.com/badge.png",
|
||
|
|
"https://myplugin.com/$user/$pkg_name.jl",
|
||
|
|
)),
|
||
|
|
]
|
||
|
|
else
|
||
|
|
String[]
|
||
|
|
end
|
||
|
|
end
|
||
|
|
end
|
||
|
|
|
||
|
|
interactive(:Type{MyPlugin}) = MyPlugin()</code></pre><p>This plugin doesn't do much, but it demonstrates how <a href="#PkgTemplates.gen_plugin"><code>gen_plugin</code></a>, <a href="#PkgTemplates.badges"><code>badges</code></a> and <a href="#PkgTemplates.interactive"><code>interactive</code></a> can be implemented using <a href="#PkgTemplates.substitute"><code>substitute</code></a>, <a href="#PkgTemplates.gen_file"><code>gen_file</code></a>, <a href="#PkgTemplates.Badge"><code>Badge</code></a>, and <a href="#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></div></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/plugin.jl#LL87-L142">source</a></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><div><pre><code class="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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/plugin.jl#LL168-L179">source</a></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><div><pre><code class="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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/plugin.jl#LL215-L221">source</a></section><p><strong>Note</strong>: <a href="#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/#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><div><pre><code class="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
|
||
|
|
substitute(
|
||
|
|
template::AbstractString,
|
||
|
|
pkg_template::Template;
|
||
|
|
view::Dict{String, Any}=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. 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 <a href="#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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/generate.jl#LL309-L326">source</a></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><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><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><a class="source-link" target="_blank" href="https://github.com/JuliaLang/julia/blob/099e826241fca365a120df9bac9a9fede6e7bae4/base/#L0-L9">source</a></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><div><pre><code class="language-none">format(b::Badge) -> String</code></pre><p>Return <code>badge</code>'s data formatted as a Markdown string.</p></div></div><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/plugin.jl#LL161-L165">source</a></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><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><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><a class="source-link" target="_blank" href="https://github.com/invenia/PkgTemplates.jl/blob/95555df86feaea2dc7371475d716a7a9710817e8/src/generate.jl#LL290-L300">source</a></section><footer><hr/><a class="previous" href="../plugins/"><span class="direction">Previous</span><span class="title">Plugins</span></a><a class="next" href="../licenses/"><span class="direction">Next</span><span class="title">Licenses</span></a></footer></article></body></html>
|