// Port of the `Language`, `LanguageMetadata`, `LanguageError` and
// `LookaheadIterator` parts of tree-sitter lib/binding_rust/lib.rs.
///|
/// The latest ABI version that is supported by the current version of the
/// library.
///
/// When Languages are generated by the Tree-sitter CLI, they are assigned an
/// ABI version number that corresponds to the current CLI version. The
/// Tree-sitter library is generally backwards-compatible with languages
/// generated using older CLI versions, but is not forwards-compatible.
pub let language_version : Int32 = @language.language_version
///|
/// The earliest ABI version that is supported by the current version of the
/// library.
pub let min_compatible_language_version : Int32 = @runtime.min_compatible_language_version
///|
/// An object that defines how to parse a particular language: the generated
/// parse tables (`@language.Language`, the equivalent of `TSLanguage`) plus,
/// for grammars with external tokens, the factory for their external scanner
/// (the equivalent of the scanner functions linked into a C parser).
pub struct Language {
priv raw : @language.Language
priv external_scanner : @runtime.ExternalScannerFactory?
}
///|
/// Create a language from its parse tables and, if the grammar has external
/// tokens, its external scanner.
pub fn Language::new(
raw : @language.Language,
external_scanner? : @runtime.ExternalScannerFactory,
) -> Language {
{ raw, external_scanner, }
}
///|
/// The parse tables of this language.
pub fn Language::raw(self : Language) -> @language.Language {
self.raw
}
///|
/// The external scanner factory of this language, if any.
pub fn Language::external_scanner(
self : Language,
) -> @runtime.ExternalScannerFactory? {
self.external_scanner
}
///|
/// Two languages are equal when they share the same parse tables (upstream
/// compares `TSLanguage` pointers).
pub impl Eq for Language with fn equal(self, other) {
physical_equal(self.raw, other.raw)
}
///|
/// Consistent with [`Eq`]: languages sharing the same parse tables hash
/// equally (upstream hashes the `TSLanguage` pointer). The hash combines the
/// table's name and sizes, which equal languages share.
pub impl Hash for Language with fn hash_combine(self, hasher) {
let raw = self.raw
hasher.combine_string(raw.name)
hasher.combine_int(raw.symbol_count)
hasher.combine_int(raw.state_count)
hasher.combine_int(raw.field_count)
}
///|
pub impl Debug for Language with fn to_repr(self) {
Repr::opaque_("Language", Repr::string(self.raw.name))
}
///|
/// Check whether this language can be assigned to a parser.
///
/// A language whose grammar uses external tokens can only be used for
/// parsing when it was created with its external scanner.
pub fn Language::is_parseable(self : Language) -> Bool {
self.raw.external_token_count == 0 || self.external_scanner is Some(_)
}
///|
/// Get the name of this language. This returns `None` in older parsers.
pub fn Language::name(self : Language) -> String? {
self.raw.language_name()
}
///|
/// Get the ABI version number that indicates which version of the
/// Tree-sitter CLI that was used to generate this [`Language`].
pub fn Language::abi_version(self : Language) -> Int32 {
self.raw.abi_version
}
///|
/// Get the metadata for this language. This information is generated by the
/// CLI, and relies on the language author providing the correct metadata in
/// the language's `tree-sitter.json` file.
pub fn Language::metadata(self : Language) -> LanguageMetadata? {
match self.raw.language_metadata() {
Some(m) =>
Some({
major_version: m.major_version,
minor_version: m.minor_version,
patch_version: m.patch_version,
})
None => None
}
}
///|
/// Get the number of distinct node types in this language.
pub fn Language::node_kind_count(self : Language) -> Int32 {
self.raw.symbol_count_with_aliases()
}
///|
/// Get the number of valid states in this language.
pub fn Language::parse_state_count(self : Language) -> Int32 {
self.raw.state_count
}
///|
/// Get a list of all supertype symbols for the language.
pub fn Language::supertypes(self : Language) -> ArrayView[Int32] {
self.raw.supertypes()
}
///|
/// Get a list of all subtype symbols for a given supertype symbol.
pub fn Language::subtypes_for_supertype(
self : Language,
supertype : Int32,
) -> ArrayView[Int32] {
self.raw.subtypes(supertype)
}
///|
/// Get the name of the node kind for the given numerical id.
pub fn Language::node_kind_for_id(self : Language, id : Int32) -> String? {
if id < 0 {
None
} else {
self.raw.symbol_name(id)
}
}
///|
/// Get the numeric id for the given node kind.
pub fn Language::id_for_node_kind(
self : Language,
kind : StringView,
named : Bool,
) -> Int32 {
self.raw.symbol_for_name(kind, named)
}
///|
/// Check whether `id` can be used to index this language's symbol tables:
/// one entry per grammar symbol plus one per alias, with `ERROR` and
/// `_ERROR` at the top of the `u16` range handled before any table lookup.
fn Language::node_kind_id_is_valid(self : Language, id : Int32) -> Bool {
(id >= 0 && id < self.node_kind_count()) ||
id == @language.ts_builtin_sym_error ||
id == @language.ts_builtin_sym_error_repeat
}
///|
/// Check if the node type for the given numerical id is named (as opposed
/// to an anonymous node type).
pub fn Language::node_kind_is_named(self : Language, id : Int32) -> Bool {
self.node_kind_id_is_valid(id) && self.raw.symbol_type(id) is Regular
}
///|
/// Check if the node type for the given numerical id is visible (as opposed
/// to a hidden node type).
pub fn Language::node_kind_is_visible(self : Language, id : Int32) -> Bool {
self.node_kind_id_is_valid(id) &&
self.raw.symbol_type(id) is (Regular | Anonymous)
}
///|
/// Check if the node type for the given numerical id is a supertype.
pub fn Language::node_kind_is_supertype(self : Language, id : Int32) -> Bool {
self.node_kind_id_is_valid(id) && self.raw.symbol_type(id) is Supertype
}
///|
/// Get the number of distinct field names in this language.
pub fn Language::field_count(self : Language) -> Int32 {
self.raw.field_count
}
///|
/// Get the field name for the given numerical id.
pub fn Language::field_name_for_id(
self : Language,
field_id : Int32,
) -> String? {
self.raw.field_name_for_id(field_id)
}
///|
/// Get the numerical id for the given field name. Field ids are never 0.
pub fn Language::field_id_for_name(
self : Language,
field_name : StringView,
) -> Int32? {
match self.raw.field_id_for_name(field_name) {
0 => None
id => Some(id)
}
}
///|
/// Get the next parse state. Combine this with
/// [`lookahead_iterator`](Language::lookahead_iterator) to generate
/// completion suggestions or valid symbols in error nodes.
///
/// Example: `language.next_state(node.parse_state(), node.grammar_id())`.
pub fn Language::next_state(
self : Language,
state : Int32,
id : Int32,
) -> Int32 {
self.raw.next_state(state, id)
}
///|
/// Create a new lookahead iterator for this language and parse state.
///
/// This returns `None` if state is invalid for this language.
///
/// Iterating [`LookaheadIterator`] will yield valid symbols in the given
/// parse state. A newly created iterator is not positioned on a symbol, so
/// [`LookaheadIterator::current_symbol`] returns `None` until the first
/// [`LookaheadIterator::next`] call.
///
/// Lookahead iterators can be useful to generate suggestions and improve
/// syntax error diagnostics. To get symbols valid in an `ERROR` node, use the
/// lookahead iterator on its first leaf node state. For a missing node, use
/// the node's [`parse_state`](Node::parse_state). Keep in mind that lookahead
/// symbols are valid in that parse state, but are not necessarily valid
/// continuations in the context of the actual following token or guaranteed
/// to be considered during error recovery.
pub fn Language::lookahead_iterator(
self : Language,
state : Int32,
) -> LookaheadIterator? {
if state < 0 {
return None
}
match @language.LookaheadIterator::new(self.raw, state) {
Some(raw) => Some({ raw, language: self, })
None => None
}
}
///|
/// The metadata associated with a language.
///
/// Currently, this metadata can be used to check the
/// [Semantic Version](https://semver.org/) of the language. This version
/// information should be used to signal if a given parser might be
/// incompatible with existing queries when upgrading between major versions,
/// or minor versions if it's in zerover.
pub(all) struct LanguageMetadata {
major_version : Int32
minor_version : Int32
patch_version : Int32
} derive(Eq, Debug)
///|
/// An error that occurred when trying to assign a [`Language`] to a
/// [`Parser`].
pub(all) suberror LanguageError {
/// The language's ABI version is not supported.
Version(Int32)
/// The language cannot be used for parsing (here: it has external tokens
/// but no external scanner).
NotParseable
} derive(Eq, Debug)
///|
pub impl Show for LanguageError with fn output(self, logger) {
match self {
Version(version) =>
logger.write_string(
"Incompatible language version \{version}. Expected minimum \{min_compatible_language_version}, maximum \{language_version}",
)
NotParseable => logger.write_string("Language cannot be used for parsing.")
}
}
///|
/// A stateful object that is used to look up symbols valid in a specific
/// parse state.
pub struct LookaheadIterator {
priv raw : @language.LookaheadIterator
priv mut language : Language
}
///|
/// Get the current language of the lookahead iterator.
pub fn LookaheadIterator::language(self : LookaheadIterator) -> Language {
self.language
}
///|
/// Get the current symbol of the lookahead iterator.
///
/// Returns `None` if the iterator is not positioned on a symbol: before the
/// first [`LookaheadIterator::next`] call, after the iterator is exhausted,
/// and after a [`LookaheadIterator::reset`] or
/// [`LookaheadIterator::reset_state`] call.
pub fn LookaheadIterator::current_symbol(self : LookaheadIterator) -> Int32? {
// C signals "not positioned" through a null symbol name.
match self.raw.current_symbol_name() {
Some(_) => Some(self.raw.current_symbol())
None => None
}
}
///|
/// Get the current symbol name of the lookahead iterator.
///
/// Returns `None` if the iterator is not positioned on a symbol.
pub fn LookaheadIterator::current_symbol_name(
self : LookaheadIterator,
) -> String? {
self.raw.current_symbol_name()
}
///|
/// Reset the lookahead iterator.
///
/// This returns `true` if the language was set successfully and `false`
/// otherwise.
pub fn LookaheadIterator::reset(
self : LookaheadIterator,
language : Language,
state : Int32,
) -> Bool {
if state < 0 {
return false
}
let ok = self.raw.reset(language.raw, state)
if ok {
self.language = language
}
ok
}
///|
/// Reset the lookahead iterator to another state.
///
/// This returns `true` if the iterator was reset to the given state and
/// `false` otherwise.
pub fn LookaheadIterator::reset_state(
self : LookaheadIterator,
state : Int32,
) -> Bool {
state >= 0 && self.raw.reset_state(state)
}
///|
/// Advance to the next valid symbol, returning it (`Iterator::next`).
pub fn LookaheadIterator::next(self : LookaheadIterator) -> Int32? {
if self.raw.next() {
Some(self.raw.current_symbol())
} else {
None
}
}
///|
/// Iterate the remaining valid symbols.
pub fn LookaheadIterator::iter(self : LookaheadIterator) -> Iter[Int32] {
Iter::new(() => self.next())
}
///|
/// Iterate the names of the remaining valid symbols.
pub fn LookaheadIterator::iter_names(self : LookaheadIterator) -> Iter[String] {
Iter::new(() => {
if self.raw.next() {
self.raw.current_symbol_name()
} else {
None
}
})
}