converter

package
v1.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 12, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package converter provides functionality to convert OPNsense configurations to various formats.

Package converter provides functionality to convert OPNsense configurations to markdown.

Package converter provides functionality to convert OPNsense configurations to various formats.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnsupportedFormat is returned when an unsupported output format is requested.
	ErrUnsupportedFormat = errors.New("unsupported format")

	// ErrNilConfiguration is returned when the input OPNsense configuration is nil.
	ErrNilConfiguration = errors.New("configuration cannot be nil")
)
View Source 
var ErrInvalidWrapWidth = errors.New("wrap width must be -1 (auto-detect), 0 (no wrapping), or positive")

ErrInvalidWrapWidth indicates that the wrap width setting is invalid.

View Source 
var ErrNilOpnSenseDocument = errors.New("input OpnSenseDocument struct is nil")

ErrNilOpnSenseDocument is returned when the input OpnSenseDocument struct is nil.

Functions

func NewMarkdownBuilder deprecated added in v1.1.0 

func NewMarkdownBuilder() *builder.MarkdownBuilder

NewMarkdownBuilder creates a new MarkdownBuilder instance.

Deprecated: use builder.NewMarkdownBuilder instead.

func NewMarkdownBuilderWithConfig deprecated added in v1.1.0 

func NewMarkdownBuilderWithConfig(
	config *model.OpnSenseDocument,
	logger *log.Logger,
) *builder.MarkdownBuilder

NewMarkdownBuilderWithConfig creates a new MarkdownBuilder with configuration.

Deprecated: use builder.NewMarkdownBuilderWithConfig instead.

func RunConverterTests 

func RunConverterTests(
	t *testing.T,
	tests []TestCase,
	convertFunc func(context.Context, *model.OpnSenseDocument) (string, error),
)

RunConverterTests runs the standard converter test suite.

Types

type Adapter 

type Adapter interface {
	Converter
	SetOptions(opts any)
	GetOptions() any
}

Adapter represents the interface for adapters that bridge between old and new converter implementations.

type Converter 

type Converter interface {
	ToMarkdown(ctx context.Context, opnsense *model.OpnSenseDocument) (string, error)
}

Converter is the interface for converting OPNsense configurations to markdown.

type Format added in v1.1.0 

type Format string

Format represents the output format type. 

const (
	// FormatMarkdown represents markdown output format.
	FormatMarkdown Format = "markdown"
	// FormatJSON represents JSON output format.
	FormatJSON Format = "json"
	// FormatYAML represents YAML output format.
	FormatYAML Format = "yaml"
)

func (Format) String added in v1.1.0 

func (f Format) String() string

String returns the string representation of the format.

func (Format) Validate added in v1.1.0 

func (f Format) Validate() error

Validate checks if the format is supported.

type Generator added in v1.1.0 

type Generator interface {
	// Generate creates documentation in a specified format from the provided OPNsense configuration.
	// This method returns the complete output as a string, which is useful when the output
	// needs further processing (e.g., HTML conversion).
	Generate(ctx context.Context, cfg *model.OpnSenseDocument, opts Options) (string, error)
}

Generator interface for creating documentation in various formats.

func NewMarkdownGenerator added in v1.1.0 

func NewMarkdownGenerator(logger *log.Logger, _ Options) (Generator, error)

NewMarkdownGenerator creates a new Generator that produces documentation in Markdown, JSON, or YAML formats. NewMarkdownGenerator creates a Generator that produces Markdown output using the programmatic report builder. It ensures a usable logger (creating a default logger if nil) and constructs a Markdown report builder. The provided Options parameter is ignored and exists only for backward compatibility. Returns a Generator configured for Markdown or an error if logger creation fails.

type HybridGenerator added in v1.1.0 

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

HybridGenerator provides programmatic markdown, JSON, and YAML generation. It uses the builder pattern for markdown output and direct serialization for JSON/YAML.

HybridGenerator implements both Generator (string-based) and StreamingGenerator (io.Writer-based) interfaces. Use GenerateToWriter for memory-efficient streaming output, or Generate when you need the output as a string for further processing.

func NewHybridGenerator added in v1.1.0 

func NewHybridGenerator(reportBuilder builder.ReportBuilder, logger *log.Logger) (*HybridGenerator, error)

NewHybridGenerator creates a HybridGenerator that uses the provided ReportBuilder and logger. If logger is nil, NewHybridGenerator creates a default logger and returns an error if logger creation fails.

func (*HybridGenerator) Generate added in v1.1.0 

func (g *HybridGenerator) Generate(_ context.Context, data *model.OpnSenseDocument, opts Options) (string, error)

Generate creates documentation in the specified format from the provided OPNsense configuration. Supported formats: markdown (default), json, yaml.

For memory-efficient streaming output, use GenerateToWriter instead. Generate is preferred when you need the output as a string for further processing (e.g., converting markdown to HTML).

func (*HybridGenerator) GenerateToWriter added in v1.1.0 

func (g *HybridGenerator) GenerateToWriter(
	_ context.Context,
	w io.Writer,
	data *model.OpnSenseDocument,
	opts Options,
) error

GenerateToWriter writes documentation directly to the provided io.Writer. This is more memory-efficient than Generate() as it streams output section-by-section without accumulating the entire output in memory first.

For markdown format, sections are written incrementally as they are generated. For JSON and YAML formats, the full output is generated then written (these formats require complete document serialization).

Use Generate() instead when you need the output as a string for further processing (e.g., converting markdown to HTML before writing).

func (*HybridGenerator) GetBuilder added in v1.1.0 

func (g *HybridGenerator) GetBuilder() builder.ReportBuilder

GetBuilder returns the current report builder.

func (*HybridGenerator) SetBuilder added in v1.1.0 

func (g *HybridGenerator) SetBuilder(reportBuilder builder.ReportBuilder)

SetBuilder sets the report builder for programmatic generation.

type JSONConverter 

type JSONConverter struct{}

JSONConverter is a JSON converter for OPNsense configurations.

func NewJSONConverter 

func NewJSONConverter() *JSONConverter

NewJSONConverter creates and returns a new JSONConverter for converting OPNsense configurations to JSON format.

func (*JSONConverter) ToJSON 

func (c *JSONConverter) ToJSON(_ context.Context, opnsense *model.OpnSenseDocument) (string, error)

ToJSON converts an OPNsense configuration to JSON.

type MarkdownBuilder deprecated added in v1.1.0 

type MarkdownBuilder = builder.MarkdownBuilder

MarkdownBuilder provides compatibility for legacy converter package callers.

Deprecated: use builder.MarkdownBuilder instead.

type MarkdownConverter 

type MarkdownConverter struct{}

MarkdownConverter is a markdown converter for OPNsense configurations.

func NewMarkdownConverter 

func NewMarkdownConverter() *MarkdownConverter

NewMarkdownConverter creates and returns a new MarkdownConverter for converting OPNsense configuration data to markdown format.

func (*MarkdownConverter) ToMarkdown 

func (c *MarkdownConverter) ToMarkdown(_ context.Context, opnsense *model.OpnSenseDocument) (string, error)

ToMarkdown converts an OPNsense configuration to markdown.

type Options added in v1.1.0 

type Options struct {
	// Format specifies the output format (markdown, json, yaml).
	Format Format

	// Comprehensive specifies whether to generate a comprehensive report.
	Comprehensive bool

	// Sections specifies which configuration sections to include.
	Sections []string

	// Theme specifies the terminal rendering theme for markdown output.
	Theme Theme

	// WrapWidth specifies the column width for text wrapping.
	WrapWidth int

	// EnableTables controls whether to render data as tables.
	EnableTables bool

	// EnableColors controls whether to use colored output.
	EnableColors bool

	// EnableEmojis controls whether to include emoji icons in output.
	EnableEmojis bool

	// Compact controls whether to use a more compact output format.
	Compact bool

	// IncludeMetadata controls whether to include generation metadata.
	IncludeMetadata bool

	// CustomFields allows for additional custom fields to be passed to generation.
	CustomFields map[string]any

	// SuppressWarnings suppresses non-critical warnings.
	SuppressWarnings bool

	// AuditMode specifies the audit reporting mode (standard, blue, red).
	AuditMode string

	// BlackhatMode enables red team blackhat commentary.
	BlackhatMode bool

	// SelectedPlugins specifies which compliance plugins to run.
	SelectedPlugins []string
}

Options contains configuration options for report generation.

func DefaultOptions added in v1.1.0 

func DefaultOptions() Options

DefaultOptions returns an Options initialized with the package's default settings for report generation. Defaults: Format=markdown, Theme=auto, WrapWidth=0, EnableTables=true, EnableColors=true, EnableEmojis=true, IncludeMetadata=true, CustomFields["IncludeTunables"]=false, Comprehensive and Compact set to false, and SuppressWarnings set to false.

func (Options) Validate added in v1.1.0 

func (o Options) Validate() error

Validate checks if the options are valid.

func (Options) WithAuditMode added in v1.1.0 

func (o Options) WithAuditMode(mode string) Options

WithAuditMode sets the audit reporting mode.

func (Options) WithBlackhatMode added in v1.1.0 

func (o Options) WithBlackhatMode(enabled bool) Options

WithBlackhatMode enables or disables blackhat mode for red team reports.

func (Options) WithColors added in v1.1.0 

func (o Options) WithColors(enabled bool) Options

WithColors enables or disables colored output.

func (Options) WithCompact added in v1.1.0 

func (o Options) WithCompact(compact bool) Options

WithCompact enables or disables compact output format.

func (Options) WithComprehensive added in v1.1.0 

func (o Options) WithComprehensive(enabled bool) Options

WithComprehensive enables or disables comprehensive report generation.

func (Options) WithCustomField added in v1.1.0 

func (o Options) WithCustomField(key string, value any) Options

WithCustomField adds a custom field for template rendering.

func (Options) WithEmojis added in v1.1.0 

func (o Options) WithEmojis(enabled bool) Options

WithEmojis enables or disables emoji icons.

func (Options) WithFormat added in v1.1.0 

func (o Options) WithFormat(format Format) Options

WithFormat sets the output format.

func (Options) WithMetadata added in v1.1.0 

func (o Options) WithMetadata(enabled bool) Options

WithMetadata enables or disables generation metadata.

func (Options) WithSections added in v1.1.0 

func (o Options) WithSections(sections ...string) Options

WithSections sets the sections to include in output.

func (Options) WithSelectedPlugins added in v1.1.0 

func (o Options) WithSelectedPlugins(plugins ...string) Options

WithSelectedPlugins sets the compliance plugins to run.

func (Options) WithSuppressWarnings added in v1.1.0 

func (o Options) WithSuppressWarnings(suppress bool) Options

WithSuppressWarnings enables or disables warning suppression.

func (Options) WithTables added in v1.1.0 

func (o Options) WithTables(enabled bool) Options

WithTables enables or disables table rendering.

func (Options) WithTheme added in v1.1.0 

func (o Options) WithTheme(theme Theme) Options

WithTheme sets the terminal rendering theme.

func (Options) WithWrapWidth added in v1.1.0 

func (o Options) WithWrapWidth(width int) Options

WithWrapWidth sets the text wrapping width.

type ReportBuilder deprecated added in v1.1.0 

type ReportBuilder = builder.ReportBuilder

ReportBuilder provides compatibility for legacy converter package callers.

Deprecated: use builder.ReportBuilder instead.

type StreamingGenerator added in v1.1.0 

type StreamingGenerator interface {
	Generator

	// GenerateToWriter writes documentation directly to the provided io.Writer.
	// This is more memory-efficient than Generate() for large configurations
	// as it streams output section-by-section.
	GenerateToWriter(ctx context.Context, w io.Writer, cfg *model.OpnSenseDocument, opts Options) error
}

StreamingGenerator extends Generator with io.Writer-based output support. This interface enables memory-efficient generation by writing directly to the destination without accumulating the entire output in memory first.

type TestCase 

type TestCase struct {
	Name        string
	OpnSense    *model.OpnSenseDocument
	WantErr     bool
	ErrType     error
	ValidateOut func(t *testing.T, result string) // Function to validate the output format
}

TestCase represents a test case for converter tests.

func GetCommonTestCases 

func GetCommonTestCases() []TestCase

GetCommonTestCases returns common test cases for both JSON and YAML converters.

type Theme added in v1.1.0 

type Theme string

Theme represents the rendering theme for terminal output. 

const (
	// ThemeAuto automatically detects the appropriate theme.
	ThemeAuto Theme = "auto"
	// ThemeDark uses a dark terminal theme.
	ThemeDark Theme = "dark"
	// ThemeLight uses a light terminal theme.
	ThemeLight Theme = "light"
	// ThemeNone disables styling for plain text output.
	ThemeNone Theme = "none"
)

func (Theme) String added in v1.1.0 

func (t Theme) String() string

String returns the string representation of the theme.

type YAMLConverter 

type YAMLConverter struct{}

YAMLConverter is a YAML converter for OPNsense configurations.

func NewYAMLConverter 

func NewYAMLConverter() *YAMLConverter

NewYAMLConverter creates and returns a new YAMLConverter for transforming OPNsense configurations to YAML format.

func (*YAMLConverter) ToYAML 

func (c *YAMLConverter) ToYAML(_ context.Context, opnsense *model.OpnSenseDocument) (string, error)

ToYAML converts an OPNsense configuration to YAML.

Source Files

View all Source files

Directories

Path Synopsis
Package builder provides programmatic report building functionality for OPNsense configurations.
 Package builder provides programmatic report building functionality for OPNsense configurations.
Package formatters provides utility functions for formatting data in markdown reports.
 Package formatters provides utility functions for formatting data in markdown reports.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.