Skip to main content

Formatter

spikard_cli::codegen::formatters

Trait Formatter 

Source 
pub trait Formatter: Send + Sync {
    // Required methods
    fn format_header(&self, metadata: &HeaderMetadata) -> String;
    fn format_imports(&self, imports: &[Import]) -> String;
    fn format_docstring(&self, content: &str) -> String;
    fn merge_sections(&self, sections: &[Section]) -> String;
}
Expand description

Core formatter trait for language-specific code generation output

Implement this trait to support a new target language. Each method should produce formatted code that adheres to the language’s conventions and integrates with its standard tooling (linters, formatters, type checkers).

§Safety

Implementations must:

  • Never panic (return errors via Result types where applicable)
  • Escape special characters appropriately for the language
  • Handle both empty and non-empty inputs gracefully
  • Preserve code semantics when reformatting

Required Methods§

Source

fn format_header(&self, metadata: &HeaderMetadata) -> String

Format a file header with metadata about auto-generation

This method should produce language-specific output including:

  • Shebang line (if applicable)
  • Tool directives (ruff: noqa, eslint-disable, etc.)
  • Auto-generation notices
  • Module/file docstrings

The output should NOT include trailing newlines; those are added during merge.

Source

fn format_imports(&self, imports: &[Import]) -> String

Format import/require/use statements

This method should:

  • Group imports by category (stdlib, third-party, local, type-only)
  • Sort imports alphabetically within each group
  • Handle language-specific syntax (from/import, require, use, etc.)
  • Preserve any special import semantics (type imports in TypeScript, etc.)

Input imports may be in any order; output should be normalized. The output should NOT include trailing newlines.

Source

fn format_docstring(&self, content: &str) -> String

Format a docstring with proper escaping and indentation

This method should:

  • Use the language’s standard docstring format (triple quotes, JSDoc, etc.)
  • Escape any special characters (e.g., triple quotes within the content)
  • Apply proper indentation for nested context
  • Preserve line breaks and formatting in the original content

The output should NOT include trailing newlines.

Source

fn merge_sections(&self, sections: &[Section]) -> String

Merge multiple code sections into final output

This method combines header, imports, and body sections with proper spacing:

  • Exactly 2 blank lines between top-level definitions (PEP 8, similar standards)
  • No duplicate headers (if both are present, deduplicate)
  • Ensure trailing newline on final output
  • Handle sections in any order (normalize to header → imports → body)
§Example

The output might look like:

#!/usr/bin/env python3
# Auto-generated by spikard

from typing import List
import msgspec

class MyType(msgspec.Struct):
    fields: List[str]

Implementors§