Module: TreeHaver::Backends::FFI

Defined in:
lib/tree_haver/backends/ffi.rb

Overview

Note:

Requires the ‘ffi` gem and libtree-sitter shared library to be installed

FFI-based backend for calling libtree-sitter directly

This backend uses Ruby FFI (JNR-FFI on JRuby) to call the native tree-sitter C library without requiring MRI C extensions. This makes it compatible with JRuby, TruffleRuby, and other Ruby implementations that support FFI.

The FFI backend currently supports:

  • Parsing source code

  • AST node traversal

  • Accessing node types and children

Not yet supported:

  • Query API (tree-sitter queries/patterns)

See Also:

Defined Under Namespace

Modules: Native Classes: Language, Node, Parser, Tree

Class Method Summary collapse

Class Method Details

.available? ⇒ Boolean

Check if the FFI backend is available

Returns true if:

  1. The ‘ffi` gem is present

  2. MRI backend (ruby_tree_sitter) has NOT been loaded

FFI and MRI backends conflict at the libtree-sitter level. Once MRI loads, using FFI will cause segfaults.

Examples:

if TreeHaver::Backends::FFI.available?
  puts "FFI backend is ready"
end

Returns:

  • (Boolean) —

    true if FFI backend can be used



198
199
200
201
202
203
 
# File 'lib/tree_haver/backends/ffi.rb', line 198

def available?
  return false unless TreeHaver::Backends::FFI.ffi_gem_available?

  # Check if MRI backend has been loaded (which blocks FFI)
  !defined?(::TreeSitter::Parser)
end

.capabilities ⇒ Hash{Symbol => Object}

Get capabilities supported by this backend

Examples:

TreeHaver::Backends::FFI.capabilities
# => { backend: :ffi, parse: true, query: false, bytes_field: true }

Returns:

  • (Hash{Symbol => Object}) —

    capability map



223
224
225
226
227
228
229
230
231
 
# File 'lib/tree_haver/backends/ffi.rb', line 223

def capabilities
  return {} unless available?
  {
    backend: :ffi,
    parse: true,
    query: false,
    bytes_field: true,
  }
end

.ffi_gem_available? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if the FFI gem can be loaded

Returns:

  • (Boolean) —

    true if FFI gem can be loaded



31
32
33
34
35
36
37
38
39
40
 
# File 'lib/tree_haver/backends/ffi.rb', line 31

def ffi_gem_available?
  return @ffi_gem_available if defined?(@ffi_gem_available)

  @ffi_gem_available = begin
    require "ffi"
    true
  rescue LoadError
    false
  end
end

.reset! ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Reset the load state (primarily for testing)

Note: FFI backend doesn’t maintain load state like other backends, but this method is provided for API consistency.



212
213
214
215
 
# File 'lib/tree_haver/backends/ffi.rb', line 212

def reset!
  # FFI backend uses constant-time availability check, no state to reset
  nil
end