» Usage

bitshift is a search-engine optimized for source code: beyond supporting searches with the full range of ASCII symbols, the engine understands code, allowing users to query for metadata, like time of creation/last modification, programming language, and even symbols like function names and variables. Basic use boils down to general and advanced searches.

• general search

  To perform a "general search," simply place your cursor in the search bar on our home page and begin entering text; when you stop typing for a short period of time, we'll automatically execute the query for you. As you scroll down the page, new codelets, or results, will be seamlessly downloaded from our server and appended to the end.

• advanced search

  General searches, though, are limited. To allow users to make the best of our engine, we created an advanced search form that allows the creation of complex queries with the following specifiers:

  • search fields

    • languages : The programming languages to search for.
    • authors : Search for code written/modified by a specific person.
    • date last modified : Search for code last modified on a specific date (mm/dd/yy format).
    • date created : Search for code created on a specific date (mm/dd/yy format).
    • symbols : Search for specific symbols.
    • functions : Search for functions with specific names.
    • classes : Search for classes with specific names.
    • variables : Search for variables with specific names.

    Each of the search fields allows for numerous values; just separate them with spaces. If you'd like to search for a multi-word, space-delimited string, on the other hand, enclose it in double quotes. A query for foo bar will search for occurrences of both "foo" and "bar", while "foo bar" will search for occurrences of "foo bar".

  • search groups

    Search groups facilitate even more robust queries: they're like a bunch of individual searches grouped into one. A user searching for occurrenes of symbol "curses" in the language "Python", and "ncurses" in "C", won't get away with: "symbols:curses ncurses" and "languages:Python C". The engine might return results "curses" in "C" and "ncurses" in "Python"! To work around that, you can use two search groups: one for "curses" in "Python", and another for "curses" in "C". bitshift will return the union of both sets of search results.

» API

bitshift provides an API through GET requests to /search.json.

parameters

• q : The search query, as entered into the search bar.
• p : The result page to return. Defaults to 1. Each page contains ten results, so this effectively offsets the search by 10 * (p - 1) codelets.
• hl : Whether to return code as pygments-highlighted HTML or as plain source. Defaults to false.

output

/search.json returns a JSON-encoded dictionary. If there was an error, it will contain a single key, "error", whose value will contain a human-readable description of the error. Otherwise, there will be two keys: "count", storing the number of results, and "results", storing a list of codelets. Each codelet is a dictionary with the following key–value pairs:

• name : The name of the codelet.
• code : The actual source code if hl was not given or was false; HTML code otherwise.
• lang : The language of the code.
• authors : A list of authors. Each author is a list of two items: their name, and URL (or null if none is known).
• url : The URL of the page where the code was crawled from.
• created : The date the code was created, as a ISO 8601-formatted string (e.g. "2014-06-01T12:41:28").
• modified : The date the code was last modified, as a ISO 8601-formatted string (e.g. "2014-06-01T12:41:28").
• origin : A list of two items: the originating site's name (e.g. "GitHub") and URL (e.g. "https://github.com").

example

The following example Python 2 code searches for a given Python function definition and prints the URL of the first result:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#!/usr/bin/env python

from json import loads
from sys import argv
from urllib import urlencode
from urllib2 import urlopen

def get_function(name):
    params = {"q": "lang:python and func:def:%s" % name}
    request = urlopen("http://bitshift.it/search.json?" + urlencode(params))
    res = loads(request.read())["results"]
    if res:
        print "%s: %s" % (name, res[0]["url"])
    else:
        print "%s not found." % name

if __name__ == "__main__":
    if len(argv) == 2:
        get_function(argv[1])

» Get Involved

bitshift is (gasp) open-source! The project is hosted on GitHub; feel free to file an issue or submit a pull request.