lisp/net/xesam.el

   1 ;;; xesam.el --- Xesam interface to search engines.
   2
   3 ;; Copyright (C) 2008-2012 Free Software Foundation, Inc.
   4
   5 ;; Author: Michael Albinus <michael.albinus@gmx.de>
   6 ;; Keywords: tools, hypermedia
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software: you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation, either version 3 of the License, or
  13 ;; (at your option) any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24
  25 ;; This package provides an interface to Xesam, a D-Bus based "eXtEnsible
  26 ;; Search And Metadata specification".  It has been tested with
  27 ;;
  28 ;; xesam-glib 0.3.4, xesam-tools 0.6.1
  29 ;; beagle 0.3.7, beagle-xesam 0.2
  30 ;; strigi 0.5.11
  31
  32 ;; The precondition for this package is a D-Bus aware Emacs.  This is
  33 ;; configured per default, when Emacs is built on a machine running
  34 ;; D-Bus.  Furthermore, there must be at least one search engine
  35 ;; running, which supports the Xesam interface.  Beagle and strigi have
  36 ;; been tested; tracker, pinot and recoll are also said to support
  37 ;; Xesam.  You can check the existence of such a search engine by
  38 ;;
  39 ;;   (dbus-list-queued-owners :session "org.freedesktop.xesam.searcher")
  40
  41 ;; In order to start a search, you must load xesam.el:
  42 ;;
  43 ;;   (require 'xesam)
  44
  45 ;; xesam.el supports two types of queries, which are explained *very* short:
  46 ;;
  47 ;; * Full text queries.  Just search keys shall be given, like
  48 ;;
  49 ;;     hello world
  50 ;;
  51 ;;   A full text query in xesam.el is restricted to files.
  52 ;;
  53 ;; * Xesam End User Search Language queries.  The Xesam query language
  54 ;;   is described at <http://xesam.org/main/XesamUserSearchLanguage>,
  55 ;;   which must be consulted for the whole features.
  56 ;;
  57 ;;   A query string consists of search keys, collectors, selectors,
  58 ;;   and phrases.  Search keys are words like in a full text query:
  59 ;;
  60 ;;     hello word
  61 ;;
  62 ;;   A selector is a tuple <keyword><relation>.  <keyword> can be any
  63 ;;   predefined Xesam keyword, the most common keywords are "ext"
  64 ;;   (file name extension), "format " (mime type), "tag" (user
  65 ;;   keywords) and "type" (types of items, like "audio", "file",
  66 ;;   "picture", "attachment").  <relation> is a comparison to a value,
  67 ;;   which must be a string (relation ":" or "=") or number (relation
  68 ;;   "<=", ">=", "<", ">"):
  69 ;;
  70 ;;     type:attachment ext=el
  71 ;;
  72 ;;   A collector is one of the items "AND", "and", "&&", "OR", "or",
  73 ;;   "||", or "-".  The default collector on multiple terms is "AND";
  74 ;;   "-" means "AND NOT".
  75 ;;
  76 ;;     albinus -type:file
  77 ;;
  78 ;;   A phrase is a string enclosed in quotes, with appended modifiers
  79 ;;   (single letters).  Examples of modifiers are "c" (case
  80 ;;   sensitive), "C" (case insensitive), "e" (exact match), "r"
  81 ;;   (regular expression):
  82 ;;
  83 ;;     "Hello world"c
  84
  85 ;; You can customize, whether you want to apply a Xesam user query, or
  86 ;; a full text query.  Note, that not every search engine supports
  87 ;; both query types.
  88 ;;
  89 ;;   (setq xesam-query-type 'fulltext-query)
  90 ;;
  91 ;; Another option to be customized is the number of hits to be
  92 ;; presented at once.
  93 ;;
  94 ;;   (setq xesam-hits-per-page 50)
  95
  96 ;; A search can be started by the command
  97 ;;
  98 ;;   M-x xesam-search
  99 ;;
 100 ;; When several search engines are registered, the engine to be used
 101 ;; can be selected via minibuffer completion.  Afterwards, the query
 102 ;; shall be entered in the minibuffer.
 103
 104 ;; Search results are presented in a new buffer.  This buffer has the
 105 ;; major mode `xesam-mode', with the following keybindings:
 106
 107 ;;   SPC        `scroll-up'
 108 ;;   DEL        `scroll-down'
 109 ;;   <          `beginning-of-buffer'
 110 ;;   >          `end-of-buffer'
 111 ;;   q          `quit-window'
 112 ;;   z          `kill-this-buffer'
 113 ;;   g          `revert-buffer'
 114
 115 ;; The search results are represented by widgets.  Navigation commands
 116 ;; are the usual widget navigation commands:
 117
 118 ;;   TAB        `widget-forward'
 119 ;;   <backtab>  `widget-backward'
 120
 121 ;; Applying RET, <down-mouse-1>, or <down-mouse-2> on a URL belonging
 122 ;; to the widget, brings up more details of the search hit.  The way,
 123 ;; how this hit is presented, depends on the type of the hit.  HTML
 124 ;; files are opened via `browse-url'.  Local files are opened in a new
 125 ;; buffer, with highlighted search hits (highlighting can be toggled
 126 ;; by `xesam-minor-mode' in that buffer).
 127
 128 ;;; Code:
 129
 130 ;; D-Bus support in the Emacs core can be disabled with configuration
 131 ;; option "--without-dbus".  Declare used subroutines and variables.
 132 (declare-function dbus-call-method "dbusbind.c")
 133 (declare-function dbus-register-signal "dbusbind.c")
 134
 135 (require 'dbus)
 136
 137 ;; Pacify byte compiler.
 138 (eval-when-compile
 139   (require 'cl))
 140
 141 ;; Widgets are used to highlight the search results.
 142 (require 'widget)
 143 (require 'wid-edit)
 144
 145 ;; `run-at-time' is used in the signal handler.
 146 (require 'timer)
 147
 148 ;; The default search field is "xesam:url".  It must be inspected.
 149 (require 'url)
 150
 151 (defgroup xesam nil
 152   "Xesam compatible interface to search engines."
 153   :group 'extensions
 154   :group 'comm
 155   :version "23.1")
 156
 157 (defcustom xesam-query-type 'user-query
 158   "Xesam query language type."
 159   :group 'xesam
 160   :type '(choice
 161           (const :tag "Xesam user query" user-query)
 162           (const :tag "Xesam fulltext query" fulltext-query)))
 163
 164 (defcustom xesam-hits-per-page 20
 165   "Number of search hits to be displayed in the result buffer."
 166   :group 'xesam
 167   :type 'integer)
 168
 169 (defface xesam-mode-line '((t :inherit mode-line-emphasis))
 170   "Face to highlight mode line."
 171   :group 'xesam)
 172
 173 (defface xesam-highlight '((t :inherit match))
 174   "Face to highlight query entries.
 175 It will be overlaid by `widget-documentation-face', so it shall
 176 be different at least in one face property not set in that face."
 177   :group 'xesam)
 178
 179 (defvar xesam-debug nil
 180   "Insert debug information in the help echo.")
 181
 182 (defconst xesam-service-search "org.freedesktop.xesam.searcher"
 183   "The D-Bus name used to talk to Xesam.")
 184
 185 (defconst xesam-path-search "/org/freedesktop/xesam/searcher/main"
 186   "The D-Bus object path used to talk to Xesam.")
 187
 188 ;; Methods: "NewSession", "SetProperty", "GetProperty",
 189 ;; "CloseSession", "NewSearch", "StartSearch", "GetHitCount",
 190 ;; "GetHits", "GetHitData", "CloseSearch" and "GetState".
 191 ;; Signals: "HitsAdded", "HitsRemoved", "HitsModified", "SearchDone"
 192 ;; and "StateChanged".
 193 (defconst xesam-interface-search "org.freedesktop.xesam.Search"
 194   "The D-Bus Xesam search interface.")
 195
 196 (defconst xesam-all-fields
 197   '("xesam:35mmEquivalent" "xesam:aimContactMedium" "xesam:aperture"
 198     "xesam:aspectRatio" "xesam:attachmentEncoding" "xesam:attendee"
 199     "xesam:audioBitrate" "xesam:audioChannels" "xesam:audioCodec"
 200     "xesam:audioCodecType" "xesam:audioSampleFormat" "xesam:audioSampleRate"
 201     "xesam:author" "xesam:bcc" "xesam:birthDate" "xesam:blogContactURL"
 202     "xesam:cameraManufacturer" "xesam:cameraModel" "xesam:cc" "xesam:ccdWidth"
 203     "xesam:cellPhoneNumber" "xesam:characterCount" "xesam:charset"
 204     "xesam:colorCount" "xesam:colorSpace" "xesam:columnCount" "xesam:comment"
 205     "xesam:commentCharacterCount" "xesam:conflicts" "xesam:contactMedium"
 206     "xesam:contactName" "xesam:contactNick" "xesam:contactPhoto"
 207     "xesam:contactURL" "xesam:contains" "xesam:contenKeyword"
 208     "xesam:contentComment" "xesam:contentCreated" "xesam:contentModified"
 209     "xesam:contentType" "xesam:contributor" "xesam:copyright" "xesam:creator"
 210     "xesam:definesClass" "xesam:definesFunction" "xesam:definesGlobalVariable"
 211     "xesam:deletionTime" "xesam:depends" "xesam:description" "xesam:device"
 212     "xesam:disclaimer" "xesam:documentCategory" "xesam:duration"
 213     "xesam:emailAddress" "xesam:eventEnd" "xesam:eventLocation"
 214     "xesam:eventStart" "xesam:exposureBias" "xesam:exposureProgram"
 215     "xesam:exposureTime" "xesam:faxPhoneNumber" "xesam:fileExtension"
 216     "xesam:fileSystemType" "xesam:flashUsed" "xesam:focalLength"
 217     "xesam:focusDistance" "xesam:formatSubtype" "xesam:frameCount"
 218     "xesam:frameRate" "xesam:freeSpace" "xesam:gender" "xesam:generator"
 219     "xesam:generatorOptions" "xesam:group" "xesam:hash" "xesam:hash"
 220     "xesam:height" "xesam:homeEmailAddress" "xesam:homePhoneNumber"
 221     "xesam:homePostalAddress" "xesam:homepageContactURL"
 222     "xesam:horizontalResolution" "xesam:icqContactMedium" "xesam:id"
 223     "xesam:imContactMedium" "xesam:interests" "xesam:interlaceMode"
 224     "xesam:isEncrypted" "xesam:isImportant" "xesam:isInProgress"
 225     "xesam:isPasswordProtected" "xesam:isRead" "xesam:isoEquivalent"
 226     "xesam:jabberContactMedium" "xesam:keyword" "xesam:language" "xesam:legal"
 227     "xesam:license" "xesam:licenseType" "xesam:lineCount" "xesam:links"
 228     "xesam:mailingPostalAddress" "xesam:maintainer" "xesam:md5Hash"
 229     "xesam:mediaCodec" "xesam:mediaCodecBitrate" "xesam:mediaCodecType"
 230     "xesam:meteringMode" "xesam:mimeType" "xesam:mountPoint"
 231     "xesam:msnContactMedium" "xesam:name" "xesam:occupiedSpace"
 232     "xesam:orientation" "xesam:originalLocation" "xesam:owner"
 233     "xesam:pageCount" "xesam:permissions" "xesam:phoneNumber"
 234     "xesam:physicalAddress" "xesam:pixelFormat" "xesam:primaryRecipient"
 235     "xesam:programmingLanguage" "xesam:rating" "xesam:receptionTime"
 236     "xesam:recipient" "xesam:related" "xesam:remoteUser" "xesam:rowCount"
 237     "xesam:sampleBitDepth" "xesam:sampleFormat" "xesam:secondaryRecipient"
 238     "xesam:sha1Hash" "xesam:size" "xesam:skypeContactMedium"
 239     "xesam:sourceCreated" "xesam:sourceModified" "xesam:storageSize"
 240     "xesam:subject" "xesam:supercedes" "xesam:title" "xesam:to"
 241     "xesam:totalSpace" "xesam:totalUncompressedSize" "xesam:url"
 242     "xesam:usageIntensity" "xesam:userComment" "xesam:userKeyword"
 243     "xesam:uuid" "xesam:version" "xesam:verticalResolution"
 244     "xesam:videoBitrate"
 245     "xesam:videoCodec" "xesam:videoCodecType" "xesam:whiteBalance"
 246     "xesam:width" "xesam:wordCount" "xesam:workEmailAddress"
 247     "xesam:workPhoneNumber" "xesam:workPostalAddress"
 248     "xesam:yahooContactMedium")
 249   "All fields from the Xesam Core Ontology.
 250 This defconst can be used to check for a new search engine, which
 251 fields are supported.")
 252
 253 (defconst xesam-user-query
 254   "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
 255 <request xmlns=\"http://freedesktop.org/standards/xesam/1.0/query\">
 256   <userQuery>
 257     %s
 258   </userQuery>
 259 </request>"
 260   "The Xesam user query XML.")
 261
 262 (defconst xesam-fulltext-query
 263   "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
 264 <request xmlns=\"http://freedesktop.org/standards/xesam/1.0/query\">
 265   <query content=\"xesam:Document\" source=\"xesam:File\">
 266     <fullText>
 267       <string>%s</string>
 268     </fullText>
 269   </query>
 270 </request>"
 271   "The Xesam fulltext query XML.")
 272
 273 (declare-function dbus-get-unique-name "dbusbind.c" (bus))
 274
 275 (defvar xesam-dbus-unique-names
 276   (list (cons :system (dbus-get-unique-name :system))
 277         (cons :session (dbus-get-unique-name :session)))
 278   "The unique names, under which Emacs is registered at D-Bus.")
 279
 280 (defun xesam-dbus-call-method (&rest args)
 281   "Apply a D-Bus method call.
 282 `dbus-call-method' is preferred, because it performs better.
 283 If the target D-Bus service is owned by Emacs, this
 284 is not applicable, and `dbus-call-method-non-blocking' must be
 285 used instead.  ARGS are identical to the argument list of both
 286 functions."
 287   (apply
 288    ;; The first argument is the bus, the second argument the targt service.
 289    (if (string-equal (cdr (assoc (car args) xesam-dbus-unique-names))
 290                      (cadr args))
 291        'dbus-call-method-non-blocking 'dbus-call-method)
 292    args))
 293
 294 (defun xesam-get-property (engine property)
 295   "Return the PROPERTY value of ENGINE."
 296   ;; "GetProperty" returns a variant, so we must use the car.
 297   (car (xesam-dbus-call-method
 298         :session (car engine) xesam-path-search
 299         xesam-interface-search  "GetProperty"
 300         (xesam-get-cached-property engine "session") property)))
 301
 302 (defun xesam-set-property (engine property value)
 303   "Set the PROPERTY of ENGINE to VALUE.
 304 VALUE can be a string, a non-negative integer, a boolean
 305 value (nil or t), or a list of them.  It returns the new value of
 306 PROPERTY in the search engine.  This new value can be different
 307 from VALUE, depending on what the search engine accepts."
 308   ;; "SetProperty" returns a variant, so we must use the car.
 309   (car (xesam-dbus-call-method
 310         :session (car engine) xesam-path-search
 311         xesam-interface-search  "SetProperty"
 312         (xesam-get-cached-property engine "session") property
 313         ;; The value must be a variant.  It can be only a string, an
 314         ;; unsigned int, a boolean, or an array of them.  So we need
 315         ;; no type keyword; we let the type check to the search
 316         ;; engine.
 317         (list :variant value))))
 318
 319 (defvar xesam-minibuffer-vendor-history nil
 320   "Interactive vendor history.")
 321
 322 (defvar xesam-minibuffer-query-history nil
 323   "Interactive query history.")
 324
 325 ;; Pacify byte compiler.
 326 (defvar xesam-vendor nil)
 327 (make-variable-buffer-local 'xesam-vendor)
 328 (put 'xesam-vendor 'permanent-local t)
 329
 330 (defvar xesam-engine nil)
 331 (defvar xesam-search nil)
 332 (defvar xesam-type nil)
 333 (defvar xesam-query nil)
 334 (defvar xesam-xml-string nil)
 335 (defvar xesam-objects nil)
 336 (defvar xesam-current nil)
 337 (defvar xesam-count nil)
 338 (defvar xesam-to nil)
 339 (defvar xesam-notify-function nil)
 340 (defvar xesam-refreshing nil)
 341
 342 \f
 343 ;;; Search engines.
 344
 345 (defvar xesam-search-engines nil
 346   "List of available Xesam search engines.
 347 Every entry is an association list, with a car denoting the
 348 unique D-Bus service name of the engine.  The rest of the entry
 349 are cached associations of engine attributes, like the session
 350 identifier, and the display name.  Example:
 351
 352   \(\(\":1.59\"
 353     \(\"session\" . \"0t1214948020ut358230u0p2698r3912347765k3213849828\")
 354     \(\"vendor.display\" . \"Tracker Xesam Service\"))
 355    \(\":1.27\"
 356     \(\"session\" . \"strigisession1369133069\")
 357     \(\"vendor.display\" . \"Strigi Desktop Search\")))
 358
 359 A Xesam-compatible search engine is identified as a queued D-Bus
 360 service of the known service `xesam-service-search'.")
 361
 362 (defun xesam-get-cached-property (engine property)
 363   "Return the PROPERTY value of ENGINE from the cache.
 364 If PROPERTY is not existing, retrieve it from ENGINE first."
 365   ;; If the property has not been cached yet, we retrieve it from the
 366   ;; engine, and cache it.
 367   (unless (assoc property engine)
 368     (xesam-set-cached-property
 369      engine property (xesam-get-property engine property)))
 370   (cdr (assoc property engine)))
 371
 372 (defun xesam-set-cached-property (engine property value)
 373   "Set the PROPERTY of ENGINE to VALUE in the cache."
 374   (setcdr engine (append (cdr engine) (list (cons property value)))))
 375
 376 (defun xesam-delete-search-engine (&rest args)
 377   "Remove service from `xesam-search-engines'."
 378   (setq xesam-search-engines
 379         (delete (assoc (car args) xesam-search-engines) xesam-search-engines)))
 380
 381 (defvar dbus-debug)
 382
 383 (defun xesam-search-engines ()
 384   "Return Xesam search engines, stored in `xesam-search-engines'.
 385 The first search engine is the name owner of `xesam-service-search'.
 386 If there is no registered search engine at all, the function returns `nil'."
 387   (let ((services (dbus-ignore-errors
 388                     (dbus-list-queued-owners
 389                      :session xesam-service-search)))
 390         engine vendor-id hit-fields)
 391     (dolist (service services)
 392       (unless (assoc-string service xesam-search-engines)
 393
 394         ;; Open a new session, and add it to the search engines list.
 395         (add-to-list 'xesam-search-engines (list service) 'append)
 396         (setq engine (assoc service xesam-search-engines))
 397
 398         ;; Add the session string.
 399         (xesam-set-cached-property
 400          engine "session"
 401          (xesam-dbus-call-method
 402           :session service xesam-path-search
 403           xesam-interface-search "NewSession"))
 404
 405         ;; Unset the "search.live" property; we don't want to be
 406         ;; informed by changed results.
 407         (xesam-set-property engine "search.live" nil)
 408
 409         ;; Check the vendor properties.
 410         (setq vendor-id (xesam-get-property engine "vendor.id")
 411               hit-fields (xesam-get-property engine "hit.fields"))
 412
 413         ;; Usually, `hit.fields' shall describe supported fields.
 414         ;; That is not the case now, so we set it ourselves.
 415         ;; Hopefully, this will change later.
 416         (setq hit-fields
 417               (case (intern vendor-id)
 418                 (Beagle
 419                  '("xesam:mimeType" "xesam:url"))
 420                 (Strigi
 421                  '("xesam:author" "xesam:cc" "xesam:charset"
 422                    "xesam:contentType" "xesam:fileExtension"
 423                    "xesam:id" "xesam:lineCount" "xesam:links"
 424                    "xesam:mimeType" "xesam:name" "xesam:size"
 425                    "xesam:sourceModified" "xesam:subject" "xesam:to"
 426                    "xesam:url"))
 427                 (TrackerXesamSession
 428                  '("xesam:relevancyRating" "xesam:url"))
 429                 (Debbugs
 430                  '("xesam:keyword" "xesam:owner" "xesam:title"
 431                    "xesam:url" "xesam:sourceModified" "xesam:mimeType"
 432                    "debbugs:key"))
 433                 ;; xesam-tools yahoo service.
 434                 (t '("xesam:contentModified" "xesam:mimeType" "xesam:summary"
 435                      "xesam:title" "xesam:url" "yahoo:displayUrl"))))
 436
 437         (xesam-set-property engine "hit.fields" hit-fields)
 438         (xesam-set-property engine "hit.fields.extended" '("xesam:snippet"))
 439
 440         ;; Let us notify, when the search engine disappears.
 441         (dbus-register-signal
 442          :session dbus-service-dbus dbus-path-dbus
 443          dbus-interface-dbus "NameOwnerChanged"
 444          'xesam-delete-search-engine service))))
 445   xesam-search-engines)
 446
 447 \f
 448 ;;; Search buffers.
 449
 450 (defvar xesam-mode-map
 451   (let ((map (copy-keymap special-mode-map)))
 452     (set-keymap-parent xesam-mode-map widget-keymap)
 453     map))
 454
 455 (define-derived-mode xesam-mode special-mode "Xesam"
 456   "Major mode for presenting search results of a Xesam search.
 457 In this mode, widgets represent the search results.
 458
 459 \\{xesam-mode-map}
 460 Turning on Xesam mode runs the normal hook `xesam-mode-hook'.  It
 461 can be used to set `xesam-notify-function', which must a search
 462 engine specific, widget :notify function to visualize xesam:url."
 463   (set (make-local-variable 'xesam-notify-function) nil)
 464   ;; Maybe we implement something useful, later on.
 465   (set (make-local-variable 'revert-buffer-function) 'ignore)
 466   ;; `xesam-engine', `xesam-search', `xesam-type', `xesam-query', and
 467   ;; `xesam-xml-string' will be set in `xesam-new-search'.
 468   (set (make-local-variable 'xesam-engine) nil)
 469   (set (make-local-variable 'xesam-search) nil)
 470   (set (make-local-variable 'xesam-type) "")
 471   (set (make-local-variable 'xesam-query) "")
 472   (set (make-local-variable 'xesam-xml-string) "")
 473   (set (make-local-variable 'xesam-objects) nil)
 474   ;; `xesam-current' is the last hit put into the search buffer,
 475   (set (make-local-variable 'xesam-current) 0)
 476   ;; `xesam-count' is the number of hits reported by the search engine.
 477   (set (make-local-variable 'xesam-count) 0)
 478   ;; `xesam-to' is the upper hit number to be presented.
 479   (set (make-local-variable 'xesam-to) xesam-hits-per-page)
 480   ;; `xesam-notify-function' can be a search engine specific function
 481   ;; to visualize xesam:url.  It can be overwritten in `xesam-mode'.
 482   (set (make-local-variable 'xesam-notify-function) nil)
 483   ;; `xesam-refreshing' is an indicator, whether the buffer is just
 484   ;; being updated.  Needed, because `xesam-refresh-search-buffer'
 485   ;; can be triggered by an event.
 486   (set (make-local-variable 'xesam-refreshing) nil)
 487   ;; Mode line position returns hit counters.
 488   (set (make-local-variable 'mode-line-position)
 489        (list '(-3 "%p%")
 490              '(10 (:eval (format " (%d/%d)" xesam-current xesam-count)))))
 491   ;; Header line contains the query string.
 492   (set (make-local-variable 'header-line-format)
 493        (list '(20
 494                (:eval
 495                 (list "Type: "
 496                       (propertize xesam-type 'face 'xesam-mode-line))))
 497              '(10
 498                (:eval
 499                 (list " Query: "
 500                       (propertize
 501                        xesam-query
 502                        'face 'xesam-mode-line
 503                        'help-echo (when xesam-debug xesam-xml-string)))))))
 504
 505   (when (not (called-interactively-p 'interactive))
 506     ;; Initialize buffer.
 507     (setq buffer-read-only t)
 508     (let ((inhibit-read-only t))
 509       (erase-buffer))))
 510
 511 ;; It doesn't make sense to call it interactively.
 512 (put 'xesam-mode 'disabled t)
 513
 514 ;; The very first buffer created with `xesam-mode' does not have the
 515 ;; keymap etc.  So we create a dummy buffer.  Stupid.
 516 (with-temp-buffer (xesam-mode))
 517
 518 (define-minor-mode xesam-minor-mode
 519   "Toggle Xesam minor mode.
 520 With a prefix argument ARG, enable Xesam minor mode if ARG is
 521 positive, and disable it otherwise.  If called from Lisp, enable
 522 the mode if ARG is omitted or nil.
 523
 524 When Xesam minor mode is enabled, all text which matches a
 525 previous Xesam query in this buffer is highlighted."
 526   :group 'xesam
 527   :init-value nil
 528   :lighter " Xesam"
 529   (when (local-variable-p 'xesam-query)
 530     ;; Run only if the buffer is related to a Xesam search.
 531     (save-excursion
 532       (if xesam-minor-mode
 533           ;; Highlight hits.
 534           (let ((query-regexp (regexp-opt (split-string xesam-query nil t) t))
 535                 (case-fold-search t))
 536             ;; I have no idea whether people will like setting
 537             ;; `isearch-case-fold-search' and `query-regexp'.  Maybe
 538             ;; this shall be controlled by a custom option.
 539             (unless isearch-case-fold-search (isearch-toggle-case-fold))
 540             (isearch-update-ring query-regexp t)
 541             ;; Create overlays.
 542             (goto-char (point-min))
 543             (while (re-search-forward query-regexp nil t)
 544               (overlay-put
 545                (make-overlay
 546                 (match-beginning 0) (match-end 0)) 'face 'xesam-highlight)))
 547         ;; Remove overlays.
 548         (dolist (ov (overlays-in (point-min) (point-max)))
 549           (delete-overlay ov))))))
 550
 551 (defun xesam-buffer-name (service search)
 552   "Return the buffer name where to present search results.
 553 SERVICE is the D-Bus unique service name of the Xesam search engine.
 554 SEARCH is the search identification in that engine.  Both must be strings."
 555   (format "*%s/%s*" service search))
 556
 557 (defun xesam-highlight-string (string)
 558   "Highlight text enclosed by <b> and </b>.
 559 Return propertized STRING."
 560   (while (string-match "\\(.*\\)\\(<b>\\)\\(.*\\)\\(</b>\\)\\(.*\\)" string)
 561     (setq string
 562           (format
 563            "%s%s%s"
 564            (match-string 1 string)
 565            (propertize (match-string 3 string) 'face 'xesam-highlight)
 566            (match-string 5 string))))
 567   string)
 568
 569 (defun xesam-refresh-entry (engine entry)
 570   "Refreshes one entry in the search buffer."
 571   (let* ((result (nth (1- xesam-current) xesam-objects))
 572          widget)
 573
 574     ;; Create widget.
 575     (setq widget (widget-convert 'link))
 576     (when xesam-debug
 577       (widget-put widget :help-echo ""))
 578
 579     ;; Take all results.
 580     (dolist (field (xesam-get-cached-property engine "hit.fields"))
 581       (when (cond
 582              ((stringp (caar result)) (not (zerop (length (caar result)))))
 583              ((numberp (caar result)) (not (zerop (caar result))))
 584              ((caar result) t))
 585         (when xesam-debug
 586           (widget-put
 587            widget :help-echo
 588            (format "%s%s: %s\n"
 589                    (widget-get widget :help-echo) field (caar result))))
 590         (widget-put widget (intern (concat ":" field)) (caar result)))
 591       (setq result (cdr result)))
 592
 593     ;; Strigi doesn't return URLs in xesam:url.  We must fix this.
 594     (when
 595         (not (url-type (url-generic-parse-url (widget-get widget :xesam:url))))
 596       (widget-put
 597        widget :xesam:url (concat "file://" (widget-get widget :xesam:url))))
 598
 599     ;; Strigi returns xesam:size as string.  We must fix this.
 600     (when (and (widget-member widget :xesam:size)
 601                (stringp (widget-get widget :xesam:size)))
 602       (widget-put
 603        widget :xesam:size (string-to-number (widget-get widget :xesam:url))))
 604
 605     ;; First line: :tag.
 606     (cond
 607      ((widget-member widget :xesam:title)
 608       (widget-put widget :tag (widget-get widget :xesam:title)))
 609      ((widget-member widget :xesam:subject)
 610       (widget-put widget :tag (widget-get widget :xesam:subject)))
 611      ((widget-member widget :xesam:mimeType)
 612       (widget-put widget :tag (widget-get widget :xesam:mimeType)))
 613      ((widget-member widget :xesam:name)
 614       (widget-put widget :tag (widget-get widget :xesam:name))))
 615
 616     ;; Highlight the search items.
 617     (when (widget-member widget :tag)
 618       (widget-put
 619        widget :tag (xesam-highlight-string (widget-get widget :tag))))
 620
 621     ;; Last Modified.
 622     (when (and (widget-member widget :xesam:sourceModified)
 623                (not
 624                 (zerop
 625                  (string-to-number (widget-get widget :xesam:sourceModified)))))
 626       (widget-put
 627        widget :tag
 628        (format
 629         "%s\nLast Modified: %s"
 630         (or (widget-get widget :tag) "")
 631         (format-time-string
 632          "%d %B %Y, %T"
 633          (seconds-to-time
 634           (string-to-number (widget-get widget :xesam:sourceModified)))))))
 635
 636     ;; Second line: :value.
 637     (widget-put widget :value (widget-get widget :xesam:url))
 638
 639     (cond
 640      ;; A search engine can set `xesam-notify-function' via
 641      ;; `xesam-mode-hooks'.
 642      (xesam-notify-function
 643       (widget-put widget :notify xesam-notify-function))
 644
 645      ;; In case of HTML, we use a URL link.
 646      ((and (widget-member widget :xesam:mimeType)
 647            (string-equal "text/html" (widget-get widget :xesam:mimeType)))
 648       (setcar widget 'url-link))
 649
 650      ;; For local files, we will open the file as default action.
 651      ((string-match "file"
 652                     (url-type (url-generic-parse-url
 653                                (widget-get widget :xesam:url))))
 654       (widget-put
 655        widget :notify
 656        (lambda (widget &rest ignore)
 657          (let ((query xesam-query))
 658            (find-file
 659             (url-filename (url-generic-parse-url (widget-value widget))))
 660            (set (make-local-variable 'xesam-query) query)
 661            (xesam-minor-mode 1))))
 662       (widget-put
 663        widget :value
 664        (url-filename (url-generic-parse-url (widget-get widget :xesam:url))))))
 665
 666     ;; Third line: :doc.
 667     (cond
 668      ((widget-member widget :xesam:summary)
 669       (widget-put widget :doc (widget-get widget :xesam:summary)))
 670      ((widget-member widget :xesam:snippet)
 671       (widget-put widget :doc (widget-get widget :xesam:snippet))))
 672
 673     (when (widget-member widget :doc)
 674       (with-temp-buffer
 675         (insert
 676          (xesam-highlight-string (widget-get widget :doc)))
 677         (fill-region-as-paragraph (point-min) (point-max))
 678         (widget-put widget :doc (buffer-string)))
 679       (widget-put widget :help-echo (widget-get widget :doc)))
 680
 681     ;; Format the widget.
 682     (widget-put
 683      widget :format
 684      (format "%d. %s%%[%%v%%]\n%s\n" xesam-current
 685              (if (widget-member widget :tag) "%{%t%}\n" "")
 686              (if (widget-member widget :doc) "%h" "")))
 687
 688     ;; Write widget.
 689     (goto-char (point-max))
 690     (widget-default-create widget)
 691     (set-buffer-modified-p nil)
 692     (force-mode-line-update)
 693     (redisplay)))
 694
 695 (defun xesam-get-hits (engine search hits)
 696   "Retrieve hits from ENGINE."
 697   (with-current-buffer (xesam-buffer-name (car engine) search)
 698     (setq xesam-objects
 699           (append xesam-objects
 700                   (xesam-dbus-call-method
 701                    :session (car engine) xesam-path-search
 702                    xesam-interface-search "GetHits" search hits)))))
 703
 704 (defun xesam-refresh-search-buffer (engine search)
 705   "Refreshes the buffer, presenting results of SEARCH."
 706   (with-current-buffer (xesam-buffer-name (car engine) search)
 707     ;; Work only if nobody else is here.
 708     (unless (or xesam-refreshing (>= xesam-current xesam-to))
 709       (setq xesam-refreshing t)
 710       (unwind-protect
 711           (let (widget)
 712
 713             ;; Retrieve needed hits for visualization.
 714             (while (> (min xesam-to xesam-count) (length xesam-objects))
 715               (xesam-get-hits
 716                engine search
 717                (min xesam-hits-per-page
 718                     (- (min xesam-to xesam-count) (length xesam-objects)))))
 719
 720             ;; Add all result widgets.
 721             (while (< xesam-current (min xesam-to xesam-count))
 722               (setq xesam-current (1+ xesam-current))
 723               (xesam-refresh-entry engine search))
 724
 725             ;; Add "NEXT" widget.
 726             (when (> xesam-count xesam-to)
 727               (goto-char (point-max))
 728               (widget-create
 729                'link
 730                :notify
 731                (lambda (widget &rest ignore)
 732                  (setq xesam-to (+ xesam-to xesam-hits-per-page))
 733                  (widget-delete widget)
 734                  (xesam-refresh-search-buffer xesam-engine xesam-search))
 735                "NEXT")
 736               (widget-beginning-of-line))
 737
 738             ;; Prefetch next hits.
 739             (when (> (min (+ xesam-hits-per-page xesam-to) xesam-count)
 740                      (length xesam-objects))
 741               (xesam-get-hits
 742                engine search
 743                (min xesam-hits-per-page
 744                     (- (min (+ xesam-hits-per-page xesam-to) xesam-count)
 745                        (length xesam-objects)))))
 746
 747             ;; Add "DONE" widget.
 748             (when (= xesam-current xesam-count)
 749               (goto-char (point-max))
 750               (widget-create 'link :notify 'ignore "DONE")
 751               (widget-beginning-of-line)))
 752
 753         ;; Return with save settings.
 754         (setq xesam-refreshing nil)))))
 755
 756 \f
 757 ;;; Search functions.
 758
 759 (defun xesam-signal-handler (&rest args)
 760   "Handles the different D-Bus signals of a Xesam search."
 761   (let* ((service (dbus-event-service-name last-input-event))
 762          (member (dbus-event-member-name last-input-event))
 763          (search (nth 0 args))
 764          (buffer (xesam-buffer-name service search)))
 765
 766     (when (get-buffer buffer)
 767       (with-current-buffer buffer
 768         (cond
 769
 770          ((string-equal member "HitsAdded")
 771           (setq xesam-count (+ xesam-count (nth 1 args)))
 772           ;; We use `run-at-time' in order to not block the event queue.
 773           (run-at-time
 774            0 nil
 775            'xesam-refresh-search-buffer
 776            (assoc service xesam-search-engines) search))
 777
 778          ((string-equal member "SearchDone")
 779           (setq mode-line-process
 780                 (propertize " Done" 'face 'xesam-mode-line))
 781           (force-mode-line-update)))))))
 782
 783 (defun xesam-kill-buffer-function ()
 784   "Send the CloseSearch indication."
 785   (when (and (eq major-mode 'xesam-mode) (stringp xesam-search))
 786     (ignore-errors ;; The D-Bus service could have disappeared.
 787       (xesam-dbus-call-method
 788        :session (car xesam-engine) xesam-path-search
 789        xesam-interface-search "CloseSearch" xesam-search))))
 790
 791 (defun xesam-new-search (engine type query)
 792   "Create a new search session.
 793 ENGINE identifies the search engine.  TYPE is the query type, it
 794 can be either `fulltext-query', or `user-query'.  QUERY is a
 795 string in the Xesam query language.  A string, identifying the
 796 search, is returned."
 797   (let* ((service (car engine))
 798          (session (xesam-get-cached-property engine "session"))
 799          (xml-string
 800           (format
 801            (if (eq type 'user-query) xesam-user-query xesam-fulltext-query)
 802            (url-insert-entities-in-string query)))
 803          (search (xesam-dbus-call-method
 804                   :session service xesam-path-search
 805                   xesam-interface-search "NewSearch" session xml-string)))
 806
 807     ;; Let us notify for relevant signals.  We ignore "HitsRemoved",
 808     ;; "HitsModified" and "StateChanged"; there is nothing to do for
 809     ;; us.
 810     (dbus-register-signal
 811      :session service xesam-path-search
 812      xesam-interface-search "HitsAdded"
 813      'xesam-signal-handler search)
 814     (dbus-register-signal
 815      :session service xesam-path-search
 816      xesam-interface-search "SearchDone"
 817      'xesam-signal-handler search)
 818
 819     ;; Create the search buffer.
 820     (with-current-buffer
 821         (generate-new-buffer (xesam-buffer-name service search))
 822       (switch-to-buffer-other-window (current-buffer))
 823       ;; Initialize buffer with `xesam-mode'.  `xesam-vendor' must be
 824       ;; set before calling `xesam-mode', because we want to give the
 825       ;; hook functions a chance to identify their search engine.
 826       (setq xesam-vendor (xesam-get-cached-property engine "vendor.id"))
 827       (xesam-mode)
 828       (setq xesam-engine engine
 829             xesam-search search
 830             ;; `xesam-type', `xesam-query' and `xesam-xml-string'
 831             ;; are displayed in the header line.
 832             xesam-type (symbol-name type)
 833             xesam-query query
 834             xesam-xml-string xml-string
 835             xesam-objects nil
 836             ;; The buffer identification shall indicate the search
 837             ;; engine.  The `help-echo' property is used for debug
 838             ;; information, when applicable.
 839             mode-line-buffer-identification
 840             (if (not xesam-debug)
 841                 (list 12 (propertized-buffer-identification xesam-vendor))
 842               (propertize
 843                xesam-vendor
 844                'help-echo
 845                (mapconcat
 846                 (lambda (x)
 847                   (format "%s: %s" x (xesam-get-cached-property engine x)))
 848                 '("vendor.id" "vendor.version" "vendor.display" "vendor.xesam"
 849                   "vendor.ontology.fields" "vendor.ontology.contents"
 850                   "vendor.ontology.sources" "vendor.extensions"
 851                   "vendor.ontologies" "vendor.maxhits")
 852                 "\n"))))
 853       (add-hook 'kill-buffer-hook 'xesam-kill-buffer-function)
 854       (force-mode-line-update))
 855
 856     ;; Start the search.
 857     (xesam-dbus-call-method
 858      :session (car engine) xesam-path-search
 859      xesam-interface-search "StartSearch" search)
 860
 861     ;; Return search id.
 862     search))
 863
 864 ;;;###autoload
 865 (defun xesam-search (engine query)
 866   "Perform an interactive search.
 867 ENGINE is the Xesam search engine to be applied, it must be one of the
 868 entries of `xesam-search-engines'.  QUERY is the search string in the
 869 Xesam user query language.  If the search engine does not support
 870 the Xesam user query language, a Xesam fulltext search is applied.
 871
 872 The default search engine is the first entry in `xesam-search-engines'.
 873 Example:
 874
 875   (xesam-search (car (xesam-search-engines)) \"emacs\")"
 876   (interactive
 877    (let* ((vendors (mapcar
 878                     (lambda (x) (xesam-get-cached-property x "vendor.display"))
 879                     (xesam-search-engines)))
 880           (vendor
 881            (if (> (length vendors) 1)
 882                (completing-read
 883                 "Enter search engine: " vendors nil t
 884                 (try-completion "" vendors) 'xesam-minibuffer-vendor-history)
 885              (car vendors))))
 886      (list
 887       ;; ENGINE.
 888       (when vendor
 889         (dolist (elt (xesam-search-engines) engine)
 890           (when (string-equal
 891                  (xesam-get-cached-property elt "vendor.display") vendor)
 892             (setq engine elt))))
 893       ;; QUERY.
 894       (when vendor
 895         (read-from-minibuffer
 896          "Enter search string: " nil nil nil
 897          'xesam-minibuffer-query-history)))))
 898
 899   (if (null engine)
 900       (message "No search engine running")
 901     (if (zerop (length query))
 902         (message "No query applied")
 903       (xesam-new-search engine xesam-query-type query))))
 904
 905 (provide 'xesam)
 906
 907 ;;; TODO:
 908
 909 ;; * Buffer highlighting needs better analysis of query string.
 910 ;; * Accept input while retrieving prefetched hits. `run-at-time'?
 911 ;; * With prefix, let's choose search engine.
 912 ;; * Minibuffer completion for user queries.
 913 ;; * `revert-buffer-function' implementation.
 914 ;;
 915 ;; * Mid term
 916 ;;   - If available, use ontologies for field selection.
 917 ;;   - Search engines for Emacs bugs database, wikipedia, google,
 918 ;;     yahoo, ebay, ...
 919 ;;   - Construct complex queries via widgets, like in mairix.el.
 920
 921 ;;; xesam.el ends here