interfaces

type AnyInvariant struct {
	Expr Expr
}

type Arg struct {
	Name string
	Type *types.Type // nil if unspecified (needs to be solved for)
}

type CallFuncArgsValueInvariant struct {
	// Expr represents the pointer to the ExprCall.
	Expr Expr

	// Func represents the pointer to the ExprFunc that ExprCall is using.
	Func Expr

	// Args represents the list of args that the ExprCall is using to call
	// the ExprFunc. A solver might speculatively call Value() on each of
	// these in the hopes of doing something useful if a value happens to be
	// known statically at compile time. One such solver that might do this
	// is the GeneratorInvariant inside of a difficult function like printf.
	Args []Expr
}

type ConjunctionInvariant struct {
	Invariants []Invariant
}

type Data struct {
	// Fs represents a handle to the filesystem that we're running on. This
	// is necessary for opening files if needed by import statements. The
	// file() paths used to get templates or other files from our deploys
	// come from here, this is *not* used to interact with the host file
	// system to manage file resources or other aspects.
	Fs engine.Fs

	// FsURI is the fs URI of the active filesystem. This is useful to pass
	// to the engine.World API for further consumption.
	FsURI string

	// Base directory (absolute path) that the running code is in. If an
	// import is found, that's a recursive addition, and naturally for that
	// run, this value would be different in the recursion.
	Base string

	// Files is a list of absolute paths seen so far. This includes all
	// previously seen paths, where as the former Offsets parameter did not.
	Files []string

	// Imports stores a graph inside a vertex so we have a current cursor.
	// This means that as we recurse through our import graph (hopefully a
	// DAG) we can know what the parent vertex in our graph is to edge to.
	// If we ever can't topologically sort it, then it has an import loop.
	Imports *pgraph.SelfVertex

	// Metadata is the metadata structure associated with the given parsing.
	// It can be present, which is often the case when importing a module,
	// or it can be nil, which is often the case when parsing a single file.
	// When imports are nested (eg: an imported module imports another one)
	// the metadata structure can recursively point to an earlier structure.
	Metadata *Metadata

	// Modules is an absolute path to a modules directory on the current Fs.
	// It is the directory to use to look for remote modules if we haven't
	// specified an alternative with the metadata Path field. This is
	// usually initialized with the global modules path that can come from
	// the cli or an environment variable, but this only occurs for the
	// initial download/get operation, and obviously not once we're running
	// a deploy, since by then everything in here would have been copied to
	// the runtime fs.
	Modules string

	// Downloader is the interface that must be fulfilled to download
	// modules. If a missing import is found, and this is not nil, then it
	// will be run once in an attempt to get the missing module before it
	// fails outright. In practice, it is recommended to separate this
	// download phase in a separate step from the production running and
	// deploys, however that is not blocked at the level of this interface.
	Downloader Downloader

	// LexParser is a function that needs to get passed in to run the lexer
	// and parser to build the initial AST. This is passed in this way to
	// avoid dependency cycles.
	LexParser func(io.Reader) (Stmt, error)

	// StrInterpolater is a function that needs to get passed in to run the
	// string interpolation. This is passed in this way to avoid dependency
	// cycles.
	StrInterpolater func(string, *Pos, *Data) (Expr, error)

	// Prefix provides a unique path prefix that we can namespace in. It is
	// currently shared identically across the whole AST. Nodes should be
	// careful to not write on top of other nodes data.
	Prefix string

	// Debug represents if we're running in debug mode or not.
	Debug bool

	// Logf is a logger which should be used.
	Logf func(format string, v ...interface{})
}

type DataFunc interface {
	Func // implement everything in Func but add the additional requirements

	// SetData is used by the language to pass our function some code-level
	// context.
	SetData(*FuncData)
}

type DownloadInfo struct {
	// Fs is the filesystem to use for downloading to.
	Fs engine.Fs

	// Noop specifies if we should actually download or just fake it. The
	// one problem is that if we *don't* download something, then we can't
	// follow it to see if there's anything else to download.
	Noop bool

	// Sema specifies the max number of simultaneous downloads to run.
	Sema int

	// Update specifies if we should try and update existing downloaded
	// artifacts.
	Update bool

	// Debug represents if we're running in debug mode or not.
	Debug bool

	// Logf is a logger which should be used.
	Logf func(format string, v ...interface{})
}

type Downloader interface {
	// Init initializes the downloader with some core structures we'll need.
	Init(*DownloadInfo) error

	// Get runs a single download of an import and stores it on disk.
	Get(*ImportData, string) error
}

type Edge struct {
	Kind1 string // kind of resource
	Name1 string // name of resource
	Send  string // name of field used for send/recv (optional)

	Kind2 string // kind of resource
	Name2 string // name of resource
	Recv  string // name of field used for send/recv (optional)

	Notify bool // is there a notification being sent?
}

type EqualityInvariant struct {
	Expr1 Expr
	Expr2 Expr
}

type EqualityInvariantList struct {
	Exprs []Expr
}

type EqualityWrapCallInvariant struct {
	Expr1     Expr
	Expr2Func Expr
}

type EqualityWrapFuncInvariant struct {
	Expr1    Expr
	Expr2Map map[string]Expr
	Expr2Ord []string
	Expr2Out Expr
}

type EqualityWrapListInvariant struct {
	Expr1    Expr
	Expr2Val Expr
}

type EqualityWrapMapInvariant struct {
	Expr1    Expr
	Expr2Key Expr
	Expr2Val Expr
}

type EqualityWrapStructInvariant struct {
	Expr1    Expr
	Expr2Map map[string]Expr
	Expr2Ord []string
}

type EqualsInvariant struct {
	Expr Expr
	Type *types.Type
}

type Error string

type ExclusiveInvariant struct {
	Invariants []Invariant
}

type Expr interface {
	Node

	// Init initializes the populated node and does some basic validation.
	Init(*Data) error

	// Interpolate returns an expanded form of the AST as a new AST. It does
	// a recursive interpolate (copy) of all members in the AST. For a light
	// copy use Copy.
	Interpolate() (Expr, error)

	// Copy returns a light copy of the struct. Anything static will not be
	// copied. For a full recursive copy consider using Interpolate instead.
	// TODO: do we need an error in the signature?
	Copy() (Expr, error)

	// Ordering returns a graph of the scope ordering that represents the
	// data flow. This can be used in SetScope so that it knows the correct
	// order to run it in.
	Ordering(map[string]Node) (*pgraph.Graph, map[Node]string, error)

	// SetScope sets the scope here and propagates it downwards.
	SetScope(*Scope, map[string]Expr) error

	// SetType sets the type definitively, and errors if it is incompatible.
	SetType(*types.Type) error

	// Type returns the type of this expression. It may speculate if it can
	// determine it statically. This errors if it is not yet known.
	Type() (*types.Type, error)

	// Unify returns the list of invariants that this node produces. It does
	// so recursively on any children elements that exist in the AST, and
	// returns the collection to the caller.
	Unify() ([]Invariant, error)

	// Graph returns the reactive function graph expressed by this node. It
	// takes in the environment of any functions in scope. It also returns
	// the function for this node.
	Graph(env map[string]Func) (*pgraph.Graph, Func, error)

	// SetValue stores the result of the last computation of this expression
	// node.
	SetValue(types.Value) error

	// Value returns the value of this expression in our type system.
	Value() (types.Value, error)
}

type ExprAny struct {
	V types.Value // stored value (set with SetValue)
	// contains filtered or unexported fields
}

type Func interface {
	fmt.Stringer // so that this can be stored as a Vertex

	Validate() error // FIXME: this is only needed for PolyFunc. Get it moved and used!

	// Info returns some information about the function in question, which
	// includes the function signature. For a polymorphic function, this
	// might not be known until after Build was called. As a result, the
	// sig should be allowed to return a partial or variant type if it is
	// not known yet. This is because the Info method might be called
	// speculatively to aid in type unification.
	Info() *Info

	// Init passes some important values and references to the function.
	Init(*Init) error

	// Stream is the mainloop of the function. It reads and writes from
	// channels to return the changing values that this func has over time.
	// It should shutdown and cleanup when the input context is cancelled.
	// It must not exit before any goroutines it spawned have terminated.
	// It must close the Output chan if it's done sending new values out. It
	// must send at least one value, or return an error. It may also return
	// an error at anytime if it can't continue.
	Stream(context.Context) error
}

type FuncData struct {
	// Fs represents a handle to the filesystem that we're running on. This
	// is necessary for opening files if needed by import statements. The
	// file() paths used to get templates or other files from our deploys
	// come from here, this is *not* used to interact with the host file
	// system to manage file resources or other aspects.
	Fs engine.Fs

	// FsURI is the fs URI of the active filesystem. This is useful to pass
	// to the engine.World API for further consumption.
	FsURI string

	// Base directory (absolute path) that the running code is in. This is a
	// copy of the value from the Expr and Stmt Data struct for Init.
	Base string
}

type FuncEdge struct {
	Args []string // list of named args that this edge sends to
}

type FuncSig = func([]types.Value) (types.Value, error)

type GeneratorInvariant struct {
	// Func is a generator function that takes the state of the world, and
	// returns new invariants that should be added to this world view. The
	// state of the world includes both the currently unsolved invariants,
	// as well as the known solution map that has been solved so far. If
	// this returns nil, we add the invariants it returned and we remove it
	// from the list. If we error, it's because we don't have any new
	// information to provide at this time...
	Func func(invariants []Invariant, solved map[Expr]*types.Type) ([]Invariant, error)

	// Inactive specifies that we tried to run this, but it didn't help us
	// progress forwards. It can be reset if needed. It should only be set
	// or read by the solver itself.
	Inactive bool
}

type GraphAPI interface {
	AddVertex(Func) error
	AddEdge(Func, Func, *FuncEdge) error
	DeleteVertex(Func) error
	DeleteEdge(*FuncEdge) error

	//Adjacency() map[Func]map[Func]*FuncEdge
	HasVertex(Func) bool
	FindEdge(Func, Func) *FuncEdge
	LookupEdge(*FuncEdge) (Func, Func, bool)

	// Graph returns a copy of the current graph.
	Graph() *pgraph.Graph
}

type ImportData struct {
	// Name is the original input that produced this struct. It is stored
	// here so that you can parse it once and pass this struct around
	// without having to include a copy of the original data if needed.
	Name string

	// Alias is the name identifier that should be used for this import.
	Alias string

	// IsSystem specifies that this is a system import.
	IsSystem bool

	// IsLocal represents if a module is either local or a remote import.
	IsLocal bool

	// IsFile represents if we're referring to an individual file or not.
	IsFile bool

	// Path represents the relative path to the directory that this import
	// points to. Since it specifies a directory, it will end with a
	// trailing slash which makes detection more obvious for other helpers.
	// If this points to a local import, that directory is probably not
	// expected to contain a metadata file, and it will be a simple path
	// addition relative to the current file this import was parsed from. If
	// this is a remote import, then it's likely that the file will be found
	// in a more distinct path, such as a search path that contains the full
	// fqdn of the import.
	// TODO: should system imports put something here?
	Path string

	// URL is the path that a `git clone` operation should use as the URL.
	// If it is a local import, then this is the empty value.
	URL string
}

type Info struct {
	Pure bool        // is the function pure? (can it be memoized?)
	Memo bool        // should the function be memoized? (false if too much output)
	Slow bool        // is the function slow? (avoid speculative execution)
	Sig  *types.Type // the signature of the function, must be KindFunc
	Err  error       // is this a valid function, or was it created improperly?
}

type Init struct {
	Hostname string // uuid for the host

	// Input is where a chan (stream) of values will get sent to this node.
	// The engine will close this `input` chan.
	Input chan types.Value

	// Output is the chan (stream) of values to get sent out from this node.
	// The Stream function must close this `output` chan.
	Output chan types.Value

	// Txn provides a transaction API that can be used to modify the
	// function graph while it is "running". This should not be used by most
	// nodes, and when it is used, it should be used carefully.
	Txn Txn

	Local *local.API
	World engine.World

	Debug bool
	Logf  func(format string, v ...interface{})
}

type Invariant interface {
	// TODO: should we add any other methods to this type?
	fmt.Stringer

	// ExprList returns the list of valid expressions in this invariant.
	ExprList() []Expr

	// Matches returns whether an invariant matches the existing solution.
	// If it is inconsistent, then it errors.
	Matches(solved map[Expr]*types.Type) (bool, error)

	// Possible returns an error if it is certain that it is NOT possible to
	// get a solution with this invariant and the set of partials. In
	// certain cases, it might not be able to determine that it's not
	// possible, while simultaneously not being able to guarantee a possible
	// solution either. In this situation, it should return nil, since this
	// is used as a filtering mechanism, and the nil result of possible is
	// preferred over eliminating a tricky, but possible one.
	Possible(partials []Invariant) error
}

type Metadata struct {
	// Main is the path to the entry file where we start reading code.
	// Normally this is main.mcl or the value of the MainFilename constant.
	Main string `yaml:"main"`

	// Path is the relative path to the local module search path directory
	// that we should look in. This is similar to golang's vendor directory.
	// If a module wishes to include this directory, it's recommended that
	// it have the contained directory be a `git submodule` if possible.
	Path string `yaml:"path"`

	// Files is the location of the files/ directory which can contain some
	// useful additions that might get used in the modules. You can store
	// templates, or any other data that you'd like.
	// TODO: also allow storing files alongside the .mcl files in their dir!
	Files string `yaml:"files"`

	// License is the listed license of the module. Use the short names, eg:
	// LGPLv3+, or MIT.
	License string `yaml:"license"`

	// ParentPathBlock specifies whether we're allowed to search in parent
	// metadata file Path settings for modules. We always search in the
	// global path if we don't find others first. This setting defaults to
	// false, which is important because the downloader uses it to decide
	// where to put downloaded modules. It is similar to the equivalent of
	// a `require vendoring` flag in golang if such a thing existed. If a
	// module sets this to true, and specifies a Path value, then only that
	// path will be used as long as imports are present there. Otherwise it
	// will fall-back on the global modules directory. If a module sets this
	// to true, and does not specify a Path value, then the global modules
	// directory is automatically chosen for the import location for this
	// module. When this is set to true, in no scenario will an import come
	// from a directory other than the one specified here, or the global
	// modules directory. Module authors should use this sparingly when they
	// absolutely need a specific import vendored, otherwise they might
	// rouse the ire of module consumers. Keep in mind that you can specify
	// a Path directory, and include a git submodule in it, which will be
	// used by default, without specifying this option. In that scenario,
	// the consumer can decide to not recursively clone your submodule if
	// they wish to override it higher up in the module search locations.
	ParentPathBlock bool `yaml:"parentpathblock"`

	// Metadata stores a link to the parent metadata structure if it exists.
	Metadata *Metadata // this does *NOT* get a yaml struct tag
	// contains filtered or unexported fields
}

type NamedArgsFunc interface {
	Func // implement everything in Func but add the additional requirements

	// ArgGen implements the arg name generator function. By default, we use
	// the util.NumToAlpha function when this interface isn't implemented...
	ArgGen(int) (string, error)
}

type Node interface {
	//fmt.Stringer // already provided by pgraph.Vertex
	pgraph.Vertex // must implement this since we store these in our graphs

	// Apply is a general purpose iterator method that operates on any node.
	Apply(fn func(Node) error) error
}

type OldPolyFunc interface {
	Func // implement everything in Func but add the additional requirements

	// Polymorphisms returns a list of possible function type signatures. It
	// takes as input a list of partial "hints" as to limit the number of
	// possible results it returns. These partial hints take the form of a
	// function type signature (with as many types in it specified and the
	// rest set to nil) and any known static values for the input args. If
	// the partial type is not nil, then the Ord parameter must be of the
	// correct arg length. If any types are specified, then the array must
	// be of that length as well, with the known ones filled in. Some
	// static polymorphic functions require a minimal amount of hinting or
	// they will be unable to return any possible result that is not
	// infinite in length. If you expect to need to return an infinite (or
	// very large) amount of results, then you should return an error
	// instead. The arg names in your returned func type signatures should
	// be in the standardized "a..b..c" format. Use util.NumToAlpha if you
	// want to convert easily.
	Polymorphisms(*types.Type, []types.Value) ([]*types.Type, error)

	// Build takes the known or unified type signature for this function and
	// finalizes this structure so that it is now determined, and ready to
	// function as a normal function would. (The normal methods in the Func
	// interface are all that should be needed or used after this point.)
	// Of note, the names of the specific input args shouldn't matter as
	// long as they are unique. Their position doesn't matter. This is so
	// that unification can use "arg0", "arg1", "argN"... if they can't be
	// determined statically. Build can transform them into it's desired
	// form, and must return the type (with the correct arg names) that it
	// will use. These are used when constructing the function graphs. This
	// means that when this is called from SetType, it can set the correct
	// type arg names, and this will also match what's in function Info().
	Build(*types.Type) (*types.Type, error)
}

type Output struct {
	Resources []engine.Res
	Edges     []*Edge
}

type PolyFunc interface {
	Func // implement everything in Func but add the additional requirements

	// Unify returns the list of invariants that this func produces. It is a
	// way for a polymorphic function to describe its type requirements. It
	// would be expected for this function to return at least one
	// ExclusiveInvariant or GeneratorInvariant, since these are two common
	// mechanisms for polymorphic functions to describe their constraints.
	// The important realization behind this method is that the collecting
	// of possible invariants, must happen *before* the solver runs so that
	// the solver can look at all the available logic *simultaneously* to
	// find a solution if we want to be able to reliably solve for things.
	// The input argument that it receives is the expression pointer that it
	// is unifying against-- in other words, the pointer is its own handle.
	// This is different than the `obj` reference of this function
	// implementation because _that_ handle is not the object/pointer in the
	// AST that we're discussing when performing type unification. Put
	// another way: the Expr input is the ExprFunc, not the ExprCall.
	Unify(Expr) ([]Invariant, error)

	// Build takes the known or unified type signature for this function and
	// finalizes this structure so that it is now determined, and ready to
	// function as a normal function would. (The normal methods in the Func
	// interface are all that should be needed or used after this point.)
	// Of note, the names of the specific input args shouldn't matter as
	// long as they are unique. Their position doesn't matter. This is so
	// that unification can use "arg0", "arg1", "argN"... if they can't be
	// determined statically. Build can transform them into it's desired
	// form, and must return the type (with the correct arg names) that it
	// will use. These are used when constructing the function graphs. This
	// means that when this is called from SetType, it can set the correct
	// type arg names, and this will also match what's in function Info().
	Build(*types.Type) (*types.Type, error)
}

type Pos struct {
	Line     int    // line number starting at 1
	Column   int    // column number starting at 1
	Filename string // optional source filename, if known
}

type Scope struct {
	Variables map[string]Expr
	Functions map[string]Expr // the Expr will usually be an *ExprFunc (actually it's usually (or always) an *ExprSingleton, which wraps an *ExprFunc now)
	Classes   map[string]Stmt

	Chain []Node // chain of previously seen node's
}

type ScopeGrapher interface {
	Node

	// ScopeGraph adds nodes and vertices to the supplied graph.
	ScopeGraph(g *pgraph.Graph)
}

type SkipInvariant struct {
	Expr Expr
}

type Stmt interface {
	Node

	// Init initializes the populated node and does some basic validation.
	Init(*Data) error

	// Interpolate returns an expanded form of the AST as a new AST. It does
	// a recursive interpolate (copy) of all members in the AST.
	Interpolate() (Stmt, error) // return expanded form of AST as a new AST

	// Copy returns a light copy of the struct. Anything static will not be
	// copied. For a full recursive copy consider using Interpolate instead.
	// TODO: do we need an error in the signature?
	Copy() (Stmt, error)

	// Ordering returns a graph of the scope ordering that represents the
	// data flow. This can be used in SetScope so that it knows the correct
	// order to run it in.
	Ordering(map[string]Node) (*pgraph.Graph, map[Node]string, error)

	// SetScope sets the scope here and propagates it downwards.
	SetScope(*Scope) error

	// Unify returns the list of invariants that this node produces. It does
	// so recursively on any children elements that exist in the AST, and
	// returns the collection to the caller.
	Unify() ([]Invariant, error)

	// Graph returns the reactive function graph expressed by this node.
	Graph() (*pgraph.Graph, error)

	// Output returns the output that this "program" produces. This output
	// is what is used to build the output graph. It requires the input
	// table of values that are used to populate each function.
	Output(map[Func]types.Value) (*Output, error)
}

type Txn interface {
	// AddVertex adds a vertex to the running graph. The operation will get
	// completed when Commit is run.
	AddVertex(Func) Txn

	// AddEdge adds an edge to the running graph. The operation will get
	// completed when Commit is run.
	AddEdge(Func, Func, *FuncEdge) Txn

	// DeleteVertex removes a vertex from the running graph. The operation
	// will get completed when Commit is run.
	DeleteVertex(Func) Txn

	// AddGraph adds a graph to the running graph. The operation will get
	// completed when Commit is run. This function panics if your graph
	// contains vertices that are not of type interfaces.Func or if your
	// edges are not of type *interfaces.FuncEdge.
	AddGraph(*pgraph.Graph) Txn

	// Commit runs the pending transaction.
	Commit() error

	// Clear erases any pending transactions that weren't committed yet.
	Clear()

	// Reverse runs the reverse commit of the last successful operation to
	// Commit. AddVertex is reversed by DeleteVertex, and vice-versa, and
	// the same for AddEdge and DeleteEdge. Keep in mind that if AddEdge is
	// called with either vertex not already part of the graph, it will
	// implicitly add them, but the Reverse operation will not necessarily
	// know that. As a result, it's recommended to not perform operations
	// that have implicit Adds or Deletes. Notwithstanding the above, the
	// initial Txn implementation can and does try to track these changes
	// so that it can correctly reverse them, but this is not guaranteed by
	// API, and it could contain bugs.
	Reverse() error

	// Erase removes the historical information that Reverse would run after
	// Commit.
	Erase()

	// Free releases the wait group that was used to lock around this Txn if
	// needed. It should get called when we're done with any Txn.
	Free()

	// Copy returns a new child Txn that has the same handles, but a
	// separate state. This allows you to do an Add*/Commit/Reverse that
	// isn't affected by a different user of this transaction.
	Copy() Txn

	// Graph returns a copy of the graph. It returns what has been already
	// committed.
	Graph() *pgraph.Graph
}

type ValueInvariant struct {
	Expr  Expr
	Value types.Value // pointer
}

type Var interface {
	types.Value
}