UserManual.md

% EA(1) Version 0.2.1 | EA MANUAL

NAME

ea -- Making paths in CLI output actionable.

SYNOPSIS

ea [options] run style executable [-- argument...]
ea [options] [list]
ea [options] p[rint] [format]

DESCRIPTION

Command-line tools often prints out file paths. Often, we want to follow up with some action on files in these paths, such as viewing, copying, editing, etc. When running these commands through ea, the paths in output will be stored in a local database, and become available for later use.

Use ea run to invoke your command. For example:

ea run grouped rg -- Vec src

... is how you run rg Vec src through ea. Note: any argument for rg comes after --.

grouped hints at the format of rg's output' so that ea knows how to find paths from rg's output. This hint is necessary for ea to work with any many arbitrary commands as possible. See FORMATS to learn more.

You'll see that file locations in the original command are now prefixed with a number:

src/something.rs
[1] 23: let list: Vec
[2] 41: fn build() -> Vec
...

ea list, or simply ea, will print out these locations along with their numbers again:

[1] src/something.rs:23
[2] src/something.rs:41
...

With the numbers, ea can retrieve a corresponding path. In our example, ea print 2 (or ea p 2 in short) results in:

src/something.rs

ea print takes an optional second argument format, making it possible to retrieve the location info mixed in this format string. The sequences {path}, {line}, and {column} appearing in format get replaced by the location info. Running ea p 2 '{path} @ {line}' results in

src/something.rs @ 41

ea print's output is expected to be used as part of a longer command, such as vim $(ea p 2).

It is recommended to create shell aliases or functions for frequently used ea commands.

FORMATS

ea run's first argument style is mandatory. It indicates how file locations will appear in the output. This argument must be one of the following: grouped, linear, search, rust python. This section will explain what each of them means. The command you run through ea should have a matching format value.

grouped indicates the command's output contains one or more sections, each section begins with a file path, and lines of line/column, and possibly more content, follows. An example of this style of output is ripgrep's default output:

src/archive.rs
41: pub fn read() -> Vec {
45: pub fn read_from(path: &Path) -> Vec {

src/interface.rs
53: arguments: Vec,

linear indicates each line in the command's output is a location. A location can be a file path, optionally followed by line, and, optionally, column number separated by ":" (colon). This is the default output from commands such as find or fd:

src/archive.rs:41
src/archive.rs:45
src/interface.rs:53

search means the output is almost arbitrary, except every now and then, an location appears at the beginning of a line. This is common in error messages from compilers like clang or swift:

Sources/Critic/DocProblem.swift:5:26: error: cannot find type 'Stringx' in scope

rust means the format from Rust tools such as rustc, or clippy.

python means Python or iPython's backtrace.

If you need ea to support more formats, please file an issue at https://github.com/dduan/ea

SHELL INTEGRATION

Some shell aliases, and functions makes using ea more effective.

First, you'll want alias your normal command to the ea version:

alias fd 'ea run linear fd --'

Then, optionally, make a shell function that consume a path from ea's output. The following example makes e 6 opens the 6th paths known to ea in your default editor in zsh/bash:

e() {  
    eval $(ea p \$1 "$EDITOR {path}")  
}

For more examples, see documentation at https://github.com/dduan/ea/blob/main/docs/UserManual.md

AUTHOR

Daniel Duan daniel@duan.ca