DXR Query Language Refresh
The upcoming refresh of DXR's query language will make improvements to brevity, memorability, and compactness. This document represents our eventual goal. This will probably land a little at a time.
Entering plain text searches the code and pathnames. Each word is taken as a separate substring to match, and the substrings are and-ed together on a per-line basis.
To exclude lines matching a word, precede the word with "-".
Other, more specific search filters are also available:
- Pathname with shell-style globbing
- fn (or fun or func or function?)
- Definitions or declarations of a function with the given prefix
- Uses of a given function
- (or regex: or regexp: : Regular expression
- Find member functions of a class (or struct?).
- Identifier of any kind (maybe not necessary if we do search ranking better)
- A reference to any kind of identifier
- caller or callers
- Functions that call a given function
- Functions called by a given function
- The definition or declaration of a given type
- Uses of a given type
- Definitions or declarations of a variable
- Uses of a given variable
- Definition or declaration of a namespace
- Uses of a namespace
- namespace-alias or namespace-alias-ref
- Should these merge into the above?
- Definition or declaration of a macro
- Use of a macro
- subclass or sub
- Subclass of a class
- superclass or super
- Superclass of a class
- Compiler warnings?
- More compiler warnings?
Again, query terms are and-ed together and matched against individual lines of the codebase, like grep's single-line mode. This query, for example, finds all the lines from ``.h`` files containing the words "big", "angry", and either "hamster" or "hippo".
path:*.h big angry re:hamster|hippo
You can negate a filter by preceding it with "-":
-path:*.cpp -path:*.c fn:foo
Let's try to standardize with https://code.google.com/p/chromium/codesearch as much as possible.
- `ext:` goes away. It's covered by `-path:*.c`
- `*-decl:` goes away until somebody asks for it. It's merged into `*`.
To Be Determined
- a way to express case-sensitivity. Possibilities include quotes and +.
More Explicit Operators
Some people expect runs of barewords to be treated as phrase matches. Here's how we could do that.
Take any continguous sequence of text: filters to be a single string. Otherwise, AND everything.
For example... ::
three blind mice path:*.c def
…would search for "three blind mice" AND path:*.c AND "def".
You can go back to the old behavior by saying explicitly... ::
three AND blind AND mice
Maybe we could even do… ::
mice IN fn:main
fn:frob IN type:Frobulator
Quoting and Escaping
To do phrase matching or include spaces in a term, use single or double quotes. Doubles can contain singles, and vice versa. You can also backslash-escape them.
"big, bad wolf" 'That "wolf" is a hamster.' 'Don\'t call my wolf a "hamster".' re:"big old|great big" -"not this phrase"
You can use a literal quote without enclosing it in other quotes, as long as it isn't a leading one:
What of backslashes in unquoted strings and preceding things other than quotes?
- In a quoted string, a backslash before a quote of the same type is an escaper. Otherwise, it's a literal backslash.
"one long \"quoted\" string" "literal \backslash" "\\" is backslash-quote"
- Later, we may let backslashes in unquoted strings escape spaces:
one\ long\ string
These rules are akin to common shell syntax and designed so you don't need to plan ahead (or backtrack) when typing a query.
GitHub's issue query language might provide some inspiration.