Plugin Development

A plugin to be added to a Template, which adds some functionality or integration. New plugins should almost always extend GenericPlugin or CustomPlugin.

Generic plugins are plugins that add any number of patterns to the generated package's .gitignore, and have at most one associated file to generate.

Attributes

• gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.
• src::Union{AbstractString, Nothing}: Path to the file that will be copied into the generated package repository. If set to nothing, no file will be generated. When this defaults to an empty string, there should be a default file in defaults that will be copied. That file's name is usually the same as the plugin's name, except in all lowercase and with the .yml extension. If this is not the case, an interactive method needs to be implemented to call interactive(; file="file.ext").
• dest::AbstractString: Path to the generated file, relative to the root of the generated package repository.
• badges::Vector{Badge}: Array of Badges containing information used to create Markdown-formatted badges from the plugin. Entries will be run through substitute, so they may contain placeholder values.
• view::Dict{String, Any}: Additional substitutions to make in both the plugin's badges and its associated file. See substitute for details.

Example

struct MyPlugin <: GenericPlugin
    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")

The above plugin ignores files ending with .mgp, copies defaults/my-plugin.toml by default, and creates a badge that links to the project on its own site, using the default substitutions with one addition: {{YEAR}} => year(today()). Since the default config template file doesn't follow the generic naming convention, we added another interactive method to correct the assumed filename.

Custom plugins are plugins whose behaviour does not follow the GenericPlugin pattern. They can implement gen_plugin, badges, and interactive in any way they choose, as long as they conform to the usual type signature.

Attributes

• gitignore::Vector{AbstractString}: Array of patterns to be added to the .gitignore of generated packages that use this plugin.

Example

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()

This plugin doesn't do much, but it demonstrates how gen_plugin, badges and interactive can be implemented using substitute, gen_file, Badge, and format.

Defining Template Files

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 defaults) can use here's syntax to define replacements.

gen_plugin(p::Plugin, t::Template, pkg_name::AbstractString) -> Vector{String}

Generate any files associated with a plugin.

Arguments

• p::Plugin: Plugin whose files are being generated.
• t::Template: Template configuration.
• pkg_name::AbstractString: Name of the package.

Returns an array of generated file/directory names.

interactive(T::Type{<:Plugin}; file::Union{AbstractString, Nothing}="") -> Plugin

Interactively create a plugin of type T, where file is the plugin type's default config template with a non-standard name (for MyPlugin, this is anything but "myplugin.yml").

badges(p::Plugin, user::AbstractString, pkg_name::AbstractString) -> Vector{String}

Generate Markdown badges for the plugin.

Arguments

• p::Plugin: Plugin whose badges we are generating.
• user::AbstractString: Username of the package creator.
• pkg_name::AbstractString: Name of the package.

Returns an array of Markdown badges.

gen_file(file::AbstractString, text::AbstractString) -> Int

Create a new file containing some given text. Always ends the file with a newline.

Arguments

• file::AbstractString: Path to the file to be created.
• text::AbstractString: Text to write to the file.

Returns the number of bytes written to the file.

substitute(template::AbstractString, view::Dict{String, Any}) -> String
substitute(
    template::AbstractString,
    pkg_template::Template;
    view::Dict{String, Any}=Dict{String, Any}(),
) -> String

Replace placeholders in template with values in view via Mustache. template is not modified. If pkg_template is supplied, some default replacements are also performed.

For information on how to structure template, see "Defining Template Files" section in Custom Plugins.

Note: Conditionals in template without a corresponding key in view won't error, but will simply be evaluated as false.

Badge(hover::AbstractString, image::AbstractString, link::AbstractString) -> Badge

A Badge contains the data necessary to generate a Markdown badge.

Arguments

• hover::AbstractString: Text to appear when the mouse is hovered over the badge.
• image::AbstractString: URL to the image to display.
• link::AbstractString: URL to go to upon clicking the badge.

format(b::Badge) -> String

Return badge's data formatted as a Markdown string.

version_floor(v::VersionNumber=VERSION) -> String

Format the given Julia version.

Keyword arguments

• v::VersionNumber=VERSION: Version to floor.

Returns "major.minor" for the most recent release version relative to v. For prereleases with v.minor == v.patch == 0, returns "major.minor-".