A semantic search engine for source code https://bitshift.benkurtovic.com/
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

docs.html 13 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290
  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 id="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 id="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> Handwritten Queries</h1>
  130. <p>
  131. No content, yet.
  132. </p>
  133. </li>
  134. <li>
  135. <h1><span>&raquo;</span> API</h1>
  136. <p>
  137. <span class="title">bitshift</span> provides an API through GET
  138. requests to
  139. <a href="http://bitshift.it/search.json"><span class="code">/search.json</span></a>.
  140. </p>
  141. <h2>parameters</h2>
  142. <ul>
  143. <li>
  144. <span class="code">q</span> : The search query, as entered into the
  145. search bar.
  146. </li>
  147. <li>
  148. <span class="code">p</span> : The result page to return. Defaults to
  149. <span class="code">1</span>. Each page contains ten results, so this
  150. effectively offsets the search by
  151. <span class="code">10 * (p - 1)</span> codelets.
  152. </li>
  153. <li>
  154. <span class="code">hl</span> : Whether to return code as
  155. <a href="http://pygments.org/">pygments</a>-highlighted HTML or as
  156. plain source. Defaults to <span class="code">false</span>.
  157. </li>
  158. </ul>
  159. <h2>output</h2>
  160. <p>
  161. <span class="code">/search.json</span> returns a JSON-encoded
  162. dictionary. If there was an error, it will contain a single key,
  163. <span class="code">"error"</span>, whose value will contain a
  164. human-readable description of the error. Otherwise, there will be two
  165. keys: <span class="code">"count"</span>, storing the number of results,
  166. and <span class="code">"results"</span>, storing a list of codelets.
  167. Each codelet is a dictionary with the following key–value pairs:
  168. </p>
  169. <ul>
  170. <li>
  171. <span class="code">name</span> : The name of the codelet.
  172. </li>
  173. <li>
  174. <span class="code">code</span> : The actual source code if
  175. <span class="code">hl</span> was not given or was
  176. <span class="code">false</span>; HTML code otherwise.
  177. </li>
  178. <li>
  179. <span class="code">lang</span> : The language of the code.
  180. </li>
  181. <li>
  182. <span class="code">authors</span> : A list of authors. Each author is
  183. a list of two items: their name, and URL (or
  184. <span class="code">null</span> if none is known).
  185. </li>
  186. <li>
  187. <span class="code">url</span> : The URL of the page where the code
  188. was crawled from.
  189. </li>
  190. <li>
  191. <span class="code">created</span> : The date the code was created, as
  192. 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">modified</span> : The date the code was last
  198. modified, as a
  199. <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>-formatted
  200. string (e.g. <span class="code">"2014-06-01T12:41:28"</span>).
  201. </li>
  202. <li>
  203. <span class="code">origin</span> : A list of two items: the
  204. originating site's name (e.g. <span class="code">"GitHub"</span>) and
  205. URL (e.g. <span class="code">"https://github.com"</span>).
  206. </li>
  207. </ul>
  208. <h2>example</h2>
  209. <p>
  210. The following example Python 2 code searches for a given Python
  211. function definition and prints the URL of the first result:
  212. </p>
  213. <table class="highlighttable">
  214. <tr>
  215. <td class="linenos">
  216. <div class="linenodiv">
  217. <pre> 1
  218. 2
  219. 3
  220. 4
  221. 5
  222. 6
  223. 7
  224. 8
  225. 9
  226. 10
  227. 11
  228. 12
  229. 13
  230. 14
  231. 15
  232. 16
  233. 17
  234. 18
  235. 19</pre>
  236. </div>
  237. </td>
  238. <td class="code">
  239. <div class="highlight">
  240. <pre><span class="c">#!/usr/bin/env python</span>
  241. <span class="kn">from</span> <span class="nn">json</span> <span class="kn">import</span> <span class="n">loads</span>
  242. <span class="kn">from</span> <span class="nn">sys</span> <span class="kn">import</span> <span class="n">argv</span>
  243. <span class="kn">from</span> <span class="nn">urllib</span> <span class="kn">import</span> <span class="n">urlencode</span>
  244. <span class="kn">from</span> <span class="nn">urllib2</span> <span class="kn">import</span> <span class="n">urlopen</span>
  245. <span class="k">def</span> <span class="nf">get_function</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
  246. <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>
  247. <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>
  248. <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>
  249. <span class="k">if</span> <span class="n">res</span><span class="p">:</span>
  250. <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>
  251. <span class="k">else</span><span class="p">:</span>
  252. <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>
  253. <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>
  254. <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>
  255. <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>
  256. </pre>
  257. </div>
  258. </td>
  259. </tr>
  260. </table>
  261. </li>
  262. <li id="sec3">
  263. <h1><span>&raquo;</span> Get Involved</h1>
  264. <p>
  265. <span class="title">bitshift</span> is <span id="gasp">(gasp)</span>
  266. open-source! The project is hosted on
  267. <a href="https://github.com/earwig/bitshift">GitHub</a>; feel free to
  268. file an issue or submit a pull request.
  269. </p>
  270. </li>
  271. </ul>
  272. = endblock