treesitter.c: 'R' Bindings to the 'C' Grammar for Tree-Sitter

Description

Provides bindings to a 'C' grammar for Tree-sitter, to be used alongside the 'treesitter' package. Tree-sitter builds concrete syntax trees for source files and can efficiently update them or generate code like producing R C API wrappers from C functions, structs and global definitions from header files.

Author(s)

Maintainer: Sounkou Mahamane Toure sounkoutoure@gmail.com

Other contributors:

• Tree-sitter authors (Tree-sitter C grammar) [copyright holder]

• Eli Bendersky and Co-authors (pycparser fake_libc headers) [copyright holder]

See Also

Useful links:

• https://sounkou-bioinfo.github.io/treesitter.c/

• https://github.com/sounkou-bioinfo/treesitter.c

• Report bugs at https://github.com/sounkou-bioinfo/treesitter.c/issues

Get the path to the installed fake_libc headers

Description

Returns the absolute path to the inst/fake_libc directory in the installed package.

Usage

fake_libc_path()

Value

Character scalar with the path to fake_libc headers

This function will use the configured C compiler to list macro definitions (-dM -E) if use_cpp = TRUE and a compiler is available; otherwise, a simple scan of ⁠#define⁠ lines is used as a fallback.

Description

This function will use the configured C compiler to list macro definitions (-dM -E) if use_cpp = TRUE and a compiler is available; otherwise, a simple scan of ⁠#define⁠ lines is used as a fallback.

Usage

get_defines_from_file(file, use_cpp = TRUE, cc = r_cc(), ccflags = NULL)

Arguments

Value

Character vector of macro names defined in file

Extract enum members from a parsed header

Description

Extract enum members from a parsed header

Usage

get_enum_members_from_root(root)

Arguments

Value

Data frame with enum member names and values.

Extract enum names from a parsed header

Description

Extract enum names from a parsed header

Usage

get_enum_nodes(root)

Arguments

Value

Data frame with enum names.

Extract function names (declarations and definitions) from a root

Description

Returns a data frame with capture_name, text, start_line, and start_col.

Usage

get_function_nodes(root, extract_params = FALSE, extract_return = FALSE)

Arguments

Value

Data frame with function captures; when extract_params=TRUE a params list-column is present.

Extract global variable names from a parsed tree root

Description

Extract global variable names from a parsed tree root

Usage

get_globals_from_root(root)

Arguments

Value

Data frame with top-level global names.

Extract global variables with types from a parsed tree root

Description

Extract global variables with types from a parsed tree root

Usage

get_globals_with_types_from_root(root)

Arguments

Value

Data frame with global names and C types.

Extract members of structs (including nested anonymous struct members)

Description

Extract members of structs (including nested anonymous struct members)

Usage

get_struct_members(root)

Arguments

Value

Data frame describing struct members, including bitfields.

Extract struct names from a parsed tree root

Description

Extract struct names from a parsed tree root

Usage

get_struct_nodes(root)

Arguments

Value

Data frame with struct name captures.

Extract members of unions

Description

Extract members of unions

Usage

get_union_members_from_root(root)

Arguments

Value

Data frame describing union members, including bitfields.

Extract union names from a parsed header

Description

Extract union names from a parsed header

Usage

get_union_nodes(root)

Arguments

Value

Data frame with union names.

tree-sitter language for C

Description

language() returns a tree_sitter_language object for C for use with the treesitter package.

Usage

language()

Value

A tree_sitter_language object.

Examples

language()

Convert character content of a header file into a tree-sitter root

Description

Convert character content of a header file into a tree-sitter root

Usage

parse_header_text(text, lang = language())

Arguments

Value

The tree root node object

Examples

if (requireNamespace("treesitter", quietly = TRUE)) {
  root <- parse_header_text("int foo(int);\n")
  root
}

Parse a directory of headers and return named list of data.frames with

Description

functions, structs, struct members, enums, unions, globals, and macros.

Usage

parse_headers_collect(
  dir = R.home("include"),
  recursive = TRUE,
  pattern = c("\\.h$", "\\.H$"),
  preprocess = FALSE,
  cc = r_cc(),
  ccflags = NULL,
  include_dirs = NULL,
  extract_params = FALSE,
  extract_return = FALSE,
  ...
)

Arguments

Details

This helper loops over headers found in a directory and returns a list with tidy data.frames. Useful for programmatic analysis of header collections.

Value

A named list of data frames with components: functions, structs, struct_members, enums, unions, globals, defines.

Examples

## Not run: 
if (requireNamespace("treesitter", quietly = TRUE)) {
  res <- parse_headers_collect(dir = R.home("include"), preprocess = FALSE)
  head(res$functions)
}

## End(Not run)

Parse C header files for function declarations using tree-sitter

Description

This utility uses the C language provided by this package and the treesitter parser to find function declarations and definitions in C header files. The default dir is R.home("include"), which is typically where R's headers live.

Usage

parse_r_include_headers(
  dir = R.home("include"),
  recursive = TRUE,
  pattern = c("\\.h$", "\\.H$"),
  preprocess = FALSE,
  cc = r_cc(),
  ccflags = NULL,
  include_dirs = NULL,
  ...
)

Arguments

Value

A data frame with columns name, file, line, and kind (either 'declaration' or 'definition').

Examples

if (requireNamespace("treesitter", quietly = TRUE)) {
  # Parse a small header file from a temp dir
  tmp <- tempdir()
  path <- file.path(tmp, "example.h")
  writeLines(c(
    "int foo(int a);",
    "static inline int bar(void) { return 1; }"
  ), path)
  parse_r_include_headers(dir = tmp)
}

Run the C preprocessor on file using the provided compiler

Description

This function runs the configured C compiler with the -E preprocessor flag and returns the combined preprocessed output as a single string.

Usage

preprocess_header(file, cc = r_cc(), ccflags = NULL, ...)

Arguments

Value

Character scalar with the preprocessed output of file.

Examples

## Not run: 
# Check for a compiler before running an example that invokes the preprocessor
rcc <- treesitter.c::r_cc()
if (nzchar(rcc)) {
  rcc_prog <- strsplit(rcc, "\\s+")[[1]][1]
  if (nzchar(Sys.which(rcc_prog))) {
    tmp <- tempfile("hdr3")
    dir.create(tmp)
    path <- file.path(tmp, "p.h")
    writeLines(c("#define TYPE int", "TYPE foo(TYPE x);"), path)
    out <- preprocess_header(path)
    grepl("int foo\\(", out)
  } else {
    message("Skipping preprocess example: compiler not found on PATH")
  }
}

## End(Not run)

Preprocess a set of header files found under dir

Description

This helper calls preprocess_header() for each matching file in dir and returns a named list with the path as the keys and the preprocessed text as the values.

Usage

preprocess_headers(
  dir = R.home("include"),
  recursive = TRUE,
  pattern = c("\\.h$", "\\.H$"),
  cc = r_cc(),
  ccflags = NULL,
  ...
)

Arguments

Value

Named list of file => preprocessed text.

Return the default R-configured C compiler (possibly with flags)

Description

This function queries common places to find the C compiler used by R. It checks Sys.getenv("CC"), then ⁠R CMD config CC⁠, and finally cc on PATH. The returned value may include flags (e.g., 'gcc -std=...').

Usage

r_cc()

Value

Character scalar with compiler program (or empty string).