parser

Documentation

Index

• func ClearCache()
• func ConfigureCache(opts ...CacheOption)
• func ConfigureGlobalCache(opts ...CacheOption)
• func ExtractPropertyNames(template string) []string
• func ExtractPropertyNamesFromTemplate(tmpl *MessageTemplate) []string
• func ResetGlobalCacheForTesting()
• func ValidateTemplate(template string) error
• type CacheOption
  • func WithMaxSize(size int) CacheOption
  • func WithTTL(ttl time.Duration) CacheOption
• type CapturingHint
• type MessageTemplate
  • func Parse(template string) (*MessageTemplate, error)
  • func ParseCached(template string) (*MessageTemplate, error)
  • func (mt *MessageTemplate) Render(properties map[string]any) string
• type MessageTemplateToken
• type PropertyToken
  • func (p *PropertyToken) Render(properties map[string]any) string
• type Stats
  • func GetCacheStats() Stats
• type TemplateCache
  • func GetGlobalCache() *TemplateCache
  • func NewTemplateCache(opts ...CacheOption) *TemplateCache
  • func (c *TemplateCache) Clear()
  • func (c *TemplateCache) Close()
  • func (c *TemplateCache) Delete(key string) bool
  • func (c *TemplateCache) Get(key string) (*MessageTemplate, bool)
  • func (c *TemplateCache) Put(key string, value *MessageTemplate)
  • func (c *TemplateCache) Stats() Stats
• type TextToken
  • func (t *TextToken) Render(properties map[string]any) string
• type ValidationError
  • func (e ValidationError) Error() string

Functions

func ClearCache

func ClearCache()

ClearCache clears the template cache (useful for tests).

func ConfigureCache

func ConfigureCache(opts ...CacheOption)

ConfigureCache is a convenience function to configure the global cache This should be called at application startup before any cache usage

func ConfigureGlobalCache

func ConfigureGlobalCache(opts ...CacheOption)

ConfigureGlobalCache sets up the global cache with options This should only be called at application startup before any cache usage Panics if called more than once to prevent runtime reconfiguration issues

func ExtractPropertyNames

func ExtractPropertyNames(template string) []string

ExtractPropertyNames returns all property names from a template.

func ExtractPropertyNamesFromTemplate

func ExtractPropertyNamesFromTemplate(tmpl *MessageTemplate) []string

ExtractPropertyNamesFromTemplate extracts property names from an already parsed template.

func ResetGlobalCacheForTesting

func ResetGlobalCacheForTesting()

ResetGlobalCacheForTesting allows tests to reset the configuration flag This should ONLY be used in tests, never in production code

func ValidateTemplate

func ValidateTemplate(template string) error

ValidateTemplate validates a message template and returns any errors found. This is used for runtime validation and selflog instrumentation.

Types

type CacheOption

type CacheOption func(*TemplateCache)

CacheOption configures the template cache

func WithMaxSize

func WithMaxSize(size int) CacheOption

WithMaxSize sets the maximum number of entries (default: 10,000)

func WithTTL

func WithTTL(ttl time.Duration) CacheOption

WithTTL sets the time-to-live for cache entries

type CapturingHint

type CapturingHint int

CapturingHint specifies how a property should be captured.

const (
	// Default capturing uses Go's default string conversion (e.g., fmt.Sprintf("%v", value)).
	Default CapturingHint = iota

	// Stringify forces string conversion.
	Stringify

	// Capture captures object structure.
	Capture

	// AsScalar treats as scalar value.
	AsScalar
)

type MessageTemplate

type MessageTemplate struct {
	// Raw is the original template string.
	Raw string

	// Tokens are the parsed tokens from the template.
	Tokens []MessageTemplateToken
}

MessageTemplate represents a parsed message template.

func Parse

func Parse(template string) (*MessageTemplate, error)

Parse parses a message template string into a MessageTemplate.

func ParseCached

func ParseCached(template string) (*MessageTemplate, error)

ParseCached parses a template with caching to avoid repeated allocations. It uses the global LRU cache with bounded size to prevent memory exhaustion.

func (*MessageTemplate) Render

func (mt *MessageTemplate) Render(properties map[string]any) string

Render generates the final message using the provided properties.

type MessageTemplateToken

type MessageTemplateToken interface {
	// Render returns the string representation of the token using the provided properties.
	Render(properties map[string]any) string
}

MessageTemplateToken represents a single token in a message template.

type PropertyToken

type PropertyToken struct {
	// PropertyName is the name of the property.
	PropertyName string

	// Capturing specifies how the property should be captured.
	Capturing CapturingHint

	// Format specifies the format string, if any.
	Format string

	// Alignment specifies text alignment, if any.
	Alignment int
}

PropertyToken represents a property placeholder in a message template.

func (*PropertyToken) Render

func (p *PropertyToken) Render(properties map[string]any) string

Render returns the string representation of the property value.

type Stats

type Stats struct {
	Hits        uint64
	Misses      uint64
	Evictions   uint64
	Expirations uint64
	Size        int
	MaxSize     int
}

Stats returns a snapshot of cache statistics

func GetCacheStats

func GetCacheStats() Stats

GetCacheStats returns global cache statistics

type TemplateCache

type TemplateCache struct {
	// contains filtered or unexported fields
}

TemplateCache is a concurrent, sharded LRU cache with optional TTL

func GetGlobalCache

func GetGlobalCache() *TemplateCache

GetGlobalCache returns the current global cache instance

func NewTemplateCache

func NewTemplateCache(opts ...CacheOption) *TemplateCache

NewTemplateCache creates a new template cache

func (*TemplateCache) Clear

func (c *TemplateCache) Clear()

Clear removes all entries from the cache and resets statistics

func (*TemplateCache) Close

func (c *TemplateCache) Close()

Close stops the cleanup goroutine if running

func (*TemplateCache) Delete

func (c *TemplateCache) Delete(key string) bool

Delete removes an entry from the cache

func (*TemplateCache) Get

func (c *TemplateCache) Get(key string) (*MessageTemplate, bool)

Get retrieves a template from the cache

func (*TemplateCache) Put

func (c *TemplateCache) Put(key string, value *MessageTemplate)

Put adds a template to the cache

func (*TemplateCache) Stats

func (c *TemplateCache) Stats() Stats

Stats returns current cache statistics

type TextToken

type TextToken struct {
	// Text is the literal text content.
	Text string
}

TextToken represents literal text in a message template.

func (*TextToken) Render

func (t *TextToken) Render(properties map[string]any) string

Render returns the literal text.

type ValidationError

type ValidationError struct {
	Message  string
	Position int
	Property string
}

ValidationError represents a template validation error

func (ValidationError) Error

func (e ValidationError) Error() string