Documentation
¶
Index ¶
Constants ¶
const ( // LoadFiles loads the name and file names for the initial packages. LoadFiles = NeedName | NeedFiles | NeedCompiledMoonBitFiles // LoadImports loads the name, file names, and import mapping for the initial packages. LoadImports = LoadFiles | NeedImports // LoadTypes loads exported type information for the initial packages. LoadTypes = LoadImports | NeedTypes | NeedTypesSizes // LoadSyntax loads typed syntax for the initial packages. LoadSyntax = LoadTypes | NeedSyntax | NeedTypesInfo // LoadAllSyntax loads typed syntax for the initial packages and all dependencies. LoadAllSyntax = LoadSyntax | NeedDeps // Deprecated: NeedExportsFile is a historical misspelling of NeedExportFile. NeedExportsFile = NeedExportFile )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Mode controls the level of information returned for each package.
Mode LoadMode
// Dir is the directory in which to run the build system's query tool
// that provides information about the packages.
// If Dir is empty, the tool is run in the current directory.
Dir string
// Env is the environment to use when invoking the build system's query tool.
// If Env is nil, the current environment is used.
// As in os/exec's Cmd, only the last value in the slice for
// each environment key is used. To specify the setting of only
// a few variables, append to the current environment, as in:
//
// opt.Env = append(os.Environ(), "GOOS=plan9", "GOARCH=386")
//
Env []string
}
A Config specifies details about how packages should be loaded. The zero value is a valid configuration.
Calls to Load do not modify this struct.
type Error ¶
type Error struct {
Pos string // "file:line:col" or "file:line" or "" or "-"
Msg string
Kind ErrorKind
}
An Error describes a problem with a package's metadata, syntax, or types.
type ErrorKind ¶
type ErrorKind int
ErrorKind describes the source of the error, allowing the user to differentiate between errors generated by the driver, the parser, or the type-checker.
type LinkTarget ¶
type LinkTarget struct {
// Exports is a list of exported functions in the resulting wasm module.
Exports []string `json:"exports,omitempty"`
// ExportMemoryName is the name of the exported memory (e.g. "memory").
ExportMemoryName string `json:"export-memory-name,omitempty"`
}
LinkTarget represents the JSON format of a link target in moon.pkg.json.
type LoadMode ¶
type LoadMode int
A LoadMode controls the amount of detail to return when loading. The bits below can be combined to specify which fields should be filled in the result packages.
The zero value is a special case, equivalent to combining the NeedName, NeedFiles, and NeedCompiledMoonBitFiles bits.
ID and Errors (if present) will always be filled. Load may return more information than requested.
The Mode flag is a union of several bits named NeedName, NeedFiles, and so on, each of which determines whether a given field of Package (Name, Files, etc) should be populated.
For convenience, we provide named constants for the most common combinations of Need flags:
[LoadFiles] lists of files in each package [LoadImports] ... plus imports [LoadTypes] ... plus type information [LoadSyntax] ... plus type-annotated syntax [LoadAllSyntax] ... for all dependencies
Unfortunately there are a number of open bugs related to interactions among the LoadMode bits:
- https://github.com/golang/go/issues/56633
- https://github.com/golang/go/issues/56677
- https://github.com/golang/go/issues/58726
- https://github.com/golang/go/issues/63517
const ( // NeedName adds Name and PkgPath. NeedName LoadMode = 1 << iota // NeedFiles adds Dir, MoonBitFiles, OtherFiles, and IgnoredFiles NeedFiles // NeedCompiledMoonBitFiles adds CompiledMoonBitFiles. NeedCompiledMoonBitFiles // NeedImports adds Imports. If NeedDeps is not set, the Imports field will contain // "placeholder" Packages with only the ID set. NeedImports // NeedDeps adds the fields requested by the LoadMode in the packages in Imports. NeedDeps // NeedExportFile adds ExportFile. NeedExportFile // NeedTypes adds Types, Fset, and IllTyped. NeedTypes // NeedSyntax adds Syntax and Fset. NeedSyntax // NeedTypesInfo adds TypesInfo and Fset. NeedTypesInfo // NeedTypesSizes adds TypesSizes. NeedTypesSizes // NeedForTest adds ForTest. // // Tests must also be set on the context for this field to be populated. NeedForTest // NeedModule adds Module. NeedModule // NeedEmbedFiles adds EmbedFiles. NeedEmbedFiles // NeedEmbedPatterns adds EmbedPatterns. NeedEmbedPatterns )
type Module ¶
type Module struct {
Path string // module path
Version string // module version
Replace *Module // replaced by this module
Time *time.Time // time version was created
Main bool // is this the main module?
Indirect bool // is this module only an indirect dependency of main module?
Dir string // directory holding files for this module, if any
MoonBitMod string // path to go.mod file used when loading this module, if any
MoonBitVersion string // go version used in module
Error *ModuleError // error loading module
}
Module provides module information for a package.
It also defines part of the JSON schema of [DriverResponse]. See the package documentation for an overview.
type ModuleError ¶
type ModuleError struct {
Err string // the error itself
}
ModuleError holds errors loading a module.
type MoonPkgJSON ¶
type MoonPkgJSON struct {
IsMain bool `json:"is-main,omitempty"`
Imports []json.RawMessage `json:"import,omitempty"`
TestImport []json.RawMessage `json:"test-import,omitempty"`
// Targets is a map of filenames (keys) followed by its compilation rules
// (which is an array of strings).
// e.g. "file_notwasm.mbt": ["not", "wasm"], "file_wasm.mbt": ["wasm"], etc.
Targets map[string][]string `json:"targets,omitempty"`
// LinkTargets is a map of link targets (e.g. "wasm", "js", etc.)
// followed by its exports.
LinkTargets map[string]*LinkTarget `json:"link,omitempty"`
}
MoonPkgJSON represents the JSON format of the moon.pkg.json file.
type Package ¶
type Package struct {
// MoonPkgJSON is the parsed moon.pkg.json file.
MoonPkgJSON MoonPkgJSON
// ID is a unique identifier for a package,
// in a syntax provided by the underlying build system.
//
// Because the syntax varies based on the build system,
// clients should treat IDs as opaque and not attempt to
// interpret them.
ID string
// Name is the package name as it appears in the package source code.
Name string
// PkgPath is the package path as used by the go/types package.
PkgPath string
// MoonBitFiles lists the absolute file paths of the package's MoonBit source files.
// It may include files that should not be compiled, for example because
// they contain non-matching build tags, are documentary pseudo-files such as
// unsafe/unsafe.go or builtin/builtin.go, or are subject to cgo preprocessing.
MoonBitFiles []string
// Imports maps import paths appearing in the package's MoonBit source files
// to corresponding loaded Packages.
Imports map[string]*Package
// Fset provides position information for Types, TypesInfo, and Syntax.
// It is set only when Types is set.
Fset *token.FileSet `json:"-"`
// Syntax is the package's syntax trees, for the files listed in CompiledMoonBitFiles.
//
// The NeedSyntax LoadMode bit populates this field for packages matching the patterns.
// If NeedDeps and NeedImports are also set, this field will also be populated
// for dependencies.
//
// Syntax is kept in the same order as CompiledMoonBitFiles, with the caveat that nils are
// removed. If parsing returned nil, Syntax may be shorter than CompiledMoonBitFiles.
Syntax []*ast.File `json:"-"`
// TypesInfo provides type information about the package's syntax trees.
// It is set only when Syntax is set.
TypesInfo *types.Info `json:"-"`
}
A Package describes a loaded MoonBit package.
It also defines part of the JSON schema of [DriverResponse]. See the package documentation for an overview.
func Load ¶
Load loads and returns the MoonBit packages named by the given patterns.
The cfg parameter specifies loading options; nil behaves the same as an empty Config.
The [Config.Mode] field is a set of bits that determine what kinds of information should be computed and returned. Modes that require more information tend to be slower. See LoadMode for details and important caveats. Its zero value is equivalent to NeedName | NeedFiles | NeedCompiledMoonBitFiles.
Each call to Load returns a new set of Package instances. The Packages and their Imports form a directed acyclic graph.
If the NeedTypes mode flag was set, each call to Load uses a new types.Importer, so types.Object and types.Type values from different calls to Load must not be mixed as they will have inconsistent notions of type identity.
If any of the patterns was invalid as defined by the underlying build system, Load returns an error. It may return an empty list of packages without an error, for instance for an empty expansion of a valid wildcard. Errors associated with a particular package are recorded in the corresponding Package's Errors list, and do not cause Load to return an error. Clients may need to handle such errors before proceeding with further analysis. The [PrintErrors] function is provided for convenient display of all errors.
func (*Package) MarshalJSON ¶
MarshalJSON returns the Package in its JSON form. For the most part, the structure fields are written out unmodified, and the type and syntax fields are skipped. The imports are written out as just a map of path to package id. The errors are written using a custom type that tries to preserve the structure of error types we know about.
This method exists to enable support for additional build systems. It is not intended for use by clients of the API and we may change the format.
func (*Package) UnmarshalJSON ¶
UnmarshalJSON reads in a Package from its JSON format. See MarshalJSON for details about the format accepted.
Source Files