csvlens

https://github.com/ys-l/csvlens
Admin
csvlens is a command-line CSV file viewer that provides an interactive interface similar to 'less'...
Tokens:6,747
Snippets:80
Trust Score:9
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install csvlens on OpenBSD

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Use the OpenBSD package manager to install the tool.

```shell
doas pkg_add csvlens
```

--------------------------------

### Install csvlens with Pkgin

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Install csvlens on NetBSD using the pkgin package manager.

```bash
pkgin install csvlens
```

--------------------------------

### Install csvlens with Pkg

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Install csvlens on FreeBSD using the pkg package manager.

```bash
pkg install csvlens
```

--------------------------------

### Install csvlens with Winget

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Install csvlens on Windows using the winget package manager.

```powershell
winget install --id YS-L.csvlens
```

--------------------------------

### Install csvlens with Pacman

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Install csvlens on Arch Linux using the pacman package manager.

```bash
pacman -S csvlens
```

--------------------------------

### Install csvlens with Homebrew

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Install csvlens on macOS using the Homebrew package manager.

```bash
brew install csvlens
```

--------------------------------

### Install csvlens via Cargo

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Install the tool from crates.io or build directly from the local source repository.

```shell
cargo install csvlens
```

```shell
cargo install --path $(pwd)
```

--------------------------------

### Use csvlens as a library

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Basic and advanced usage examples for integrating csvlens into Rust applications.

```rust
use csvlens::run_csvlens;

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

```rust
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);
}
```

--------------------------------

### Select Columns by Regex

Source: https://github.com/ys-l/csvlens/blob/main/README.md

The --columns option allows specifying a regex to select which columns to display by default. Example: 'column1|column2'.

```bash
csvlens file.csv --columns "column1|column2"
```

--------------------------------

### Find and Highlight Matches

Source: https://github.com/ys-l/csvlens/blob/main/README.md

The --find option uses a regex to highlight cells containing matching text. Example: 'value1|value2'.

```bash
csvlens file.csv --find "value1|value2"
```

--------------------------------

### Filter Rows by Regex

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Use the --filter option with a regex to display only rows where at least one cell matches the pattern. Example: 'value1|value2'.

```bash
csvlens file.csv --filter "value1|value2"
```

--------------------------------

### run_csvlens_with_options

Source: https://context7.com/ys-l/csvlens/llms.txt

Launches the csvlens TUI using a CsvlensOptions struct for programmatic configuration.

```APIDOC
## run_csvlens_with_options

### Description
Executes the csvlens TUI using a structured configuration object, allowing for fine-grained control over the viewer's behavior.

### Parameters
- **options** (CsvlensOptions) - Required - A struct containing configuration fields such as filename, delimiter, filtering, and display settings.

### Response
- **Result<Option<String>, Error>** - Returns Ok(Some(value)) on selection, Ok(None) if cancelled, or an Err if the TUI fails to initialize.
```

--------------------------------

### run_csvlens

Source: https://context7.com/ys-l/csvlens/llms.txt

Launches the csvlens TUI using a slice of string arguments, mimicking the CLI interface.

```APIDOC
## run_csvlens

### Description
Executes the csvlens TUI with command-line style arguments. Returns the value of the selected cell if a selection is made.

### Parameters
- **args** (&[&str]) - Required - A slice of strings representing command-line arguments (e.g., ["file.csv", "--delimiter", ","])

### Response
- **Result<Option<String>, Error>** - Returns Ok(Some(value)) on selection, Ok(None) if cancelled, or an Err if the TUI fails to initialize.
```

--------------------------------

### CLI Usage - Display Options

Source: https://context7.com/ys-l/csvlens/llms.txt

Customize the visual appearance and behavior of the viewer.

```APIDOC
## CLI Usage - Display Options

### Description
Customize the visual appearance and behavior of the viewer.

### Options
- `-W` - Enable word wrapping
- `-S` - Enable character wrapping
- `--color-columns` - Color each column differently
- `--prompt [STRING]` - Custom prompt message
- `--echo-column [NAME]` - Echo specific column value on selection
- `--auto-reload` - Auto-reload file on changes
- `--debug` - Show debug statistics
```

--------------------------------

### Csvlens Filtering and Search CLI Options

Source: https://context7.com/ys-l/csvlens/llms.txt

Demonstrates how to filter columns and rows using regex, and find/highlight matches. Combine --columns and --filter for precise data selection.

```bash
# Filter columns using regex (show only matching columns)
csvlens data.csv --columns "name|email|phone"
```

```bash
# Filter rows using regex (show only matching rows)
csvlens data.csv --filter "active|pending"
```

```bash
# Find and highlight matches (without filtering)
csvlens data.csv --find "error"
```

```bash
# Combine column and row filters
csvlens data.csv --columns "status|message" --filter "ERROR"
```

--------------------------------

### Csvlens Display Options CLI

Source: https://context7.com/ys-l/csvlens/llms.txt

Covers CLI options for customizing the viewer's appearance, including word/character wrapping, column coloring, custom prompts, and auto-reloading.

```bash
# Enable word wrapping
csvlens data.csv -W
```

```bash
# Enable character wrapping
csvlens data.csv -S
```

```bash
# Color each column differently
csvlens data.csv --color-columns
```

```bash
# Custom prompt message (supports ANSI codes)
csvlens data.csv --prompt $'
ze1m
ze32mSelect a row!
ze0m'
```

```bash
# Echo specific column value on selection
csvlens data.csv --echo-column "id"
```

```bash
# Auto-reload file on changes
csvlens data.csv --auto-reload
```

```bash
# Show debug statistics
csvlens data.csv --debug
```

--------------------------------

### Run csvlens with CLI arguments

Source: https://context7.com/ys-l/csvlens/llms.txt

Executes the csvlens TUI using a slice of string arguments, mimicking command-line input.

```rust
use csvlens::run_csvlens;

fn main() {
    // Basic usage - open a CSV file
    match run_csvlens(&["/path/to/data.csv"]) {
        Ok(Some(selected_cell)) => println!("Selected: {}", selected_cell),
        Ok(None) => println!("No selection made"),
        Err(e) => eprintln!("Error: {:?}", e),
    }

    // With tab delimiter
    match run_csvlens(&["/path/to/data.tsv", "--delimiter", "\t"]) {
        Ok(Some(selected_cell)) => println!("Selected: {}", selected_cell),
        Ok(None) => {},
        Err(e) => eprintln!("Error: {:?}", e),
    }

    // With multiple options
    match run_csvlens(&[
        "/path/to/data.csv",
        "--ignore-case",
        "--columns", "name|email",
        "--filter", "active"
    ]) {
        Ok(Some(selected_cell)) => println!("Selected: {}", selected_cell),
        Ok(None) => {},
        Err(e) => eprintln!("Error: {:?}", e),
    }
}
```

--------------------------------

### CLI Usage - Basic Commands

Source: https://context7.com/ys-l/csvlens/llms.txt

Basic commands for opening CSV files and specifying delimiters.

```APIDOC
## CLI Usage - Basic Commands

### Description
View a CSV file interactively with navigation, search, and filtering capabilities. Auto-detects delimiter by default.

### Usage
- `csvlens [FILE]` - View a CSV file
- `cat [FILE] | csvlens` - Pipe data from another command
- `-t` - Use explicit tab delimiter
- `-c` - Use explicit comma delimiter
- `-d [DELIMITER]` - Use custom delimiter (or 'auto')
- `--no-headers` - Treat file as having no headers
- `-i` - Enable case-insensitive search
```

--------------------------------

### Csvlens Key Bindings Reference

Source: https://context7.com/ys-l/csvlens/llms.txt

A reference for interactive key bindings in Csvlens for navigation, search, filtering, selection, marking, and output operations.

```text
Navigation:
  hjkl or Arrow Keys    Scroll one row/column
  Ctrl+f / Page Down    Scroll one window down
  Ctrl+b / Page Up      Scroll one window up
  Ctrl+d / d            Scroll half window down
  Ctrl+u / u            Scroll half window up
  Ctrl+h                Scroll one window left
  Ctrl+l                Scroll one window right
  Ctrl+Left             Scroll to first column
  Ctrl+Right            Scroll to last column
  G / End               Go to bottom
  g / Home              Go to top
  <n>G                  Go to line n

Search and Filter:
  /<regex>              Find and highlight matches
  n                     Jump to next match
  N                     Jump to previous match
  &<regex>              Filter rows (show only matches)
  *<regex>              Filter columns (show only matches)
  #                     Find rows like selected cell (Cell mode)
  @                     Filter rows like selected cell (Cell mode)

Selection and Display:
  TAB                   Toggle row/column/cell selection mode
  >                     Increase column width
  <                     Decrease column width
  Shift+Down / J        Sort by selected column
  Ctrl+j                Natural sort (file2 < file10)
  -S                    Toggle line wrapping
  -W                    Toggle word wrapping
  f<n>                  Freeze n columns from left

Marking and Output:
  m                     Mark/unmark selected row
  M                     Clear all marks
  Ctrl+e                Print marked rows to stdout and exit
  y                     Copy selected row/cell to clipboard
  Enter                 Print selected cell to stdout and exit (Cell mode)

Other:
  r                     Reset view (clear filters and custom widths)
  H / ?                 Display help
  q                     Exit
```

--------------------------------

### CLI Usage - Filtering and Search

Source: https://context7.com/ys-l/csvlens/llms.txt

Options for pre-filtering rows and columns, and highlighting matches.

```APIDOC
## CLI Usage - Filtering and Search

### Description
Pre-filter rows and columns, and highlight matches when opening the file.

### Options
- `--columns [REGEX]` - Filter columns using regex
- `--filter [REGEX]` - Filter rows using regex
- `--find [REGEX]` - Find and highlight matches
```

--------------------------------

### Run csvlens with structured options

Source: https://context7.com/ys-l/csvlens/llms.txt

Provides fine-grained control over the csvlens TUI using the CsvlensOptions struct.

```rust
use csvlens::{run_csvlens_with_options, CsvlensOptions, WrapMode};

fn main() {
    // Basic options
    let options = CsvlensOptions {
        filename: Some("/path/to/data.csv".to_string()),
        ..Default::default()
    };

    match run_csvlens_with_options(options) {
        Ok(Some(selected_cell)) => println!("Selected: {}", selected_cell),
        Ok(None) => println!("No selection made"),
        Err(e) => eprintln!("Error: {:?}", e),
    }

    // Advanced configuration
    let options = CsvlensOptions {
        filename: Some("/path/to/data.csv".to_string()),
        delimiter: Some("|".to_string()),
        ignore_case: true,
        no_headers: false,
        columns: Some("name|email|phone".to_string()),
        filter: Some("active".to_string()),
        echo_column: Some("id".to_string()),
        color_columns: true,
        prompt: Some("Select a record:".to_string()),
        wrap_mode: Some(WrapMode::Words),
        auto_reload: true,
        debug: false,
        ..Default::default()
    };

    match run_csvlens_with_options(options) {
        Ok(Some(id)) => println!("Selected record ID: {}", id),
        Ok(None) => println!("Cancelled"),
        Err(e) => eprintln!("Error: {:?}", e),
    }
}
```

--------------------------------

### Basic Csvlens CLI Commands

Source: https://context7.com/ys-l/csvlens/llms.txt

Shows basic commands for viewing CSV files, piping data, and specifying delimiters. Use -t for tab, -c for comma, or -d for custom/auto-detect.

```bash
# View a CSV file
csvlens data.csv
```

```bash
# Pipe data from another command
cat data.csv | csvlens
```

```bash
# Use explicit tab delimiter
csvlens data.tsv -t
```

```bash
# Use explicit comma delimiter
csvlens data.csv -c
```

```bash
# Use custom delimiter
csvlens data.csv -d '|'
```

```bash
# Auto-detect delimiter (default behavior)
csvlens data.csv -d auto
```

```bash
# File without headers
csvlens data.csv --no-headers
```

```bash
# Enable case-insensitive search
csvlens data.csv -i
```

--------------------------------

### Configure csvlens dependency in Cargo.toml

Source: https://context7.com/ys-l/csvlens/llms.txt

Shows various ways to include csvlens as a dependency, including optional feature flags for clipboard support.

```toml
[dependencies]
# Basic library usage (no CLI, with clipboard support)
csvlens = { version = "0.15.1", default-features = false, features = ["clipboard"] }

# Library usage without clipboard
csvlens = { version = "0.15.1", default-features = false }

# Full features (CLI + clipboard) - same as default
csvlens = "0.15.1"

# Available features:
# - "cli": Enables command-line interface (clap dependency)
# - "clipboard": Enables clipboard support (arboard dependency)
# Default features include both "cli" and "clipboard"
```

--------------------------------

### Configure CsvlensOptions struct

Source: https://context7.com/ys-l/csvlens/llms.txt

Defines the full configuration schema for customizing csvlens behavior.

```rust
use csvlens::{CsvlensOptions, WrapMode};

// Complete CsvlensOptions structure with all fields
let options = CsvlensOptions {
    // Input file path (None for stdin)
    filename: Some("/path/to/file.csv".to_string()),

    // Delimiter character or "auto" for auto-detection
    delimiter: Some(",".to_string()),

    // Use tab as delimiter (overrides delimiter if true)
    tab_separated: false,

    // Use comma as delimiter explicitly
    comma_separated: false,

    // Treat first row as data, not headers
    no_headers: false,

    // Regex to filter which columns are displayed
    columns: Some("col1|col2".to_string()),

    // Regex to filter rows
    filter: Some("pattern".to_string()),

    // Regex to find and highlight matches
    find: Some("search_term".to_string()),

    // Case-insensitive search (ignored if pattern has uppercase)
    ignore_case: true,

    // Column name to echo on selection
    echo_column: Some("id".to_string()),

    // Show debug statistics
    debug: false,

    // Number of columns to freeze from left
    freeze_cols_offset: Some(2),

    // Display each column in a different color
    color_columns: true,

    // Custom prompt message (supports ANSI escape codes)
    prompt: Some("\x1b[32mSelect item:\x1b[0m".to_string()),

    // Line wrapping mode
    wrap_mode: Some(WrapMode::Words),

    // Auto-reload file on changes
    auto_reload: true,

    // Disable streaming from stdin
    no_streaming_stdin: false,
};
```

--------------------------------

### Run csvlens with a Filename

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Provide the CSV filename as an argument to csvlens to open and view the file.

```bash
csvlens <filename>
```

--------------------------------

### Custom Prompt with ANSI Colors

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Use the --prompt option to display a custom message in the status bar, supporting ANSI escape codes for styling.

```bash
csvlens Pokemon.csv --prompt $'[1m[32mSelect a Pokémon![0m'
```

--------------------------------

### CsvlensOptions Struct

Source: https://context7.com/ys-l/csvlens/llms.txt

Configuration structure for customizing the csvlens TUI behavior.

```APIDOC
## CsvlensOptions Struct

### Fields
- **filename** (Option<String>) - Optional - Path to the CSV file; if None, reads from stdin.
- **delimiter** (Option<String>) - Optional - Delimiter character or "auto".
- **tab_separated** (bool) - Optional - Forces tab as delimiter.
- **no_headers** (bool) - Optional - If true, treats the first row as data.
- **columns** (Option<String>) - Optional - Regex to filter displayed columns.
- **filter** (Option<String>) - Optional - Regex to filter rows.
- **find** (Option<String>) - Optional - Regex to highlight matches.
- **ignore_case** (bool) - Optional - Enables case-insensitive searching.
- **echo_column** (Option<String>) - Optional - Column name to return upon selection.
- **freeze_cols_offset** (Option<usize>) - Optional - Number of columns to freeze.
- **color_columns** (bool) - Optional - Enables column-specific coloring.
- **prompt** (Option<String>) - Optional - Custom prompt text.
- **wrap_mode** (Option<WrapMode>) - Optional - Line wrapping configuration.
- **auto_reload** (bool) - Optional - Enables automatic file reloading on changes.
```

--------------------------------

### Add csvlens dependency to Cargo.toml

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Include the crate in your project dependencies with specific features enabled.

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

--------------------------------

### Handle CsvlensError types in Rust

Source: https://context7.com/ys-l/csvlens/llms.txt

Demonstrates how to catch and handle specific error variants when running csvlens with custom options.

```rust
use csvlens::{run_csvlens_with_options, CsvlensOptions};
use csvlens::errors::CsvlensError;

fn main() {
    let options = CsvlensOptions {
        filename: Some("/nonexistent/file.csv".to_string()),
        delimiter: Some("::".to_string()),  // Invalid: multiple characters
        echo_column: Some("missing_column".to_string()),
        ..Default::default()
    };

    match run_csvlens_with_options(options) {
        Ok(result) => println!("Result: {:?}", result),
        Err(e) => {
            // Handle specific error types
            match e {
                CsvlensError::FileNotFound(path) => {
                    eprintln!("File not found: {}", path);
                }
                CsvlensError::ColumnNameNotFound(name) => {
                    eprintln!("Echo column not found: {}", name);
                }
                CsvlensError::DelimiterEmpty => {
                    eprintln!("Delimiter cannot be empty");
                }
                CsvlensError::DelimiterNotAscii(c) => {
                    eprintln!("Delimiter must be ASCII: {}", c);
                }
                CsvlensError::DelimiterMultipleCharacters(s) => {
                    eprintln!("Delimiter must be single char: {}", s);
                }
                _ => eprintln!("Error: {}", e),
            }
        }
    }
}
```

--------------------------------

### WrapMode Enum Usage in Rust

Source: https://context7.com/ys-l/csvlens/llms.txt

Demonstrates how to use the WrapMode enum in Rust to control cell content display. Import WrapMode and CsvlensOptions to configure wrapping behavior.

```rust
use csvlens::WrapMode;

// Available wrap modes
let disabled = WrapMode::Disabled;  // No wrapping, truncate long content
let chars = WrapMode::Chars;        // Wrap at character boundaries
let words = WrapMode::Words;        // Wrap at word boundaries (preserves words)

// Use in CsvlensOptions
use csvlens::CsvlensOptions;

let options = CsvlensOptions {
    filename: Some("/path/to/data.csv".to_string()),
    wrap_mode: Some(WrapMode::Words),
    ..Default::default()
};
```

--------------------------------

### Pipe CSV Data to csvlens

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Redirect CSV data from other commands directly into csvlens for viewing.

```bash
<your commands producing some csv data> | csvlens
```

--------------------------------

### Colorize Columns

Source: https://github.com/ys-l/csvlens/blob/main/README.md

The --color-columns or --colorful flag assigns a different color to each column for better visual distinction.

```bash
csvlens file.csv --color-columns
```

--------------------------------

### Use Tab Delimiter

Source: https://github.com/ys-l/csvlens/blob/main/README.md

The -t or --tab-separated flag forces csvlens to use tabs as delimiters, ignoring any -d option.

```bash
csvlens file.tsv -t
```

--------------------------------

### Disable Header Interpretation

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Use the --no-headers flag to prevent csvlens from treating the first row as headers.

```bash
csvlens file.csv --no-headers
```

--------------------------------

### Echo Specific Column on Enter

Source: https://github.com/ys-l/csvlens/blob/main/README.md

The --echo-column option prints the value of the specified column for the selected row to stdout when Enter is pressed, then exits.

```bash
csvlens file.csv --echo-column "column_name"
```

--------------------------------

### Specify Custom Delimiter

Source: https://github.com/ys-l/csvlens/blob/main/README.md

Use the -d option to specify a custom delimiter for parsing CSV files. Supports auto-detection with '-d auto'.

```bash
csvlens file.csv -d '\t'
```

--------------------------------

### Ignore Case in Searches

Source: https://github.com/ys-l/csvlens/blob/main/README.md

The -i or --ignore-case flag makes searches case-insensitive. This flag is ignored if the search string contains uppercase letters.

```bash
csvlens file.csv -i
```
Tokens:
Raw