View Source Cascade.Template behaviour (Cascade v0.1.1)
The template generation logic.
Every Cascade
template must implement this behaviour. It provides
callbacks which affect the template generation logic.
Summary
Callbacks
The CLI arguments (if any) schema of the template.
The absolute path to the template.
Returns the destination path for the given template file.
Returns the name of template.
Optional callback to be invoked after the template generation has finished.
Optional callback to be invoked before the template generation.
Used for custom validation and post-processing of cli arguments.
Functions
Generates a template
Gets the moduledoc for the given template module
.
Gets the shortdoc for the given template module
.
Callbacks
@callback args_schema() :: keyword()
The CLI arguments (if any) schema of the template.
It should return a valid CliOptions
arguments schema. These CLI options will
be automatically parsed and assigned to the template's bindings when invoked
from the cascade mix task.
Examples
defmodule MyTemplate do
@behaviour Cascade.Template
@impl true
def args_schema do
[
path: [
type: :string,
doc: "The path to store the template to",
required: true
],
auth: [
type: :boolean,
doc: "Whether to generate authentication logic",
default: false
]
]
end
end
@callback assets_path() :: String.t()
The absolute path to the template.
@callback destination_path( asset_path :: String.t(), output_path :: String.t(), opts :: keyword() ) :: Path.t()
Returns the destination path for the given template file.
It expects a file path, the template's config and the user provided CLI arguments and
is expected to return the destination path for this specific asset. The asset_path
is
the template file's path with respect to the assets
.
This will be called for all template files. For example for the following foo
template:
templates/foo
├── README.md ├── lib │ └── foo.ex └── mix.exs
it will be called for the following asset paths:
README.md
mix.exs
lib/foo.ex
@callback name() :: atom()
Returns the name of template.
The names must be unique, it is advised to use a prefix in order to avoid collisions with other packages.
Optional callback to be invoked after the template generation has finished.
You can use it to perform post-generation clean up, log a message to the user or perform any custom logic after the template generation completion (e.g. format the generated code).
Optional callback to be invoked before the template generation.
You can use it to perform setup before the actual template invocation.
Used for custom validation and post-processing of cli arguments.
This can be used for performing custom validations/casting of cli arguments
and optionally augment them. It expects the parsed cli arguments and is
expected to return {:ok, opts}
in case of success or {:error, reason}
in case of failure.
All templates are required to define the expected cli arguments under their
config.exs
. The callback will be called in order to validate the user provided
arguments.
Examples
Assuming that you have a template that expects a --path
argument. Since
generator works with absolute paths you can override this callback in order
to expand the path if it is relative.
def validate_cli_opts(opts) do
path =
Keyword.fetch!(opts, :path)
|> Path.expand(File.cwd())
opts = Keyword.put(opts, :path, path)
{:ok, opts}
end
Functions
Generates a template
Gets the moduledoc for the given template module
.
Returns the moduledoc or nil
.
Gets the shortdoc for the given template module
.
Returns the shortdoc or nil
.