Library API Reference
This document provides comprehensive API documentation for the SwissArmyHammer Rust library.
Core Types
Prompt
The Prompt
struct represents a single prompt with metadata and template content.
pub struct Prompt {
pub name: String,
pub content: String,
pub description: Option<String>,
pub category: Option<String>,
pub tags: Vec<String>,
pub arguments: Vec<ArgumentSpec>,
pub file_path: Option<PathBuf>,
}
Methods
new(name: &str, content: &str) -> Self
- Create a new promptwith_description(self, description: &str) -> Self
- Add a description (builder pattern)with_category(self, category: &str) -> Self
- Add a category (builder pattern)add_tag(self, tag: &str) -> Self
- Add a tag (builder pattern)add_argument(self, arg: ArgumentSpec) -> Self
- Add an argument specificationrender(&self, args: &HashMap<String, String>) -> Result<String>
- Render the prompt with argumentsvalidate_arguments(&self, args: &HashMap<String, String>) -> Result<()>
- Validate provided arguments
Example
use swissarmyhammer::{Prompt, ArgumentSpec};
use std::collections::HashMap;
let prompt = Prompt::new("greet", "Hello {{name}}!")
.with_description("A greeting prompt")
.add_argument(ArgumentSpec {
name: "name".to_string(),
description: Some("Name to greet".to_string()),
required: true,
default: None,
type_hint: Some("string".to_string()),
});
let mut args = HashMap::new();
args.insert("name".to_string(), "World".to_string());
let result = prompt.render(&args)?;
// result: "Hello World!"
ArgumentSpec
Defines the specification for a prompt argument.
pub struct ArgumentSpec {
pub name: String,
pub description: Option<String>,
pub required: bool,
pub default: Option<String>,
pub type_hint: Option<String>,
}
PromptLibrary
The main interface for managing collections of prompts.
pub struct PromptLibrary {
// internal fields...
}
Methods
new() -> Self
- Create a new empty libraryadd_directory<P: AsRef<Path>>(&mut self, path: P) -> Result<()>
- Load prompts from directoryadd_prompt(&mut self, prompt: Prompt)
- Add a single promptget(&self, name: &str) -> Result<&Prompt>
- Get a prompt by namelist_prompts(&self) -> Vec<&Prompt>
- List all promptsfind_by_category(&self, category: &str) -> Vec<&Prompt>
- Find prompts by categoryfind_by_tag(&self, tag: &str) -> Vec<&Prompt>
- Find prompts by tagremove(&mut self, name: &str) -> Option<Prompt>
- Remove a prompt
Example
use swissarmyhammer::PromptLibrary;
let mut library = PromptLibrary::new();
library.add_directory("./prompts")?;
let prompt = library.get("code-review")?;
let rendered = prompt.render(&args)?;
PromptLoader
Handles loading prompts from various sources.
pub struct PromptLoader {
// internal fields...
}
Methods
new() -> Self
- Create a new loaderload_file<P: AsRef<Path>>(&self, path: P) -> Result<Prompt>
- Load single prompt fileload_directory<P: AsRef<Path>>(&self, path: P) -> Result<Vec<Prompt>>
- Load all prompts from directoryload_string(&self, name: &str, content: &str) -> Result<Prompt>
- Load prompt from string
Template Engine
Template
Wrapper for Liquid templates with custom filters.
pub struct Template {
// internal fields...
}
Methods
new(template_str: &str) -> Result<Self>
- Create template from stringrender(&self, args: &HashMap<String, String>) -> Result<String>
- Render with argumentsraw(&self) -> &str
- Get the raw template string
TemplateEngine
Manages template parsing and custom filters.
pub struct TemplateEngine {
// internal fields...
}
Methods
new() -> Self
- Create new enginedefault_parser() -> Parser
- Get default Liquid parser with custom filtersregister_filter<F>(&mut self, name: &str, filter: F)
- Register custom filter
Storage
PromptStorage
High-level storage interface for prompts.
pub trait PromptStorage {
fn store_prompt(&mut self, prompt: &Prompt) -> Result<()>;
fn load_prompt(&self, name: &str) -> Result<Prompt>;
fn list_prompts(&self) -> Result<Vec<String>>;
fn delete_prompt(&mut self, name: &str) -> Result<()>;
}
StorageBackend
Low-level storage abstraction.
pub trait StorageBackend {
fn read(&self, key: &str) -> Result<Vec<u8>>;
fn write(&mut self, key: &str, data: &[u8]) -> Result<()>;
fn delete(&mut self, key: &str) -> Result<()>;
fn list(&self) -> Result<Vec<String>>;
}
Search
Available with the search
feature
SearchEngine
Full-text search functionality for prompts.
pub struct SearchEngine {
// internal fields...
}
Methods
new() -> Result<Self>
- Create new search engineindex_prompt(&mut self, prompt: &Prompt) -> Result<()>
- Add prompt to search indexsearch(&self, query: &str) -> Result<Vec<SearchResult>>
- Search for prompts
SearchResult
Represents a search result.
pub struct SearchResult {
pub name: String,
pub score: f32,
pub snippet: Option<String>,
}
MCP Integration
Available with the mcp
feature
McpServer
Model Context Protocol server implementation.
pub struct McpServer {
// internal fields...
}
Methods
new(library: PromptLibrary) -> Self
- Create server with prompt libraryrun(&mut self) -> Result<()>
- Start the MCP server
Plugin System
SwissArmyHammerPlugin
Trait for creating plugins.
pub trait SwissArmyHammerPlugin {
fn name(&self) -> &str;
fn filters(&self) -> Vec<Box<dyn CustomLiquidFilter>>;
}
CustomLiquidFilter
Trait for custom Liquid template filters.
pub trait CustomLiquidFilter {
fn name(&self) -> &str;
fn filter(&self, input: &str, args: &[&str]) -> Result<String>;
}
PluginRegistry
Manages registered plugins and filters.
pub struct PluginRegistry {
// internal fields...
}
Methods
new() -> Self
- Create new registryregister_plugin<P: SwissArmyHammerPlugin>(&mut self, plugin: P)
- Register pluginget_filters(&self) -> Vec<&dyn CustomLiquidFilter>
- Get all registered filters
Error Handling
SwissArmyHammerError
Main error type for the library.
pub enum SwissArmyHammerError {
Io(std::io::Error),
Template(String),
PromptNotFound(String),
Config(String),
Storage(String),
Serialization(serde_yaml::Error),
Other(String),
}
Result Type
Convenient result type alias.
pub type Result<T> = std::result::Result<T, SwissArmyHammerError>;
Feature Flags
The library supports several optional features:
search
- Enables full-text search functionalitymcp
- Enables Model Context Protocol server support
Enable features in your Cargo.toml
:
[dependencies]
swissarmyhammer = { version = "0.1", features = ["search", "mcp"] }
Complete Example
use swissarmyhammer::{PromptLibrary, ArgumentSpec, Result};
use std::collections::HashMap;
fn main() -> Result<()> {
// Create library and load prompts
let mut library = PromptLibrary::new();
library.add_directory("./prompts")?;
// Get a prompt
let prompt = library.get("code-review")?;
// Prepare arguments
let mut args = HashMap::new();
args.insert("code".to_string(), "fn main() { println!(\"Hello\"); }".to_string());
args.insert("language".to_string(), "rust".to_string());
// Render the prompt
let rendered = prompt.render(&args)?;
println!("{}", rendered);
Ok(())
}
Advanced Usage
Custom Filters
Create custom Liquid filters for domain-specific transformations:
use swissarmyhammer::{CustomLiquidFilter, PluginRegistry, TemplateEngine};
struct UppercaseFilter;
impl CustomLiquidFilter for UppercaseFilter {
fn name(&self) -> &str { "uppercase" }
fn filter(&self, input: &str, _args: &[&str]) -> Result<String> {
Ok(input.to_uppercase())
}
}
let mut registry = PluginRegistry::new();
registry.register_filter("uppercase", Box::new(UppercaseFilter));
Storage Backends
Implement custom storage backends:
use swissarmyhammer::{StorageBackend, Result};
struct DatabaseBackend {
// database connection...
}
impl StorageBackend for DatabaseBackend {
fn read(&self, key: &str) -> Result<Vec<u8>> {
// Read from database
todo!()
}
fn write(&mut self, key: &str, data: &[u8]) -> Result<()> {
// Write to database
todo!()
}
// ... implement other methods
}
For more examples and advanced usage patterns, see the Library Examples page.