ast.go

package sham

import (
	"fmt"
	"math/rand"
)

// Node represents a single element in the abstract syntax tree. A valid Sham
// AST must be able to generate data. As such, every node in tree must be
// implement the Generator interface. There are two main type of nodes: structural
// and terminal. Terminal nodes are leaves that generate values. Structural nodes
// generate the data structures that hold these values.
type Node interface {
	Generator
}

// Schema represents a Sham schema and holds the root of the AST. The root of the
// AST must either be a single terminal node, or a structural node.
type Schema struct {
	Root Node
}

// Generate triggers the Sham data generation process. The generation process
// begins with the root and walks the tree, generating data structures and data
// as it goes. Data generation cannot cause errors. Any possible errors will
// have been caught during the tokenization and parsing processes. This method
// can be called more than once to generate more data using the same schema.
func (s Schema) Generate() interface{} {
	if s.Root == nil {
		return nil
	}

	return s.Root.Generate()
}

// Object represents a key-value data structure. In order to maintain the key
// order in the schema, the pairs are stored in a slice and converted to an
// ordered map during the generation process. If a key is provided multiple
// times, the last value will be used during generation.
type Object struct {
	Values []KV
}

// KV represents a single key-value pair in an Object.
type KV struct {
	Key   string
	Value Node
}

// AppendPair adds a key-value pair to an Object.
func (m *Object) AppendPair(k string, v Node) {
	m.Values = append(m.Values, KV{Key: k, Value: v})
}

// Generate creates a map of key-value pairs from the slice of KVs. An ordered
// map is used to preserve the order of the provided keys. If the same key is
// provided multiple times, then only the last value will be used.
func (m Object) Generate() interface{} {
	out := NewOrderedMap()
	for _, kv := range m.Values {
		out.Set(kv.Key, kv.Value.Generate())
	}
	return out
}

// Array represents a list of values that can be generated. An array has two
// potential parts: an inner node and a range. The inner node defines the
// structure of the array elements, and the range defines how many elements
// should be present. The range is optional. If omitted, one element will be
// generated.
type Array struct {
	Range *Range
	Inner Node
}

// Generate creates a slice of generated values where each value is defined by
// the inner node field. If the range is omitted, then exactly one element will
// populate the array. Otherwise, a random number of elements will be generated
// based on the inclusive range of integers.
func (a Array) Generate() interface{} {
	if a.Inner == nil {
		return []interface{}{}
	}

	n := 1
	if a.Range != nil {
		n = a.Range.GetValue()
	}

	out := make([]interface{}, n)
	for i := 0; i < n; i++ {
		out[i] = a.Inner.Generate()
	}
	return out
}

// Range is an inclusive range of integers. Ranges have two uses within the a
// Sham schema. If provided as the first argument in an array, the range will
// be used to determine the number of elements to populate the array. If provided
// in the position of a terminal generator, then a random integer will be
// generated for the value.
type Range struct {
	Min int
	Max int
}

// GetValue retrieves a random integer from the inclusive range [min, max]. The
// chosen integer is not cryptographically secure and should never be treated
// as such.
func (r Range) GetValue() int {
	if r.Min == r.Max {
		return r.Min
	}

	return rand.Intn((r.Max+1)-r.Min) + r.Min
}

// Generate chooses a random integer from the inclusive range.
func (r Range) Generate() interface{} { return r.GetValue() }

// FormattedString represents a string literal with values that can be interpolated
// into the string. In the Sham language, formatted strings are enclosed in
// backticks, and the interpolated values are enclosed by curly braces. Interpolated
// values must be valid, registered terminal generators.
type FormattedString struct {
	Raw    string
	Format string
	Params []Generator
}

// Generate produces a string literal value by replacing interpolated values with
// the values generated by the corresponding terminal generator.
func (f FormattedString) Generate() interface{} {
	if len(f.Params) == 0 {
		return f.Raw
	}

	params := make([]interface{}, len(f.Params))
	for i, p := range f.Params {
		params[i] = p.Generate()
	}
	return fmt.Sprintf(f.Format, params...)
}

// TerminalGenerator represents a function that can generate data.
type TerminalGenerator struct {
	Name string
	fn   Generator
}

// Generate runs the terminal generator's generation function. The generator is
// expected to be a non nil interface. If nil was registered for this terminal
// generator, then this method will panic.
func (t TerminalGenerator) Generate() interface{} {
	return t.fn.Generate()
}

// Literal represents a literal value. No data generation is involved here, but
// rather values are returned as-is.
type Literal struct {
	Value interface{}
}

// Generate returns the literal value.
func (l Literal) Generate() interface{} { return l.Value }