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.

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)

Platform Compatibility

  • MRI Ruby: ✓ Full support

  • JRuby: ✓ Full support (uses JNR-FFI)

  • TruffleRuby: ✗ TruffleRuby’s FFI doesn’t support STRUCT_BY_VALUE return types (used by ts_tree_root_node, ts_node_child, ts_node_start_point, etc.)

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

The FFI backend requires:

  • The ffi gem to be installed

  • NOT running on TruffleRuby (STRUCT_BY_VALUE limitation)

  • MRI backend (ruby_tree_sitter) not already loaded (symbol conflicts)

Examples:

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

Returns:

  • (Boolean) —

    true if FFI backend can be used



45
46
47
48
49
50
 
# File 'lib/tree_haver/backends/ffi.rb', line 45

def available?
  return false unless 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



89
90
91
92
93
94
95
96
97
98
 
# File 'lib/tree_haver/backends/ffi.rb', line 89

def capabilities
  return {} unless available?
  {
    backend: :ffi,
    parse: true,
    query: false, # Query API not yet implemented in FFI backend
    bytes_field: true,
    incremental: false,
  }
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.

Note:

Returns false on TruffleRuby because TruffleRuby’s FFI doesn’t support STRUCT_BY_VALUE return types (used by ts_tree_root_node, ts_node_child, etc.)

Check if the FFI gem can be loaded and is usable for tree-sitter

Returns:

  • (Boolean) —

    true if FFI gem can be loaded and works with tree-sitter



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/tree_haver/backends/ffi.rb', line 58

def ffi_gem_available?
  return @loaded if @load_attempted

  @load_attempted = true
  @loaded = begin
    # TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
    # which tree-sitter uses extensively (ts_tree_root_node, ts_node_child, etc.)
    return false if RUBY_ENGINE == "truffleruby"

    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)



78
79
80
81
 
# File 'lib/tree_haver/backends/ffi.rb', line 78

def reset!
  @load_attempted = false
  @loaded = false
end