A semantic search engine for source code https://bitshift.benkurtovic.com/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

docs.html 12 KiB

10 jaren geleden
10 jaren geleden
10 jaren geleden
10 jaren geleden
10 jaren geleden
10 jaren geleden
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282
  1. = extends "layout.html"
  2. = block title
  3. docs
  4. = endblock
  5. = block head
  6. {{ assets.tag("lib/highlight.css") }}
  7. {{ assets.tag("docs.css") }}
  8. = endblock
  9. = block body
  10. <a id="logo" href="/">
  11. <div id="logo">
  12. <span id="logo-bit">bit</span
  13. ><span id="logo-angle">&laquo;</span
  14. ><span id="logo-shift">shift</span>
  15. </div>
  16. </a>
  17. <ul>
  18. <li>
  19. <h1><span>&raquo;</span> Usage</h1>
  20. <p>
  21. <span class="title">bitshift</span> is a search-engine optimized for
  22. source code: beyond supporting searches with the full range of ASCII
  23. symbols, the engine <em>understands</em> code, allowing users to query
  24. for metadata, like time of creation/last modification, programming
  25. language, and even symbols like function names and variables. Basic use
  26. boils down to general and advanced searches.
  27. <ul>
  28. <li>
  29. <h2>general search</h2>
  30. <p>
  31. To perform a "general search," simply place your cursor in the
  32. search bar on our home page and begin entering text; when you
  33. stop typing for a short period of time, we'll automatically
  34. execute the query for you. As you scroll down the page, new
  35. codelets, or results, will be seamlessly downloaded from our
  36. server and appended to the end.
  37. </p>
  38. </li>
  39. <li>
  40. <h2>advanced search</h2>
  41. <p>
  42. General searches, though, are limited. To allow users to make the
  43. best of our engine, we created an advanced search form that
  44. allows the creation of complex queries with the following
  45. specifiers:
  46. <ul>
  47. <li>
  48. <h3>search fields</h3>
  49. <ul id="search-fields">
  50. <li>
  51. <span class="code">languages</span> : The programming
  52. languages to search for.
  53. </li>
  54. <li>
  55. <span class="code">authors</span> : Search for code
  56. written/modified by a specific person.
  57. </li>
  58. <li>
  59. <span class="code">date last modified</span> : Search for
  60. code last modified on a specific date
  61. (<span class="code">mm/dd/yy</span> format).
  62. </li>
  63. <li>
  64. <span class="code">date created</span> : Search for code
  65. created on a specific date
  66. (<span class="code">mm/dd/yy</span> format).
  67. </li>
  68. <li>
  69. <span class="code">symbols</span> : Search for specific
  70. symbols.
  71. </li>
  72. <li>
  73. <span class="code">functions</span> : Search for
  74. functions with specific names.
  75. </li>
  76. <li>
  77. <span class="code">classes</span> : Search for classes
  78. with specific names.
  79. </li>
  80. <li>
  81. <span class="code">variables</span> : Search for
  82. variables with specific names.
  83. </li>
  84. </ul>
  85. <p>
  86. Each of the search fields allows for numerous values; just
  87. separate them with spaces. If you'd like to search for a
  88. multi-word, space-delimited string, on the other hand,
  89. enclose it in double quotes.
  90. A query for <span class="code">foo bar</span> will search
  91. for occurrences of both <span id="string">"foo"</span> and
  92. <span class="string">"bar"</span>, while
  93. <span class="code">"foo bar"</span> will search for
  94. occurrences of <span class="string">"foo bar"</span>.
  95. </p>
  96. </li>
  97. <li>
  98. <h3>search groups</h3>
  99. <p>
  100. Search groups facilitate even more robust queries: they're
  101. like a bunch of individual searches grouped into one. A
  102. user searching for occurrenes of symbol
  103. <span class="string">"curses"</span> in the language
  104. <span class="string">"Python"</span>, and
  105. <span class="string">"ncurses"</span> in
  106. <span id="string">"C"</span>, won't get away with:
  107. <span class="code">"symbols:curses ncurses"</span> and
  108. <span class="code">"languages:Python C"</span>. The engine
  109. might return results <span id="string">"curses"</span> in
  110. <span class="string">"C"</span> and
  111. <span class="string">"ncurses"</span> in
  112. <span class="string">"Python"</span>!
  113. To work around that, you can use two search groups: one for
  114. <span class="string">"curses"</span> in
  115. <span class="string">"Python"</span>, and another for
  116. <span class="string">"curses"</span> in
  117. <span id="string">"C"</span>.
  118. <span class="title">bitshift</span> will return the union
  119. of both sets of search results.
  120. </p>
  121. </li>
  122. </ul>
  123. </p>
  124. </li>
  125. </ul>
  126. </p>
  127. </li>
  128. <li>
  129. <h1><span>&raquo;</span> API</h1>
  130. <p>
  131. <span class="title">bitshift</span> provides an API through GET
  132. requests to
  133. <a href="http://bitshift.it/search.json"><span class="code">/search.json</span></a>.
  134. </p>
  135. <h2>parameters</h2>
  136. <ul>
  137. <li>
  138. <span class="code">q</span> : The search query, as entered into the
  139. search bar.
  140. </li>
  141. <li>
  142. <span class="code">p</span> : The result page to return. Defaults to
  143. <span class="code">1</span>. Each page contains ten results, so this
  144. effectively offsets the search by
  145. <span class="code">10 * (p - 1)</span> codelets.
  146. </li>
  147. <li>
  148. <span class="code">hl</span> : Whether to return code as
  149. <a href="http://pygments.org/">pygments</a>-highlighted HTML or as
  150. plain source. Defaults to <span class="code">false</span>.
  151. </li>
  152. </ul>
  153. <h2>output</h2>
  154. <p>
  155. <span class="code">/search.json</span> returns a JSON-encoded
  156. dictionary. If there was an error, it will contain a single key,
  157. <span class="code">"error"</span>, whose value will contain a
  158. human-readable description of the error. Otherwise, there will be two
  159. keys: <span class="code">"count"</span>, storing the number of results,
  160. and <span class="code">"results"</span>, storing a list of codelets.
  161. Each codelet is a dictionary with the following key–value pairs:
  162. </p>
  163. <ul>
  164. <li>
  165. <span class="code">name</span> : The name of the codelet.
  166. </li>
  167. <li>
  168. <span class="code">code</span> : The actual source code if
  169. <span class="code">hl</span> was not given or was
  170. <span class="code">false</span>; HTML code otherwise.
  171. </li>
  172. <li>
  173. <span class="code">lang</span> : The language of the code.
  174. </li>
  175. <li>
  176. <span class="code">authors</span> : A list of authors. Each author is
  177. a list of two items: their name, and URL (or
  178. <span class="code">null</span> if none is known).
  179. </li>
  180. <li>
  181. <span class="code">url</span> : The URL of the page where the code
  182. was crawled from.
  183. </li>
  184. <li>
  185. <span class="code">created</span> : The date the code was created, as
  186. a
  187. <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>-formatted
  188. string (e.g. <span class="code">"2014-06-01T12:41:28"</span>).
  189. </li>
  190. <li>
  191. <span class="code">modified</span> : The date the code was last
  192. modified, as a
  193. <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>-formatted
  194. string (e.g. <span class="code">"2014-06-01T12:41:28"</span>).
  195. </li>
  196. <li>
  197. <span class="code">origin</span> : A list of two items: the
  198. originating site's name (e.g. <span class="code">"GitHub"</span>) and
  199. URL (e.g. <span class="code">"https://github.com"</span>).
  200. </li>
  201. </ul>
  202. <h2>example</h2>
  203. <p>
  204. The following example Python 2 code searches for a given Python
  205. function definition and prints the URL of the first result:
  206. </p>
  207. <table class="highlighttable code-example">
  208. <tr>
  209. <td class="linenos">
  210. <div class="linenodiv">
  211. <pre> 1
  212. 2
  213. 3
  214. 4
  215. 5
  216. 6
  217. 7
  218. 8
  219. 9
  220. 10
  221. 11
  222. 12
  223. 13
  224. 14
  225. 15
  226. 16
  227. 17
  228. 18
  229. 19</pre>
  230. </div>
  231. </td>
  232. <td class="code">
  233. <div class="highlight">
  234. <pre><span class="c">#!/usr/bin/env python</span>
  235. <span class="kn">from</span> <span class="nn">json</span> <span class="kn">import</span> <span class="n">loads</span>
  236. <span class="kn">from</span> <span class="nn">sys</span> <span class="kn">import</span> <span class="n">argv</span>
  237. <span class="kn">from</span> <span class="nn">urllib</span> <span class="kn">import</span> <span class="n">urlencode</span>
  238. <span class="kn">from</span> <span class="nn">urllib2</span> <span class="kn">import</span> <span class="n">urlopen</span>
  239. <span class="k">def</span> <span class="nf">get_function</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
  240. <span class="n">params</span> <span class="o">=</span> <span class="p">{</span><span class="s">&quot;q&quot;</span><span class="p">:</span> <span class="s">&quot;lang:python and func:def:</span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="n">name</span><span class="p">}</span>
  241. <span class="n">request</span> <span class="o">=</span> <span class="n">urlopen</span><span class="p">(</span><span class="s">&quot;http://bitshift.it/search.json?&quot;</span> <span class="o">+</span> <span class="n">urlencode</span><span class="p">(</span><span class="n">params</span><span class="p">))</span>
  242. <span class="n">res</span> <span class="o">=</span> <span class="n">loads</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">read</span><span class="p">())[</span><span class="s">&quot;results&quot;</span><span class="p">]</span>
  243. <span class="k">if</span> <span class="n">res</span><span class="p">:</span>
  244. <span class="k">print</span> <span class="s">&quot;</span><span class="si">%s</span><span class="s">: </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">res</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s">&quot;url&quot;</span><span class="p">])</span>
  245. <span class="k">else</span><span class="p">:</span>
  246. <span class="k">print</span> <span class="s">&quot;</span><span class="si">%s</span><span class="s"> not found.&quot;</span> <span class="o">%</span> <span class="n">name</span>
  247. <span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&quot;__main__&quot;</span><span class="p">:</span>
  248. <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">argv</span><span class="p">)</span> <span class="o">==</span> <span class="mi">2</span><span class="p">:</span>
  249. <span class="n">get_function</span><span class="p">(</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span></pre>
  250. </div>
  251. </td>
  252. </tr>
  253. </table>
  254. </li>
  255. <li id="sec3">
  256. <h1><span>&raquo;</span> Get Involved</h1>
  257. <p>
  258. <span class="title">bitshift</span> is <span id="gasp">(gasp)</span>
  259. open-source! The project is hosted on
  260. <a href="https://github.com/earwig/bitshift">GitHub</a>; feel free to
  261. file an issue or submit a pull request.
  262. </p>
  263. </li>
  264. </ul>
  265. = endblock