Struct Template 

pub struct Template<'a> { /* private fields */ }

A Pawn include written by hand, with the declarations filled in.

The prose, the sections, the constants and the callback documentation stay in the template, where they belong; every native line comes from the Rust signature, so it cannot drift. This is the middle ground between generating the whole file — which throws the documentation away — and maintaining it by hand, which drifts.

Placeholders, all written {{NAME}}:

Placeholder	Becomes
{{NATIVES}}	every declaration not placed individually, in registration order
{{NATIVE:Name}}	that one declaration
{{NATIVE:Name as Alias}}	native Alias(…) = Name;, the aliased form
{{PLUGIN}}	the plugin’s crate name
{{GUARD}}	_<plugin>_included, the usual include guard symbol
anything else	what Template::var supplied, or an error

let template = std::fs::read_to_string("include/my_plugin.inc.in")?;

samp::pawn_include::Template::new(&template, &pawn_native_decls())
    .var("VERSION", env!("CARGO_PKG_VERSION"))
    .write("include/my_plugin.inc")
    .expect("the template and the natives agree");

A native the template never places is an error, not a silent omission: that is the drift this exists to prevent.

Implementations

impl<'a> Template<'a>

pub fn new(source: &'a str, decls: &[&str]) -> Self

Takes the template’s text and the declarations to place into it, as pawn_native_decls() produces them.

pub fn var(self, name: impl Into<String>, value: impl Into<String>) -> Self

Supplies one {{NAME}}. The last value for a name wins.

pub fn docs(self, docs: &[&str]) -> Self

The doc comment of each native, in the order the declarations came.

Defaults to what #[native] captured from the Rust doc comments, so this is for generating an include without a plugin loaded — from a test.

pub fn with_docs(self) -> Self

Puts each native’s documentation above its declaration, as a Pawn documentation comment.

Off by default: a template that documents each native in its own prose should not get a second copy. With it on, the documentation lives once, next to the Rust code. {{DOC:Name}} places one on its own either way.

pub fn callbacks(self, callbacks: &[&str]) -> Self

The callbacks {{CALLBACKS}} should forward.

Defaults to what initialize_plugin! declared in callbacks: [...], so this is for generating an include without a plugin loaded — from a test.

pub fn plugin_name(self, name: impl Into<String>) -> Self

Names the plugin, for {{PLUGIN}} and {{GUARD}}.

Defaults to the name the plugin registered, which is its crate name.

pub fn render(&self) -> Result<String, Vec<TemplateError>>

Renders the include.

Errors

Returns every TemplateError found, in the order they were met, so one pass names all of them rather than one per run.

pub fn write(&self, path: impl AsRef<Path>) -> Result<(), WriteError>

Renders and writes the include to path.

Errors

The template’s own errors, or the std::io::Error from writing.