/* Generated by cbindgen — do not edit manually. */ #ifndef FFF_C_H #define FFF_C_H /* Generated with cbindgen:0.29.2 */ #include #include #include /** * 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 */