amber

You can customize amber's behavior using a TOML configuration file.

Configuration File Locations

For ambs (search):

• Linux: ~/.config/amber/ambs.toml or /etc/amber/ambs.toml
• macOS: ~/Library/Preferences/com.github.dalance.amber/ambs.toml or /etc/amber/ambs.toml
• Windows: ~/AppData/Roaming/dalance/amber/config/ambs.toml
• Compatibility Note: If ~/.ambs.toml exists, it takes precedence over the OS-specific locations.

For ambr (replace):

• Use ambr.toml located in the same directory as the command.

Configurable Keys

Available entries in the TOML file include:

• regex (bool, default: false)
• column (bool, default: false)
• row (bool, default: false)
• binary (bool, default: false)
• statistics (bool, default: false)
• skipped (bool, default: false)
• interactive (bool, default: true)
• recursive (bool, default: true)
• symlink (bool, default: true)
• color (bool, default: true)
• file (bool, default: true)
• skip_vcs (bool, default: true)
• skip_gitignore (bool, default: true)
• fixed_order (bool, default: true)
• parent_ignore (bool, default: true)
• line_by_match (bool, default: false)

column = true

The ambr command is a high-performance tool for searching and replacing text patterns within files across specified paths. It supports multiple matching engines (QuickSearch, Regex, and TBM), multi-threaded execution, and interactive replacement modes.

Basic Usage:

ambr <KEYWORD> <REPLACEMENT> <PATHS...>

Key Features:

• Search Engines: Use --regex for regular expressions or --tbm for the experimental TBM matcher.
• Input Sources: Use --key-from-file or --rep-from-file to read the search keyword or replacement string from a file instead of command-line arguments.
• Concurrency: Control performance using --max-threads and --size-per-thread (bytes per thread).
• File Handling: Supports recursive directory search (--recursive), following symbolic links (--symlink), and skipping VCS directories (--skip-vcs) or .gitignore files (--skip-gitignore).

ambr "old_text" "new_text" ./src ./tests

The PipelineMatcher<T> struct is used to perform keyword searches across files within a pipeline. You can configure several behaviors to optimize performance or visibility:

• skip_binary: If true, the matcher will attempt to detect and skip binary files. Defaults to true.
• print_skipped: If true, information about skipped binary files is collected and sent via the pipeline.
• print_search: If true, debug messages indicating the start and finish of a search for a specific path are sent.
• binary_check_bytes: The number of leading bytes to inspect to determine if a file is binary. Defaults to 128.
• mmap_bytes: The file size threshold. Files larger than this value will be memory-mapped (mmap) instead of read into a buffer for better performance. Defaults to 1024 * 1024 (1 MiB).

let mut matcher = PipelineMatcher::new(matcher, &keyword);
matcher.skip_binary = false;
matcher.print_search = true;
matcher.mmap_bytes = 2 * 1024 * 1024; // 2 MiB threshold

The PipelineReplacer struct provides several configuration fields to control how replacements are displayed and executed:

Note: keyword and replacement are stored as Vec<u8> (byte vectors).

The ambr tool looks for a configuration file named ambr.toml to set default flags. These settings are merged with command-line arguments, where command-line flags typically override the configuration.

Supported configuration keys (based on DefaultFlags) include:

• regex: Enable regular expression search.
• column: Enable column output format.
• row: Enable row output format.
• binary: Enable binary file search.
• statistics: Enable statistics output.
• skipped: Enable skipped file output.
• interactive: Enable interactive replace mode.
• recursive: Enable recursive directory search.
• symlink: Enable symbolic link follow.
• color: Enable colored output.
• file: Enable filename output.
• skip_vcs: Enable skipping VCS directories (e.g., .git, .hg).
• skip_gitignore: Enable skipping files matched by .gitignore.
• fixed_order: Enable output order guarantee.
• parent_ignore: Enable searching for .*ignore files in parent directories.
• preserve_time: Enable preserving file timestamps.

The ambr command is used for recursive search and replace. It is interactive by default, prompting you for every match found.

Interactive Prompt Options:

• y, Y, Yes: Replace the current match.
• n, N, No: Skip the current match.
• a, A, All: Replace all remaining matches non-interactively.
• q, Q, Quit: Stop the process.

Usage patterns:

• ambr keyword replacement: Search and replace keyword with replacement in the current directory.
• ambr keyword replacement path: Search and replace keyword with replacement in the specified path.

Regex and Captures: If the --regex flag is enabled, you can use regex captures in the replacement string. You can also use the --no-interactive flag to skip prompts entirely.

ambr keyword replacement      // recursively search 'keyword' from the current directory, and replace to 'replacement' interactively.
ambr keyword replacement path // recursively search 'keyword' from 'path', and replace to 'replacement' interactively.

# Example with regex captures:
$ ambr --no-interactive --regex '(aaa) (?<pat>bbb)' '$1 $pat ${1} ${pat}' test.txt