From d995ba22ec92312acc32aeac7a043dc37e6ebfd7 Mon Sep 17 00:00:00 2001 From: Jonathan Mace Date: Wed, 8 Nov 2023 15:18:44 -0800 Subject: [PATCH] Remove README --- blueprint/pkg/blueprint/README.md | 870 ------------------------------ 1 file changed, 870 deletions(-) delete mode 100644 blueprint/pkg/blueprint/README.md diff --git a/blueprint/pkg/blueprint/README.md b/blueprint/pkg/blueprint/README.md deleted file mode 100644 index 6482180f..00000000 --- a/blueprint/pkg/blueprint/README.md +++ /dev/null @@ -1,870 +0,0 @@ - - -# blueprint - -```go -import "gitlab.mpi-sws.org/cld/blueprint/blueprint/pkg/blueprint" -``` - -## Index - -- [Constants](<#constants>) -- [func Capitalize\(s string\) string](<#Capitalize>) -- [func CleanName\(name string\) string](<#CleanName>) -- [func DisableCompilerLogging\(\)](<#DisableCompilerLogging>) -- [func EnableCompilerLogging\(\)](<#EnableCompilerLogging>) -- [func Errorf\(format string, a ...any\) error](<#Errorf>) -- [func Filter\[T any\]\(nodes \[\]IRNode\) \[\]T](<#Filter>) -- [func Indent\(str string, amount int\) string](<#Indent>) -- [func NewBlueprintError\(msg string\) error](<#NewBlueprintError>) -- [func RegisterDefaultBuilder\[T IRNode\]\(name string, buildFunc func\(outputDir string, node IRNode\) error\)](<#RegisterDefaultBuilder>) -- [func RegisterDefaultNamespace\[T IRNode\]\(name string, buildFunc func\(outputDir string, nodes \[\]IRNode\) error\)](<#RegisterDefaultNamespace>) -- [func Reindent\(str string, amount int\) string](<#Reindent>) -- [func ReplaceSuffix\(s string, suffix string, replacement string\) string](<#ReplaceSuffix>) -- [type ApplicationNode](<#ApplicationNode>) - - [func \(app \*ApplicationNode\) Compile\(outputDir string\) error](<#ApplicationNode.Compile>) - - [func \(node \*ApplicationNode\) Name\(\) string](<#ApplicationNode.Name>) - - [func \(node \*ApplicationNode\) String\(\) string](<#ApplicationNode.String>) -- [type Blueprint](<#Blueprint>) - - [func \(blueprint \*Blueprint\) BuildIR\(\) \(\*ApplicationNode, error\)](<#Blueprint.BuildIR>) - - [func \(blueprint \*Blueprint\) Instantiate\(names ...string\)](<#Blueprint.Instantiate>) - - [func \(blueprint \*Blueprint\) InstantiateAll\(\)](<#Blueprint.InstantiateAll>) -- [type BlueprintError](<#BlueprintError>) - - [func \(e \*BlueprintError\) Error\(\) string](<#BlueprintError.Error>) -- [type BlueprintLoggerHandler](<#BlueprintLoggerHandler>) - - [func \(h \*BlueprintLoggerHandler\) Handle\(ctx context.Context, r slog.Record\) error](<#BlueprintLoggerHandler.Handle>) -- [type BlueprintLoggerHandlerOptions](<#BlueprintLoggerHandlerOptions>) -- [type BuildContext](<#BuildContext>) -- [type BuildFunc](<#BuildFunc>) -- [type DefaultNamespaceHandler](<#DefaultNamespaceHandler>) - - [func \(handler \*DefaultNamespaceHandler\) Accepts\(nodeType any\) bool](<#DefaultNamespaceHandler.Accepts>) - - [func \(handler \*DefaultNamespaceHandler\) AddEdge\(name string, node IRNode\) error](<#DefaultNamespaceHandler.AddEdge>) - - [func \(handler \*DefaultNamespaceHandler\) AddNode\(name string, node IRNode\) error](<#DefaultNamespaceHandler.AddNode>) - - [func \(handler \*DefaultNamespaceHandler\) Init\(namespace \*SimpleNamespace\)](<#DefaultNamespaceHandler.Init>) - - [func \(handler \*DefaultNamespaceHandler\) LookupDef\(name string\) \(\*WiringDef, error\)](<#DefaultNamespaceHandler.LookupDef>) -- [type IRConfig](<#IRConfig>) -- [type IRMetadata](<#IRMetadata>) -- [type IRNode](<#IRNode>) - - [func FilterNodes\[T any\]\(nodes \[\]IRNode\) \[\]IRNode](<#FilterNodes>) - - [func Remove\[T any\]\(nodes \[\]IRNode\) \[\]IRNode](<#Remove>) -- [type Namespace](<#Namespace>) -- [type SimpleNamespace](<#SimpleNamespace>) - - [func \(namespace \*SimpleNamespace\) Debug\(message string, args ...any\)](<#SimpleNamespace.Debug>) - - [func \(namespace \*SimpleNamespace\) Defer\(f func\(\) error\)](<#SimpleNamespace.Defer>) - - [func \(namespace \*SimpleNamespace\) Error\(message string, args ...any\) error](<#SimpleNamespace.Error>) - - [func \(namespace \*SimpleNamespace\) Get\(name string, dst any\) error](<#SimpleNamespace.Get>) - - [func \(namespace \*SimpleNamespace\) GetProperties\(name string, key string, dst any\) error](<#SimpleNamespace.GetProperties>) - - [func \(namespace \*SimpleNamespace\) GetProperty\(name string, key string, dst any\) error](<#SimpleNamespace.GetProperty>) - - [func \(namespace \*SimpleNamespace\) Info\(message string, args ...any\)](<#SimpleNamespace.Info>) - - [func \(namespace \*SimpleNamespace\) Init\(name, namespacetype string, parent Namespace, wiring WiringSpec, handler SimpleNamespaceHandler\)](<#SimpleNamespace.Init>) - - [func \(namespace \*SimpleNamespace\) Instantiate\(name string, dst any\) error](<#SimpleNamespace.Instantiate>) - - [func \(namespace \*SimpleNamespace\) Name\(\) string](<#SimpleNamespace.Name>) - - [func \(namespace \*SimpleNamespace\) Put\(name string, node IRNode\) error](<#SimpleNamespace.Put>) -- [type SimpleNamespaceHandler](<#SimpleNamespaceHandler>) -- [type SourceFileInfo](<#SourceFileInfo>) - - [func GetSourceFileInfo\(fileName string\) \*SourceFileInfo](<#GetSourceFileInfo>) - - [func \(info \*SourceFileInfo\) String\(\) string](<#SourceFileInfo.String>) -- [type VisitTracker](<#VisitTracker>) -- [type VisitTrackerImpl](<#VisitTrackerImpl>) - - [func \(tracker \*VisitTrackerImpl\) Visited\(name string\) bool](<#VisitTrackerImpl.Visited>) -- [type WiringCallsite](<#WiringCallsite>) - - [func \(cs WiringCallsite\) String\(\) string](<#WiringCallsite.String>) -- [type WiringCallstack](<#WiringCallstack>) - - [func \(stack \*WiringCallstack\) String\(\) string](<#WiringCallstack.String>) -- [type WiringDef](<#WiringDef>) - - [func \(def \*WiringDef\) AddProperty\(key string, value any\)](<#WiringDef.AddProperty>) - - [func \(def \*WiringDef\) GetProperties\(key string, dst any\) error](<#WiringDef.GetProperties>) - - [func \(def \*WiringDef\) GetProperty\(key string, dst any\) error](<#WiringDef.GetProperty>) - - [func \(def \*WiringDef\) String\(\) string](<#WiringDef.String>) -- [type WiringError](<#WiringError>) - - [func \(e WiringError\) Error\(\) string](<#WiringError.Error>) -- [type WiringSpec](<#WiringSpec>) - - [func NewWiringSpec\(name string\) WiringSpec](<#NewWiringSpec>) - - -## Constants - - - -```go -const ( - MAX_ERR_SIZE = 2048 -) -``` - - -## func Capitalize - -```go -func Capitalize(s string) string -``` - - - - -## func CleanName - -```go -func CleanName(name string) string -``` - - - - -## func DisableCompilerLogging - -```go -func DisableCompilerLogging() -``` - - - - -## func EnableCompilerLogging - -```go -func EnableCompilerLogging() -``` - - - - -## func Errorf - -```go -func Errorf(format string, a ...any) error -``` - - - - -## func Filter - -```go -func Filter[T any](nodes []IRNode) []T -``` - -A helper method to filter out nodes of a specific type from a slice of IRnodes - - -## func Indent - -```go -func Indent(str string, amount int) string -``` - - - - -## func NewBlueprintError - -```go -func NewBlueprintError(msg string) error -``` - - - - -## func RegisterDefaultBuilder - -```go -func RegisterDefaultBuilder[T IRNode](name string, buildFunc func(outputDir string, node IRNode) error) -``` - -If the root Blueprint application contains nodes of type T, this function enables plugins to register a default builder to individually build those nodes - - -## func RegisterDefaultNamespace - -```go -func RegisterDefaultNamespace[T IRNode](name string, buildFunc func(outputDir string, nodes []IRNode) error) -``` - -If the root Blueprint application contains nodes of type T, this function enables plugins to register a default namespace to combine and build those nodes. - - -## func Reindent - -```go -func Reindent(str string, amount int) string -``` - - - - -## func ReplaceSuffix - -```go -func ReplaceSuffix(s string, suffix string, replacement string) string -``` - - - - -## type ApplicationNode - -The IR Node that represents the whole application - -```go -type ApplicationNode struct { - IRNode - - Children []IRNode - // contains filtered or unexported fields -} -``` - - -### func \(\*ApplicationNode\) Compile - -```go -func (app *ApplicationNode) Compile(outputDir string) error -``` - - - - -### func \(\*ApplicationNode\) Name - -```go -func (node *ApplicationNode) Name() string -``` - - - - -### func \(\*ApplicationNode\) String - -```go -func (node *ApplicationNode) String() string -``` - -Print the IR graph - - -## type Blueprint - - - -```go -type Blueprint struct { - // contains filtered or unexported fields -} -``` - - -### func \(\*Blueprint\) BuildIR - -```go -func (blueprint *Blueprint) BuildIR() (*ApplicationNode, error) -``` - - - - -### func \(\*Blueprint\) Instantiate - -```go -func (blueprint *Blueprint) Instantiate(names ...string) -``` - -Instantiates one or more specific named nodes - - -### func \(\*Blueprint\) InstantiateAll - -```go -func (blueprint *Blueprint) InstantiateAll() -``` - -Instantiates any nodes that haven't yet been instantiated. Although this is commonly used, it is preferred to explicitly instantiate nodes by name. - - -## type BlueprintError - - - -```go -type BlueprintError struct { - Stack []byte - Err error -} -``` - - -### func \(\*BlueprintError\) Error - -```go -func (e *BlueprintError) Error() string -``` - - - - -## type BlueprintLoggerHandler - -Implementation of Blueprint's custom Handler of slog.Logger - -```go -type BlueprintLoggerHandler struct { - slog.Handler - // contains filtered or unexported fields -} -``` - - -### func \(\*BlueprintLoggerHandler\) Handle - -```go -func (h *BlueprintLoggerHandler) Handle(ctx context.Context, r slog.Record) error -``` - - - - -## type BlueprintLoggerHandlerOptions - - - -```go -type BlueprintLoggerHandlerOptions struct { - SlogOpts slog.HandlerOptions -} -``` - - -## type BuildContext - -Base interface used during build time; plugins that generate artifacts use this - -```go -type BuildContext interface { - VisitTracker - ImplementsBuildContext() -} -``` - - -## type BuildFunc - - - -```go -type BuildFunc func(Namespace) (IRNode, error) -``` - - -## type DefaultNamespaceHandler - - - -```go -type DefaultNamespaceHandler struct { - SimpleNamespaceHandler - Namespace *SimpleNamespace - - Nodes []IRNode - Edges []IRNode -} -``` - - -### func \(\*DefaultNamespaceHandler\) Accepts - -```go -func (handler *DefaultNamespaceHandler) Accepts(nodeType any) bool -``` - -should return true if the specified node type should be built within this namespace, or false if we should ask the parent to build it instead. Most namespace implementations will only - -``` -accept certain node types, and will thus want to override this method. For example, a golang process -will only accept golang nodes -``` - - -### func \(\*DefaultNamespaceHandler\) AddEdge - -```go -func (handler *DefaultNamespaceHandler) AddEdge(name string, node IRNode) error -``` - -This is called after getting a node from the parent namespace. By default it just saves the node as an edge. Namespace implementations can override this method to do other things. - - -### func \(\*DefaultNamespaceHandler\) AddNode - -```go -func (handler *DefaultNamespaceHandler) AddNode(name string, node IRNode) error -``` - -This is called after building a node in the current namespace. By default it just saves the node on the namespace. Namespace implementations can override this method to do other things. - - -### func \(\*DefaultNamespaceHandler\) Init - -```go -func (handler *DefaultNamespaceHandler) Init(namespace *SimpleNamespace) -``` - - - - -### func \(\*DefaultNamespaceHandler\) LookupDef - -```go -func (handler *DefaultNamespaceHandler) LookupDef(name string) (*WiringDef, error) -``` - -Look up a WiringDef; default implementation directly consults the WiringSpec. - -``` -callers can override this if they want to restrict, modify, or wrap definitions -that get instantiated within this namespace. -``` - - -## type IRConfig - - - -```go -type IRConfig interface { - IRNode - Optional() bool - HasValue() bool - Value() string - ImplementsIRConfig() -} -``` - - -## type IRMetadata - - - -```go -type IRMetadata interface { - ImplementsIRMetadata() -} -``` - - -## type IRNode - -The base IRNode type - -```go -type IRNode interface { - Name() string - String() string -} -``` - - -### func FilterNodes - -```go -func FilterNodes[T any](nodes []IRNode) []IRNode -``` - - - - -### func Remove - -```go -func Remove[T any](nodes []IRNode) []IRNode -``` - -Remove nodes of the given type - - -## type Namespace - -A Namespace is used during the IR\-building process to accumulate built nodes. - -Blueprint has several basic out\-of\-the\-box namespaces that are used when building applications. A plugin can implement its own custom namespace. Implementing a custom Namespace is useful to achieve any of the following: - -- Namespaces are the mechanism for limiting the visibility and addressibility of nodes -- Namespaces are the mechanism for templating nodes \(e.g. to implement replication of nodes\) - -For example, to build a GoProcess that contains Golang object instances, there will be a Namespace that accumulates Golang object instance nodes during the building process, and then creates a GoProcess namespace node. - -Most namespace implementations should extend the BasicNamespace struct - -```go -type Namespace interface { - Name() string // The name of this namespace - Get(name string, dst any) error // Get an IRNode from this namespace or a parent namespace, possibly building it. Places the IRNode in the pointer dst. dst can be an IRNode or any implementation of an IRNode - Instantiate(name string, dst any) error // The same as Get, but without creating a dependency (an edge) into the current namespace. Places the IRNode in the pointer dst. dst can be an IRNode or any implementation of an IRNode - GetProperty(name string, key string, dst any) error // Get a property from this namespace; dst should be a pointer to value - GetProperties(name string, key string, dst any) error // Get a slice property from this namespace; dst should be a pointer to a slice - Put(name string, node IRNode) error // Put a node into this namespace - Defer(f func() error) // Enqueue a function to be executed once finished building the current nodes - - Info(message string, args ...any) // Logging - Warn(message string, args ...any) // Logging - Error(message string, args ...any) error // Logging -} -``` - - -## type SimpleNamespace - -A SimpleNamespace implements all of the Namespace methods and only requires users to implement a SimpleNamespaceHandler interface. Most plugins will want to use SimpleNamespace rather than directly implementing Namespace. - -See the documentation of SimpleNamespaceHandler for methods to override. - -```go -type SimpleNamespace struct { - Namespace - - NamespaceName string // A name for this namespace - NamespaceType string // The type of this namespace - ParentNamespace Namespace // The parent namespace that created this namespace; can be nil - Wiring WiringSpec // The wiring spec - Handler SimpleNamespaceHandler // User-provided handler - Seen map[string]IRNode // Cache of built nodes - Added map[string]any // Nodes that have been passed to the handler - Deferred []func() error // Deferred functions to execute - // contains filtered or unexported fields -} -``` - - -### func \(\*SimpleNamespace\) Debug - -```go -func (namespace *SimpleNamespace) Debug(message string, args ...any) -``` - -Augments debug messages with information about the namespace - - -### func \(\*SimpleNamespace\) Defer - -```go -func (namespace *SimpleNamespace) Defer(f func() error) -``` - - - - -### func \(\*SimpleNamespace\) Error - -```go -func (namespace *SimpleNamespace) Error(message string, args ...any) error -``` - -Augments debug messages with information about the namespace - - -### func \(\*SimpleNamespace\) Get - -```go -func (namespace *SimpleNamespace) Get(name string, dst any) error -``` - - - - -### func \(\*SimpleNamespace\) GetProperties - -```go -func (namespace *SimpleNamespace) GetProperties(name string, key string, dst any) error -``` - - - - -### func \(\*SimpleNamespace\) GetProperty - -```go -func (namespace *SimpleNamespace) GetProperty(name string, key string, dst any) error -``` - - - - -### func \(\*SimpleNamespace\) Info - -```go -func (namespace *SimpleNamespace) Info(message string, args ...any) -``` - -Augments debug messages with information about the namespace - - -### func \(\*SimpleNamespace\) Init - -```go -func (namespace *SimpleNamespace) Init(name, namespacetype string, parent Namespace, wiring WiringSpec, handler SimpleNamespaceHandler) -``` - - - - -### func \(\*SimpleNamespace\) Instantiate - -```go -func (namespace *SimpleNamespace) Instantiate(name string, dst any) error -``` - - - - -### func \(\*SimpleNamespace\) Name - -```go -func (namespace *SimpleNamespace) Name() string -``` - - - - -### func \(\*SimpleNamespace\) Put - -```go -func (namespace *SimpleNamespace) Put(name string, node IRNode) error -``` - - - - -## type SimpleNamespaceHandler - -Has four methods with default implementations that callers can override with custom logic: - -- LookupDef\(name\) \- look up a WiringDef; default implementation directly consults the WiringSpec. callers can override this if they want to restrict, modify, or wrap definitions that get instantiated within this namespace. -- Accepts\(nodeType\) \- should return true if the specified node type should be built within this namespace, or false if we should ask the parent to build it instead. Most namespace implementations will only accept certain node types, and will thus want to override this method. For example, a golang process will only accept golang nodes -- AddNode\(name, IRNode\) \- this is called when a node is created within this namespace. The SimpleNamespace internally saves the node for future lookups; callers might want to save the node e.g. as a child within a node that is being created. -- AddEdge\(name, IRNode\) \- this is called when a node was created by a parent namespace but referenced within this namespace. The SimpleNamespace internally saves the node for future lookups; callers might want to save the node e.g. as an argument to the node that is being created - -```go -type SimpleNamespaceHandler interface { - Init(*SimpleNamespace) - LookupDef(string) (*WiringDef, error) - Accepts(any) bool - AddEdge(string, IRNode) error - AddNode(string, IRNode) error -} -``` - - -## type SourceFileInfo - - - -```go -type SourceFileInfo struct { - Filename string // Local filename - Module string // Fully qualified module name - ModulePath string // path to module on disk - ModuleFilename string // Filename within module - WorkspaceFilename string // Filename within workspace, if the module is in a workspace; otherwise ModuleFilename -} -``` - - -### func GetSourceFileInfo - -```go -func GetSourceFileInfo(fileName string) *SourceFileInfo -``` - - - - -### func \(\*SourceFileInfo\) String - -```go -func (info *SourceFileInfo) String() string -``` - - - - -## type VisitTracker - -Base interface used during build time; plugins that generate artifacts use this - -```go -type VisitTracker interface { - Visited(name string) bool -} -``` - - -## type VisitTrackerImpl - -In Blueprint, it is possible for there to be multiple different IRNode instances, across that application, that generate and use the same code. It is possible that the corresponding plugin does not want to generate that code multiple times. The VisitTracker provides a simple way for plugins to prevent generating output code multiple times. - -In methods where code gets generated \(e.g. in golang Instantiable\), before generating any code, plugins invoke \`VisitTracker.Visited\` with a unique identifier \(e.g. representing the node, instance, or plugin\). The first invocation for the identifier returns true; subsequent invocations return false. - -```go -type VisitTrackerImpl struct { - // contains filtered or unexported fields -} -``` - - -### func \(\*VisitTrackerImpl\) Visited - -```go -func (tracker *VisitTrackerImpl) Visited(name string) bool -``` - -Multiple instances of a node can exist across a Blueprint application that generates and uses the same code. This method is used by nodes to determine whether code has already been generated in this workspace by a different instance of the same node type. The first call to this method for a given name will return false; subsequent calls will return true - - -## type WiringCallsite - - - -```go -type WiringCallsite struct { - Source *SourceFileInfo - LineNumber int - Func string - FuncName string -} -``` - - -### func \(WiringCallsite\) String - -```go -func (cs WiringCallsite) String() string -``` - - - - -## type WiringCallstack - - - -```go -type WiringCallstack struct { - Stack []WiringCallsite -} -``` - - -### func \(\*WiringCallstack\) String - -```go -func (stack *WiringCallstack) String() string -``` - - - - -## type WiringDef - - - -```go -type WiringDef struct { - Name string - NodeType any - Build BuildFunc - Properties map[string][]any -} -``` - - -### func \(\*WiringDef\) AddProperty - -```go -func (def *WiringDef) AddProperty(key string, value any) -``` - - - - -### func \(\*WiringDef\) GetProperties - -```go -func (def *WiringDef) GetProperties(key string, dst any) error -``` - - - - -### func \(\*WiringDef\) GetProperty - -```go -func (def *WiringDef) GetProperty(key string, dst any) error -``` - - - - -### func \(\*WiringDef\) String - -```go -func (def *WiringDef) String() string -``` - - - - -## type WiringError - - - -```go -type WiringError struct { - Errors []error -} -``` - - -### func \(WiringError\) Error - -```go -func (e WiringError) Error() string -``` - - - - -## type WiringSpec - - - -```go -type WiringSpec interface { - Define(name string, nodeType any, build BuildFunc) // Adds a named node definition to the spec that can be built with the provided build function - GetDef(name string) *WiringDef // For use by plugins to access the defined build functions and metadata - - Alias(name string, pointsto string) // Defines an alias to another defined node; these can be recursive - GetAlias(alias string) (string, bool) // Gets the value of the specified alias, if it exists - - SetProperty(name string, key string, value any) // Sets a static property value in the wiring spec, replacing any existing value specified - AddProperty(name string, key string, value any) // Adds a static property value in the wiring spec - GetProperty(name string, key string, dst any) error // Gets a static property value from the wiring spec - GetProperties(name string, key string, dst any) error // Gets all static property values from the wiring spec - - String() string // Returns a string representation of everything that has been defined - - // Errors while building a wiring spec are accumulated within the wiring spec, rather than as return values to calls - AddError(err error) // Used by plugins to signify an error; the error will be returned by a call to Err or GetBlueprint - Err() error // Gets an error if there is currently one - - GetBlueprint() (*Blueprint, error) // After defining everything, this method provides the means to then build everything. -} -``` - - -### func NewWiringSpec - -```go -func NewWiringSpec(name string) WiringSpec -``` - - - -Generated by [gomarkdoc]()