gogen

gogen

import "github.com/blueprint-uservices/blueprint/plugins/golang/gogen"

Package gogen provides implementations of the builder interfaces defined by the golang plugin

The builders are intended for use by plugins that define golang namespace nodes. For example, the goproc plugin defines a process node that collects together golang instance nodes. The goproc plugin then uses the builders defined here to accumulate the code declarations of those golang instances, and to generate the main file for the process.

Index

• func ExecuteTemplate(name string, body string, args any) (string, error)
• func ExecuteTemplateToFile(name string, body string, args any, filename string) error
• type Imports
  • func NewImports(packageName string) *Imports
  • func (imports *Imports) AddPackage(pkg string) string
  • func (imports *Imports) AddPackages(pkgs ...string)
  • func (imports *Imports) AddType(typeName gocode.TypeName)
  • func (imports *Imports) NameOf(typeName gocode.TypeName) string
  • func (imports *Imports) Qualify(pkg string, name string) string
  • func (imports *Imports) String() string
• type ModuleBuilderImpl
  • func NewModuleBuilder(workspace *WorkspaceBuilderImpl, moduleName string) (*ModuleBuilderImpl, error)
  • func (module *ModuleBuilderImpl) CreatePackage(packageName string) (golang.PackageInfo, error)
  • func (module *ModuleBuilderImpl) ImplementsBuildContext()
  • func (module *ModuleBuilderImpl) Info() golang.ModuleInfo
  • func (module *ModuleBuilderImpl) Require(moduleName string, version string) error
  • func (module *ModuleBuilderImpl) Workspace() golang.WorkspaceBuilder
• type NamespaceBuilderImpl
  • func NewNamespaceBuilder(module golang.ModuleBuilder, name, fileName, packagePath, funcName string) (*NamespaceBuilderImpl, error)
  • func (code *NamespaceBuilderImpl) Build() error
  • func (n *NamespaceBuilderImpl) Declare(name, buildFuncSrc string) error
  • func (namespace *NamespaceBuilderImpl) DeclareConstructor(name string, constructor *gocode.Constructor, args []ir.IRNode) error
  • func (code *NamespaceBuilderImpl) ImplementsBuildContext()
  • func (n *NamespaceBuilderImpl) Import(packageName string) string
  • func (n *NamespaceBuilderImpl) ImportType(typeName gocode.TypeName) string
  • func (n *NamespaceBuilderImpl) Info() golang.NamespaceInfo
  • func (n *NamespaceBuilderImpl) Instantiate(name string)
  • func (n *NamespaceBuilderImpl) Module() golang.ModuleBuilder
  • func (n *NamespaceBuilderImpl) OptionalArg(name, description string)
  • func (n *NamespaceBuilderImpl) RequiredArg(name, description string)
• type WorkspaceBuilderImpl
  • func NewWorkspaceBuilder(workspaceDir string) (*WorkspaceBuilderImpl, error)
  • func (workspace *WorkspaceBuilderImpl) AddLocalModule(shortName string, moduleSrcPath string) (string, error)
  • func (workspace *WorkspaceBuilderImpl) CreateModule(moduleName string, moduleVersion string) (string, error)
  • func (workspace *WorkspaceBuilderImpl) Finish() error
  • func (workspace *WorkspaceBuilderImpl) GetLocalModule(modulePath string) (string, bool)
  • func (workspace *WorkspaceBuilderImpl) ImplementsBuildContext()
  • func (workspace *WorkspaceBuilderImpl) Info() golang.WorkspaceInfo

func ExecuteTemplate

func ExecuteTemplate(name string, body string, args any) (string, error)

A helper function for executing text/template templates to string.

When executing the provided template body, the body can make use of a number of convenience functions. See gogen/template.go for details.

func ExecuteTemplateToFile

func ExecuteTemplateToFile(name string, body string, args any, filename string) error

A helper function for executing text/template templates to file

When executing the provided template body, the body can make use of a number of convenience functions. See gogen/template.go for details.

type Imports

A helper struct for managing imports in generated golang files.

Used by plugins like the GRPC plugin.

The string representation of the Imports struct is the import declaration.

The NameOf method provides the correctly qualified name for the specified userType

type Imports struct {
    // contains filtered or unexported fields
}

func NewImports

func NewImports(packageName string) *Imports

Creates a new ImportedPackages struct, treating the provided fully-qualified packageName as the "current" package

func (*Imports) AddPackage

func (imports *Imports) AddPackage(pkg string) string

Imports the fully-qualified package pkg. Returns the shortname of the package, to use when referring to names exported by pkg.

func (*Imports) AddPackages

func (imports *Imports) AddPackages(pkgs ...string)

func (*Imports) AddType

func (imports *Imports) AddType(typeName gocode.TypeName)

Adds all necessary import statements to be able to use typeName

func (*Imports) NameOf

func (imports *Imports) NameOf(typeName gocode.TypeName) string

Returns the qualified import name to use for typeName

func (*Imports) Qualify

func (imports *Imports) Qualify(pkg string, name string) string

Given fully-qualified package name pkg and exported member name, returns the short name used to reference that member.

e.g. Qualify("github.com/blueprint-uservices/plugins/golang/gogen", "Imports") returns "gogen.Imports"

func (*Imports) String

func (imports *Imports) String() string

Returns the import statement needed to import all added packages and types

type ModuleBuilderImpl

Implements [golang.ModuleBuilder].

Creates a module on the local filesystem with a user-provided module name.

type ModuleBuilderImpl struct {
    ir.VisitTrackerImpl
    Name string // The FQ name of this module

    ModuleDir string // The directory containing this module
    // contains filtered or unexported fields
}

func NewModuleBuilder

func NewModuleBuilder(workspace *WorkspaceBuilderImpl, moduleName string) (*ModuleBuilderImpl, error)

Creates a module within the provided workspace, and returns a ModuleBuilderImpl that can be used to accumulate code in the created module.

The typical usage of this is by plugins such as the goproc plugin that accumulate golang nodes and generate code to run those nodes.

After calling this method, the returned ModuleBuilder can be passed to golang nodes, to accumulate the interfaces and funcs of those nodes.

func (*ModuleBuilderImpl) CreatePackage

func (module *ModuleBuilderImpl) CreatePackage(packageName string) (golang.PackageInfo, error)

Implements [golang.ModuleBuilder]

func (*ModuleBuilderImpl) ImplementsBuildContext

func (module *ModuleBuilderImpl) ImplementsBuildContext()

func (*ModuleBuilderImpl) Info

func (module *ModuleBuilderImpl) Info() golang.ModuleInfo

Implements [golang.ModuleBuilder]

func (*ModuleBuilderImpl) Require

func (module *ModuleBuilderImpl) Require(moduleName string, version string) error

Implements [golang.ModuleBuilder]

func (*ModuleBuilderImpl) Workspace

func (module *ModuleBuilderImpl) Workspace() golang.WorkspaceBuilder

Implements [golang.ModuleBuilder]

type NamespaceBuilderImpl

Implements [golang.NamespaceBuilder].

Creates a source file, {{FileName}}.go, containing a function, {{FuncName}}. The body of {{FuncName}} instantiates all nodes of this namespace.

type NamespaceBuilderImpl struct {
    ir.VisitTrackerImpl

    Package        golang.PackageInfo
    Name           string            // IR node name
    FileName       string            // The short name of the file
    FilePath       string            // The fully qualified path to the file
    FuncName       string            // The name of the function to generate
    Imports        *Imports          // Import declarations in the file; map of shortname to full package import name
    Declarations   map[string]string // The DI declarations
    Required       map[string]string
    Optional       map[string]string
    Instantiations []string
    // contains filtered or unexported fields
}

func NewNamespaceBuilder

func NewNamespaceBuilder(module golang.ModuleBuilder, name, fileName, packagePath, funcName string) (*NamespaceBuilderImpl, error)

Creates a function called funcName within a file called fileName, within the provided module. Returns a NamespaceBuilderImpl that can be used to accumulate instantiation code.

The typical usage of this is by plugins such as the [goproc] plugin that accumulate golang nodes and generate code to run those nodes.

After calling this method, the returned NamespaceBuilderImpl can be passed to golang nodes, to accumulate the instantiation code for those nodes.

After all instantiations have been accumulated, the caller should invoke [Build], which will actually generate the file fileName, combining all provided node instantiation code snippets.

func (*NamespaceBuilderImpl) Build

func (code *NamespaceBuilderImpl) Build() error

Build should be the last invocation, used to generate the namespace file.

func (*NamespaceBuilderImpl) Declare

func (n *NamespaceBuilderImpl) Declare(name, buildFuncSrc string) error

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) DeclareConstructor

func (namespace *NamespaceBuilderImpl) DeclareConstructor(name string, constructor *gocode.Constructor, args []ir.IRNode) error

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) ImplementsBuildContext

func (code *NamespaceBuilderImpl) ImplementsBuildContext()

func (*NamespaceBuilderImpl) Import

func (n *NamespaceBuilderImpl) Import(packageName string) string

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) ImportType

func (n *NamespaceBuilderImpl) ImportType(typeName gocode.TypeName) string

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) Info

func (n *NamespaceBuilderImpl) Info() golang.NamespaceInfo

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) Instantiate

func (n *NamespaceBuilderImpl) Instantiate(name string)

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) Module

func (n *NamespaceBuilderImpl) Module() golang.ModuleBuilder

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) OptionalArg

func (n *NamespaceBuilderImpl) OptionalArg(name, description string)

Implements [golang.NamespaceBuilder]

func (*NamespaceBuilderImpl) RequiredArg

func (n *NamespaceBuilderImpl) RequiredArg(name, description string)

Implements [golang.NamespaceBuilder]

type WorkspaceBuilderImpl

Implements [golang.WorkspaceBuilder].

Creates a golang workspace on the local filesystem

type WorkspaceBuilderImpl struct {
    ir.VisitTrackerImpl
    WorkspaceDir     string            // The directory containing this workspace
    ModuleDirs       map[string]string // map from FQ module name to directory name within WorkspaceDir
    Modules          map[string]string // map from directory name to FQ module name within WorkspaceDir
    GeneratedModules map[string]string // map from directory name to FQ module name within WorkspaceDir
}

func NewWorkspaceBuilder

func NewWorkspaceBuilder(workspaceDir string) (*WorkspaceBuilderImpl, error)

Creates a golang workspace in the specified directory on the local filesystem.

Calls to [CreateModule] will create golang modules in subdirectories of the workspace. The builder will automatically create the necessary go.mod files of modules, and go.work file of the workspace.

The typical usage of this is by plugins such as the [goproc] plugin that accumulate golang nodes and generate code to run those nodes.

After calling this method, the returned WorkspaceBuilder can be passed to golang nodes, to accumulate modules.

After all modules have been accumulated, the caller should invoke [Finish], which will write the go.work file, insert replace directives in go.mod files for sibling modules, and invoke go mod tidy to resolve external package dependencies.

Returns an error if the directory already exists.

func (*WorkspaceBuilderImpl) AddLocalModule

func (workspace *WorkspaceBuilderImpl) AddLocalModule(shortName string, moduleSrcPath string) (string, error)

Implements [golang.WorkspaceBuilder]

func (*WorkspaceBuilderImpl) CreateModule

func (workspace *WorkspaceBuilderImpl) CreateModule(moduleName string, moduleVersion string) (string, error)

Implements [golang.WorkspaceBuilder]

func (*WorkspaceBuilderImpl) Finish

func (workspace *WorkspaceBuilderImpl) Finish() error

This method should be called by plugins after all modules in a workspace have been combined.

The method will do the following:

• creates a go.work file in the root of the workspace that points to all of the modules contained therein
• updates the go.mod files of all contained modules with 'replace' directives for any required modules that exist in the workspace

func (*WorkspaceBuilderImpl) GetLocalModule

func (workspace *WorkspaceBuilderImpl) GetLocalModule(modulePath string) (string, bool)

Implements [golang.WorkspaceBuilder]

func (*WorkspaceBuilderImpl) ImplementsBuildContext

func (workspace *WorkspaceBuilderImpl) ImplementsBuildContext()

func (*WorkspaceBuilderImpl) Info

func (workspace *WorkspaceBuilderImpl) Info() golang.WorkspaceInfo

Implements [golang.WorkspaceBuilder]

Generated by gomarkdoc