Awesome

Last modified: 2014-04-13 12:00:30 tkych

Version: 0.01.04 (beta)

Quicksearch

Quicksearch is a search-engine-interface for Common Lisp. The goal of Quicksearch is to find the CL library quickly. For example, if you will find the library about json, just type (qs:? 'json) at REPL.

The function quicksearch searches for CL projects in Quicklisp, Cliki, GitHub and BitBucket, then outputs results in REPL. The function ? is abbreviation wrapper for quicksearch.

Depends-on

• bordeaux-threads
• iterate
• alexandria
• anaphora
• cl-ppcre
• drakma
• html-entities
• yason
• flexi-streams
• do-urlencode

Installation

cl-test-grid results:

• http://common-lisp.net/project/cl-test-grid/library/quicksearch.html

Auto:

0. CL-REPL> (ql:quickload :quicksearch)

Manual:

0. SHELL$ git clone https://github.com/tkych/quicksearch.git
1. CL-REPL> (push #p"/path-to-quicksearch/quicksearch/" asdf:*central-registry*)
2. CL-REPL> (ql:quickload :quicksearch) or (asdf:load-system :quicksearch)

Examples

Null result:

CL-REPL> (qs:? "supercalifragilisticexpialidocious") ;<=> (qs:quicksearch "supercalifragilisticexpialidocious")
NIL

• If it raises a threading error, probably your CL system might be not support threads. In this case, please type (qs:config :threading? nil) at REPL, then try it again.
• If search-results is null, then just return NIL.

Simple search:

CL-REPL> (qs:? "crypt") ;<=> (qs:quicksearch "crypt")

SEARCH-RESULTS: "crypt"

 Quicklisp
  crypt

 Cliki
  ARC4
  JARW
  VLM_on_Linux

 GitHub
  cl-crypt
  cl-crypto
  cl-crypto
  cryptography
  cryptoschool
  Cryptopsaras
T

• If search-results is not null, then results are printed and return T.
• Since bitbucket-result is null, it is not printed.

Description:

CL-REPL> (qs:? 'Crypt :d) ;<=> (qs:quicksearch 'Crypt :?description t)

SEARCH-RESULTS: "crypt"
=======================

 Quicklisp
 ---------
  crypt
      http://quickdocs.org/cl-crypt/

 Cliki
 -----
  ARC4
      A Common Lisp implementation of ARC4, a Cryptography code, can be found on
      the
  JARW
      Dr John AR Williams' utilities
  VLM_on_Linux
      Instructions for running the Symbolics VLM virtual machine on Linux

 GitHub
 ------
  cl-crypt
      Common-Lisp implementation of unix crypt function
  cl-crypto
      A common lisp package of ciphers, public-key algorithms, etc.
  cl-crypto
      Pure lisp crypto, written from specs
  cryptography
      implementations of ciphers for cryptography class
  cryptoschool
      Lisp files related to the cryptography class being taught by Ben Warner
  Cryptopsaras
      Reads files generated by Acinonyx.
T

• A symbol (as search-word) is automatically converted into a downcase-string.
• If option :d is on, then the description of the project is printed (QuickDocs-url for Quicklisp-search).
• The function QUICKSEARCH's options are redundant, but explanatory.
• The function ?'s options are not explanatory, but minimum.

URL, Space, Cutoff:

CL-REPL> (qs:? "crypt" :ug 4) ;<=> (qs:quicksearch "crypt"
                              ;                    :?url t :?cut-off 4
                              ;                    :?quicklisp nil :?cliki nil :?bitbucket nil)

SEARCH-RESULTS: "crypt"
=======================

 GitHub
 ------
  cl-crypt
      https://github.com/renard/cl-crypt
  cl-crypto
      https://github.com/bgs100/cl-crypto
  cl-crypto
      https://github.com/billstclair/cl-crypto
  cryptography
      https://github.com/MorganBauer/cryptography
  .......> 2
T

• If option :u is on, then the project's url is printed.
• If option :g is on, then only github-results are printed (also :q - quicklisp, :c - cliki, :b - bitbutcket. these options are addable).
• If cut-off is supplied (above 4), then the number of output results is bellow cut-off (the number (above 2) after .......> is number of remains).
• The order of options is nothing to do with search-result (e.g. :ug 4 <=> 4 :gu <=> :u 4 :g <=> ...).

Config:

CL-REPL> (qs:? 'lisp-koans :du 1) ;<=> (qs:quicksearch 'lisp-koans
                                  ;                    :?description t :?url t :?cut-off 1)

SEARCH-RESULTS: "lisp-koans"
============================

 GitHub
 ------
  lisp-koans
      https://github.com/google/lisp-koans
      Common Lisp Koans is a language learning exercise in the same vein as the
      ruby koans, python koans and others.   It is a port of the prior koans
      with some modifications to highlight lisp-specific features.  Structured
      as ordered groups of broken unit tests, the project guides the learner
      progressively through many Common Lisp language features.
  .......> 4
T

CL-REPL> (qs:config :maximum-columns-of-description 50)
Current maximum columns of description: 50
T

CL-REPL> (qs:? 'lisp-koans :du 1)

SEARCH-RESULTS: "lisp-koans"
============================

 GitHub
 ------
  lisp-koans
      https://github.com/google/lisp-koans
      Common Lisp Koans is a language learning
      exercise in the same vein as the ruby koans,
      python koans and others.   It is a port of
      the prior koans with some modifications to
      highlight lisp-specific features.
      Structured as ordered groups of broken unit
      tests, the project guides the learner
      progressively through many Common Lisp
      language features.
  .......> 4
T

• :maximum-columns-of-description controls in printing description (default is 80).

Reference Manual

[function] QUICKSEARCH search-word &key ?web ?description ?url ?cut-off ?quicklisp ?cliki ?github ?bitbucket

QUICKSEARCH searches for CL projects with search-word in Quicklisp, Cliki, GitHub and BitBucket. search-word must be a string, number or symbol (symbol will be automatically converted into downcase-string).

Keywords:

• If ?web is NIL, it does not search in Cliki, GitHub and BitBucket.
• If ?quicklisp is NIL, it does not search in Quicklisp (also ?cliki, ?github, ?bitbucket).
• At least one search-space must be specified.
• If ?description is T, it displays project's descriptions (QuickDocs-url for Quicklisp-search).
• If ?url is T, it display project's url.
• ?cut-off is the max number of printing repositories each space.

Note:

• ?cut-off controls only printing results, nothing to do with the max number of fetching repositories. see. function CONFIG documentation

• About #\Space in search-word:

  In case search-word contains #\Space, Quicklisp-search is OR-search, whereas Cliki-search, GitHub-, BitBucket- is AND-search.

  e.g. (quicksearch "foo bar") Quicklisp-search for "foo" OR "bar". Cliki-search, GitHub-, BitBucket- for "foo" AND "bar".

[function] ? search-word &rest options

? is abbreviation wrapper for function QUICKSEARCH. search-word must be a string, number or symbol. options must be a non-negative integer (as Cut-Off) and/or some keywords which consists of some Option-Chars.

Examples:

(? "crypt")
<=>
(quicksearch "crypt" :?description nil :?url nil :?cut-off 50
                     :?quicklisp t :?cliki t :?github t :?bitbucket t)

(? "crypt" :du 10)
<=>
(quicksearch "crypt" :?description T :?url T :?cut-off 10
                     :?quicklisp t :?cliki t :?github t :?bitbucket t)

(? "crypt" 20 :g :d)
<=>
(quicksearch "crypt" :?description T :?url nil :?cut-off 20
                     :?quicklisp nil :?cliki nil :?github T :?bitbucket nil)

Options:

• Cut-Off:

  • The max number of printing results (default is 50).

• Option-Chars:

  • d, D -- output Description (or QuickDocs-url for Quicklisp-search)
  • u, U -- output URL
  • q, Q -- search in Quicklisp
  • c, C -- search in Cliki
  • g, G -- search in GitHub
  • b, B -- search in Bitbucket

Note:

• Option-Char is idempotent (e.g. :dd <=> :d).
• The order of Option-Chars is nothing to do with output. (e.g. :du <=> :ud)
• If options contains more than 2 Cut-Offs, only last one is applied.
• The order of options is nothing to do with output (except for some Cut-Offs).
• If no search space is specified, all spaces is specified (e.g. :d <=> :dqcgb)
• If at most one search space is specified, then others are not specified.

[function] CONFIG &key maximum-columns-of-description maximum-number-of-fetching-repositories cache-size clear-cache? threading? quicklisp-verbose?

Function CONFIG customizes printing, fetching or caching.

Keywords:

• :maximum-columns-of-description The value must be a plus integer bigger than 5. If the length of description-string is bigger than this value, then output of description is inserted newline for easy to see. Default value is 80.

• :maximum-number-of-fetching-repositories This value controls the number of fetching repositories. The value must be a plus integer. Increasing this value, the number of fetching repositories increases, but also space & time does. Default value is 50.

• :cache-size The value must be a plus integer. This value is the number of stored previous search-results. Increasing this value, the number of caching results increases, but also space does. Default value is 4.

• :clear-cache? The value must be a boolean. If value is T, then clear all caches.

• :threading? The value must be a boolean (default T). If value is NIL, then QUICKSEARCH becomes not to use threads for searching.

  Note: Currently in SBCL (1.1.8), threads are part of the default build on x86[-64] Linux only. Other platforms (x86[-64] Darwin (Mac OS X), x86[-64] FreeBSD, x86 SunOS (Solaris), and PPC Linux) experimentally supports threads and must be explicitly enabled at build-time. For more details, please see SBCL manual.

• quicklisp-verbose? The value must be a boolean (default NIL). If value is T, then outputs version of quicklisp and whether library had installed your local.

  Example:

     CL-REPL> (qs:config :quicklisp-verbose? T)
     CL-REPL> (qs:? "json" :q)

     SEARCH-RESULTS: "json"

      Quicklisp: 2013-04-20   ;<- quicklisp version
       !cl-json               ;<- if library has installed via quicklisp, print prefix "!".
       !cl-json.test
       com.gigamonkeys.json   ;<- if not, none.
       json-template
       st-json
     T

Note:

If you would prefer permanent config, for example, add codes something like the following in the CL init file.

In .sbclrc for SBCL, ccl-init.lisp for CCL:

(ql:quickload :quicksearch)
(qs:config :maximum-columns-of-description 50
           :maximum-number-of-fetching-repositories 20
           :cache-size 2
           :threading? nil
           :quicklisp-verbose? t)

[special variable] *USER-AGENT*

*user-agent* tells the server who is requested (i.e. User-Agent header value). If you are embedding quicksearch in a larger application, you should change the value of *user-agent* to your application name and URL.

TODO

• ADD search-space: Common-Lisp.net
• ADD search-space: Google code

Author, License, Copyright

• Takaya OCHIAI <#.(reverse "moc.liamg@lper.hcykt")>

• MIT License

• Copyright (C) 2013 Takaya OCHIAI