grok

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 16, 2018 License: BSD-3-Clause Imports: 21 Imported by: 1

Documentation

Overview

Package grok provides helpers and tooling for reading, understanding and writing Serulian code.

Index

Constants

View Source
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"
)
View Source
const (
	SerulianCodeText  TextKind = "serulian"
	DocumentationText          = "documentation"
	NormalText                 = "normal"
)
View Source
const (
	SnippetCompletion   CompletionKind = "snippet"
	TypeCompletion                     = "type"
	MemberCompletion                   = "member"
	ImportCompletion                   = "import"
	ValueCompletion                    = "value"
	ParameterCompletion                = "parameter"
	VariableCompletion                 = "variable"
)
View Source
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"
)
View Source
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

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

func NewGrokerWithConfig(config Config) *Groker

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) GetHandle

func (g *Groker) GetHandle() (Handle, error)

GetHandle returns a handle for querying the Grok toolkit.

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

func (gh Handle) FindSymbols(query string) ([]Symbol, error)

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

func (gh Handle) IsCompilable() bool

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

type MarkedText struct {
	Value string
	Kind  TextKind
}

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 RangeKind

type RangeKind string

RangeKind defines the kind of the range.

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.

type SymbolKind

type SymbolKind string

SymbolKind defines the various kinds of symbols.

type TextKind

type TextKind string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL