nanodoc

package
v0.4.2 Latest Latest
Warning

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

Go to latest
Published: Jul 20, 2025 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ThemeClassic      = "classic"
	ThemeClassicLight = "classic-light"
	ThemeClassicDark  = "classic-dark"
)

Default theme names

View Source
const BundlePattern = ".bundle."

Bundle file pattern

View Source
const (
	// DefaultTheme is the default theme name
	DefaultTheme = "classic"
)
View Source
const OUTPUT_WIDTH = 80

Default output width for alignment

Variables

View Source
var (
	// ErrFileNotFound is returned when a file cannot be found
	ErrFileNotFound = errors.New("file not found")

	// ErrCircularDependency is returned when a circular dependency is detected in bundles
	ErrCircularDependency = errors.New("circular dependency detected (see: nanodoc topics circular-dependencies)")

	// ErrInvalidRange is returned when a line range is invalid
	ErrInvalidRange = errors.New("invalid line range (see: nanodoc topics content)")

	// ErrEmptySource is returned when no source files are provided
	ErrEmptySource = errors.New("no source files provided")

	// ErrInvalidTheme is returned when a theme cannot be loaded
	ErrInvalidTheme = errors.New("invalid or missing theme (see: nanodoc topics themes)")
)

Common errors

View Source
var DefaultTextExtensions = []string{".txt", ".md"}

Default file extensions to process

View Source
var FilePatterns = []string{"*.txt", "*.md"}

FilePatterns are the default file patterns to match when scanning directories

Functions

func ExtractBundleOptionLines added in v0.4.0

func ExtractBundleOptionLines(pathInfos []PathInfo) ([]string, error)

ExtractBundleOptionLines extracts raw option lines from all bundle files

func FormatDryRunOutput

func FormatDryRunOutput(info *DryRunInfo) string

FormatDryRunOutput formats the dry run information for display

func GetAvailableThemes

func GetAvailableThemes() ([]string, error)

GetAvailableThemes returns a list of available theme names

func GetBannerStyleDescriptions added in v0.4.0

func GetBannerStyleDescriptions() map[string]string

GetBannerStyleDescriptions returns descriptions of all banner styles

func GetBannerStyleNames added in v0.4.0

func GetBannerStyleNames() []string

GetBannerStyleNames returns all registered banner style names

func GetFilesFromDirectory

func GetFilesFromDirectory(dir string, extensions []string) ([]string, error)

GetFilesFromDirectory is a helper that returns all text files from a directory

func GetTerminalWidth added in v0.4.0

func GetTerminalWidth() int

GetTerminalWidth returns the current terminal width, or the default if it cannot be determined

func IsTerminal added in v0.4.0

func IsTerminal(fd int) bool

IsTerminal checks if the given file descriptor is a terminal

func ProcessLiveBundle

func ProcessLiveBundle(content string) (string, error)

ProcessLiveBundle handles inline bundle processing It looks for directives like [[file:path/to/file.txt]] or [[file:path/to/file.txt:L10-20]] and replaces them with the actual file content

func ProcessLiveBundles

func ProcessLiveBundles(doc *Document) error

ProcessLiveBundles iterates through document content and processes inline bundles.

func RegisterBannerStyle added in v0.4.0

func RegisterBannerStyle(style BannerStyle) error

RegisterBannerStyle registers a banner style in the global registry

func RenderDocument

func RenderDocument(doc *Document, ctx *FormattingContext) (string, error)

RenderDocument renders a Document object to a string

func TrackExplicitFlags added in v0.4.0

func TrackExplicitFlags(cmd *cobra.Command) map[string]bool

TrackExplicitFlags determines which flags were explicitly set by the user

Types

type BannerRegistry added in v0.4.0

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

BannerRegistry manages banner style implementations

func (*BannerRegistry) Get added in v0.4.0

func (r *BannerRegistry) Get(name string) (BannerStyle, bool)

Get retrieves a banner style by name

func (*BannerRegistry) GetDescriptions added in v0.4.0

func (r *BannerRegistry) GetDescriptions() map[string]string

GetDescriptions returns a map of style names to descriptions

func (*BannerRegistry) List added in v0.4.0

func (r *BannerRegistry) List() []string

List returns all registered banner style names

func (*BannerRegistry) Register added in v0.4.0

func (r *BannerRegistry) Register(style BannerStyle) error

Register adds a new banner style to the registry

type BannerStyle added in v0.4.0

type BannerStyle interface {
	// Apply formats the filename with the banner style
	Apply(filename string, opts *FormattingOptions) string
	// Name returns the name of the banner style
	Name() string
	// Description returns a description of the banner style
	Description() string
}

BannerStyle defines the interface for banner style implementations

func GetBannerStyle added in v0.4.0

func GetBannerStyle(name string) (BannerStyle, bool)

GetBannerStyle retrieves a banner style from the global registry

type BoxedBannerStyle added in v0.4.0

type BoxedBannerStyle struct{}

BoxedBannerStyle creates a box around the filename

func (BoxedBannerStyle) Apply added in v0.4.0

func (b BoxedBannerStyle) Apply(filename string, opts *FormattingOptions) string

func (BoxedBannerStyle) Description added in v0.4.0

func (b BoxedBannerStyle) Description() string

func (BoxedBannerStyle) Name added in v0.4.0

func (b BoxedBannerStyle) Name() string

type BundleProcessor

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

BundleProcessor handles bundle file processing and circular dependency detection

func NewBundleProcessor

func NewBundleProcessor() *BundleProcessor

NewBundleProcessor creates a new bundle processor

func (*BundleProcessor) ProcessBundleFile

func (bp *BundleProcessor) ProcessBundleFile(bundlePath string) ([]string, error)

ProcessBundleFile reads and processes a bundle file, returning the list of paths it contains

func (*BundleProcessor) ProcessBundleFileWithOptions

func (bp *BundleProcessor) ProcessBundleFileWithOptions(bundlePath string) (*BundleResult, error)

ProcessBundleFileWithOptions reads and processes a bundle file, returning both paths and options

func (*BundleProcessor) ProcessPaths

func (bp *BundleProcessor) ProcessPaths(paths []string) ([]string, error)

ProcessPaths takes a list of paths and expands any bundle files recursively

type BundleResult

type BundleResult struct {
	// File paths from the bundle
	Paths []string
	// Raw option lines from the bundle (unparsed)
	OptionLines []string
}

BundleResult holds both the raw option lines and file paths from a bundle file

type CircularDependencyError

type CircularDependencyError struct {
	Path  string
	Chain []string
}

CircularDependencyError represents a circular dependency in bundle files

func (*CircularDependencyError) Error

func (e *CircularDependencyError) Error() string

type DashedBannerStyle added in v0.4.0

type DashedBannerStyle struct{}

DashedBannerStyle uses dashed lines above and below

func (DashedBannerStyle) Apply added in v0.4.0

func (d DashedBannerStyle) Apply(filename string, opts *FormattingOptions) string

func (DashedBannerStyle) Description added in v0.4.0

func (d DashedBannerStyle) Description() string

func (DashedBannerStyle) Name added in v0.4.0

func (d DashedBannerStyle) Name() string

type Document

type Document struct {
	// Ordered list of content blocks
	ContentItems []FileContent

	// Table of contents data
	TOC []TOCEntry

	// Name of the theme to use for styling
	ThemeName string

	// Whether to use Rich formatting
	UseRichFormatting bool

	// Formatting options
	FormattingOptions FormattingOptions
}

Document represents the entire document after processing bundles

func BuildDocument

func BuildDocument(pathInfos []PathInfo, options FormattingOptions) (*Document, error)

BuildDocument creates a Document from resolved paths Note: Bundle option processing has been moved to the CLI layer

func BuildDocumentWithExplicitFlags

func BuildDocumentWithExplicitFlags(pathInfos []PathInfo, options FormattingOptions, explicitFlags map[string]bool) (*Document, error)

BuildDocumentWithExplicitFlags creates a Document from resolved paths Note: Bundle option processing has been moved to the CLI layer

func BuildDocumentWithOptions

func BuildDocumentWithOptions(pathInfos []PathInfo, options FormattingOptions) (*Document, error)

BuildDocumentWithOptions creates a Document from resolved paths with already-merged options

func NewDocument

func NewDocument() *Document

NewDocument creates a new Document with default options

type DryRunInfo

type DryRunInfo struct {
	// Files that would be processed
	Files []FileInfo
	// Bundle files detected
	Bundles []string
	// Total count of files
	TotalFiles int
	// Total line count across all files
	TotalLines int
	// Files requiring additional extensions
	RequiresExtension map[string]string
	// Active formatting options
	Options FormattingOptions
}

DryRunInfo contains information about what would be processed

func GenerateDryRunInfo

func GenerateDryRunInfo(pathInfos []PathInfo, opts FormattingOptions) (*DryRunInfo, error)

GenerateDryRunInfo analyzes what files would be processed without actually processing them

type FileContent

type FileContent struct {
	// Path to the file (absolute path)
	Filepath string

	// Line ranges to include
	Ranges []Range

	// Content after applying ranges
	Content string

	// True if this represents a bundle file
	IsBundle bool

	// Source file if part of an inline bundle
	OriginalSource string
}

FileContent represents the content and metadata for a single file

func ExtractFileContent

func ExtractFileContent(pathWithRange string) (*FileContent, error)

ExtractFileContent reads a file and extracts content based on optional range specifications. The path can include a range suffix like "file.txt:L10-20,L30,L40-".

func ResolveAndExtractFiles

func ResolveAndExtractFiles(pathInfos []PathInfo, additionalExtensions []string) ([]FileContent, error)

ResolveAndExtractFiles takes a list of resolved paths and extracts their content

type FileError

type FileError struct {
	Path string
	Err  error
}

FileError represents an error related to a specific file

func (*FileError) Error

func (e *FileError) Error() string

func (*FileError) Unwrap

func (e *FileError) Unwrap() error

type FileInfo

type FileInfo struct {
	Path      string
	Source    string // Where it came from (directory, bundle, etc.)
	Extension string
	LineCount int    // Number of lines that will be processed
	RangeSpec string // Range specification if any (e.g., "L10-20")
}

FileInfo contains dry run information about a file

type FormattingContext

type FormattingContext struct {
	Theme         *Theme
	LineNumbers   LineNumberMode
	ShowFilenames bool
	HeaderFormat  HeaderFormat
	SequenceStyle SequenceStyle
	ShowTOC       bool
}

FormattingContext holds the state for formatting operations

func NewFormattingContext

func NewFormattingContext(options FormattingOptions) (*FormattingContext, error)

NewFormattingContext creates a new formatting context with the given options

func (*FormattingContext) ApplyTheme

func (fc *FormattingContext) ApplyTheme(doc *Document) error

ApplyTheme applies the theme to a document (placeholder for now)

type FormattingOptions

type FormattingOptions struct {
	// Theme name to use
	Theme string

	// Line numbering mode
	LineNumbers LineNumberMode

	// Whether to show filenames
	ShowFilenames bool

	// Header format
	HeaderFormat HeaderFormat

	// Filename sequence type
	SequenceStyle SequenceStyle

	// Whether to show table of contents
	ShowTOC bool

	// Header alignment
	HeaderAlignment string

	// Header style
	HeaderStyle string

	// Page width for alignment
	PageWidth int

	// Additional file extensions to process
	AdditionalExtensions []string

	// Include patterns for file filtering (gitignore-style)
	IncludePatterns []string

	// Exclude patterns for file filtering (gitignore-style)
	ExcludePatterns []string

	// Output format (term, plain, markdown)
	OutputFormat string
}

FormattingOptions contains all formatting-related options

func BuildFormattingOptions added in v0.4.0

func BuildFormattingOptions(
	lineNum string,
	toc bool,
	theme string,
	showFilenames bool,
	fileNumbering string,
	filenameFormat string,
	filenameAlign string,
	filenameBanner string,
	pageWidth int,
	additionalExt []string,
	includePatterns []string,
	excludePatterns []string,
	outputFormat string,
) (FormattingOptions, error)

BuildFormattingOptions constructs FormattingOptions from command-line flag values

func MergeOptionsWithExplicitFlags added in v0.4.0

func MergeOptionsWithExplicitFlags(bundleOpts, cmdOpts FormattingOptions, explicitFlags map[string]bool) FormattingOptions

MergeOptionsWithExplicitFlags merges bundle options with command options based on explicit flags

func ParseBundleOptions added in v0.4.0

func ParseBundleOptions(optionLines []string) (FormattingOptions, error)

ParseBundleOptions parses bundle option lines using Cobra

type HeaderFormat added in v0.4.0

type HeaderFormat string

HeaderFormat represents different header formats

const (
	// HeaderFormatNice - formatted headers with decorations
	HeaderFormatNice HeaderFormat = "nice"
	// HeaderFormatFilename - just the filename
	HeaderFormatFilename HeaderFormat = "filename"
	// HeaderFormatPath - full file path
	HeaderFormatPath HeaderFormat = "path"
)

type LineNumberMode

type LineNumberMode int

LineNumberMode represents different line numbering modes

const (
	// LineNumberNone - no line numbers
	LineNumberNone LineNumberMode = iota
	// LineNumberFile - restart numbering for each file
	LineNumberFile
	// LineNumberGlobal - continuous numbering across all files
	LineNumberGlobal
)

type NoneBannerStyle added in v0.4.0

type NoneBannerStyle struct{}

NoneBannerStyle displays just the filename with optional alignment

func (NoneBannerStyle) Apply added in v0.4.0

func (n NoneBannerStyle) Apply(filename string, opts *FormattingOptions) string

func (NoneBannerStyle) Description added in v0.4.0

func (n NoneBannerStyle) Description() string

func (NoneBannerStyle) Name added in v0.4.0

func (n NoneBannerStyle) Name() string

type PathInfo

type PathInfo struct {
	// Original path as provided by user
	Original string

	// Absolute resolved path
	Absolute string

	// Type of path: "file", "directory", or "bundle"
	Type string

	// If directory, the files found within
	Files []string
}

PathInfo represents information about a resolved path

func ResolvePaths

func ResolvePaths(sources []string) ([]PathInfo, error)

ResolvePaths takes a list of source paths and resolves them to absolute paths It handles files, directories, and bundle files

func ResolvePathsWithOptions

func ResolvePathsWithOptions(sources []string, options *FormattingOptions) ([]PathInfo, error)

ResolvePathsWithOptions resolves paths with optional pattern filtering

type PatternMatcher

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

PatternMatcher handles include/exclude pattern matching for files

func NewPatternMatcher

func NewPatternMatcher(baseDir string, includePatterns, excludePatterns []string) *PatternMatcher

NewPatternMatcher creates a new pattern matcher

func (*PatternMatcher) HasPatterns

func (pm *PatternMatcher) HasPatterns() bool

HasPatterns returns true if any include or exclude patterns are specified

func (*PatternMatcher) NeedsRecursion

func (pm *PatternMatcher) NeedsRecursion() bool

NeedsRecursion returns true if recursive directory traversal is needed

func (*PatternMatcher) ShouldInclude

func (pm *PatternMatcher) ShouldInclude(filePath string) (bool, error)

ShouldInclude determines if a file should be included based on patterns

type Range

type Range struct {
	Start int
	End   int // 0 means end of file
}

Range represents a line range in a file Start is 1-based inclusive, End is 1-based inclusive (or 0 for EOF)

func NewRange

func NewRange(start, end int) (Range, error)

NewRange creates a new Range with validation

func (Range) Contains

func (r Range) Contains(line int) bool

Contains checks if a line number is within this range

func (Range) IsFullFile

func (r Range) IsFullFile() bool

IsFullFile returns true if this range represents the entire file

type RangeError

type RangeError struct {
	Input string
	Err   error
}

RangeError represents an error in line range specification

func (*RangeError) Error

func (e *RangeError) Error() string

func (*RangeError) Unwrap

func (e *RangeError) Unwrap() error

type RendererOptions

type RendererOptions struct {
	IncludeTOC         bool
	IncludeLineNumbers bool
	UseRichFormatting  bool
}

RendererOptions controls how the document is rendered

type SequenceStyle

type SequenceStyle string

SequenceStyle represents different sequence numbering styles

const (
	// SequenceNumerical - 1, 2, 3...
	SequenceNumerical SequenceStyle = "numerical"
	// SequenceLetter - a, b, c...
	SequenceLetter SequenceStyle = "letter"
	// SequenceRoman - i, ii, iii...
	SequenceRoman SequenceStyle = "roman"
)

type SolidBannerStyle added in v0.4.0

type SolidBannerStyle struct{}

SolidBannerStyle uses solid lines above and below

func (SolidBannerStyle) Apply added in v0.4.0

func (s SolidBannerStyle) Apply(filename string, opts *FormattingOptions) string

func (SolidBannerStyle) Description added in v0.4.0

func (s SolidBannerStyle) Description() string

func (SolidBannerStyle) Name added in v0.4.0

func (s SolidBannerStyle) Name() string

type TOCEntry

type TOCEntry struct {
	// Display title for the TOC entry
	Title string

	// File path this entry refers to
	Path string

	// Heading level (1 for H1, 2 for H2, etc.)
	Level int

	// Sequence number/letter/roman numeral if applicable
	Sequence string

	// Line number in the final document
	LineNumber int
}

TOCEntry represents an entry in the table of contents

type Theme

type Theme struct {
	Name   string
	Styles map[string]string
}

Theme represents a formatting theme with style definitions

func LoadCustomTheme

func LoadCustomTheme(themePath string) (*Theme, error)

LoadCustomTheme loads a theme from a custom file path

func LoadTheme

func LoadTheme(themeName string) (*Theme, error)

LoadTheme loads a theme from the embedded filesystem

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL