READSEEK(1)

NAME
readseek - hashline and structural source read tool

SYNOPSIS
readseek [-h] [-V]

readseek file [--language=language] target

readseek read [--start=line] [--end=line] [--offset=line] [--limit=n] [--language=language] target

readseek map [--language=language] target

readseek symbol [--language=language] target [address]

DESCRIPTION
readseek reads UTF-8 source files and emits JSON for file type detection, line-hash addressed reads, structural source maps, and symbol reads.

A target is a file path. It may include a one-based line number or a 3-character xxHash32 line hash suffix, in the form file:line or file:hash. For symbol, it may also include a symbol address or unqualified symbol name in the form file:symbol.

readseek recognizes common source and project file types, including C, C++, C#, Bash, CSS, Go, HTML, Java, JavaScript, JSON, Just, Make, Meson, PHP, Python, Ruby, Rust, Swift, TypeScript, JSX, and TSX. Unsupported text files can still be detected as unknown.

All command output is JSON.

  Commands

file
    Detect the target file language, binary status, MIME type, and syntax name.

read
    Print the target file range with line numbers, 3-character line hashes, and text.

map Print a structural source map with symbol kind, name, address, start and end lines, and boundary line hashes.

symbol
    Print the source range for a mapped symbol. The symbol can be selected by an address argument, a target symbol suffix, or a target line/hash suffix.

  Options

-h, --help
    Print help and exit.

-V, --version
    Print version and exit.

--language=language
    Override detected language. Accepted values are bash, c, cpp, csharp, css, go, html, java, javascript, json, jsx, just, make, meson, php, python, ruby, rust, swift, typescript, tsx, and unknown. Common aliases include cxx, cplusplus, cs, golang, htm, js, makefile, py, rb, rs, sh, shell, and ts.

--start=line
    First one-based line to include for read.

--end=line
    Last one-based line to include for read.

--offset=line
    Alias for --start.

--limit=n
    Maximum number of lines to include for read.

EXIT STATUS

0   Success.

1   Operational error (missing file, unsupported binary file, malformed input, cache error, or symbol lookup failure).

2   Usage error.

FILES

${XDG_CACHE_HOME:-~/.cache}/readseek/cache.sqlite3
    Source map cache on Linux. The cache location follows the platform cache directory returned by the operating system.

EXAMPLES
Detect a file:
readseek file src/main.rs

Read lines 10 through 20:
readseek read src/main.rs --start 10 --end 20

Read a file around a target line:
readseek read src/main.rs:42 --limit 12

Build a structural map:
readseek map src/main.rs

Read a symbol by target suffix:
readseek symbol src/main.rs:run

Read the symbol containing a line:
readseek symbol src/main.rs:270

BUILDING
See README.md in the source distribution for build instructions.

LICENSE
readseek is licensed under the LGPL-2.1-or-later.

SEE ALSO
cargo(1)