steps

type Accessor[M any] interface {
	// Path compiles one path, or reports why it cannot.
	Path(raw string) (Path[M], error)

	// Condition compiles a when expression over this format.
	Condition(src string) (expr.Expr[M], error)

	// CheckStep refuses a step this format cannot honour, and returns nil for everything it can.
	//
	// For the refusals that are real but specific: a trim on an X12 ISA element can never have an effect, because ISA is
	// fixed width and the padding is put straight back. Refusing at load beats a step that runs forever and does nothing.
	CheckStep(s Step) error
}

type CaseStep struct {
	Path string `yaml:"path"`

	// To is "upper" or "lower".
	To string `yaml:"to"`
}

type Change struct {
	// Path is where it happened, in canonical form.
	Path string
	// Description is the step's own explanation, when it gave one.
	Description string
	// From and To are the values before and after.
	From string
	To   string
}

type ClearStep struct {
	Path string `yaml:"path"`
}

type CopyStep struct {
	From string `yaml:"from"`
	To   string `yaml:"to"`
}

type MapStep struct {
	Path string `yaml:"path"`

	// Table names a code set loaded with the channel.
	Table string `yaml:"table"`

	// Default is written when the value is not in the table. Optional.
	Default string `yaml:"default,omitempty"`

	// OnMissing decides what happens when the value is absent from the table and no default is given.
	//
	// Defaults to "keep", which leaves the value alone. The alternative is "fail", which stops the message. There is no
	// option that silently blanks it, because a claim with an empty payer identifier is rejected downstream in a way
	// that points at the wrong system.
	OnMissing string `yaml:"on_missing,omitempty"`
}

type Path[M any] struct {
	// Canonical is the path in canonical form, for change records and error messages.
	Canonical string

	// Read returns the value at this path and whether it was present.
	//
	// The bool distinguishes absent from empty, which every format here treats as different things: a blank field was
	// sent deliberately and an absent one was never sent.
	Read func(M) (string, bool)

	// Write returns a message with the value written. It must not modify its receiver.
	Write func(M, string) (M, error)
}

type ReplaceStep struct {
	Path    string `yaml:"path"`
	Pattern string `yaml:"pattern"`
	With    string `yaml:"with"`
}

type SetStep struct {
	Path  string `yaml:"path"`
	Value string `yaml:"value"`
}

type Step struct {
	// Description is free text explaining why this step exists. Optional, shown in the interface, and worth writing: the
	// next person to read this channel is trying to work out whether the step is still needed.
	Description string `yaml:"description,omitempty"`

	// When is an optional condition. The step is skipped unless it holds.
	//
	// The same grammar as any filter in this server - and, or, not, ==, !=, =~, exists, empty, in - because the grammar
	// is generic over the format. The only thing that changes between formats is how the path is written.
	When string `yaml:"when,omitempty"`

	// Set writes a value at a path.
	Set *SetStep `yaml:"set,omitempty"`

	// Copy takes the value at one path and writes it to another.
	Copy *CopyStep `yaml:"copy,omitempty"`

	// Clear empties a field, leaving it present.
	//
	// Not the same as removing it, and these formats make that distinction meaningful: a blank field was sent
	// deliberately while an absent one was never sent. There is no remove step for exactly that reason - the honest
	// options are to blank the field or to leave it alone.
	Clear *ClearStep `yaml:"clear,omitempty"`

	// Map translates a value through a lookup table.
	Map *MapStep `yaml:"map,omitempty"`

	// Replace performs a regular-expression substitution.
	Replace *ReplaceStep `yaml:"replace,omitempty"`

	// Trim removes surrounding whitespace.
	//
	// Worth having as its own step rather than a replace: these formats pad fixed-width fields with spaces, so this is
	// one of the most common changes an interface needs, and a named step is readable where a pattern is not.
	Trim *TrimStep `yaml:"trim,omitempty"`

	// Case changes a value to upper or lower case.
	Case *CaseStep `yaml:"case,omitempty"`
}

type Steps[M any] struct {
	// contains filtered or unexported fields
}

type TrimStep struct {
	Path string `yaml:"path"`
}