Dmitriy Kovalenko
a9df55d18e
* feat: Expose fff watcher * fix: Snapshots * fix: Snapshots * fix: CI cache
1359 lines
43 KiB
C
1359 lines
43 KiB
C
/* Generated by cbindgen — do not edit manually. */
|
|
|
|
#ifndef FFF_C_H
|
|
#define FFF_C_H
|
|
|
|
/* Generated with cbindgen:0.29.2 */
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
|
|
/**
|
|
* Current used version of [`FffCreateOptions`].
|
|
*/
|
|
#define FFF_CREATE_OPTIONS_VERSION 2
|
|
|
|
/**
|
|
* Current version of [`FffWatchOptions`].
|
|
*/
|
|
#define FFF_WATCH_OPTIONS_VERSION 1
|
|
|
|
/**
|
|
* Result envelope returned by all `fff_*` functions.
|
|
*
|
|
* Heap-allocated. The caller must free it with `fff_free_result`. Calling `fff_free_result`
|
|
* **does not** deallocate the underlying `handle` pointer. It needs to be cleaned separately.
|
|
* see (`fff_destroy`, `fff_free_search_result`, `fff_free_grep_result`, `fff_free_string`, etc.).
|
|
*
|
|
* Depending on the function, the payload is delivered through different fields:
|
|
*
|
|
* | Function | Payload field | Type |
|
|
* |----------------------------|---------------|-------------------------------|
|
|
* | `fff_create_instance` | `handle` | opaque instance pointer |
|
|
* | `fff_search` | `handle` | `*mut FffSearchResult` |
|
|
* | `fff_live_grep` | `handle` | `*mut FffGrepResult` |
|
|
* | `fff_multi_grep` | `handle` | `*mut FffGrepResult` |
|
|
* | `fff_get_scan_progress` | `handle` | `*mut FffScanProgress` |
|
|
* | `fff_health_check` | `handle` | `*mut c_char` (JSON string) |
|
|
* | `fff_get_historical_query` | `handle` | `*mut c_char` (string or null)|
|
|
* | `fff_wait_for_scan` | `int_value` | 1 = completed, 0 = timed out |
|
|
* | `fff_track_query` | `int_value` | 1 = success, 0 = failure |
|
|
* | `fff_refresh_git_status` | `int_value` | number of files updated |
|
|
* | `fff_scan_files` | (none) | success flag only |
|
|
* | `fff_restart_index` | (none) | success flag only |
|
|
*
|
|
* On failure, `success` is false and `error` contains the message.
|
|
*/
|
|
typedef struct FffResult {
|
|
/**
|
|
* Whether the operation succeeded.
|
|
*/
|
|
bool success;
|
|
/**
|
|
* Error message on failure. Null on success.
|
|
*/
|
|
char *error;
|
|
/**
|
|
* Opaque pointer payload. May be null.
|
|
*/
|
|
void *handle;
|
|
/**
|
|
* Integer payload for simple return values (bool as 0/1, counts, etc.).
|
|
*/
|
|
int64_t int_value;
|
|
} FffResult;
|
|
|
|
/**
|
|
* Options for `fff_create_instance_with`.
|
|
*
|
|
* Versioned struct: the layout is stable across releases, new fields are
|
|
* only appended.
|
|
*/
|
|
typedef struct FffCreateOptions {
|
|
/**
|
|
* Set to [`FFF_CREATE_OPTIONS_VERSION`] when allocating; tells the
|
|
* library which trailing fields are populated.
|
|
*/
|
|
uint32_t version;
|
|
/**
|
|
* Directory to index (required, non-NULL).
|
|
*/
|
|
const char *base_path;
|
|
/**
|
|
* Frecency LMDB database path. NULL/empty to skip frecency tracking.
|
|
*/
|
|
const char *frecency_db_path;
|
|
/**
|
|
* Query history LMDB database path. NULL/empty to skip query tracking.
|
|
*/
|
|
const char *history_db_path;
|
|
/**
|
|
* Pre-populate mmap caches for top-frecency files after the initial scan.
|
|
*/
|
|
bool enable_mmap_cache;
|
|
/**
|
|
* Build content index after the initial scan for faster grep.
|
|
*/
|
|
bool enable_content_indexing;
|
|
/**
|
|
* Start a background file-system watcher for live updates.
|
|
*/
|
|
bool watch;
|
|
/**
|
|
* Enable AI-agent optimizations.
|
|
*/
|
|
bool ai_mode;
|
|
/**
|
|
* Tracing log file path. NULL/empty to skip log init.
|
|
*/
|
|
const char *log_file_path;
|
|
/**
|
|
* Log level: `"trace" | "debug" | "info" | "warn" | "error"`.
|
|
* NULL/empty defaults to `"info"`. Ignored when `log_file_path` is unset.
|
|
*/
|
|
const char *log_level;
|
|
/**
|
|
* Content cache file-count cap. 0 = auto.
|
|
*/
|
|
uint64_t cache_budget_max_files;
|
|
/**
|
|
* Content cache byte cap. 0 = auto.
|
|
*/
|
|
uint64_t cache_budget_max_bytes;
|
|
/**
|
|
* Per-file byte cap inside the content cache. 0 = auto.
|
|
*/
|
|
uint64_t cache_budget_max_file_size;
|
|
/**
|
|
* Allow indexing the filesystem root (`/`). Off by default: root is rarely
|
|
* intended and floods the watcher with churn.
|
|
*/
|
|
bool enable_fs_root_scanning;
|
|
/**
|
|
* Allow indexing the user's home directory. Same trade-off as `enable_fs_root_scanning`.
|
|
*/
|
|
bool enable_home_dir_scanning;
|
|
/**
|
|
* Follow symlinks during scan and watcher walks. Off by default: without
|
|
* external loop protection cyclic symlinks can wedge the watcher.
|
|
*/
|
|
bool follow_symlinks;
|
|
} FffCreateOptions;
|
|
|
|
/**
|
|
* A file item returned by `fff_search`. Strings are owned by the parent
|
|
* `FffSearchResult`; free everything with `fff_free_search_result`.
|
|
*/
|
|
typedef struct FffFileItem {
|
|
char *relative_path;
|
|
char *file_name;
|
|
char *git_status;
|
|
uint64_t size;
|
|
uint64_t modified;
|
|
int64_t access_frecency_score;
|
|
int64_t modification_frecency_score;
|
|
int64_t total_frecency_score;
|
|
bool is_binary;
|
|
} FffFileItem;
|
|
|
|
/**
|
|
* Score breakdown for a search result.
|
|
*/
|
|
typedef struct FffScore {
|
|
int32_t total;
|
|
int32_t base_score;
|
|
int32_t filename_bonus;
|
|
int32_t special_filename_bonus;
|
|
int32_t frecency_boost;
|
|
int32_t distance_penalty;
|
|
int32_t current_file_penalty;
|
|
int32_t combo_match_boost;
|
|
int32_t path_alignment_bonus;
|
|
bool exact_match;
|
|
char *match_type;
|
|
} FffScore;
|
|
|
|
/**
|
|
* Location parsed from a query string (e.g. `"file.ts:42:10"`). `tag`:
|
|
* 0 = none, 1 = line, 2 = position (`line` + `col`),
|
|
* 3 = range (`line`/`col` = start, `end_line`/`end_col` = end).
|
|
*/
|
|
typedef struct FffLocation {
|
|
uint8_t tag;
|
|
int32_t line;
|
|
int32_t col;
|
|
int32_t end_line;
|
|
int32_t end_col;
|
|
} FffLocation;
|
|
|
|
/**
|
|
* Search result returned by `fff_search`; free with `fff_free_search_result`.
|
|
*/
|
|
typedef struct FffSearchResult {
|
|
/**
|
|
* Heap array of `FffFileItem` (length = `count`).
|
|
*/
|
|
struct FffFileItem *items;
|
|
/**
|
|
* Heap array of `FffScore` (length = `count`).
|
|
*/
|
|
struct FffScore *scores;
|
|
/**
|
|
* Number of items/scores in the arrays.
|
|
*/
|
|
uint32_t count;
|
|
/**
|
|
* Total number of files that matched the query.
|
|
*/
|
|
uint32_t total_matched;
|
|
/**
|
|
* Total number of indexed files.
|
|
*/
|
|
uint32_t total_files;
|
|
/**
|
|
* Location parsed from the query string.
|
|
*/
|
|
struct FffLocation location;
|
|
} FffSearchResult;
|
|
|
|
/**
|
|
* A byte range within a matched line, used for highlighting.
|
|
*/
|
|
typedef struct FffMatchRange {
|
|
uint32_t start;
|
|
uint32_t end;
|
|
} FffMatchRange;
|
|
|
|
/**
|
|
* A single grep match with file and line information. Strings and arrays are
|
|
* owned by the parent `FffGrepResult`; free everything with `fff_free_grep_result`.
|
|
*/
|
|
typedef struct FffGrepMatch {
|
|
char *relative_path;
|
|
char *file_name;
|
|
char *git_status;
|
|
char *line_content;
|
|
struct FffMatchRange *match_ranges;
|
|
char **context_before;
|
|
char **context_after;
|
|
uint64_t size;
|
|
uint64_t modified;
|
|
int64_t total_frecency_score;
|
|
int64_t access_frecency_score;
|
|
int64_t modification_frecency_score;
|
|
uint64_t line_number;
|
|
uint64_t byte_offset;
|
|
uint32_t col;
|
|
uint32_t match_ranges_count;
|
|
uint32_t context_before_count;
|
|
uint32_t context_after_count;
|
|
uint16_t fuzzy_score;
|
|
bool has_fuzzy_score;
|
|
bool is_binary;
|
|
bool is_definition;
|
|
} FffGrepMatch;
|
|
|
|
/**
|
|
* Grep result returned by `fff_live_grep` and `fff_multi_grep`;
|
|
* free with `fff_free_grep_result`.
|
|
*/
|
|
typedef struct FffGrepResult {
|
|
/**
|
|
* Heap array of `FffGrepMatch` (length = `count`).
|
|
*/
|
|
struct FffGrepMatch *items;
|
|
/**
|
|
* Number of matches in the `items` array.
|
|
*/
|
|
uint32_t count;
|
|
/**
|
|
* Total number of matches (always equal to `count`).
|
|
*/
|
|
uint32_t total_matched;
|
|
/**
|
|
* Number of files actually opened and searched in this call.
|
|
*/
|
|
uint32_t total_files_searched;
|
|
/**
|
|
* Total number of indexed files (before any filtering).
|
|
*/
|
|
uint32_t total_files;
|
|
/**
|
|
* Number of files eligible for search after filtering.
|
|
*/
|
|
uint32_t filtered_file_count;
|
|
/**
|
|
* File offset for the next page. 0 if all files have been searched.
|
|
*/
|
|
uint32_t next_file_offset;
|
|
/**
|
|
* Regex compilation error when falling back to literal matching. Null if none.
|
|
*/
|
|
char *regex_fallback_error;
|
|
} FffGrepResult;
|
|
|
|
/**
|
|
* Scan progress returned by `fff_get_scan_progress`.
|
|
* The caller must free this with `fff_free_scan_progress`.
|
|
*/
|
|
typedef struct FffScanProgress {
|
|
uint64_t scanned_files_count;
|
|
bool is_scanning;
|
|
bool is_watcher_ready;
|
|
bool is_warmup_complete;
|
|
} FffScanProgress;
|
|
|
|
/**
|
|
* A directory item returned by `fff_search_directories`. Strings are owned by
|
|
* the parent `FffDirSearchResult`; free everything with `fff_free_dir_search_result`.
|
|
*/
|
|
typedef struct FffDirItem {
|
|
char *relative_path;
|
|
char *dir_name;
|
|
int32_t max_access_frecency;
|
|
} FffDirItem;
|
|
|
|
/**
|
|
* Directory search result returned by `fff_search_directories`;
|
|
* free with `fff_free_dir_search_result`.
|
|
*/
|
|
typedef struct FffDirSearchResult {
|
|
/**
|
|
* Heap array of `FffDirItem` (length = `count`).
|
|
*/
|
|
struct FffDirItem *items;
|
|
/**
|
|
* Heap array of `FffScore` (length = `count`).
|
|
*/
|
|
struct FffScore *scores;
|
|
/**
|
|
* Number of items/scores in the arrays.
|
|
*/
|
|
uint32_t count;
|
|
/**
|
|
* Total number of directories that matched the query.
|
|
*/
|
|
uint32_t total_matched;
|
|
/**
|
|
* Total number of indexed directories.
|
|
*/
|
|
uint32_t total_dirs;
|
|
} FffDirSearchResult;
|
|
|
|
/**
|
|
* A single item in a mixed (files + directories) search result.
|
|
* `item_type`: 0 = file, 1 = directory. Strings are owned by the parent
|
|
* `FffMixedSearchResult`.
|
|
*/
|
|
typedef struct FffMixedItem {
|
|
/**
|
|
* 0 = file, 1 = directory.
|
|
*/
|
|
uint8_t item_type;
|
|
char *relative_path;
|
|
/**
|
|
* Filename for files, last directory segment for directories.
|
|
*/
|
|
char *display_name;
|
|
char *git_status;
|
|
uint64_t size;
|
|
uint64_t modified;
|
|
/**
|
|
* Access frecency for files; max among immediate children for directories.
|
|
*/
|
|
int64_t access_frecency_score;
|
|
/**
|
|
* Always 0 for directories
|
|
*/
|
|
int64_t modification_frecency_score;
|
|
/**
|
|
* Always 0 for directories
|
|
*/
|
|
int64_t total_frecency_score;
|
|
/**
|
|
* Always 0 for directories
|
|
*/
|
|
bool is_binary;
|
|
} FffMixedItem;
|
|
|
|
/**
|
|
* Mixed search result returned by `fff_search_mixed`
|
|
* free with `fff_free_mixed_search_result`.
|
|
*/
|
|
typedef struct FffMixedSearchResult {
|
|
/**
|
|
* Heap array of `FffMixedItem` (length = `count`).
|
|
*/
|
|
struct FffMixedItem *items;
|
|
/**
|
|
* Heap array of `FffScore` (length = `count`).
|
|
*/
|
|
struct FffScore *scores;
|
|
/**
|
|
* Number of items/scores in the arrays.
|
|
*/
|
|
uint32_t count;
|
|
/**
|
|
* Total number of items (files + dirs) that matched the query.
|
|
*/
|
|
uint32_t total_matched;
|
|
/**
|
|
* Total number of indexed files.
|
|
*/
|
|
uint32_t total_files;
|
|
/**
|
|
* Total number of indexed directories.
|
|
*/
|
|
uint32_t total_dirs;
|
|
/**
|
|
* Location parsed from the query string.
|
|
*/
|
|
struct FffLocation location;
|
|
} FffMixedSearchResult;
|
|
|
|
/**
|
|
* A single watch event. `kind`: 0 = created, 1 = modified, 2 = removed,
|
|
* 3 = rescan (events were lost; re-stat what you care about).
|
|
*/
|
|
typedef struct FffWatchEvent {
|
|
/**
|
|
* Absolute path (heap C string owned by the parent batch).
|
|
*/
|
|
char *path;
|
|
uint8_t kind;
|
|
} FffWatchEvent;
|
|
|
|
/**
|
|
* A batch of watch events. Free with `fff_free_watch_events`.
|
|
*/
|
|
typedef struct FffWatchEventBatch {
|
|
struct FffWatchEvent *events;
|
|
uint32_t count;
|
|
} FffWatchEventBatch;
|
|
|
|
/**
|
|
* Instance-wide callback invoked with `(watch_id, batch)` for every `fff_watch`
|
|
* subscription. The callee owns and frees `batch` via `fff_free_watch_events`.
|
|
*/
|
|
typedef void (*FffWatchCallback)(uint64_t watch_id,
|
|
struct FffWatchEventBatch *batch,
|
|
void *user_data);
|
|
|
|
/**
|
|
* Options for `fff_watch`. Versioned: new fields are only appended.
|
|
*/
|
|
typedef struct FffWatchOptions {
|
|
/**
|
|
* Set to [`FFF_WATCH_OPTIONS_VERSION`] when allocating.
|
|
*/
|
|
uint32_t version;
|
|
/**
|
|
* Per-subscription excludes (parcel-watcher style): entries with wildcards
|
|
* are base-relative globs, entries without are path prefixes. NULL when
|
|
* `ignore_count` is 0.
|
|
*/
|
|
const char *const *ignore;
|
|
uint32_t ignore_count;
|
|
} FffWatchOptions;
|
|
|
|
/**
|
|
* Create a new file finder instance (legacy 8-arg positional signature).
|
|
*
|
|
* @deprecated Use [`fff_create_instance_with`] (or [`fff_create_instance_with_value`]
|
|
* for FFI bindings). The `use_unsafe_no_lock` parameter is ignored.
|
|
*
|
|
* ## Safety
|
|
* See `fff_create_instance_with`.
|
|
*/
|
|
__attribute__((deprecated("Use fff_create_instance_with (by pointer) or fff_create_instance_with_value (by value) with FffCreateOptions instead. The struct evolves without ABI breaks.")))
|
|
struct FffResult *fff_create_instance(const char *base_path,
|
|
const char *frecency_db_path,
|
|
const char *history_db_path,
|
|
bool _use_unsafe_no_lock,
|
|
bool enable_mmap_cache,
|
|
bool enable_content_indexing,
|
|
bool watch,
|
|
bool ai_mode);
|
|
|
|
/**
|
|
* Create a new file finder instance (legacy 13-arg positional signature).
|
|
*
|
|
* @deprecated Use [`fff_create_instance_with`] (or [`fff_create_instance_with_value`]
|
|
* for FFI bindings). The `use_unsafe_no_lock` parameter is ignored.
|
|
*
|
|
* ## Safety
|
|
* See `fff_create_instance_with`.
|
|
*/
|
|
__attribute__((deprecated("Use fff_create_instance_with (by pointer) or fff_create_instance_with_value (by value) with FffCreateOptions instead. The struct evolves without ABI breaks.")))
|
|
struct FffResult *fff_create_instance2(const char *base_path,
|
|
const char *frecency_db_path,
|
|
const char *history_db_path,
|
|
bool _use_unsafe_no_lock,
|
|
bool enable_mmap_cache,
|
|
bool enable_content_indexing,
|
|
bool watch,
|
|
bool ai_mode,
|
|
const char *log_file_path,
|
|
const char *log_level,
|
|
uint64_t cache_budget_max_files,
|
|
uint64_t cache_budget_max_bytes,
|
|
uint64_t cache_budget_max_file_size);
|
|
|
|
/**
|
|
* Create a new file finder instance from a versioned [`FffCreateOptions`] struct.
|
|
*
|
|
* Populate the struct, set `version` to [`FFF_CREATE_OPTIONS_VERSION`], pass by
|
|
* pointer. New fields are only appended; older `version` values keep working.
|
|
* FFI bindings needing struct-by-value should use [`fff_create_instance_with_value`].
|
|
*
|
|
* `opts.base_path` is required (non-NULL, non-empty). Zero `cache_budget_*`
|
|
* values are auto-computed from repo size after the initial scan.
|
|
*
|
|
* ## Safety
|
|
* * `opts` must be a valid pointer to an `FffCreateOptions` whose `version`
|
|
* is in the range `1..=FFF_CREATE_OPTIONS_VERSION`.
|
|
* * All string pointers inside `opts` must be valid null-terminated UTF-8
|
|
* or NULL.
|
|
*/
|
|
struct FffResult *fff_create_instance_with(const struct FffCreateOptions *opts);
|
|
|
|
/**
|
|
* [`fff_create_instance_with`] adapter taking [`FffCreateOptions`] **by value**,
|
|
* for FFI libraries that pass native structs by value (e.g. Node's `ffi-rs`).
|
|
*
|
|
* ## Safety
|
|
* All `*const c_char` fields inside `opts` must be valid null-terminated
|
|
* UTF-8 or NULL. The struct itself is consumed by value.
|
|
*/
|
|
struct FffResult *fff_create_instance_with_value(struct FffCreateOptions opts);
|
|
|
|
/**
|
|
* Destroy a file finder instance and free all its resources.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid pointer returned by `fff_create_instance`, or null (no-op).
|
|
*/
|
|
void fff_destroy(void *fff_handle);
|
|
|
|
/**
|
|
* Perform fuzzy search on indexed files.
|
|
*
|
|
* `current_file` deprioritizes the currently open file (NULL/empty to skip).
|
|
* Zero picks the default: `max_threads` auto, `page_size` 100,
|
|
* `combo_boost_multiplier` 100, `min_combo_count` 3.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `query` and `current_file` must be valid null-terminated UTF-8 strings or NULL.
|
|
*/
|
|
struct FffResult *fff_search(void *fff_handle,
|
|
const char *query,
|
|
const char *current_file,
|
|
uint32_t max_threads,
|
|
uint32_t page_index,
|
|
uint32_t page_size,
|
|
int32_t combo_boost_multiplier,
|
|
uint32_t min_combo_count);
|
|
|
|
/**
|
|
* Glob-only search: filter indexed files by a single glob pattern (passed
|
|
* through verbatim, no query parsing), rank by frecency, and paginate.
|
|
*
|
|
* `current_file` deprioritizes the currently open file (NULL/empty to skip).
|
|
* Zero picks the default: `max_threads` auto, `page_size` 100.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `pattern` and `current_file` must be valid null-terminated UTF-8 strings or NULL.
|
|
*/
|
|
struct FffResult *fff_glob(void *fff_handle,
|
|
const char *pattern,
|
|
const char *current_file,
|
|
uint32_t max_threads,
|
|
uint32_t page_index,
|
|
uint32_t page_size);
|
|
|
|
/**
|
|
* Perform fuzzy search on indexed directories.
|
|
*
|
|
* `current_file` is used for distance scoring (NULL/empty to skip).
|
|
* Zero picks the default: `max_threads` auto, `page_size` 100.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `query` and `current_file` must be valid null-terminated UTF-8 strings or NULL.
|
|
*/
|
|
struct FffResult *fff_search_directories(void *fff_handle,
|
|
const char *query,
|
|
const char *current_file,
|
|
uint32_t max_threads,
|
|
uint32_t page_index,
|
|
uint32_t page_size);
|
|
|
|
/**
|
|
* Perform a mixed fuzzy search across both files and directories.
|
|
*
|
|
* Returns one flat list interleaved by descending total score; each item's
|
|
* `item_type` is 0 = file, 1 = directory. Parameters as in [`fff_search`].
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `query` and `current_file` must be valid null-terminated UTF-8 strings or NULL.
|
|
*/
|
|
struct FffResult *fff_search_mixed(void *fff_handle,
|
|
const char *query,
|
|
const char *current_file,
|
|
uint32_t max_threads,
|
|
uint32_t page_index,
|
|
uint32_t page_size,
|
|
int32_t combo_boost_multiplier,
|
|
uint32_t min_combo_count);
|
|
|
|
/**
|
|
* Perform content search (grep) across indexed files.
|
|
*
|
|
* `query` supports constraint syntax like `*.rs pattern`; `mode` is
|
|
* 0 = plain text (SIMD), 1 = regex, 2 = fuzzy. Zero picks the default:
|
|
* `max_file_size` 10 MB, `page_limit` 50, `max_matches_per_file` and
|
|
* `time_budget_ms` unlimited. `smart_case` is case-insensitive for
|
|
* all-lowercase queries; `classify_definitions` tags code definitions.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `query` must be a valid null-terminated UTF-8 string.
|
|
*/
|
|
struct FffResult *fff_live_grep(void *fff_handle,
|
|
const char *query,
|
|
uint8_t mode,
|
|
uint64_t max_file_size,
|
|
uint32_t max_matches_per_file,
|
|
bool smart_case,
|
|
uint32_t file_offset,
|
|
uint32_t page_limit,
|
|
uint64_t time_budget_ms,
|
|
uint32_t before_context,
|
|
uint32_t after_context,
|
|
bool classify_definitions);
|
|
|
|
/**
|
|
* Multi-pattern OR search (SIMD Aho-Corasick): lines matching ANY pattern.
|
|
*
|
|
* `patterns_joined` is `\n`-separated (e.g. `"foo\nbar"`); `constraints` is an
|
|
* optional file filter like `"*.rs"` or `"/src/"` (NULL/empty to skip).
|
|
* Remaining parameters as in [`fff_live_grep`].
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `patterns_joined` and `constraints` must be valid null-terminated UTF-8 or NULL.
|
|
*/
|
|
struct FffResult *fff_multi_grep(void *fff_handle,
|
|
const char *patterns_joined,
|
|
const char *constraints,
|
|
uint64_t max_file_size,
|
|
uint32_t max_matches_per_file,
|
|
bool smart_case,
|
|
uint32_t file_offset,
|
|
uint32_t page_limit,
|
|
uint64_t time_budget_ms,
|
|
uint32_t before_context,
|
|
uint32_t after_context,
|
|
bool classify_definitions);
|
|
|
|
/**
|
|
* Trigger a rescan of the file index.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_scan_files(void *fff_handle);
|
|
|
|
/**
|
|
* Check if a scan is currently in progress.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
bool fff_is_scanning(void *fff_handle);
|
|
|
|
/**
|
|
* Get the picker's base path as a heap C string in `handle`;
|
|
* free it with `fff_free_string`.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_get_base_path(void *fff_handle);
|
|
|
|
/**
|
|
* Get scan progress information.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_get_scan_progress(void *fff_handle);
|
|
|
|
/**
|
|
* Wait for initial scan to complete.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_wait_for_scan(void *fff_handle, uint64_t timeout_ms);
|
|
|
|
/**
|
|
* Wait for the background file watcher to be ready.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_wait_for_watcher(void *fff_handle, uint64_t timeout_ms);
|
|
|
|
/**
|
|
* Restart indexing in a new directory.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `new_path` must be a valid null-terminated UTF-8 string.
|
|
*/
|
|
struct FffResult *fff_restart_index(void *fff_handle, const char *new_path);
|
|
|
|
/**
|
|
* Refresh git status cache.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_refresh_git_status(void *fff_handle);
|
|
|
|
/**
|
|
* Track query completion for smart suggestions.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `query` and `file_path` must be valid null-terminated UTF-8 strings.
|
|
*/
|
|
struct FffResult *fff_track_query(void *fff_handle, const char *query, const char *file_path);
|
|
|
|
/**
|
|
* Get historical query by offset (0 = most recent).
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_get_historical_query(void *fff_handle, uint64_t offset);
|
|
|
|
/**
|
|
* Get health check information.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`, or null for
|
|
* a limited health check (version + git only).
|
|
* * `test_path` can be null or a valid null-terminated UTF-8 string.
|
|
*/
|
|
struct FffResult *fff_health_check(void *fff_handle, const char *test_path);
|
|
|
|
/**
|
|
* Free a search result returned by `fff_search`: the struct, its `items`
|
|
* and `scores` arrays, and every string within.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid pointer previously returned via `FffResult.handle`
|
|
* from `fff_search`, or null (no-op).
|
|
*/
|
|
void fff_free_search_result(struct FffSearchResult *result);
|
|
|
|
/**
|
|
* Pointer to the `index`-th `FffFileItem`; null if `result` is null or
|
|
* `index >= count`. Valid until the search result is freed.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffSearchResult` pointer from `fff_search`.
|
|
*/
|
|
const struct FffFileItem *fff_search_result_get_item(const struct FffSearchResult *result,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Pointer to the `index`-th `FffScore`; null if `result` is null or
|
|
* `index >= count`. Valid until the search result is freed.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffSearchResult` pointer from `fff_search`.
|
|
*/
|
|
const struct FffScore *fff_search_result_get_score(const struct FffSearchResult *result,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Free a grep result returned by `fff_live_grep` or `fff_multi_grep`:
|
|
* the struct, its `items` array, and all strings/ranges/context within.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid pointer previously returned via `FffResult.handle`
|
|
* from `fff_live_grep` or `fff_multi_grep`, or null (no-op).
|
|
*/
|
|
void fff_free_grep_result(struct FffGrepResult *result);
|
|
|
|
/**
|
|
* Pointer to the `index`-th `FffGrepMatch`; null if `result` is null or
|
|
* `index >= count`. Valid until the grep result is freed.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffGrepResult` pointer from `fff_live_grep` or `fff_multi_grep`.
|
|
*/
|
|
const struct FffGrepMatch *fff_grep_result_get_match(const struct FffGrepResult *result,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Free a scan progress result returned by `fff_get_scan_progress`.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid pointer previously returned via `FffResult.handle`
|
|
* from `fff_get_scan_progress`, or null (no-op).
|
|
*/
|
|
void fff_free_scan_progress(struct FffScanProgress *result);
|
|
|
|
/**
|
|
* Offset a pointer by `byte_offset` bytes (FFI array iteration helper).
|
|
* Returns null if `base` is null.
|
|
*
|
|
* ## Safety
|
|
* The resulting pointer must be within the bounds of the original allocation.
|
|
*/
|
|
const void *fff_ptr_offset(const void *base, uintptr_t byte_offset);
|
|
|
|
/**
|
|
* Free a result envelope returned by any `fff_*` function.
|
|
* **IMPORTANT:** the `handle` payload is NOT freed release it separately
|
|
* using handle specific cleaning methods (`fff_destroy`, `fff_free_search_result`, etc.).
|
|
*
|
|
* ## Safety
|
|
* `result_ptr` must be a valid pointer returned by a `fff_*` function.
|
|
*/
|
|
void fff_free_result(struct FffResult *result_ptr);
|
|
|
|
/**
|
|
* Free a string returned by `fff_*` functions.
|
|
*
|
|
* ## Safety
|
|
* `s` must be a valid C string allocated by this library.
|
|
*/
|
|
void fff_free_string(char *s);
|
|
|
|
/**
|
|
* Free a directory search result returned by `fff_search_directories`.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid pointer previously returned via `FffResult.handle`
|
|
* from `fff_search_directories`, or null (no-op).
|
|
*/
|
|
void fff_free_dir_search_result(struct FffDirSearchResult *result);
|
|
|
|
/**
|
|
* Get a pointer to the `index`-th `FffDirItem` in a directory search result.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffDirSearchResult` pointer from `fff_search_directories`.
|
|
*/
|
|
const struct FffDirItem *fff_dir_search_result_get_item(const struct FffDirSearchResult *result,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Get a pointer to the `index`-th `FffScore` in a directory search result.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffDirSearchResult` pointer from `fff_search_directories`.
|
|
*/
|
|
const struct FffScore *fff_dir_search_result_get_score(const struct FffDirSearchResult *result,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Free a mixed search result returned by `fff_search_mixed`.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid pointer previously returned via `FffResult.handle`
|
|
* from `fff_search_mixed`, or null (no-op).
|
|
*/
|
|
void fff_free_mixed_search_result(struct FffMixedSearchResult *result);
|
|
|
|
/**
|
|
* Get a pointer to the `index`-th `FffMixedItem` in a mixed search result.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffMixedSearchResult` pointer from `fff_search_mixed`.
|
|
*/
|
|
const struct FffMixedItem *fff_mixed_search_result_get_item(const struct FffMixedSearchResult *result,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Get a pointer to the `index`-th `FffScore` in a mixed search result.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffMixedSearchResult` pointer from `fff_search_mixed`.
|
|
*/
|
|
const struct FffScore *fff_mixed_search_result_get_score(const struct FffMixedSearchResult *result,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Returns whether the operation completed successfully. Returns `false` if `result` is null.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffResult` pointer or null.
|
|
*/
|
|
bool fff_result_get_success(const struct FffResult *result);
|
|
|
|
/**
|
|
* Returns the operation error message, or null when there is no error or `result` is null.
|
|
*
|
|
* Do not free the returned pointer. It remains valid until `fff_free_result` is called.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffResult` pointer or null.
|
|
*/
|
|
const char *fff_result_get_error(const struct FffResult *result);
|
|
|
|
/**
|
|
* Returns the result payload handle, or null if `result` is null.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffResult` pointer or null.
|
|
*/
|
|
void *fff_result_get_handle(const struct FffResult *result);
|
|
|
|
/**
|
|
* Returns the result integer payload. Returns `0` if `result` is null.
|
|
*
|
|
* ## Safety
|
|
* `result` must be a valid `FffResult` pointer or null.
|
|
*/
|
|
int64_t fff_result_get_int_value(const struct FffResult *result);
|
|
|
|
/**
|
|
* Relative path of a file item (e.g. `"src/main.rs"`); null if `item` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
const char *fff_file_item_get_relative_path(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* File-name component of a file item (e.g. `"main.rs"`); null if `item` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
const char *fff_file_item_get_file_name(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* Git status string of a file item (e.g. `"M "`, `"??"`); null if git is unavailable,
|
|
* the file is untracked, or `item` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
const char *fff_file_item_get_git_status(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* File size in bytes; `0` if `item` is null.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
uint64_t fff_file_item_get_size(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* Last-modified time as seconds since the UNIX epoch; `0` if `item` is null.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
uint64_t fff_file_item_get_modified(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* Combined frecency score; `0` if `item` is null.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
int64_t fff_file_item_get_total_frecency_score(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* Access-based frecency score; `0` if `item` is null.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
int64_t fff_file_item_get_access_frecency_score(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* Modification-based frecency score; `0` if `item` is null.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
int64_t fff_file_item_get_modification_frecency_score(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* `true` if the file was detected as binary; `false` if `item` is null.
|
|
*
|
|
* ## Safety
|
|
* `item` must be a valid `FffFileItem` pointer or null.
|
|
*/
|
|
bool fff_file_item_get_is_binary(const struct FffFileItem *item);
|
|
|
|
/**
|
|
* Relative path of the file containing this grep match; null if `m` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
const char *fff_grep_match_get_relative_path(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* File-name component of the file containing this grep match; null if `m` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
const char *fff_grep_match_get_file_name(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Git status string of the matched file (e.g. `"M "`, `"??"`); null if git is unavailable,
|
|
* the file is untracked, or `m` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
const char *fff_grep_match_get_git_status(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Full text content of the matched line; null if `m` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
const char *fff_grep_match_get_line_content(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* 1-based line number of the match within its file; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint64_t fff_grep_match_get_line_number(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* 0-based column of the match start within its line; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_match_get_col(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Byte offset of the match start from the beginning of the file; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint64_t fff_grep_match_get_byte_offset(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* File size in bytes of the matched file; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint64_t fff_grep_match_get_size(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Combined frecency score of the matched file; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
int64_t fff_grep_match_get_total_frecency_score(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Access-based frecency score of the matched file; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
int64_t fff_grep_match_get_access_frecency_score(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Modification-based frecency score of the matched file; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
int64_t fff_grep_match_get_modification_frecency_score(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Last-modified time of the matched file as seconds since the UNIX epoch; `0` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint64_t fff_grep_match_get_modified(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Number of highlight ranges in this match; `0` if `m` is null.
|
|
* Use with [`fff_grep_match_get_match_range`] to iterate the highlight spans.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_match_get_match_ranges_count(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Pointer to the `index`-th [`FffMatchRange`] highlight span; null if `m` is null,
|
|
* `index >= match_ranges_count`, or the ranges array is null. Valid until the owning `FffGrepResult` is freed; do not free.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
const struct FffMatchRange *fff_grep_match_get_match_range(const struct FffGrepMatch *m,
|
|
uint32_t index);
|
|
|
|
/**
|
|
* Number of context lines captured before the match; `0` if `m` is null.
|
|
* Use with [`fff_grep_match_get_context_before`] to read each line.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_match_get_context_before_count(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* The `index`-th context line before the match; null if `m` is null,
|
|
* `index >= context_before_count`, or the context array is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
const char *fff_grep_match_get_context_before(const struct FffGrepMatch *m, uint32_t index);
|
|
|
|
/**
|
|
* Number of context lines captured after the match; `0` if `m` is null.
|
|
* Use with [`fff_grep_match_get_context_after`] to read each line.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_match_get_context_after_count(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* The `index`-th context line after the match; null if `m` is null,
|
|
* `index >= context_after_count`, or the context array is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
const char *fff_grep_match_get_context_after(const struct FffGrepMatch *m, uint32_t index);
|
|
|
|
/**
|
|
* Fuzzy match score; `0` if `m` is null or no fuzzy score is present.
|
|
* Always check [`fff_grep_match_get_has_fuzzy_score`] first; `0` is ambiguous without that flag.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
uint16_t fff_grep_match_get_fuzzy_score(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* `true` if this match carries a valid fuzzy score; `false` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
bool fff_grep_match_get_has_fuzzy_score(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* `true` if the match was identified as a symbol definition; `false` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
bool fff_grep_match_get_is_definition(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* `true` if the matched file was detected as binary; `false` if `m` is null.
|
|
*
|
|
* ## Safety
|
|
* `m` must be a valid `FffGrepMatch` pointer or null.
|
|
*/
|
|
bool fff_grep_match_get_is_binary(const struct FffGrepMatch *m);
|
|
|
|
/**
|
|
* Number of items in the result; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffSearchResult` pointer or null.
|
|
*/
|
|
uint32_t fff_search_result_get_count(const struct FffSearchResult *r);
|
|
|
|
/**
|
|
* Total number of files that matched before truncation to the page size; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffSearchResult` pointer or null.
|
|
*/
|
|
uint32_t fff_search_result_get_total_matched(const struct FffSearchResult *r);
|
|
|
|
/**
|
|
* Total number of indexed files considered during search; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffSearchResult` pointer or null.
|
|
*/
|
|
uint32_t fff_search_result_get_total_files(const struct FffSearchResult *r);
|
|
|
|
/**
|
|
* Number of matches in the result; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffGrepResult` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_result_get_count(const struct FffGrepResult *r);
|
|
|
|
/**
|
|
* Total number of matches found across all pages; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffGrepResult` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_result_get_total_matched(const struct FffGrepResult *r);
|
|
|
|
/**
|
|
* Number of files actually opened and searched in this call; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffGrepResult` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_result_get_total_files_searched(const struct FffGrepResult *r);
|
|
|
|
/**
|
|
* Total number of indexed files before any filtering; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffGrepResult` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_result_get_total_files(const struct FffGrepResult *r);
|
|
|
|
/**
|
|
* Number of files eligible for search after path/type filtering; `0` if `r` is null.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffGrepResult` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_result_get_filtered_file_count(const struct FffGrepResult *r);
|
|
|
|
/**
|
|
* File offset for the next page; `0` if all files have been searched or `r` is null.
|
|
* Pass as `file_offset` to a subsequent `fff_live_grep`/`fff_multi_grep` call to continue pagination.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffGrepResult` pointer or null.
|
|
*/
|
|
uint32_t fff_grep_result_get_next_file_offset(const struct FffGrepResult *r);
|
|
|
|
/**
|
|
* Regex compilation error string if the engine fell back to literal matching;
|
|
* null if there was no error or `r` is null. Do not free.
|
|
*
|
|
* ## Safety
|
|
* `r` must be a valid `FffGrepResult` pointer or null.
|
|
*/
|
|
const char *fff_grep_result_get_regex_fallback_error(const struct FffGrepResult *r);
|
|
|
|
/**
|
|
* Register the instance-wide watch callback used by all `fff_watch`
|
|
* subscriptions; call before the first `fff_watch`, calling again replaces it.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `callback` must remain callable until fff_unwatch called
|
|
* `fff_destroy(fff_handle)` returns.
|
|
*/
|
|
struct FffResult *fff_set_watch_callback(void *fff_handle,
|
|
FffWatchCallback callback,
|
|
void *user_data);
|
|
|
|
/**
|
|
* Subscribe to filesystem changes, delivered through the instance callback
|
|
* registered by `fff_set_watch_callback`.
|
|
*
|
|
* Returns the watch id, pass it to `fff_unwatch` to stop.
|
|
*
|
|
* `pattern` if non `NULL` can be wildcard pattern, absolute, or relative path
|
|
* that will be used to filter the events triggering exact subscription.
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `pattern` must be NULL or valid null-terminated UTF-8.
|
|
* * `opts` must be NULL or a valid `FffWatchOptions` pointer.
|
|
*/
|
|
struct FffResult *fff_watch(void *fff_handle,
|
|
const char *pattern,
|
|
const struct FffWatchOptions *opts);
|
|
|
|
/**
|
|
* [`fff_watch`] adapter with flattened options, for FFI libraries that cannot
|
|
* marshal pointer arrays inside structs (e.g. Node's `ffi-rs`).
|
|
*
|
|
* ## Safety
|
|
* * `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
* * `pattern` must be NULL (watch everything) or valid null-terminated UTF-8.
|
|
* * `ignore` must be NULL or point to `ignore_count` valid C strings.
|
|
*/
|
|
struct FffResult *fff_watch_args(void *fff_handle,
|
|
const char *pattern,
|
|
const char *const *ignore,
|
|
uint32_t ignore_count);
|
|
|
|
/**
|
|
* Remove a watch subscription. `int_value` = 1 if the id existed, 0 otherwise.
|
|
*
|
|
* ## Safety
|
|
* `fff_handle` must be a valid instance pointer from `fff_create_instance`.
|
|
*/
|
|
struct FffResult *fff_unwatch(void *fff_handle, uint64_t watch_id);
|
|
|
|
/**
|
|
* Number of events in a batch; 0 if `batch` is null.
|
|
*
|
|
* ## Safety
|
|
* `batch` must be a valid `FffWatchEventBatch` pointer or null.
|
|
*/
|
|
uint32_t fff_watch_events_count(const struct FffWatchEventBatch *batch);
|
|
|
|
/**
|
|
* Absolute path of event `index`, will be null when out of bounds
|
|
*
|
|
* ## Safety
|
|
* `batch` must be a valid `FffWatchEventBatch` pointer or null.
|
|
*/
|
|
const char *fff_watch_events_get_path(const struct FffWatchEventBatch *batch, uint32_t index);
|
|
|
|
/**
|
|
* Kind of event `index` (0 = created, 1 = modified, 2 = removed, 3 = rescan)
|
|
* 3 (rescan aka "re-stat something" kind) returned when OS based buffer
|
|
* has been overflown and some events might be loss. Paths will contain a list of
|
|
* directories that needs to be rescanned to ensure consistency.
|
|
*
|
|
* ## Safety
|
|
* `batch` must be a valid `FffWatchEventBatch` pointer or null.
|
|
*/
|
|
uint8_t fff_watch_events_get_kind(const struct FffWatchEventBatch *batch, uint32_t index);
|
|
|
|
/**
|
|
* Free a watch event batch delivered to the instance callback.
|
|
*
|
|
* ## Safety
|
|
* `batch` must be a pointer produced by this library, or null (no-op).
|
|
*/
|
|
void fff_free_watch_events(struct FffWatchEventBatch *batch);
|
|
|
|
#endif /* FFF_C_H */
|