TastyPancakes/PkgTemplates.jl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Properly rename BasicPlugin -> FilePlugin

Browse Source 
How did I miss this up so bad the first time?
This commit is contained in:
Chris de Graaf 2020-04-21 23:44:48 -05:00
parent 02d416bedf
commit 353acd5d1c
No known key found for this signature in database
GPG Key ID: 150FFDD9B0073C7B
12 changed files with 56 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/src/developer.md
View File

@ -10,11 +10,11 @@ Pages = ["developer.md"]
PkgTemplates can be easily extended by adding new [`Plugin`](@ref)s. PkgTemplates can be easily extended by adding new [`Plugin`](@ref)s.
There are two types of plugins: [`Plugin`](@ref) and [`BasicPlugin`](@ref). There are two types of plugins: [`Plugin`](@ref) and [`FilePlugin`](@ref).
```@docs ```@docs
Plugin Plugin
BasicPlugin FilePlugin
``` ```
## Template + Package Creation Pipeline ## Template + Package Creation Pipeline
@ -157,7 +157,7 @@ combined_view
tags tags
``` ```
For more information on text templating, see the [`BasicPlugin` Walkthrough](@ref) and the section on [Custom Template Files](@ref). For more information on text templating, see the [`FilePlugin` Walkthrough](@ref) and the section on [Custom Template Files](@ref).
### Example: `Git` ### Example: `Git`
@ -208,16 +208,16 @@ As previously mentioned, we use [`priority`](@ref) to make sure that we wait unt
Hopefully, this demonstrates the level of control you have over the package generation process when developing plugins, and when it makes sense to exercise that power! Hopefully, this demonstrates the level of control you have over the package generation process when developing plugins, and when it makes sense to exercise that power!
## `BasicPlugin` Walkthrough ## `FilePlugin` Walkthrough
Most of the time, you don't really need all of the control that we showed off above. Most of the time, you don't really need all of the control that we showed off above.
Plugins that subtype [`BasicPlugin`](@ref) perform a much more limited task. Plugins that subtype [`FilePlugin`](@ref) perform a much more limited task.
In general, they just generate one templated file. In general, they just generate one templated file.
To illustrate, let's look at the [`Citation`](@ref) plugin, which creates a `CITATION.bib` file. To illustrate, let's look at the [`Citation`](@ref) plugin, which creates a `CITATION.bib` file.
```julia ```julia
@with_kw_noshow struct Citation <: BasicPlugin @with_kw_noshow struct Citation <: FilePlugin
file::String = default_file("CITATION.bib") file::String = default_file("CITATION.bib")
end end
@ -239,7 +239,7 @@ Similar to the `Documenter` example above, we're defining a keyword constructor,
This plugin adds nothing to `.gitignore`, and it doesn't add any badges, so implementations for [`gitignore`](@ref) and [`badges`](@ref) are omitted. This plugin adds nothing to `.gitignore`, and it doesn't add any badges, so implementations for [`gitignore`](@ref) and [`badges`](@ref) are omitted.
First, we implement [`source`](@ref) and [`destination`](@ref) to define where the template file comes from, and where it goes. First, we implement [`source`](@ref) and [`destination`](@ref) to define where the template file comes from, and where it goes.
These functions are specific to [`BasicPlugin`](@ref)s, and have no effect on regular [`Plugin`](@ref)s by default. These functions are specific to [`FilePlugin`](@ref)s, and have no effect on regular [`Plugin`](@ref)s by default.
```@docs ```@docs
source source
@ -265,17 +265,17 @@ Because the file contains its own `{}` delimiters, we need to use different ones
Finally, we implement [`view`](@ref) to fill in the placeholders that we saw in the template file. Finally, we implement [`view`](@ref) to fill in the placeholders that we saw in the template file.
## Doing Extra Work With `BasicPlugin`s ## Doing Extra Work With `FilePlugin`s
Notice that we didn't have to implement [`hook`](@ref) for our plugin. Notice that we didn't have to implement [`hook`](@ref) for our plugin.
It's implemented for all [`BasicPlugin`](@ref)s, like so: It's implemented for all [`FilePlugin`](@ref)s, like so:
```julia ```julia
function render_plugin(p::BasicPlugin, t::Template, pkg::AbstractString) function render_plugin(p::FilePlugin, t::Template, pkg::AbstractString)
return render_file(source(p), combined_view(p, t, pkg), tags(p)) return render_file(source(p), combined_view(p, t, pkg), tags(p))
end end
function hook(p::BasicPlugin, t::Template, pkg_dir::AbstractString) function hook(p::FilePlugin, t::Template, pkg_dir::AbstractString)
source(p) === nothing && return source(p) === nothing && return
pkg = basename(pkg_dir) pkg = basename(pkg_dir)
path = joinpath(pkg_dir, destination(p)) path = joinpath(pkg_dir, destination(p))
@ -294,7 +294,7 @@ Of course, we could use a normal [`Plugin`](@ref), but it turns out there's a wa
The plugin implements its own `hook`, but uses `invoke` to avoid duplicating the file creation code: The plugin implements its own `hook`, but uses `invoke` to avoid duplicating the file creation code:
```julia ```julia
@with_kw_noshow struct Tests <: BasicPlugin @with_kw_noshow struct Tests <: FilePlugin
file::String = default_file("runtests.jl") file::String = default_file("runtests.jl")
end end
@ -303,14 +303,14 @@ destination(::Tests) = joinpath("test", "runtests.jl")
view(::Tests, ::Template, pkg::AbstractString) = Dict("PKG" => pkg) view(::Tests, ::Template, pkg::AbstractString) = Dict("PKG" => pkg)
function hook(p::Tests, t::Template, pkg_dir::AbstractString) function hook(p::Tests, t::Template, pkg_dir::AbstractString)
# Do the normal BasicPlugin behaviour to create the test script. # Do the normal FilePlugin behaviour to create the test script.
invoke(hook, Tuple{BasicPlugin, Template, AbstractString}, p, t, pkg_dir) invoke(hook, Tuple{FilePlugin, Template, AbstractString}, p, t, pkg_dir)
# Do some other work. # Do some other work.
add_test_dependency() add_test_dependency()
end end
``` ```
There is also a default [`validate`](@ref) implementation for [`BasicPlugin`](@ref)s, which checks that the plugin's [`source`](@ref) file exists, and throws an `ArgumentError` otherwise. There is also a default [`validate`](@ref) implementation for [`FilePlugin`](@ref)s, which checks that the plugin's [`source`](@ref) file exists, and throws an `ArgumentError` otherwise.
If you want to extend the validation but keep the file existence check, use the `invoke` method as described above. If you want to extend the validation but keep the file existence check, use the `invoke` method as described above.
For more examples, see the plugins in the [Continuous Integration (CI)](@ref) and [Code Coverage](@ref) sections. For more examples, see the plugins in the [Continuous Integration (CI)](@ref) and [Code Coverage](@ref) sections.

22
src/plugin.jl
View File

@ -20,7 +20,7 @@ Base.print(io::IO, s::Secret) = print(io, "\${{ secrets.$(s.name) }}")
""" """
A simple plugin that, in general, creates a single file. A simple plugin that, in general, creates a single file.
""" """
abstract type FilePugin <: Plugin end abstract type FilePlugin <: Plugin end
""" """
default_file(paths::AbstractString...) -> String default_file(paths::AbstractString...) -> String
@ -36,7 +36,7 @@ default_file(paths::AbstractString...) = joinpath(TEMPLATES_DIR, paths...)
Return the view to be passed to the text templating engine for this plugin. Return the view to be passed to the text templating engine for this plugin.
`pkg` is the name of the package being generated. `pkg` is the name of the package being generated.
For [`FilePugin`](@ref)s, this is used for both the plugin badges For [`FilePlugin`](@ref)s, this is used for both the plugin badges
(see [`badges`](@ref)) and the template file (see [`source`](@ref)). (see [`badges`](@ref)) and the template file (see [`source`](@ref)).
For other [`Plugin`](@ref)s, it is used only for badges, For other [`Plugin`](@ref)s, it is used only for badges,
but you can always call it yourself as part of your [`hook`](@ref) implementation. but you can always call it yourself as part of your [`hook`](@ref) implementation.
@ -60,7 +60,7 @@ user_view(::Plugin, ::Template, ::AbstractString) = Dict{String, Any}()
This function combines [`view`](@ref) and [`user_view`](@ref) for use in text templating. This function combines [`view`](@ref) and [`user_view`](@ref) for use in text templating.
If you're doing manual file creation or text templating (i.e. writing [`Plugin`](@ref)s If you're doing manual file creation or text templating (i.e. writing [`Plugin`](@ref)s
that are not [`FilePugin`](@ref)s), then you should use this function that are not [`FilePlugin`](@ref)s), then you should use this function
rather than either of the former two. rather than either of the former two.
!!! note !!! note
@ -114,16 +114,16 @@ By default, an empty list is returned.
badges(::Plugin) = Badge[] badges(::Plugin) = Badge[]
""" """
source(::FilePugin) -> Union{String, Nothing} source(::FilePlugin) -> Union{String, Nothing}
Return the path to a plugin's template file, or `nothing` to indicate no file. Return the path to a plugin's template file, or `nothing` to indicate no file.
By default, `nothing` is returned. By default, `nothing` is returned.
""" """
source(::FilePugin) = nothing source(::FilePlugin) = nothing
""" """
destination(::FilePugin) -> String destination(::FilePlugin) -> String
Return the destination, relative to the package root, of a plugin's configuration file. Return the destination, relative to the package root, of a plugin's configuration file.
@ -192,9 +192,9 @@ At this point, the [`prehook`](@ref)s have run, but not the [`posthook`](@ref)s.
(so `basename(pkg_dir)` is the package name). (so `basename(pkg_dir)` is the package name).
!!! note !!! note
You usually shouldn't implement this function for [`FilePugin`](@ref)s. You usually shouldn't implement this function for [`FilePlugin`](@ref)s.
If you do, it should probably `invoke` the generic method If you do, it should probably `invoke` the generic method
(otherwise, there's not much reason to subtype `FilePugin`). (otherwise, there's not much reason to subtype `FilePlugin`).
""" """
hook(::Plugin, ::Template, ::AbstractString) = nothing hook(::Plugin, ::Template, ::AbstractString) = nothing
@ -206,13 +206,13 @@ At this point, both the [`prehook`](@ref)s and [`hook`](@ref)s have run.
""" """
posthook(::Plugin, ::Template, ::AbstractString) = nothing posthook(::Plugin, ::Template, ::AbstractString) = nothing
function validate(p::T, ::Template) where T <: FilePugin function validate(p::T, ::Template) where T <: FilePlugin
src = source(p) src = source(p)
src === nothing && return src === nothing && return
isfile(src) || throw(ArgumentError("$(nameof(T)): The file $src does not exist")) isfile(src) || throw(ArgumentError("$(nameof(T)): The file $src does not exist"))
end end
function hook(p::FilePugin, t::Template, pkg_dir::AbstractString) function hook(p::FilePlugin, t::Template, pkg_dir::AbstractString)
source(p) === nothing && return source(p) === nothing && return
pkg = basename(pkg_dir) pkg = basename(pkg_dir)
path = joinpath(pkg_dir, destination(p)) path = joinpath(pkg_dir, destination(p))
@ -220,7 +220,7 @@ function hook(p::FilePugin, t::Template, pkg_dir::AbstractString)
gen_file(path, text) gen_file(path, text)
end end
function render_plugin(p::FilePugin, t::Template, pkg::AbstractString) function render_plugin(p::FilePlugin, t::Template, pkg::AbstractString)
return render_file(source(p), combined_view(p, t, pkg), tags(p)) return render_file(source(p), combined_view(p, t, pkg), tags(p))
end end

12
src/plugins/ci.jl
View File

@ -44,7 +44,7 @@ $EXTRA_VERSIONS_DOC
If using coverage plugins, don't forget to manually add your API tokens as secrets, If using coverage plugins, don't forget to manually add your API tokens as secrets,
as described [here](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets). as described [here](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets).
""" """
@with_kw_noshow struct GitHubActions <: FilePugin @with_kw_noshow struct GitHubActions <: FilePlugin
file::String = default_file("github", "workflows", "ci.yml") file::String = default_file("github", "workflows", "ci.yml")
destination::String = "ci.yml" destination::String = "ci.yml"
linux::Bool = true linux::Bool = true
@ -116,7 +116,7 @@ Integrates your packages with [Travis CI](https://travis-ci.com).
Another code coverage plugin such as [`Codecov`](@ref) must also be included. Another code coverage plugin such as [`Codecov`](@ref) must also be included.
$EXTRA_VERSIONS_DOC $EXTRA_VERSIONS_DOC
""" """
@with_kw_noshow struct TravisCI <: FilePugin @with_kw_noshow struct TravisCI <: FilePlugin
file::String = default_file("travis.yml") file::String = default_file("travis.yml")
linux::Bool = true linux::Bool = true
osx::Bool = true osx::Bool = true
@ -188,7 +188,7 @@ via [AppVeyor.jl](https://github.com/JuliaCI/Appveyor.jl).
[`Codecov`](@ref) must also be included. [`Codecov`](@ref) must also be included.
$EXTRA_VERSIONS_DOC $EXTRA_VERSIONS_DOC
""" """
@with_kw_noshow struct AppVeyor <: FilePugin @with_kw_noshow struct AppVeyor <: FilePlugin
file::String = default_file("appveyor.yml") file::String = default_file("appveyor.yml")
x86::Bool = false x86::Bool = false
coverage::Bool = true coverage::Bool = true
@ -244,7 +244,7 @@ $EXTRA_VERSIONS_DOC
Code coverage submission from Cirrus CI is not yet supported by Code coverage submission from Cirrus CI is not yet supported by
[Coverage.jl](https://github.com/JuliaCI/Coverage.jl). [Coverage.jl](https://github.com/JuliaCI/Coverage.jl).
""" """
@with_kw_noshow struct CirrusCI <: FilePugin @with_kw_noshow struct CirrusCI <: FilePlugin
file::String = default_file("cirrus.yml") file::String = default_file("cirrus.yml")
image::String = "freebsd-12-0-release-amd64" image::String = "freebsd-12-0-release-amd64"
coverage::Bool = true coverage::Bool = true
@ -293,7 +293,7 @@ See [`Documenter`](@ref) for more information.
!!! note !!! note
Nightly Julia is not supported. Nightly Julia is not supported.
""" """
@with_kw_noshow struct GitLabCI <: FilePugin @with_kw_noshow struct GitLabCI <: FilePlugin
file::String = default_file("gitlab-ci.yml") file::String = default_file("gitlab-ci.yml")
coverage::Bool = true coverage::Bool = true
# Nightly has no Docker image. # Nightly has no Docker image.
@ -353,7 +353,7 @@ $EXTRA_VERSIONS_DOC
!!! note !!! note
Nightly Julia is not supported. Nightly Julia is not supported.
""" """
@with_kw_noshow struct DroneCI <: FilePugin @with_kw_noshow struct DroneCI <: FilePlugin
file::String = default_file("drone.star") file::String = default_file("drone.star")
destination::String = ".drone.star" destination::String = ".drone.star"
amd64::Bool = true amd64::Bool = true

2
src/plugins/citation.jl
View File

@ -7,7 +7,7 @@ Creates a `CITATION.bib` file for citing package repositories.
- `file::AbstractString`: Template file for `CITATION.bib`. - `file::AbstractString`: Template file for `CITATION.bib`.
- `readme::Bool`: Whether or not to include a section about citing in the README. - `readme::Bool`: Whether or not to include a section about citing in the README.
""" """
@with_kw_noshow struct Citation <: FilePugin @with_kw_noshow struct Citation <: FilePlugin
file::String = default_file("CITATION.bib") file::String = default_file("CITATION.bib")
readme::Bool = false readme::Bool = false
end end

2
src/plugins/compat_helper.jl
View File

@ -13,7 +13,7 @@ Integrates your packages with [CompatHelper](https://github.com/bcbi/CompatHelpe
relative to `.github/workflows`. relative to `.github/workflows`.
- `cron::AbstractString`: Cron expression for the schedule interval. - `cron::AbstractString`: Cron expression for the schedule interval.
""" """
@with_kw_noshow struct CompatHelper <: FilePugin @with_kw_noshow struct CompatHelper <: FilePlugin
file::String = default_file("github", "workflows", "CompatHelper.yml") file::String = default_file("github", "workflows", "CompatHelper.yml")
destination::String = "CompatHelper.yml" destination::String = "CompatHelper.yml"
cron::String = "0 0 * * *" cron::String = "0 0 * * *"

4
src/plugins/coverage.jl
View File

@ -9,7 +9,7 @@ Sets up code coverage submission from CI to [Codecov](https://codecov.io).
- `file::Union{AbstractString, Nothing}`: Template file for `.codecov.yml`, - `file::Union{AbstractString, Nothing}`: Template file for `.codecov.yml`,
or `nothing` to create no file. or `nothing` to create no file.
""" """
@with_kw_noshow struct Codecov <: FilePugin @with_kw_noshow struct Codecov <: FilePlugin
file::Union{String, Nothing} = nothing file::Union{String, Nothing} = nothing
end end
@ -31,7 +31,7 @@ Sets up code coverage submission from CI to [Coveralls](https://coveralls.io).
- `file::Union{AbstractString, Nothing}`: Template file for `.coveralls.yml`, - `file::Union{AbstractString, Nothing}`: Template file for `.coveralls.yml`,
or `nothing` to create no file. or `nothing` to create no file.
""" """
@with_kw_noshow struct Coveralls <: FilePugin @with_kw_noshow struct Coveralls <: FilePlugin
file::Union{String, Nothing} = nothing file::Union{String, Nothing} = nothing
end end

2
src/plugins/license.jl
View File

@ -12,7 +12,7 @@ Creates a license file.
- `destination::AbstractString`: File destination, relative to the repository root. - `destination::AbstractString`: File destination, relative to the repository root.
For example, `"LICENSE.md"` might be desired. For example, `"LICENSE.md"` might be desired.
""" """
struct License <: FilePugin struct License <: FilePlugin
path::String path::String
destination::String destination::String
end end

2
src/plugins/readme.jl
View File

@ -13,7 +13,7 @@ Creates a `README` file that contains badges for other included plugins.
For example, values of `"README"` or `"README.rst"` might be desired. For example, values of `"README"` or `"README.rst"` might be desired.
- `inline_badges::Bool`: Whether or not to put the badges on the same line as the package name. - `inline_badges::Bool`: Whether or not to put the badges on the same line as the package name.
""" """
@with_kw_noshow struct Readme <: FilePugin @with_kw_noshow struct Readme <: FilePlugin
file::String = default_file("README.md") file::String = default_file("README.md")
destination::String = "README.md" destination::String = "README.md"
inline_badges::Bool = false inline_badges::Bool = false

2
src/plugins/src_dir.jl
View File

@ -6,7 +6,7 @@ Creates a module entrypoint.
## Keyword Arguments ## Keyword Arguments
- `file::AbstractString`: Template file for `src/<module>.jl`. - `file::AbstractString`: Template file for `src/<module>.jl`.
""" """
@with_kw_noshow mutable struct SrcDir <: FilePugin @with_kw_noshow mutable struct SrcDir <: FilePlugin
file::String = default_file("src", "module.jl") file::String = default_file("src", "module.jl")
destination::String = "" destination::String = ""
end end

2
src/plugins/tagbot.jl
View File

@ -34,7 +34,7 @@ Adds GitHub release support via [TagBot](https://github.com/JuliaRegistries/TagB
- `dispatch::Bool`: Whether or not to enable the `dispatch` option. - `dispatch::Bool`: Whether or not to enable the `dispatch` option.
- `dispatch_delay::Int`: Number of minutes to delay for dispatch events. - `dispatch_delay::Int`: Number of minutes to delay for dispatch events.
""" """
@with_kw_noshow struct TagBot <: FilePugin @with_kw_noshow struct TagBot <: FilePlugin
file::String = default_file("github", "workflows", "TagBot.yml") file::String = default_file("github", "workflows", "TagBot.yml")
destination::String = "TagBot.yml" destination::String = "TagBot.yml"
cron::String = "0 0 * * *" cron::String = "0 0 * * *"

8
src/plugins/tests.jl
View File

@ -16,7 +16,7 @@ Sets up testing for packages.
Managing test dependencies with `test/Project.toml` is only supported Managing test dependencies with `test/Project.toml` is only supported
in Julia 1.2 and later. in Julia 1.2 and later.
""" """
@with_kw_noshow struct Tests <: FilePugin @with_kw_noshow struct Tests <: FilePlugin
file::String = default_file("test", "runtests.jl") file::String = default_file("test", "runtests.jl")
project::Bool = false project::Bool = false
end end
@ -26,7 +26,7 @@ destination(::Tests) = joinpath("test", "runtests.jl")
view(::Tests, ::Template, pkg::AbstractString) = Dict("PKG" => pkg) view(::Tests, ::Template, pkg::AbstractString) = Dict("PKG" => pkg)
function validate(p::Tests, t::Template) function validate(p::Tests, t::Template)
invoke(validate, Tuple{FilePugin, Template}, p, t) invoke(validate, Tuple{FilePlugin, Template}, p, t)
p.project && t.julia < v"1.2" && @warn string( p.project && t.julia < v"1.2" && @warn string(
"Tests: The project option is set to create a project (supported in Julia 1.2 and later) ", "Tests: The project option is set to create a project (supported in Julia 1.2 and later) ",
"but a Julia version older than 1.2 ($(t.julia)) is supported by the template", "but a Julia version older than 1.2 ($(t.julia)) is supported by the template",
@ -34,8 +34,8 @@ function validate(p::Tests, t::Template)
end end
function hook(p::Tests, t::Template, pkg_dir::AbstractString) function hook(p::Tests, t::Template, pkg_dir::AbstractString)
# Do the normal FilePugin behaviour to create the test script. # Do the normal FilePlugin behaviour to create the test script.
invoke(hook, Tuple{FilePugin, Template, AbstractString}, p, t, pkg_dir) invoke(hook, Tuple{FilePlugin, Template, AbstractString}, p, t, pkg_dir)
# Then set up the test depdendency in the chosen way. # Then set up the test depdendency in the chosen way.
f = p.project ? make_test_project : add_test_dependency f = p.project ? make_test_project : add_test_dependency

24
test/plugin.jl
View File

@ -1,20 +1,20 @@
# Don't move this line from the top, please. {{X}} {{Y}} {{Z}} # Don't move this line from the top, please. {{X}} {{Y}} {{Z}}
struct BasicTest <: PT.FilePugin struct FileTest <: PT.FilePlugin
a::String a::String
b::Bool b::Bool
end end
PT.gitignore(::BasicTest) = ["a", "aa", "aaa"] PT.gitignore(::FileTest) = ["a", "aa", "aaa"]
PT.source(::BasicTest) = @__FILE__ PT.source(::FileTest) = @__FILE__
PT.destination(::BasicTest) = "foo.txt" PT.destination(::FileTest) = "foo.txt"
PT.badges(::BasicTest) = PT.Badge("{{X}}", "{{Y}}", "{{Z}}") PT.badges(::FileTest) = PT.Badge("{{X}}", "{{Y}}", "{{Z}}")
PT.view(::BasicTest, ::Template, ::AbstractString) = Dict("X" => 0, "Y" => 2) PT.view(::FileTest, ::Template, ::AbstractString) = Dict("X" => 0, "Y" => 2)
PT.user_view(::BasicTest, ::Template, ::AbstractString) = Dict("X" => 1, "Z" => 3) PT.user_view(::FileTest, ::Template, ::AbstractString) = Dict("X" => 1, "Z" => 3)
@testset "Plugins" begin @testset "Plugins" begin
@testset "FilePugin" begin @testset "FilePlugin" begin
p = BasicTest("foo", true) p = FileTest("foo", true)
t = tpl(; plugins=[p]) t = tpl(; plugins=[p])
# The X from user_view should override the X from view. # The X from user_view should override the X from view.
@ -39,10 +39,10 @@ PT.user_view(::BasicTest, ::Template, ::AbstractString) = Dict("X" => 1, "Z" =>
end end
@testset "Equality" begin @testset "Equality" begin
a = BasicTest("foo", true) a = FileTest("foo", true)
b = BasicTest("foo", true) b = FileTest("foo", true)
@test a == b @test a == b
c = BasicTest("foo", false) c = FileTest("foo", false)
@test a != c @test a != c
end end
end end