The VIM-like "doc-walker"
Rover is a tool that simplifies the naviation of large JSON/YAML files (i.e. OpenAPI spec files) by allowing you to load a document and navigate the file by walking through the keys as if they were a file system like Finder in MacOS or Ranger.
curl -O -L https://github.com/jhamill34/rover/releases/download/v0.1.0/rover-v0.1.0-aarch64-apple-darwin.tar.gz
tar xvf rover-v0.1.0-aarch64-apple-darwin.tar.gz
mv rover-v0.1.0-aarch64-apple-darwin/rover <somewhere in your path>curl -O -L https://github.com/jhamill34/rover/releases/download/v0.1.0/rover-v0.1.0-x86_64-apple-darwin.tar.gz
tar xvf rover-v0.1.0-x86_64-apple-darwin.tar.gz
mv rover-v0.1.0-x86_64-apple-darwin/rover <somewhere in your path>Not supported at the moment
At the moment installation requires the Cargo toolchain.
cargo install --path .
In the terminal run the following command to open the file. Currently we support both JSON and YAML files.
rover ./any-file.yaml
This will start at TUI in the Navigation View.
Most of the implementation is based around the concepts of JSON pointers.
This section shows your current JSON path in the document (with a leading # to indicate the root of the document).
Example:
#/components/schemas/CreateProject
In the "Current" pane, keys found at your current location (indicies for a list) are listed out. Only Maps and Lists are rendered in the Current/Previous sections.
In the "Previous" pane, all the siblings of your current location are listed out similar to the "Current" pane.
The Preview pane shows what the document would look like if your current location was the root serialized in the same format as the main document. For example, if you're currently in a YAML file then the preview will be serialized in YAML.
Any information related to an executed command will be shown here (Info, Warnings, Errors, etc.). Most
updates should time out in 2 seconds but you can also manually clear them with <Ctrl-c>.
| Key | Description |
|---|---|
h, <Backspace>, <Left Arrow> |
Move to the previously selected path |
j, <Down Arrow>, <C-n> |
Highlight the next item in the current view, wraps around to the top if the current item is the last in the list |
k, <Up Arrow>, <C-p> |
Highlight the previous item in the current view, wraps around to the bottom if the current item is the top in the list |
l, <Right Arrow>, <Enter> |
Select the currently highlighted item |
g |
Move cursor to the top of the list |
G |
Move cursor to the bottom of the list |
I |
Opens up the Import View |
O |
Opens up the Export View |
/ |
Open the Search View |
<C-q> |
Quit without saving (bypasses warning) |
q, <Esc> |
Quit |
<C-c> |
Clear status (or quit if status is cleared already) |
References can be followed during navigation. Any map that has the key $ref will be treated as a
reference. Selecting this will jump directly to that location in the document.
Reference maps look like the following:
{
"$ref": "#/components/schemas/Project"
}
| Key | Description |
|---|---|
<C-e> |
Edit the currently selected item in default editor |
<C-s> |
Persist changes to the document (currently this wipes out the undo history) |
u |
Undo the last mutating operation |
r |
Redo the last mutating operation |
| Key | Description |
|---|---|
<Shift-J> |
Swaps the currently highlighted item with the next in the current list |
<Shift-K> |
Swaps the currently highlighted item with the previous in the current list |
The "input" section shows your current search query. The default search behavior is a "fuzzy" search based on available JSON pointers like fzf.
A similar syntax used in fzf can be used here as well.
By adding a prefix or suffix to your query you can alter the search behavior. Spaces are treated as a
"logical AND" and pipes (i.e. |) are used to represent "logical OR". Unlike normal boolean logic, to make
search feel more natural OR actually has a higher natural precedence than AND. Prefixing a search query with
! inverts there results and returns any items that don't match that query.
| Token | Match Type | Description |
|---|---|---|
sbtrkt |
fuzzy-match | JSON Pointers that match sbtrkt |
'path |
exact-match | JSON Pointers that contain the substring path |
^#/info |
prefix-match | JSON Pointers that start with #/info |
operationId$ |
exact-match | JSON Pointers that end with operationId |
*description |
deref-match | Dereferences the JSON pointer and matches only if description matches the Object keys of the children or string value of the value |
A good example of using the extended syntax would be editing an OpenAPI spec and finding all paths that have an operationId contain the string list
operationId$ *'list
The "Current Selected" shows the currently selected search result (similar to the current pane in the navigation view)
The "Paths" pane shows the current results of your search query.
Similar to the "Preview" in the "Navigation View", this shows a preview of what the document would look like if the currently selected search result was the root of the document.
| Key | Description |
|---|---|
<Down Arrow>, <C-n> |
Highlight the next item in the current view, wraps around to the top if the current item is the last in the list |
<Up Arrow>, <C-p> |
Highlight the previous item in the current view, wraps around to the bottom if the current item is the top in the list |
<Enter> |
Select the currently highlighted path, navigate to it, and open the Navigation View |
<C-c>, <Esc> |
Move back to the Navigation View |
| Key | Description |
|---|---|
<Enter> |
Attempt to replace the currently selected item with the value in the location specified and navigate back to the Navigation View |
<C-c>, <Esc> |
Move back to the Navigation View |
| Key | Description |
|---|---|
<Enter> |
Attempt to persist the current location in the document to the location specified and navigate back to the Navigation View |
<C-c>, <Esc> |
Move back to the Navigation View |
For diagnostics reasons, a logging file will be created. By default this file will be located at $HOME/rover.log but you can customize this
by setting the environment variable ROVER_HOME
This tool is inspired by VIM navigations and the Ranger file manager tool.