parser

Documentation

Overview

Package parser is the foundational Markdown engine for cheatmd. It reads Markdown files, extracting code blocks, metadata, variable bindings, and module scopes into a unified Abstract Syntax Tree (AST) that the rest of the application utilizes.

Index

• func ExtractVars(command string, allowDollar, allowAngle bool) []string
• func IsCheatEnd(trimmed string) bool
• func IsCheatStart(trimmed string) bool
• func IsShellLanguage(lang string) bool
• func IsVarChar(c byte, first bool) bool
• func ParseCheatSingleLine(trimmed string) (string, bool)
• func ParseMarkdownHeader(trimmed string) (header string, level int, ok bool)
• func SplitFirstWord(s string) (head, rest string)
• func SplitLines(s string) []string
• type Cheat
  • func NewCheat(file, header string) *Cheat
• type CheatIndex
  • func NewCheatIndex() *CheatIndex
  • func (idx *CheatIndex) AddCheat(cheat *Cheat)
  • func (idx *CheatIndex) FilterByConfig(requireCheatBlock bool) []*Cheat
  • func (idx *CheatIndex) RegisterModule(cheat *Cheat)
• type DuplicateExport
• type Module
  • func NewModule(cheat *Cheat) *Module
• type ParseError
• type Parser
  • func NewParser() *Parser
  • func (p *Parser) ParseDirectory(dir string) (*CheatIndex, error)
  • func (p *Parser) ParseSingleFile(path string) (*CheatIndex, error)
• type VarDef
  • func ParseVarDef(name, value string) VarDef
  • func ParseVarDefLiteral(name, value string) VarDef
  • func ParseVarDefWithCondition(name, value, condition string, isLiteral bool) VarDef

Functions

func ExtractVars

func ExtractVars(command string, allowDollar, allowAngle bool) []string

ExtractVars finds all variables in a command string. It respects the provided flags for dollar ($var) and angle bracket (<var>) syntaxes. It returns a deduplicated list of variable names in the exact order they appear from left to right.

func IsCheatEnd

func IsCheatEnd(trimmed string) bool

IsCheatEnd checks if the line closes an HTML comment block.

func IsCheatStart

func IsCheatStart(trimmed string) bool

IsCheatStart checks if the line is the start of a multi-line cheat comment block.

func IsShellLanguage

func IsShellLanguage(lang string) bool

IsShellLanguage reports whether the code-fence language is a shell language (one where $var injection is safe).

func IsVarChar

func IsVarChar(c byte, first bool) bool

IsVarChar returns true if c is valid in a variable name.

func ParseCheatSingleLine

func ParseCheatSingleLine(trimmed string) (string, bool)

ParseCheatSingleLine extracts the content of a single-line HTML comment if it starts with "cheat".

func ParseMarkdownHeader

func ParseMarkdownHeader(trimmed string) (header string, level int, ok bool)

ParseMarkdownHeader parses a line to see if it is a markdown header. It returns the header text, the level (number of #s), and a boolean indicating if it is a valid header.

func SplitFirstWord

func SplitFirstWord(s string) (head, rest string)

SplitFirstWord splits a string into the first word and the rest of the string.

func SplitLines

func SplitLines(s string) []string

SplitLines splits text into non-empty trimmed lines.

Types

type Cheat

type Cheat struct {
	File          string            // Source file path
	Header        string            // Section header
	HeaderLine    int               // 1-indexed source line of the heading
	Description   string            // Description text
	Command       string            // Shell command template
	CommandLang   string            // Code fence language for Command
	CommandStart  int               // 1-indexed source line of first command line
	CommandEnd    int               // 1-indexed source line of last command line
	Tags          []string          // Tags from path/header
	Export        string            // Module name if exported
	Imports       []string          // Imported modules
	ChainName     string            // Chain group name, when this cheat is a chain step
	ChainStep     int               // 1-indexed chain step number
	Vars          []VarDef          // Variable definitions
	Scope         map[string]string // Resolved values at runtime
	HasCheatBlock bool              // Whether this cheat has a <!-- cheat --> block
}

Cheat represents a single executable cheat entry.

func NewCheat

func NewCheat(file, header string) *Cheat

NewCheat creates a new Cheat.

type CheatIndex

type CheatIndex struct {
	Cheats        []*Cheat
	Modules       map[string]*Module
	Duplicates    []DuplicateExport
	Errors        []ParseError
	Root          string
	ChainMaxSteps map[string]int
}

CheatIndex holds all parsed cheats and modules.

func NewCheatIndex

func NewCheatIndex() *CheatIndex

NewCheatIndex creates an empty cheat index.

func (*CheatIndex) AddCheat

func (idx *CheatIndex) AddCheat(cheat *Cheat)

AddCheat adds a cheat to the index.

func (*CheatIndex) FilterByConfig

func (idx *CheatIndex) FilterByConfig(requireCheatBlock bool) []*Cheat

FilterByConfig filters the cheats, enforcing configuration requirements.

func (*CheatIndex) RegisterModule

func (idx *CheatIndex) RegisterModule(cheat *Cheat)

RegisterModule registers a module from a cheat with an export. Duplicate export names are tracked for later reporting.

type DuplicateExport

type DuplicateExport struct {
	Name  string
	File1 string
	File2 string
}

DuplicateExport records a duplicate export definition.

type Module

type Module struct {
	Name    string
	Vars    []VarDef
	Imports []string
	File    string
	Cheats  []*Cheat
}

Module represents an exportable module with variables.

func NewModule

func NewModule(cheat *Cheat) *Module

NewModule creates a Module from a Cheat.

type ParseError

type ParseError struct {
	File    string
	Line    int
	Message string
}

ParseError records a syntax error encountered during parsing.

type Parser

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

Parser handles markdown file parsing

func NewParser

func NewParser() *Parser

NewParser creates a new parser

func (*Parser) ParseDirectory

func (p *Parser) ParseDirectory(dir string) (*CheatIndex, error)

ParseDirectory recursively parses all markdown files in a directory

func (*Parser) ParseSingleFile

func (p *Parser) ParseSingleFile(path string) (*CheatIndex, error)

ParseSingleFile parses a single markdown file

type VarDef

type VarDef struct {
	Name      string // Variable name
	Shell     string // Shell command to generate values (for = syntax)
	Literal   string // Literal value with var substitution (for := syntax)
	Args      string // Selector arguments after ---
	Condition string // Conditional expression: "$var == value" or "$var != value"
}

VarDef represents a variable definition.

func ParseVarDef

func ParseVarDef(name, value string) VarDef

ParseVarDef parses a variable definition from name and value (shell command).

func ParseVarDefLiteral

func ParseVarDefLiteral(name, value string) VarDef

ParseVarDefLiteral parses a literal variable definition (no shell, just substitution).

func ParseVarDefWithCondition

func ParseVarDefWithCondition(name, value, condition string, isLiteral bool) VarDef

ParseVarDefWithCondition parses a variable definition with an optional condition.