EA(1)

💅 EA(1) — the EA manual, bestie, and yes it’s giving “paths but actionable” 💅

🌸 NAME 🌸

ea — making paths in CLI output actionable. Like, the paths stop being just text and start being something you can do stuff with, periodt.

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

Command-line tools often print 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 as 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 means 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 means 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, a 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 to alias your normal command to the ea version:

alias fd 'ea run linear fd --'

Then, optionally, make a shell function that consumes a path from ea’s output. The following example makes e 6 open the 6th path 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>

Cute sign-off: this is the EA manual, Version 0.2.1, and there’s no date printed on this footer — bye bestie 💖🎀