DOCSEARCHbyAlgolia
Submit Docs

csvlens

repository·main·Indexed 26 days ago

https://github.com/ys-l/csvlens

A command-line CSV file viewer providing a 'less'-like experience optimized for CSV data. It features filtering, sorting, cell selection, and regex-based searching. Available as a standalone CLI tool (version 0.15.1) or as a Rust library for integration into other projects.

Tokens
8.9K
Snippets
16
Records
64
Agent score
87%

What's inside csvlens

  1. Install csvlens

    main

    You can install csvlens using various package managers depending on your operating system, or via Cargo if you have Rust installed.

    Cargo (Rust)

    Requires Rust 1.88.0 or newer.

    cargo install csvlens

    Or build from source:

    cargo install --path $(pwd)

    macOS (Homebrew)

    brew install csvlens

    Arch Linux

    pacman -S csvlens

    Windows (winget)

    winget install --id YS-L.csvlens

    FreeBSD

    pkg install csvlens

    NetBSD

    pkgin install csvlens

    OpenBSD

    doas pkg_add csvlens
    # Installation

### Cargo
cargo install csvlens

### Homebrew
brew install csvlens

### Arch Linux
pacman -S csvlens

### Windows
winget install --id YS-L.csvlens

### FreeBSD
pkg install csvlens

### NetBSD
pkgin install csvlens

### OpenBSD
doas pkg_add csvlens

  2. Add csvlens as a dependency

    main

    To use csvlens as a library in your Rust project, add it to your Cargo.toml. Note that default-features is set to false by default in the example, and you may need to enable specific features like clipboard depending on your requirements.

    [dependencies]
csvlens = { version = "0.11.0", default-features = false, features = ["clipboard"] }

  4. Integrate csvlens as a Rust library

    main

    You can use csvlens as a library in your Rust projects.

    Add this to your Cargo.toml:

    [dependencies]
csvlens = { version = "0.12.0", default-features = false, features = ["clipboard"] }

    Basic Usage

    Use run_csvlens to run the viewer and optionally retrieve a selected cell value.

    use csvlens::run_csvlens;

let out = run_csvlens(&["/path/to/your.csv"]).unwrap();
if let Some(selected_cell) = out {
    println!("Selected: {}", selected_cell);
}

    Advanced Usage with CsvlensOptions

    Use run_csvlens_with_options to customize behavior like delimiters, case sensitivity, and debugging.

    use csvlens::{run_csvlens_with_options, CsvlensOptions};

let options = CsvlensOptions {
    filename: "/path/to/your.csv".to_string(),
    delimiter: Some("|".to_string()),
    ignore_case: true,
    debug: true,
    ..Default::default()
};
let out = run_csvlens_with_options(options).unwrap();
if let Some(selected_cell) = out {
    println!("Selected: {}", selected_cell);
}
    use csvlens::run_csvlens;

let out = run_csvlens(&["/path/to/your.csv"]).unwrap();
if let Some(selected_cell) = out {
    println!("Selected: {}", selected_cell);
}

  5. Configure CsvConfig and CsvBaseConfig

    main

    To read CSV files with csvlens, you must configure a CsvConfig object. This requires a CsvBaseConfig which defines the fundamental parsing rules like the delimiter and whether the file contains headers.

    CsvBaseConfig parameters:

    • delimiter: A u8 representing the character used to separate fields (e.g., b',' for CSV or b'\t' for TSV).
    • no_headers: A bool indicating if the file lacks a header row.

    CsvConfig parameters:

    • path: The file path to the CSV.
    • stream_active: An optional Arc<AtomicBool> used to enable streaming mode (tailing).
    • base: An instance of CsvBaseConfig.

  6. csvlens Key Bindings

    main

    Use these keyboard shortcuts to navigate and manipulate data within the viewer:

    KeyAction
    hjkl / ← ↓ ↑ →Scroll row/column
    Ctrl + f / Page DownScroll one window down
    Ctrl + b / Page UpScroll one window up
    Ctrl + d / dScroll half a window down
    Ctrl + u / uScroll half a window up
    Ctrl + hScroll one window left
    Ctrl + lScroll one window right
    Ctrl + ←Scroll to first column
    Ctrl + →Scroll to last column
    Ctrl + ePrint marked lines to stdout and exit
    G / EndGo to bottom
    g / HomeGo to top
    <n>GGo to line n
    /<regex>Find and highlight regex matches
    n (in Find mode)Next match
    N (in Find mode)Previous match
    &<regex>Filter rows by regex
    *<regex>Filter columns by regex
    TABToggle selection modes (row, column, cell)
    >Increase column width
    <Decrease column width
    Shift + ↓ / JSort rows by selected column
    Ctrl + jSort rows by natural ordering
    # (in Cell mode)Highlight rows matching selected cell
    @ (in Cell mode)Filter rows matching selected cell
    yCopy selection to clipboard
    Enter (in Cell mode)Print selected cell to stdout and exit
    -SToggle line wrapping
    -WToggle word wrapping
    f<n>Freeze n columns from the left
    mMark/unmark selected row
    MClear all marks
    rReset view (clear filters/widths)
    H / ?Display help
    qExit

  8. Configure csvlens CLI parameters

    main

    Use the following flags to customize how csvlens parses and displays CSV data:

    • -d <char>: Specify a custom delimiter (e.g., -d '\t'). Use -d auto for auto-detection.
    • -t, --tab-separated: Use tab as the delimiter (overrides -d).
    • -i, --ignore-case: Ignore case during searches (ignored if search string contains uppercase).
    • --no-headers: Treat the first row as data instead of headers.
    • --columns <regex>: Default columns to display using a regex (e.g., --columns "column1|column2").
    • --filter <regex>: Default row filter using a regex matched against all cells.
    • --find <regex>: Default search/highlight pattern using a regex matched against all cells.
    • --echo-column <column_name>: Print the value of this specific column to stdout when pressing Enter on a row.
    • --prompt <prompt>: Set a custom status bar message (supports ANSI escape codes).
    • --color-columns or --colorful: Display each column in a unique color.

  9. Use csvlens CLI

    main

    Run csvlens by providing a CSV filename or by piping CSV data directly into it.

    # Open a file
csvlens <filename>

# Pipe data
<command_producing_csv> | csvlens
    csvlens <filename>
<your commands producing some csv data> | csvlens

  10. Navigate search results with `next` and `prev`

    main

    The Finder provides methods to navigate through found entries (headers or rows) using a cursor.

    • next(): Moves the cursor to the next match. If the current match has multiple columns that match, it moves to the next column first, then to the next row.
    • prev(): Moves the cursor to the previous match (previous column, then previous row).
    • current(): Returns the entry at the current cursor position.
    • reset_cursor(): Clears the current cursor position.

  11. Filter columns using regex

    main
    Use set_columns_filter to restrict the visible columns in the table based on a regular expression pattern. If the regex is invalid, it will reset the column filter and display an error message.

  12. Run the application main loop

    main

    Call main_loop to start the interactive terminal session. It handles user input via the InputHandler and manages the application lifecycle, including quitting, selecting rows, and displaying help pages.

    Returns Ok(None) when the user quits, or Ok(Some(String)) if a selection (cell or row) is made.

    pub fn main_loop<B: Backend>(
    &mut self,
    terminal: &mut Terminal<B>,
) -> CsvlensResult<Option<String>>