Documentation
¶
Overview ¶
Package grok provides helpers and tooling for reading, understanding and writing Serulian code.
Index ¶
- Constants
- Variables
- type Action
- type CodeContextOrAction
- type Completion
- type CompletionInformation
- type CompletionKind
- type Config
- type ContextOrAction
- type Groker
- type Handle
- func (gh Handle) ContainsSource(source compilercommon.InputSource) bool
- func (gh Handle) Errors() []compilercommon.SourceError
- func (gh Handle) ExecuteAction(action Action, params map[string]interface{}, ...) error
- func (gh Handle) FindSymbols(query string) ([]Symbol, error)
- func (gh Handle) GetActionsForPosition(source compilercommon.InputSource, lineNumber int, colPosition int) ([]ContextOrAction, error)
- func (gh Handle) GetCompletions(activationString string, sourcePosition compilercommon.SourcePosition) (CompletionInformation, error)
- func (gh Handle) GetCompletionsForPosition(activationString string, source compilercommon.InputSource, lineNumber int, ...) (CompletionInformation, error)
- func (gh Handle) GetContextActions(source compilercommon.InputSource) ([]CodeContextOrAction, error)
- func (gh Handle) GetPositionalActions(sourcePosition compilercommon.SourcePosition) ([]ContextOrAction, error)
- func (gh Handle) GetSignature(activationString string, sourcePosition compilercommon.SourcePosition) (SignatureInformation, error)
- func (gh Handle) GetSignatureForPosition(activationString string, source compilercommon.InputSource, lineNumber int, ...) (SignatureInformation, error)
- func (gh Handle) IsCompilable() bool
- func (gh Handle) LookupPosition(source compilercommon.InputSource, lineNumber int, colPosition int) (RangeInformation, error)
- func (gh Handle) LookupSourcePosition(sourcePosition compilercommon.SourcePosition) (RangeInformation, error)
- func (gh Handle) Warnings() []compilercommon.SourceWarning
- type HandleFreshnessOption
- type HandleResult
- type MarkedText
- type ParameterInformation
- type RangeInformation
- type RangeKind
- type SignatureInformation
- type Symbol
- type SymbolKind
- type TextKind
Constants ¶
const ( // NotFound indicates the specified location does not match a defined range. NotFound RangeKind = "notfound" // Keyword indicates the specified location matches a keyword. Keyword = "keyword" // Literal indicates the specified location matches a literal value. Literal = "literal" // TypeRef indicates the specified location matches a type reference. TypeRef = "type-ref" // NamedReference indicates the specified location matches a named reference, // as opposed to unnamed scope. NamedReference = "named-reference" // PackageOrModule indicates the specified location matches a package or module. PackageOrModule = "package-or-module" // UnresolvedTypeOrMember indicates the specified location matches an unresolved type // or member. This can happen if the import is invalid, or if it is referencing a // non-SRG import. UnresolvedTypeOrMember = "unresolved-type-or-member" // LocalValue indicates the specified location matches a locally named and typed value. LocalValue = "local-value" // Unknown indicates the specified location matches an unknown value. Unknown = "unknown" )
const ( SerulianCodeText TextKind = "serulian" DocumentationText = "documentation" NormalText = "normal" )
const ( SnippetCompletion CompletionKind = "snippet" TypeCompletion = "type" MemberCompletion = "member" ImportCompletion = "import" ValueCompletion = "value" ParameterCompletion = "parameter" VariableCompletion = "variable" )
const ( // TypeSymbol indicates the symbol is a type. TypeSymbol SymbolKind = "symbol-type" // MemberSymbol indicates the symbol is a member. MemberSymbol = "symbol-member" // ModuleSymbol indicates the symbol is a module. ModuleSymbol = "symbol-module" )
const ( // NoAction indicates that there is no action associated with the context. NoAction Action = "none" // UnfreezeImport indicates that an import should be unfrozen. UnfreezeImport = "unfreeze-import" // FreezeImport indicates that an import should be frozen at a commit or tag. FreezeImport = "freeze-import" )
Variables ¶
var AllActions = []string{string(NoAction), string(FreezeImport), string(UnfreezeImport)}
AllActions defines the set of all actions supported by Grok.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action string
Action represents a single action that can be performed against a sourcefile.
type CodeContextOrAction ¶
type CodeContextOrAction struct { // Range represents the range in the source to which the context is applied. Range compilercommon.SourceRange // Resolve is a function to be invoked by the tooling, to resolve the actual context or action. Resolve func() (ContextOrAction, bool) }
CodeContextOrAction represents context or an action to display inline with *specific* code. Typically provides additional information about the code (such as the SHA of an unfrozen import) or an action that can be performed by the developer (like freezing an import).
type Completion ¶
type Completion struct { // Kind is the kind of the completion. Kind CompletionKind // Title is the human readable title of the completion. Title string // Code is the code to be added when this completion is selected. Code string // The human readable documentation on the completion's item, if any. Documentation string // The type of the completion, if any. If the completion doesn't have a valid // type, will be void. TypeReference typegraph.TypeReference // SourceRanges contains the range(s) of the source file in which this completion's item is found. May be empty. SourceRanges []compilercommon.SourceRange // If the completion is a member, the member. Member *typegraph.TGMember // If the completion is a type, the type. Type *typegraph.TGTypeDecl }
Completion defines a single autocompletion returned by grok.
type CompletionInformation ¶
type CompletionInformation struct { // ActivationString contains the string used to activate the completion. May be empty. ActivationString string // Completions are the completions found, if any. Completions []Completion }
CompletionInformation represents information about auto-completion over a particular activation string, at a particular location.
type CompletionKind ¶
type CompletionKind string
type Config ¶ added in v0.3.0
type Config struct { // EntrypointPath is the path to the entrypoint of the project being groked. EntrypointPath string // VCSDevelopmentDirectories defines the development directories (if any) to use. VCSDevelopmentDirectories []string // Libraries holds the libraries to be imported. Libraries []packageloader.Library // PathLoader is the path loader to use. PathLoader packageloader.PathLoader // ScopePaths, if not empty, indicates the paths that should be considered by the // compiler when scoping. ScopePaths []compilercommon.InputSource }
Config defines the config for creating a Grok.
type ContextOrAction ¶
type ContextOrAction struct { // Range represents the range in the source to which the context/action is applied. Range compilercommon.SourceRange // Title is the title to display inline in the code. Title string // Action is the action that can be invoked for this context, if any. Action Action // ActionParams is a generic map of data to be sent when the action is invoked, if any. ActionParams map[string]interface{} }
ContextOrAction represents context or an action that is applied to code.
type Groker ¶
type Groker struct {
// contains filtered or unexported fields
}
Groker defines a toolkit for providing IDE tooling for Serulian projects.
func NewGroker ¶
func NewGroker(entrypointPath string, vcsDevelopmentDirectories []string, libraries []packageloader.Library) *Groker
NewGroker returns a new Groker for the given entrypoint file/directory path.
func NewGrokerWithConfig ¶ added in v0.3.0
NewGrokerWithConfig returns a new Groker with the given config.
func (*Groker) BuildHandle ¶ added in v0.3.0
func (g *Groker) BuildHandle() chan HandleResult
BuildHandle builds a new handle for this Grok. If an existing handle is being built, it will be canceled.
func (*Groker) GetHandleWithOption ¶
func (g *Groker) GetHandleWithOption(freshnessOption HandleFreshnessOption) (Handle, error)
GetHandleWithOption returns a handle for querying the Grok toolkit.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle defines a handle to the Grok toolkit. Once given, a handle can be used to issues queries without worrying about concurrent access issues, as the graph being accessed will be immutable.
func (Handle) ContainsSource ¶
func (gh Handle) ContainsSource(source compilercommon.InputSource) bool
ContainsSource returns true if the graph referenced by this handle contains the given input source.
func (Handle) Errors ¶
func (gh Handle) Errors() []compilercommon.SourceError
Errors returns any source errors found when building the handle, if any.
func (Handle) ExecuteAction ¶
func (gh Handle) ExecuteAction(action Action, params map[string]interface{}, source compilercommon.InputSource) error
ExecuteAction executes an action as defined by GetContextActions.
func (Handle) FindSymbols ¶
FindSymbols finds all symbols (types, type members and modules) matching the given query. If the query is empty, returns all.
func (Handle) GetActionsForPosition ¶
func (gh Handle) GetActionsForPosition(source compilercommon.InputSource, lineNumber int, colPosition int) ([]ContextOrAction, error)
GetActionsForPosition returns all asynchronous code actions for the given source position. Unlike GetContextActions, the returns items must *all* be actions, and should be displayed in a selector menu, rather than inline in the code.
func (Handle) GetCompletions ¶
func (gh Handle) GetCompletions(activationString string, sourcePosition compilercommon.SourcePosition) (CompletionInformation, error)
GetCompletions returns the autocompletion information for the given activationString at the given location. If the activation string is empty, returns all context-sensitive defined names.
func (Handle) GetCompletionsForPosition ¶
func (gh Handle) GetCompletionsForPosition(activationString string, source compilercommon.InputSource, lineNumber int, colPosition int) (CompletionInformation, error)
GetCompletionsForPosition returns the autocompletion information for the given activationString at the given position. If the activation string is empty, returns all context-sensitive defined names.
func (Handle) GetContextActions ¶
func (gh Handle) GetContextActions(source compilercommon.InputSource) ([]CodeContextOrAction, error)
GetContextActions returns all context actions for the given source file.
func (Handle) GetPositionalActions ¶
func (gh Handle) GetPositionalActions(sourcePosition compilercommon.SourcePosition) ([]ContextOrAction, error)
GetPositionalActions returns all asynchronous code actions for the given source position. Unlike GetContextActions, the returns items must *all* be actions, and should be displayed in a selector menu, rather than inline in the code.
func (Handle) GetSignature ¶
func (gh Handle) GetSignature(activationString string, sourcePosition compilercommon.SourcePosition) (SignatureInformation, error)
GetSignature returns the parameter signature information for the given activationString at the given position. If the activation string does not end in a signature activation character, returns nothing.
func (Handle) GetSignatureForPosition ¶
func (gh Handle) GetSignatureForPosition(activationString string, source compilercommon.InputSource, lineNumber int, colPosition int) (SignatureInformation, error)
GetSignatureForPosition returns the parameter signature information for the given activationString at the given position. If the activation string does not end in a signature activation character, returns nothing.
func (Handle) IsCompilable ¶
IsCompilable returns true if the graph referred to by Grok is fully valid, containing no errors of any kind.
func (Handle) LookupPosition ¶
func (gh Handle) LookupPosition(source compilercommon.InputSource, lineNumber int, colPosition int) (RangeInformation, error)
LookupPosition looks up the given position in the given source file, and returns its descriptive metadata, if any.
func (Handle) LookupSourcePosition ¶
func (gh Handle) LookupSourcePosition(sourcePosition compilercommon.SourcePosition) (RangeInformation, error)
LookupSourcePosition looks up the position as specified by the source position, and returns its descriptive metadata, if any.
func (Handle) Warnings ¶
func (gh Handle) Warnings() []compilercommon.SourceWarning
Warnings returns any source warnings found when building the handle, if any.
type HandleFreshnessOption ¶
type HandleFreshnessOption int
HandleFreshnessOption defines the options around code freshness when retrieving a handle.
const ( // HandleMustBeFresh indicates that all code must be up-to-date before returning the handle. HandleMustBeFresh HandleFreshnessOption = iota // HandleAllowStale indicates that a stale cached handle can be returned. HandleAllowStale )
type HandleResult ¶ added in v0.3.0
type HandleResult struct { // Handle is the Grok handle constructed, if there was no error. Handle Handle // Error is the error that occurred, if any. Error error }
HandleResult is the result of a BuildHandle call.
type MarkedText ¶
MarkedText is text marked with a kind.
type ParameterInformation ¶
type ParameterInformation struct { // Name is the name of the parameter. Name string // TypeReference is the type of the parameter. May be missing, in which case it will be void. TypeReference typegraph.TypeReference // The human readable documentation on the parameter, if any. Documentation string }
ParameterInformation represents information about a single parameter in a signature.
type RangeInformation ¶
type RangeInformation struct { // Kind indicates the kind of the range found (if not found, is `NotFound`). Kind RangeKind // SourceRanges contains the range(s) of the source file in which this range is found. May be empty. SourceRanges []compilercommon.SourceRange // If the range is a Keyword, the keyword. Keyword string // If the range is a Literal, the literal value. LiteralValue string // If the range is a package or module, the name of the package/module. PackageOrModule string // If the range is an unresolved type or member, the name of the import source. UnresolvedTypeOrMember string // If the range is a typeref or local value, the type referenced. If the type could not // be referenced, `void` is returned. TypeReference typegraph.TypeReference // If the range is a local value, the name. LocalName string // If the range is a named reference, the reference. NamedReference scopegraph.ReferencedName }
RangeInformation represents information about a source range in the source graph.
func (RangeInformation) HumanReadable ¶
func (ri RangeInformation) HumanReadable() []MarkedText
HumanReadable returns the human readable information for the range information.
func (RangeInformation) Name ¶
func (ri RangeInformation) Name() (string, bool)
Name returns the name of entity found in this range, if any.
type SignatureInformation ¶
type SignatureInformation struct { // Name is the name of the referenced function/operator. Name string // If the function is a member, the member. Member *typegraph.TGMember // The human readable documentation on the function/operator, if any. Documentation string // Parameters represents the parameters of the signature. Parameters []ParameterInformation // If >= 0, the active parameter for this signature when lookup occurred. ActiveParameterIndex int // TypeReference is the type of the entity being invoked. May be missing, in which case it will be void. TypeReference typegraph.TypeReference }
SignatureInformation represents information about the signature of a function/operator and its parameters.
type Symbol ¶
type Symbol struct { // Name is the name of the symbol. Name string // Kind is the kind of symbol. Kind SymbolKind // IsExported returns whether the symbol is exported. IsExported bool // SourceRanges contains the range(s) of the source file in which this symbol is found. May be empty. SourceRanges []compilercommon.SourceRange // Score is the score for this symbol under the query. Score float64 // If the symbol is a member, the member. Member *typegraph.TGMember // If the symbol is a type, the type. Type *typegraph.TGTypeDecl // If the symbol is a module, the module. Module *typegraph.TGModule }
Symbol represents a named symbol in the type graph, such as a type, member or module.