@eagleoutice/flowr-dev/util/files.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import { type PathLike } from 'fs';
import type { RParseRequestFromFile } from '../r-bridge/retriever';
/**
 * Represents a table, identified by a header and a list of rows.
 */
export interface Table {
    header: string[];
    rows: string[][];
}
/**
 * Retrieves all files in the given directory recursively
 * @param dir          - Directory path to start the search from
 * @param suffix       - Suffix of the files to be retrieved
 * @param throwOnError - If `true`, a directory that cannot be read aborts the traversal; otherwise it is logged and skipped (the default)
 * Based on {@link https://stackoverflow.com/a/45130990}
 * @see {@link getAllFilesSync} for a synchronous version.
 */
export declare function getAllFiles(dir: string, suffix?: RegExp, throwOnError?: boolean): AsyncGenerator<string>;
/**
 * Retrieves all files in the given directory recursively (synchronously)
 * @param dir        - Directory path to start the search from
 * @param suffix     - Suffix of the files to be retrieved, tested against the file name
 * @param ignoreDirs - Directories to skip, tested against the posix path relative to `dir`
 *                     (e.g. `packrat/lib`), so a pattern can address nested directories
 * @param relativeTo - The path to which the returned paths are relative (used for `ignoreDirs`), defaults to `dir`
 * @param throwOnError - If `true`, a directory that cannot be read aborts the traversal; otherwise it is logged and skipped (the default)
 * @see {@link getAllFiles} - for an asynchronous version.
 */
export declare function getAllFilesSync(dir: string, suffix?: RegExp, ignoreDirs?: RegExp | undefined, relativeTo?: string, throwOnError?: boolean): Generator<string>;
/**
 * Retrieves all R files in a given directory (asynchronously)
 * @param input - directory-path to start the search from, can be a file as well. Will just return the file then.
 * @param limit - limit the number of files to be retrieved
 * @returns Number of files processed (normally &le; `limit`, is &ge; `limit` if limit was reached).
 *          Will be `1`, if `input` is an R file (and `0` if it isn't).
 * @see getAllFiles
 */
export declare function allRFiles(input: string, limit?: number): AsyncGenerator<RParseRequestFromFile, number>;
/**
 * Retrieves all R files in a given set of directories and files (asynchronously)
 * @param inputs - Files or directories to validate for R-files
 * @param limit  - Limit the number of files to be retrieved
 * @returns Number of files processed (&le; limit)
 * @see allRFiles
 */
export declare function allRFilesFrom(inputs: string[], limit?: number): AsyncGenerator<RParseRequestFromFile, number>;
/**
 * Writes the given table as a CSV file.
 * @param table   - The table to write
 * @param file    - The file path to write the CSV to
 * @param sep     - The separator to use (default: `,`)
 * @param newline - The newline character to use (default: `\n`)
 */
export declare function writeTableAsCsv(table: Table, file: string, sep?: string, newline?: string): void;
/**
 * Reads a file line by line and calls the given function for each line.
 * The `lineNumber` starts at `0`.
 * The `maxLines` option limits the maximum number of read lines and is `Infinity` by default.
 * @returns Whether all lines have been successfully read (`false` if `maxLines` was reached)
 *
 * See {@link readLineByLineSync} for a synchronous version.
 */
export declare function readLineByLine(filePath: string, onLine: (line: Buffer, lineNumber: number) => Promise<void>, maxLines?: number): Promise<boolean>;
/**
 * Reads a file line by line and calls the given function for each line.
 * The `lineNumber` starts at `0`.
 * The `maxLines` option limits the maximum number of read lines and is `Infinity` by default.
 * @returns Whether the file exists and all lines have been successfully read (`false` if `maxLines` was reached)
 *
 * See {@link readLineByLine} for an asynchronous version.
 */
export declare function readLineByLineSync(filePath: string, onLine: (line: Buffer, lineNumber: number) => void, maxLines?: number): boolean;
/**
 * Chops off the last part of the given directory path after a path separator, essentially returning the path's parent directory.
 * If an absolute path is passed, the returned path is also absolute.
 * @param directory - The directory whose parent to return
 */
export declare function getParentDirectory(directory: string): string;
/**
 * A path with backslashes rewritten to forward slashes, i.e. POSIX form. R accepts these on every OS, so this is
 * also how a filesystem path is made safe to interpolate into an R string literal (where a raw `\` would escape).
 */
export declare function toPosixPath(p: string): string;
/**
 * The directory all given paths share, e.g. `/a` for `/a/b.R` and `/a/c/d.R`; `undefined` if they share none.
 */
export declare function commonDirectory(paths: readonly string[]): string | undefined;
/**
 * The path of `filePath` seen from `root` (`s.R` instead of `/tmp/s.R`), or unchanged if it lies outside of `root`.
 */
export declare function relativeTo(root: string, filePath: string): string;
/**
 * Checks whether the given path-like object is a file that exists on the local filesystem.
 */
export declare function isFilePath(p: PathLike): boolean;