parse

type Act struct {

	// at what point during sequence of sub-rules / tokens should this action be run?  -1 = at end, 0 = before first rule, 1 = before second rule, etc -- must be at point when relevant Ast nodes have been added, but for scope setting, must be early enough so that scope is present
	RunIdx int `` /* 280-byte string literal not displayed */

	// what action to perform
	Act Actions `desc:"what action to perform"`

	// Ast path, relative to current node: empty = current node; [idx] specifies a child node by index, and a name specifies it by name -- include name/name for sub-nodes etc -- multiple path options can be specified by | or & and will be tried in order until one succeeds (for |) or all that succeed will be used for &. ... means use all nodes with given name (only for change token) -- for PushStack, this is what to push on the stack
	Path string `` /* 447-byte string literal not displayed */

	// for ChgToken, the new token type to assign to token at given path
	Tok token.Tokens `desc:"for ChgToken, the new token type to assign to token at given path"`

	// for ChgToken, only change if token is this to start with (only if != None))
	FmTok token.Tokens `desc:"for ChgToken, only change if token is this to start with (only if != None))"`
}

type Actions int

type Acts []Act

type Ast struct {
	ki.Node

	// region in source lexical tokens corresponding to this Ast node -- Ch = index in lex lines
	TokReg lex.Reg `desc:"region in source lexical tokens corresponding to this Ast node -- Ch = index in lex lines"`

	// region in source file corresponding to this Ast node
	SrcReg lex.Reg `desc:"region in source file corresponding to this Ast node"`

	// source code corresponding to this Ast node
	Src string `desc:"source code corresponding to this Ast node"`

	// stack of symbols created for this node
	Syms syms.SymStack `desc:"stack of symbols created for this node"`
}

type AstActs int

type MatchStack []MatchState

type MatchState struct {

	// rule that either matched or ran here
	Rule *Rule `desc:"rule that either matched or ran here"`

	// scope for match
	Scope lex.Reg `desc:"scope for match"`

	// regions of match for each sub-region
	Regs Matches `desc:"regions of match for each sub-region"`
}

type Matches []lex.Reg

type Parser interface {
	ki.Ki

	// Compile compiles string rules into their runnable elements
	Compile(ps *State) bool

	// Validate checks for any errors in the rules and issues warnings,
	// returns true if valid (no err) and false if invalid (errs)
	Validate(ps *State) bool

	// Parse tries to apply rule to given input state, returns rule that matched or nil
	// par is the parent rule that we're being called from
	// ast is the current ast node that we add to
	Parse(ps *State, par *Rule, ast *Ast, scope lex.Reg, optMap lex.TokenMap, depth int) *Rule

	// AsParseRule returns object as a parse.Rule
	AsParseRule() *Rule
}

type Rule struct {
	ki.Node

	// disable this rule -- useful for testing and exploration
	Off bool `desc:"disable this rule -- useful for testing and exploration"`

	// description / comments about this rule
	Desc string `desc:"description / comments about this rule"`

	// the rule as a space-separated list of rule names and token(s) -- use single quotes around 'tokens' (using token.Tokens names or symbols). For keywords use 'key:keyword'.  All tokens are matched at the same nesting depth as the start of the scope of this rule, unless they have a +D relative depth value differential before the token.  Use @ prefix for a sub-rule to require that rule to match -- by default explicit tokens are used if available, and then only the first sub-rule failing that.  Use ! by itself to define start of an exclusionary rule -- doesn't match when those rule elements DO match.  Use : prefix for a special group node that matches a single token at start of scope, and then defers to the child rules to perform full match -- this is used for FirstTokMap when there are multiple versions of a given keyword rule.  Use - prefix for tokens anchored by the end (next token) instead of the previous one -- typically just for token prior to 'EOS' but also a block of tokens that need to go backward in the middle of a sequence to avoid ambiguity can be marked with -
	Rule string `` /* 1090-byte string literal not displayed */

	// if present, this rule only fires if stack has this on it
	StackMatch string `desc:"if present, this rule only fires if stack has this on it"`

	// what action should be take for this node when it matches
	Ast AstActs `desc:"what action should be take for this node when it matches"`

	// actions to perform based on parsed Ast tree data, when this rule is done executing
	Acts Acts `desc:"actions to perform based on parsed Ast tree data, when this rule is done executing"`

	// for group-level rules having lots of children and lots of recursiveness, and also of high-frequency, when we first encounter such a rule, make a map of all the tokens in the entire scope, and use that for a first-pass rejection on matching tokens
	OptTokMap bool `` /* 253-byte string literal not displayed */

	// for group-level rules with a number of rules that match based on first tokens / keywords, build map to directly go to that rule -- must also organize all of these rules sequentially from the start -- if no match, goes directly to first non-lookup case
	FirstTokMap bool `` /* 258-byte string literal not displayed */

	// rule elements compiled from Rule string
	Rules RuleList `json:"-" xml:"-" desc:"rule elements compiled from Rule string"`

	// strategic matching order for matching the rules
	Order []int `inactive:"+" json:"-" xml:"-" desc:"strategic matching order for matching the rules"`

	// map from first tokens / keywords to rules for FirstTokMap case
	FiTokMap map[string]*Rule `inactive:"+" json:"-" xml:"-" desc:"map from first tokens / keywords to rules for FirstTokMap case"`

	// for FirstTokMap, the start of the else cases not covered by the map
	FiTokElseIdx int `inactive:"+" json:"-" xml:"-" desc:"for FirstTokMap, the start of the else cases not covered by the map"`

	// exclusionary key index -- this is the token in Rules that we need to exclude matches for using ExclFwd and ExclRev rules
	ExclKeyIdx int `` /* 157-byte string literal not displayed */

	// exclusionary forward-search rule elements compiled from Rule string
	ExclFwd RuleList `inactive:"+" json:"-" xml:"-" desc:"exclusionary forward-search rule elements compiled from Rule string"`

	// exclusionary reverse-search rule elements compiled from Rule string
	ExclRev RuleList `inactive:"+" json:"-" xml:"-" desc:"exclusionary reverse-search rule elements compiled from Rule string"`
}

type RuleEl struct {

	// sub-rule for this position -- nil if token
	Rule *Rule `desc:"sub-rule for this position -- nil if token"`

	// token, None if rule
	Tok token.KeyToken `desc:"token, None if rule"`

	// start increment for matching -- this is the number of non-optional, non-match items between (start | last match) and this item -- increments start region for matching
	StInc int `` /* 173-byte string literal not displayed */

	// if true, this rule must match for rule to fire -- by default only tokens and, failing that, the first sub-rule is used for matching -- use @ to require a match
	Match bool `` /* 166-byte string literal not displayed */

	// this rule is optional -- will absorb tokens if they exist -- indicated with ? prefix
	Opt bool `desc:"this rule is optional -- will absorb tokens if they exist -- indicated with ? prefix"`

	// match this rule working backward from the next token -- triggered by - (minus) prefix and optimizes cases where there can be a lot of tokens going forward but few going from end -- must be anchored by a terminal EOS or other FmNext elements and is ignored if at the very end
	FmNext bool `` /* 281-byte string literal not displayed */
}

type RuleFlags int

type RuleList []RuleEl

type ScopeRule struct {
	Scope lex.Reg
	Rule  *Rule
}

type ScopeRuleSet map[ScopeRule]struct{}

type State struct {

	// [view: no-inline] source and lexed version of source we're parsing
	Src *lex.File `view:"no-inline" desc:"source and lexed version of source we're parsing"`

	// tracing for this parser
	Trace TraceOpts `desc:"tracing for this parser"`

	// root of the Ast abstract syntax tree we're updating
	Ast *Ast `desc:"root of the Ast abstract syntax tree we're updating"`

	// symbol map that everything gets added to from current file of parsing -- typically best for subsequent management to just have a single outer-most scoping symbol here (e.g., in Go it is the package), and then everything is a child under that
	Syms syms.SymMap `` /* 248-byte string literal not displayed */

	// stack of scope(s) added to FileSyms e.g., package, library, module-level elements of which this file is a part -- these are reset at the start and must be added by parsing actions within the file itself
	Scopes syms.SymStack `` /* 209-byte string literal not displayed */

	// the current lex token position
	Pos lex.Pos `desc:"the current lex token position"`

	// [view: no-inline] any error messages accumulated during parsing specifically
	Errs lex.ErrorList `view:"no-inline" desc:"any error messages accumulated during parsing specifically"`

	// [view: no-inline] rules that matched and ran at each point, in 1-to-1 correspondence with the Src.Lex tokens for the lines and char pos dims
	Matches [][]MatchStack `` /* 146-byte string literal not displayed */

	// [view: no-inline] rules that did NOT match -- represented as a map by scope of a RuleSet
	NonMatches ScopeRuleSet `view:"no-inline" desc:"rules that did NOT match -- represented as a map by scope of a RuleSet"`

	// [view: no-inline] stack for context-sensitive rules
	Stack lex.Stack `view:"no-inline" desc:"stack for context-sensitive rules"`
}

type Steps int

type TraceOpts struct {

	// perform tracing
	On bool `desc:"perform tracing"`

	// trace specific named rules here (space separated) -- if blank, then all rules are traced
	Rules string `width:"50" desc:"trace specific named rules here (space separated) -- if blank, then all rules are traced"`

	// trace full rule matches -- when a rule fully matches
	Match bool `desc:"trace full rule matches -- when a rule fully matches"`

	// trace sub-rule matches -- when the parts of each rule match
	SubMatch bool `desc:"trace sub-rule matches -- when the parts of each rule match"`

	// trace sub-rule non-matches -- why a rule doesn't match -- which terminates the matching process at first non-match (can be a lot of info)
	NoMatch bool `` /* 144-byte string literal not displayed */

	// trace progress running through each of the sub-rules when a rule has matched and is 'running'
	Run bool `desc:"trace progress running through each of the sub-rules when a rule has matched and is 'running'"`

	// trace actions performed by running rules
	RunAct bool `desc:"trace actions performed by running rules"`

	// if true, shows the full scope source for every trace statement
	ScopeSrc bool `desc:"if true, shows the full scope source for every trace statement"`

	// for the ParseOut display, whether to display the full stack of rules at each position, or just the deepest one
	FullStackOut bool `desc:"for the ParseOut display, whether to display the full stack of rules at each position, or just the deepest one"`

	// [view: -] list of rules
	RulesList []string `view:"-" json:"-" xml:"-" desc:"list of rules"`

	// [view: -] trace output is written here, connected via os.Pipe to OutRead
	OutWrite *os.File `view:"-" json:"-" xml:"-" desc:"trace output is written here, connected via os.Pipe to OutRead"`

	// [view: -] trace output is read here -- can connect this to a TextBuf via giv.OutBuf to monitor tracing output
	OutRead *os.File `` /* 132-byte string literal not displayed */
}