JSON interface
cscope’s line format separates fields with spaces and has no quoting, so a row whose
path holds a control character cannot be carried, and a line’s bytes may be shown
escaped. Add --json to any query or session to get exact output instead. Nothing else
about the query changes: the same rows, in the same order, with the same contexts and
text.
--json cannot be combined with --vim-errors, index builds or --verify.
One-shot queries
Each result is one line containing a JSON array [path, context, line, text]:
$ ripscope --json -dL -f "navigation index.db" -1 greet
["src/café/greet.c","greet",6,"void greet(const char *name)"]
pathis a string. Relative paths are relative to the directory the index was built from, or below-P PATHfor text searches.contextis a string andlinea positive integer.textis a string when the line is valid UTF-8, and otherwise an array of byte values (0 to 255), so nothing is lost. A text search’s line of a CR LF file keeps its carriage return.
An empty standard output with no diagnostic means no matches. Warnings and errors go to standard error. A query that cannot read the index, or whose output fails, exits with status 1. An unusable pattern follows cscope’s one-shot behavior: no rows, a diagnostic on standard error, and status 0. Check both streams; status 0 alone does not establish that the pattern was valid.
Sessions
In a --json session, every line Ripscope writes is one JSON value:
| Frame | Meaning |
|---|---|
{"type":"ready"} | Ready for the next command (at startup and after each command). |
{"type":"result","count":N} | A query’s answer; exactly N row arrays follow. N may be 0. |
{"type":"error","message":"..."} | A request that could not be answered, or an r that did not bring the index up to date: it failed, another process was updating the index, or the index is kept where it cannot be updated. The session continues. |
{"type":"warning","message":"..."} | Something worth knowing about the answer before it, such as a file a text search could not read or a refresh before the query that did not complete. Zero or more follow the response and all its rows, before ready. |
{"type":"rebuilt"} | The r command brought the index up to date (warnings may follow). |
Parse frames as JSON objects; do not rely on key order, and ignore keys you do not know.
$ printf '1greet\nq\n' | ripscope --json -dl -f project.db
{"type":"ready"}
{"type":"result","count":1}
["greet.c","greet",6,"void greet(const char *name)"]
{"type":"ready"}
Commands are the same as in line-format sessions, one line of at
most a field digit and 4096 bytes each. A client should treat a missing ready frame as
a failure.
A JSON session refreshes before a query after a change as a line session
does. A refresh that fails still yields the query’s result
from the last published revision, followed by a warning that its freshness is
unconfirmed. A refresh that succeeds adds no frame. The rebuilt frame belongs only to
explicit r.
Path rules
- Paths may contain spaces and any Unicode characters except NUL.
- Paths are stored as the index build named them (on Windows with
/as the separator), not case-folded. - A path that is not valid UTF-8 (possible on Linux) is written as an array of byte values, as text is.
Editor integration
The Neovim adapter uses the JSON interface directly. Other integrations can launch Ripscope and decode these responses with their language’s JSON support.