grammar

Documentation

Overview

Package grammar holds the main structure that the automation operates with: the Grammar. That encapsulates all the information we need in order to automate the updates of the various aspects related to the parsers (parsers themselves, associated queries, the documentation, etc.).

Index

• type Grammar
  • func (gr *Grammar) ContentURL() (url string, err error)
  • func (gr *Grammar) FetchNewVersion() (err error)
  • func (gr *Grammar) FilesMap() (out map[string]string, err error)
  • func (gr *Grammar) NewVersion() *Version
  • func (gr *Grammar) String() string
• type Grammars
  • func (gx Grammars) Find(lang string) (gr *Grammar, err error)
  • func (gx Grammars) ForEach(fn func(gr *Grammar) error, opts ...int64) error
  • func (gx Grammars) Pending() []string
  • func (gx Grammars) Supported() []string
• type Version

Types

type Grammar

type Grammar struct {
	// Version holds the associated version information.
	*Version

	// GrammarSha holds the SHA256 of the `grammar.js` (and all .js deps: TBD).
	// Is used for determining if regeneration of parser files is needed.
	GrammarSha string `json:"grammarSha,omitempty"`

	// Language name. The same as folder name and nvim_treesitter query name.
	Language string `json:"language"`

	// AltName is used when the language name is unclear by itself.
	AltName string `json:"altName,omitempty"`

	// URL holds the parser repo URL.
	URL string `json:"url"`

	// Doc holds maintenance related notes. Typically used for grammars with
	// problems.
	Doc string `json:"doc,omitempty"`

	// Description holds end users facing description.
	// Optional, only populated when needed (at least for now).
	Description string `json:"description,omitempty"`

	// MaintainedBy indicates the repo maintainers.
	MaintainedBy string `json:"maintainedBy,omitempty"`

	// SrcRoot holds the source root when it differs from the default (src).
	// Particularly useful for repos that expose multiple grammars.
	SrcRoot string `json:"srcRoot,omitempty"`

	// Files holds a list of files of interest from the repo.
	//
	// It MUST NOT include parser generated files (parser.c, parser.h,
	// alloc.h, array.h) nor `grammar.js` which are automatically
	// inferred.
	// Only manual files (scanner.c or .js deps for grammar.js).
	//
	// They can be bare filenames, in which case they will be
	// fetched from the "source" folder, otherwise, if they include
	// a slash, they will be considered repo absolute paths.
	Files []string `json:"files,omitempty"`

	// Tags is a way to group various grammars together.
	// The intended use is for creating smaller, more focused "forests".
	Tags []string `json:"tags,omitempty"`

	// SkipGenerate flag is used to skip parser regeneration from `grammar.js`,
	// for the files that cannot be regenerated. That way, they continue to use
	// the parser files provided by their repo, which may or may not be generated
	// with the latest version of TreeSitter, which is the whole point of doing
	// the regeneration locally.
	SkipGenerate bool `json:"skip,omitempty"`

	// SkipUpdate skips updates for the given parser.
	// Can be used when a parser becomes temporarily unbuildable.
	SkipUpdate bool `json:"skipUpdate,omitempty"`

	// Pending indicates to completly ignore this grammar, as not-yet-implemented.
	Pending bool `json:"pending,omitempty"`
	// contains filtered or unexported fields
}

Grammar holds all the information related to one language grammar. If a repository exposes multiple languages (like typescript which exposes both typescript and tsx) each one will have its own separate Grammar definition.

func (*Grammar) ContentURL

func (gr *Grammar) ContentURL() (url string, err error)

ContentURL returns the base URL for accessing content for the Grammar. It can handle several git hosting providers.

func (*Grammar) FetchNewVersion

func (gr *Grammar) FetchNewVersion() (err error)

FetchNewVersion attempts to fetch a new version, for the grammar. If there is a new version, then gr.newVersion will be populated and can be used for the upgrade.

func (*Grammar) FilesMap

func (gr *Grammar) FilesMap() (out map[string]string, err error)

FilesMap returns a map between remote files (to download) and local files (to save to). Features:

• determines the source inside repo based on default (src) or provided SrcRoot field;
• auto fills in parser.h
• maps plain filenames (no / in name) to resolved source dir;
• maps filepaths (has / in name) to root of repo;
• destination for all files is a file (no subfolders, everything is flattened out) inside the gr.Language folder.

func (*Grammar) NewVersion

func (gr *Grammar) NewVersion() *Version

NewVersion returns the new version, if one is available.

func (*Grammar) String

func (gr *Grammar) String() string

type Grammars

type Grammars []*Grammar

Grammars holds a collection of Grammar's.

func (Grammars) Find

func (gx Grammars) Find(lang string) (gr *Grammar, err error)

Find looks for a grammar with the given language name in the collection.

func (Grammars) ForEach

func (gx Grammars) ForEach(fn func(gr *Grammar) error, opts ...int64) error

ForEach iterates over all the Grammars in collection.

func (Grammars) Pending

func (gx Grammars) Pending() []string

Pending returns all the pending grammars' names.

func (Grammars) Supported

func (gx Grammars) Supported() []string

Supported returns all the supported grammars' names.

type Version

type Version struct {
	// Reference points to the branch to be used for updates.
	Reference string `json:"reference"`
	// Revision points to the latest revision we used for updating the grammar.
	Revision string `json:"revision,omitempty"`
}

Version holds the grammar version related info.