xesam.el 33.3 KB
Newer Older
Michael Albinus's avatar
Michael Albinus committed
1 2
;;; xesam.el --- Xesam interface to search engines.

3
;; Copyright (C) 2008-2011 Free Software Foundation, Inc.
Michael Albinus's avatar
Michael Albinus committed
4 5 6 7 8 9

;; Author: Michael Albinus <michael.albinus@gmx.de>
;; Keywords: tools, hypermedia

;; This file is part of GNU Emacs.

Glenn Morris's avatar
Glenn Morris committed
10
;; GNU Emacs is free software: you can redistribute it and/or modify
Michael Albinus's avatar
Michael Albinus committed
11
;; it under the terms of the GNU General Public License as published by
Glenn Morris's avatar
Glenn Morris committed
12 13
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
Michael Albinus's avatar
Michael Albinus committed
14 15 16 17 18 19 20

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
Glenn Morris's avatar
Glenn Morris committed
21
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Michael Albinus's avatar
Michael Albinus committed
22 23 24

;;; Commentary:

25
;; This package provides an interface to Xesam, a D-Bus based "eXtEnsible
Michael Albinus's avatar
Michael Albinus committed
26 27 28 29
;; Search And Metadata specification".  It has been tested with
;;
;; xesam-glib 0.3.4, xesam-tools 0.6.1
;; beagle 0.3.7, beagle-xesam 0.2
30
;; strigi 0.5.11
Michael Albinus's avatar
Michael Albinus committed
31 32 33 34

;; The precondition for this package is a D-Bus aware Emacs.  This is
;; configured per default, when Emacs is built on a machine running
;; D-Bus.  Furthermore, there must be at least one search engine
35
;; running, which supports the Xesam interface.  Beagle and strigi have
Michael Albinus's avatar
Michael Albinus committed
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
;; been tested; tracker, pinot and recoll are also said to support
;; Xesam.  You can check the existence of such a search engine by
;;
;;   (dbus-list-queued-owners :session "org.freedesktop.xesam.searcher")

;; In order to start a search, you must load xesam.el:
;;
;;   (require 'xesam)

;; xesam.el supports two types of queries, which are explained *very* short:
;;
;; * Full text queries.  Just search keys shall be given, like
;;
;;     hello world
;;
;;   A full text query in xesam.el is restricted to files.
;;
;; * Xesam End User Search Language queries.  The Xesam query language
;;   is described at <http://xesam.org/main/XesamUserSearchLanguage>,
;;   which must be consulted for the whole features.
;;
;;   A query string consists of search keys, collectors, selectors,
;;   and phrases.  Search keys are words like in a full text query:
;;
;;     hello word
;;
;;   A selector is a tuple <keyword><relation>.  <keyword> can be any
;;   predefined Xesam keyword, the most common keywords are "ext"
;;   (file name extension), "format " (mime type), "tag" (user
;;   keywords) and "type" (types of items, like "audio", "file",
;;   "picture", "attachment").  <relation> is a comparison to a value,
;;   which must be a string (relation ":" or "=") or number (relation
;;   "<=", ">=", "<", ">"):
;;
;;     type:attachment ext=el
;;
;;   A collector is one of the items "AND", "and", "&&", "OR", "or",
;;   "||", or "-".  The default collector on multiple terms is "AND";
;;   "-" means "AND NOT".
;;
;;     albinus -type:file
;;
;;   A phrase is a string enclosed in quotes, with appended modifiers
;;   (single letters).  Examples of modifiers are "c" (case
;;   sensitive), "C" (case insensitive), "e" (exact match), "r"
;;   (regular expression):
;;
;;     "Hello world"c

;; You can customize, whether you want to apply a Xesam user query, or
;; a full text query.  Note, that not every search engine supports
;; both query types.
;;
;;   (setq xesam-query-type 'fulltext-query)
;;
;; Another option to be customised is the number of hits to be
;; presented at once.
;;
;;   (setq xesam-hits-per-page 50)

;; A search can be started by the command
;;
;;   M-x xesam-search
;;
;; When several search engines are registered, the engine to be used
;; can be selected via minibuffer completion.  Afterwards, the query
;; shall be entered in the minibuffer.

104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
;; Search results are presented in a new buffer.  This buffer has the
;; major mode `xesam-mode', with the following keybindings:

;;   SPC	`scroll-up'
;;   DEL	`scroll-down'
;;   <		`beginning-of-buffer'
;;   >		`end-of-buffer'
;;   q		`quit-window'
;;   z		`kill-this-buffer'
;;   g		`revert-buffer'

;; The search results are represented by widgets.  Navigation commands
;; are the usual widget navigation commands:

;;   TAB	`widget-forward'
;;   <backtab>	`widget-backward'

;; Applying RET, <down-mouse-1>, or <down-mouse-2> on a URL belonging
;; to the widget, brings up more details of the search hit.  The way,
;; how this hit is presented, depends on the type of the hit.  HTML
;; files are opened via `browse-url'.  Local files are opened in a new
;; buffer, with highlighted search hits (highlighting can be toggled
;; by `xesam-minor-mode' in that buffer).

Michael Albinus's avatar
Michael Albinus committed
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
;;; Code:

;; D-Bus support in the Emacs core can be disabled with configuration
;; option "--without-dbus".  Declare used subroutines and variables.
(declare-function dbus-call-method "dbusbind.c")
(declare-function dbus-register-signal "dbusbind.c")

(require 'dbus)

;; Pacify byte compiler.
(eval-when-compile
  (require 'cl))

;; Widgets are used to highlight the search results.
(require 'widget)
143
(require 'wid-edit)
Michael Albinus's avatar
Michael Albinus committed
144 145 146 147 148 149 150 151 152 153

;; `run-at-time' is used in the signal handler.
(require 'timer)

;; The default search field is "xesam:url".  It must be inspected.
(require 'url)

(defgroup xesam nil
  "Xesam compatible interface to search engines."
  :group 'extensions
154
  :group 'comm
Michael Albinus's avatar
Michael Albinus committed
155 156 157 158 159 160 161 162 163 164
  :version "23.1")

(defcustom xesam-query-type 'user-query
  "Xesam query language type."
  :group 'xesam
  :type '(choice
	  (const :tag "Xesam user query" user-query)
	  (const :tag "Xesam fulltext query" fulltext-query)))

(defcustom xesam-hits-per-page 20
165
  "Number of search hits to be displayed in the result buffer."
Michael Albinus's avatar
Michael Albinus committed
166 167 168
  :group 'xesam
  :type 'integer)

169 170 171 172 173 174 175 176 177 178
(defface xesam-mode-line '((t :inherit mode-line-emphasis))
  "Face to highlight mode line."
  :group 'xesam)

(defface xesam-highlight '((t :inherit match))
  "Face to highlight query entries.
It will be overlayed by `widget-documentation-face', so it shall
be different at least in one face property not set in that face."
  :group 'xesam)

Michael Albinus's avatar
Michael Albinus committed
179
(defvar xesam-debug nil
180
  "Insert debug information in the help echo.")
Michael Albinus's avatar
Michael Albinus committed
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196

(defconst xesam-service-search "org.freedesktop.xesam.searcher"
  "The D-Bus name used to talk to Xesam.")

(defconst xesam-path-search "/org/freedesktop/xesam/searcher/main"
  "The D-Bus object path used to talk to Xesam.")

;; Methods: "NewSession", "SetProperty", "GetProperty",
;; "CloseSession", "NewSearch", "StartSearch", "GetHitCount",
;; "GetHits", "GetHitData", "CloseSearch" and "GetState".
;; Signals: "HitsAdded", "HitsRemoved", "HitsModified", "SearchDone"
;; and "StateChanged".
(defconst xesam-interface-search "org.freedesktop.xesam.Search"
  "The D-Bus Xesam search interface.")

(defconst xesam-all-fields
197 198 199 200 201
  '("xesam:35mmEquivalent" "xesam:aimContactMedium" "xesam:aperture"
    "xesam:aspectRatio" "xesam:attachmentEncoding" "xesam:attendee"
    "xesam:audioBirate" "xesam:audioChannels" "xesam:audioCodec"
    "xesam:audioCodecType" "xesam:audioSampleFormat" "xesam:audioSampleRate"
    "xesam:author" "xesam:bcc" "xesam:birthDate" "xesam:blogContactURL"
Michael Albinus's avatar
Michael Albinus committed
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271
    "xesam:cameraManufacturer" "xesam:cameraModel" "xesam:cc" "xesam:ccdWidth"
    "xesam:cellPhoneNumber" "xesam:characterCount" "xesam:charset"
    "xesam:colorCount" "xesam:colorSpace" "xesam:columnCount" "xesam:comment"
    "xesam:commentCharacterCount" "xesam:conflicts" "xesam:contactMedium"
    "xesam:contactName" "xesam:contactNick" "xesam:contactPhoto"
    "xesam:contactURL" "xesam:contains" "xesam:contenKeyword"
    "xesam:contentComment" "xesam:contentCreated" "xesam:contentModified"
    "xesam:contentType" "xesam:contributor" "xesam:copyright" "xesam:creator"
    "xesam:definesClass" "xesam:definesFunction" "xesam:definesGlobalVariable"
    "xesam:deletionTime" "xesam:depends" "xesam:description" "xesam:device"
    "xesam:disclaimer" "xesam:documentCategory" "xesam:duration"
    "xesam:emailAddress" "xesam:eventEnd" "xesam:eventLocation"
    "xesam:eventStart" "xesam:exposureBias" "xesam:exposureProgram"
    "xesam:exposureTime" "xesam:faxPhoneNumber" "xesam:fileExtension"
    "xesam:fileSystemType" "xesam:flashUsed" "xesam:focalLength"
    "xesam:focusDistance" "xesam:formatSubtype" "xesam:frameCount"
    "xesam:frameRate" "xesam:freeSpace" "xesam:gender" "xesam:generator"
    "xesam:generatorOptions" "xesam:group" "xesam:hash" "xesam:hash"
    "xesam:height" "xesam:homeEmailAddress" "xesam:homePhoneNumber"
    "xesam:homePostalAddress" "xesam:homepageContactURL"
    "xesam:horizontalResolution" "xesam:icqContactMedium" "xesam:id"
    "xesam:imContactMedium" "xesam:interests" "xesam:interlaceMode"
    "xesam:isEncrypted" "xesam:isImportant" "xesam:isInProgress"
    "xesam:isPasswordProtected" "xesam:isRead" "xesam:isoEquivalent"
    "xesam:jabberContactMedium" "xesam:keyword" "xesam:language" "xesam:legal"
    "xesam:license" "xesam:licenseType" "xesam:lineCount" "xesam:links"
    "xesam:mailingPostalAddress" "xesam:maintainer" "xesam:md5Hash"
    "xesam:mediaCodec" "xesam:mediaCodecBitrate" "xesam:mediaCodecType"
    "xesam:meteringMode" "xesam:mimeType" "xesam:mountPoint"
    "xesam:msnContactMedium" "xesam:name" "xesam:occupiedSpace"
    "xesam:orientation" "xesam:originalLocation" "xesam:owner"
    "xesam:pageCount" "xesam:permissions" "xesam:phoneNumber"
    "xesam:physicalAddress" "xesam:pixelFormat" "xesam:primaryRecipient"
    "xesam:programmingLanguage" "xesam:rating" "xesam:receptionTime"
    "xesam:recipient" "xesam:related" "xesam:remoteUser" "xesam:rowCount"
    "xesam:sampleBitDepth" "xesam:sampleFormat" "xesam:secondaryRecipient"
    "xesam:sha1Hash" "xesam:size" "xesam:skypeContactMedium"
    "xesam:sourceCreated" "xesam:sourceModified" "xesam:storageSize"
    "xesam:subject" "xesam:supercedes" "xesam:title" "xesam:to"
    "xesam:totalSpace" "xesam:totalUncompressedSize" "xesam:url"
    "xesam:usageIntensity" "xesam:userComment" "xesam:userKeyword"
    "xesam:uuid" "xesam:version" "xesam:verticalResolution" "xesam:videoBirate"
    "xesam:videoCodec" "xesam:videoCodecType" "xesam:whiteBalance"
    "xesam:width" "xesam:wordCount" "xesam:workEmailAddress"
    "xesam:workPhoneNumber" "xesam:workPostalAddress"
    "xesam:yahooContactMedium")
  "All fields from the Xesam Core Ontology.
This defconst can be used to check for a new search engine, which
fields are supported.")

(defconst xesam-user-query
  "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<request xmlns=\"http://freedesktop.org/standards/xesam/1.0/query\">
  <userQuery>
    %s
  </userQuery>
</request>"
  "The Xesam user query XML.")

(defconst xesam-fulltext-query
  "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<request xmlns=\"http://freedesktop.org/standards/xesam/1.0/query\">
  <query content=\"xesam:Document\" source=\"xesam:File\">
    <fullText>
      <string>%s</string>
    </fullText>
  </query>
</request>"
  "The Xesam fulltext query XML.")

272 273
(declare-function dbus-get-unique-name "dbusbind.c" (bus))

274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292
(defvar xesam-dbus-unique-names
  (list (cons :system (dbus-get-unique-name :system))
	(cons :session (dbus-get-unique-name :session)))
  "The unique names, under which Emacs is registered at D-Bus.")

(defun xesam-dbus-call-method (&rest args)
  "Apply a D-Bus method call.
`dbus-call-method' is to be preferred, because it is more
performant.  If the target D-Bus service is owned by Emacs, this
is not applicable, and `dbus-call-method-non-blocking' must be
used instead.  ARGS are identical to the argument list of both
functions."
  (apply
   ;; The first argument is the bus, the second argument the targt service.
   (if (string-equal (cdr (assoc (car args) xesam-dbus-unique-names))
		     (cadr args))
       'dbus-call-method-non-blocking 'dbus-call-method)
   args))

Michael Albinus's avatar
Michael Albinus committed
293 294 295
(defun xesam-get-property (engine property)
  "Return the PROPERTY value of ENGINE."
  ;; "GetProperty" returns a variant, so we must use the car.
296
  (car (xesam-dbus-call-method
Michael Albinus's avatar
Michael Albinus committed
297 298
	:session (car engine) xesam-path-search
	xesam-interface-search  "GetProperty"
299
	(xesam-get-cached-property engine "session") property)))
Michael Albinus's avatar
Michael Albinus committed
300 301 302 303 304 305 306 307

(defun xesam-set-property (engine property value)
  "Set the PROPERTY of ENGINE to VALUE.
VALUE can be a string, a non-negative integer, a boolean
value (nil or t), or a list of them.  It returns the new value of
PROPERTY in the search engine.  This new value can be different
from VALUE, depending on what the search engine accepts."
  ;; "SetProperty" returns a variant, so we must use the car.
308
  (car (xesam-dbus-call-method
Michael Albinus's avatar
Michael Albinus committed
309 310
	:session (car engine) xesam-path-search
	xesam-interface-search  "SetProperty"
311
	(xesam-get-cached-property engine "session") property
Michael Albinus's avatar
Michael Albinus committed
312 313 314 315 316 317 318 319 320 321 322 323 324
	;; The value must be a variant.  It can be only a string, an
	;; unsigned int, a boolean, or an array of them.  So we need
	;; no type keyword; we let the type check to the search
	;; engine.
	(list :variant value))))

(defvar xesam-minibuffer-vendor-history nil
  "Interactive vendor history.")

(defvar xesam-minibuffer-query-history nil
  "Interactive query history.")

;; Pacify byte compiler.
325 326 327 328
(defvar xesam-vendor nil)
(make-variable-buffer-local 'xesam-vendor)
(put 'xesam-vendor 'permanent-local t)

Michael Albinus's avatar
Michael Albinus committed
329 330
(defvar xesam-engine nil)
(defvar xesam-search nil)
331 332 333
(defvar xesam-type nil)
(defvar xesam-query nil)
(defvar xesam-xml-string nil)
334
(defvar xesam-objects nil)
Michael Albinus's avatar
Michael Albinus committed
335 336 337
(defvar xesam-current nil)
(defvar xesam-count nil)
(defvar xesam-to nil)
338
(defvar xesam-notify-function nil)
Michael Albinus's avatar
Michael Albinus committed
339 340 341 342 343 344 345
(defvar xesam-refreshing nil)


;;; Search engines.

(defvar xesam-search-engines nil
  "List of available Xesam search engines.
346 347 348 349 350 351 352 353 354 355 356
Every entry is an association list, with a car denoting the
unique D-Bus service name of the engine.  The rest of the entry
are cached associations of engine attributes, like the session
identifier, and the display name.  Example:

  \(\(\":1.59\"
    \(\"session\" . \"0t1214948020ut358230u0p2698r3912347765k3213849828\")
    \(\"vendor.display\" . \"Tracker Xesam Service\"))
   \(\":1.27\"
    \(\"session\" . \"strigisession1369133069\")
    \(\"vendor.display\" . \"Strigi Desktop Search\")))
Michael Albinus's avatar
Michael Albinus committed
357 358

A Xesam-compatible search engine is identified as a queued D-Bus
359 360 361 362 363 364 365 366 367 368 369 370 371 372 373
service of the known service `xesam-service-search'.")

(defun xesam-get-cached-property (engine property)
  "Return the PROPERTY value of ENGINE from the cache.
If PROPERTY is not existing, retrieve it from ENGINE first."
  ;; If the property has not been cached yet, we retrieve it from the
  ;; engine, and cache it.
  (unless (assoc property engine)
    (xesam-set-cached-property
     engine property (xesam-get-property engine property)))
  (cdr (assoc property engine)))

(defun xesam-set-cached-property (engine property value)
  "Set the PROPERTY of ENGINE to VALUE in the cache."
  (setcdr engine (append (cdr engine) (list (cons property value)))))
Michael Albinus's avatar
Michael Albinus committed
374 375

(defun xesam-delete-search-engine (&rest args)
376 377 378
  "Remove service from `xesam-search-engines'."
  (setq xesam-search-engines
	(delete (assoc (car args) xesam-search-engines) xesam-search-engines)))
Michael Albinus's avatar
Michael Albinus committed
379

380 381
(defvar dbus-debug)

Michael Albinus's avatar
Michael Albinus committed
382 383 384 385 386 387 388 389 390 391 392 393
(defun xesam-search-engines ()
  "Return Xesam search engines, stored in `xesam-search-engines'.
The first search engine is the name owner of `xesam-service-search'.
If there is no registered search engine at all, the function returns `nil'."
  (let ((services (dbus-ignore-errors
		    (dbus-list-queued-owners
		     :session xesam-service-search)))
	engine vendor-id hit-fields)
    (dolist (service services)
      (unless (assoc-string service xesam-search-engines)

	;; Open a new session, and add it to the search engines list.
394 395 396 397 398 399 400 401 402 403 404 405 406
	(add-to-list 'xesam-search-engines (list service) 'append)
	(setq engine (assoc service xesam-search-engines))

	;; Add the session string.
	(xesam-set-cached-property
	 engine "session"
	 (xesam-dbus-call-method
	  :session service xesam-path-search
	  xesam-interface-search "NewSession"))

	;; Unset the "search.live" property; we don't want to be
	;; informed by changed results.
	(xesam-set-property engine "search.live" nil)
Michael Albinus's avatar
Michael Albinus committed
407 408 409 410 411 412 413 414 415

	;; Check the vendor properties.
	(setq vendor-id (xesam-get-property engine "vendor.id")
	      hit-fields (xesam-get-property engine "hit.fields"))

	;; Ususally, `hit.fields' shall describe supported fields.
	;; That is not the case now, so we set it ourselves.
	;; Hopefully, this will change later.
	(setq hit-fields
416
	      (case (intern vendor-id)
417
		(Beagle
418
		 '("xesam:mimeType" "xesam:url"))
419
		(Strigi
420 421 422 423 424 425
		 '("xesam:author" "xesam:cc" "xesam:charset"
		   "xesam:contentType" "xesam:fileExtension"
		   "xesam:id" "xesam:lineCount" "xesam:links"
		   "xesam:mimeType" "xesam:name" "xesam:size"
		   "xesam:sourceModified" "xesam:subject" "xesam:to"
		   "xesam:url"))
426
		(TrackerXesamSession
427
		 '("xesam:relevancyRating" "xesam:url"))
428
		(Debbugs
429 430 431 432 433 434
		 '("xesam:keyword" "xesam:owner" "xesam:title"
		   "xesam:url" "xesam:sourceModified" "xesam:mimeType"
		   "debbugs:key"))
		;; xesam-tools yahoo service.
		(t '("xesam:contentModified" "xesam:mimeType" "xesam:summary"
		     "xesam:title" "xesam:url" "yahoo:displayUrl"))))
Michael Albinus's avatar
Michael Albinus committed
435 436 437 438 439 440 441 442 443 444 445 446 447 448

	(xesam-set-property engine "hit.fields" hit-fields)
	(xesam-set-property engine "hit.fields.extended" '("xesam:snippet"))

	;; Let us notify, when the search engine disappears.
	(dbus-register-signal
	 :session dbus-service-dbus dbus-path-dbus
	 dbus-interface-dbus "NameOwnerChanged"
	 'xesam-delete-search-engine service))))
  xesam-search-engines)


;;; Search buffers.

449 450 451 452 453 454
(defvar xesam-mode-map
  (let ((map (copy-keymap special-mode-map)))
    (set-keymap-parent xesam-mode-map widget-keymap)
    map))

(define-derived-mode xesam-mode special-mode "Xesam"
Michael Albinus's avatar
Michael Albinus committed
455 456 457 458
  "Major mode for presenting search results of a Xesam search.
In this mode, widgets represent the search results.

\\{xesam-mode-map}
459 460 461 462
Turning on Xesam mode runs the normal hook `xesam-mode-hook'.  It
can be used to set `xesam-notify-function', which must a search
engine specific, widget :notify function to visualize xesam:url."
  (set (make-local-variable 'xesam-notify-function) nil)
463 464 465 466 467 468 469 470 471
  ;; Maybe we implement something useful, later on.
  (set (make-local-variable 'revert-buffer-function) 'ignore)
  ;; `xesam-engine', `xesam-search', `xesam-type', `xesam-query', and
  ;; `xesam-xml-string' will be set in `xesam-new-search'.
  (set (make-local-variable 'xesam-engine) nil)
  (set (make-local-variable 'xesam-search) nil)
  (set (make-local-variable 'xesam-type) "")
  (set (make-local-variable 'xesam-query) "")
  (set (make-local-variable 'xesam-xml-string) "")
472
  (set (make-local-variable 'xesam-objects) nil)
473 474 475 476 477 478
  ;; `xesam-current' is the last hit put into the search buffer,
  (set (make-local-variable 'xesam-current) 0)
  ;; `xesam-count' is the number of hits reported by the search engine.
  (set (make-local-variable 'xesam-count) 0)
  ;; `xesam-to' is the upper hit number to be presented.
  (set (make-local-variable 'xesam-to) xesam-hits-per-page)
479 480 481
  ;; `xesam-notify-function' can be a search engine specific function
  ;; to visualize xesam:url.  It can be overwritten in `xesam-mode'.
  (set (make-local-variable 'xesam-notify-function) nil)
482 483 484 485 486 487 488 489 490 491 492 493 494
  ;; `xesam-refreshing' is an indicator, whether the buffer is just
  ;; being updated.  Needed, because `xesam-refresh-search-buffer'
  ;; can be triggered by an event.
  (set (make-local-variable 'xesam-refreshing) nil)
  ;; Mode line position returns hit counters.
  (set (make-local-variable 'mode-line-position)
       (list '(-3 "%p%")
	     '(10 (:eval (format " (%d/%d)" xesam-current xesam-count)))))
  ;; Header line contains the query string.
  (set (make-local-variable 'header-line-format)
       (list '(20
	       (:eval
		(list "Type: "
495
		      (propertize xesam-type 'face 'xesam-mode-line))))
496 497 498 499 500
	     '(10
	       (:eval
		(list " Query: "
		      (propertize
		       xesam-query
501
		       'face 'xesam-mode-line
502
		       'help-echo (when xesam-debug xesam-xml-string)))))))
503

504
  (when (not (called-interactively-p 'interactive))
505 506 507
    ;; Initialize buffer.
    (setq buffer-read-only t)
    (let ((inhibit-read-only t))
508 509 510 511
      (erase-buffer))))

;; It doesn't make sense to call it interactively.
(put 'xesam-mode 'disabled t)
Michael Albinus's avatar
Michael Albinus committed
512

513 514 515 516
;; The very first buffer created with `xesam-mode' does not have the
;; keymap etc.  So we create a dummy buffer.  Stupid.
(with-temp-buffer (xesam-mode))

517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549
(define-minor-mode xesam-minor-mode
  "Toggle Xesam minor mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.

When Xesam minor mode is enabled, all text which matches a
previous Xesam query in this buffer is highlighted."
  :group 'xesam
  :init-value nil
  :lighter " Xesam"
  (when (local-variable-p 'xesam-query)
    ;; Run only if the buffer is related to a Xesam search.
    (save-excursion
      (if xesam-minor-mode
	  ;; Highlight hits.
	  (let ((query-regexp (regexp-opt (split-string xesam-query nil t) t))
		(case-fold-search t))
	    ;; I have no idea whether people will like setting
	    ;; `isearch-case-fold-search' and `query-regexp'.  Maybe
	    ;; this shall be controlled by a custom option.
	    (unless isearch-case-fold-search (isearch-toggle-case-fold))
	    (isearch-update-ring query-regexp t)
	    ;; Create overlays.
	    (goto-char (point-min))
	    (while (re-search-forward query-regexp nil t)
	      (overlay-put
	       (make-overlay
		(match-beginning 0) (match-end 0)) 'face 'xesam-highlight)))
	;; Remove overlays.
	(dolist (ov (overlays-in (point-min) (point-max)))
	  (delete-overlay ov))))))

Michael Albinus's avatar
Michael Albinus committed
550 551 552 553 554 555
(defun xesam-buffer-name (service search)
  "Return the buffer name where to present search results.
SERVICE is the D-Bus unique service name of the Xesam search engine.
SEARCH is the search identification in that engine.  Both must be strings."
  (format "*%s/%s*" service search))

556
(defun xesam-highlight-string (string)
557 558
  "Highlight text enclosed by <b> and </b>.
Return propertized STRING."
559 560 561 562 563 564 565 566 567 568
  (while (string-match "\\(.*\\)\\(<b>\\)\\(.*\\)\\(</b>\\)\\(.*\\)" string)
    (setq string
	  (format
	   "%s%s%s"
	   (match-string 1 string)
	   (propertize (match-string 3 string) 'face 'xesam-highlight)
	   (match-string 5 string))))
  string)

(defun xesam-refresh-entry (engine entry)
Michael Albinus's avatar
Michael Albinus committed
569
  "Refreshes one entry in the search buffer."
570
  (let* ((result (nth (1- xesam-current) xesam-objects))
Michael Albinus's avatar
Michael Albinus committed
571 572 573 574
	 widget)

    ;; Create widget.
    (setq widget (widget-convert 'link))
575 576
    (when xesam-debug
      (widget-put widget :help-echo ""))
Michael Albinus's avatar
Michael Albinus committed
577 578

    ;; Take all results.
579
    (dolist (field (xesam-get-cached-property engine "hit.fields"))
580 581 582 583
      (when (cond
	     ((stringp (caar result)) (not (zerop (length (caar result)))))
	     ((numberp (caar result)) (not (zerop (caar result))))
	     ((caar result) t))
Michael Albinus's avatar
Michael Albinus committed
584
	(when xesam-debug
585 586 587 588
	  (widget-put
	   widget :help-echo
	   (format "%s%s: %s\n"
		   (widget-get widget :help-echo) field (caar result))))
Michael Albinus's avatar
Michael Albinus committed
589 590 591 592 593 594 595 596 597
	(widget-put widget (intern (concat ":" field)) (caar result)))
      (setq result (cdr result)))

    ;; Strigi doesn't return URLs in xesam:url.  We must fix this.
    (when
	(not (url-type (url-generic-parse-url (widget-get widget :xesam:url))))
      (widget-put
       widget :xesam:url (concat "file://" (widget-get widget :xesam:url))))

598 599 600 601 602 603
    ;; Strigi returns xesam:size as string.  We must fix this.
    (when (and (widget-member widget :xesam:size)
	       (stringp (widget-get widget :xesam:size)))
      (widget-put
       widget :xesam:size (string-to-number (widget-get widget :xesam:url))))

Michael Albinus's avatar
Michael Albinus committed
604 605 606 607 608 609 610 611 612 613 614
    ;; First line: :tag.
    (cond
     ((widget-member widget :xesam:title)
      (widget-put widget :tag (widget-get widget :xesam:title)))
     ((widget-member widget :xesam:subject)
      (widget-put widget :tag (widget-get widget :xesam:subject)))
     ((widget-member widget :xesam:mimeType)
      (widget-put widget :tag (widget-get widget :xesam:mimeType)))
     ((widget-member widget :xesam:name)
      (widget-put widget :tag (widget-get widget :xesam:name))))

615 616 617 618 619
    ;; Highlight the search items.
    (when (widget-member widget :tag)
      (widget-put
       widget :tag (xesam-highlight-string (widget-get widget :tag))))

Michael Albinus's avatar
Michael Albinus committed
620
    ;; Last Modified.
621 622 623 624
    (when (and (widget-member widget :xesam:sourceModified)
	       (not
		(zerop
		 (string-to-number (widget-get widget :xesam:sourceModified)))))
Michael Albinus's avatar
Michael Albinus committed
625 626 627 628 629 630 631 632 633 634 635 636 637 638
      (widget-put
       widget :tag
       (format
	"%s\nLast Modified: %s"
	(or (widget-get widget :tag) "")
	(format-time-string
	 "%d %B %Y, %T"
	 (seconds-to-time
	  (string-to-number (widget-get widget :xesam:sourceModified)))))))

    ;; Second line: :value.
    (widget-put widget :value (widget-get widget :xesam:url))

    (cond
639 640 641 642 643
     ;; A search engine can set `xesam-notify-function' via
     ;; `xesam-mode-hooks'.
     (xesam-notify-function
      (widget-put widget :notify xesam-notify-function))

Michael Albinus's avatar
Michael Albinus committed
644 645 646 647 648 649 650 651 652 653 654
     ;; In case of HTML, we use a URL link.
     ((and (widget-member widget :xesam:mimeType)
	   (string-equal "text/html" (widget-get widget :xesam:mimeType)))
      (setcar widget 'url-link))

     ;; For local files, we will open the file as default action.
     ((string-match "file"
		    (url-type (url-generic-parse-url
			       (widget-get widget :xesam:url))))
      (widget-put
       widget :notify
655
       (lambda (widget &rest ignore)
656 657 658
	 (let ((query xesam-query))
	   (find-file
	    (url-filename (url-generic-parse-url (widget-value widget))))
659 660
	   (set (make-local-variable 'xesam-query) query)
	   (xesam-minor-mode 1))))
Michael Albinus's avatar
Michael Albinus committed
661 662 663 664 665 666 667 668 669 670 671 672 673
      (widget-put
       widget :value
       (url-filename (url-generic-parse-url (widget-get widget :xesam:url))))))

    ;; Third line: :doc.
    (cond
     ((widget-member widget :xesam:summary)
      (widget-put widget :doc (widget-get widget :xesam:summary)))
     ((widget-member widget :xesam:snippet)
      (widget-put widget :doc (widget-get widget :xesam:snippet))))

    (when (widget-member widget :doc)
      (with-temp-buffer
674 675
	(insert
	 (xesam-highlight-string (widget-get widget :doc)))
Michael Albinus's avatar
Michael Albinus committed
676
	(fill-region-as-paragraph (point-min) (point-max))
677 678
	(widget-put widget :doc (buffer-string)))
      (widget-put widget :help-echo (widget-get widget :doc)))
Michael Albinus's avatar
Michael Albinus committed
679 680 681 682

    ;; Format the widget.
    (widget-put
     widget :format
683
     (format "%d. %s%%[%%v%%]\n%s\n" xesam-current
Michael Albinus's avatar
Michael Albinus committed
684 685 686 687 688 689 690
	     (if (widget-member widget :tag) "%{%t%}\n" "")
	     (if (widget-member widget :doc) "%h" "")))

    ;; Write widget.
    (goto-char (point-max))
    (widget-default-create widget)
    (set-buffer-modified-p nil)
691
    (force-mode-line-update)
Michael Albinus's avatar
Michael Albinus committed
692 693
    (redisplay)))

694 695 696 697 698 699 700 701 702
(defun xesam-get-hits (engine search hits)
  "Retrieve hits from ENGINE."
  (with-current-buffer (xesam-buffer-name (car engine) search)
    (setq xesam-objects
	  (append xesam-objects
		  (xesam-dbus-call-method
		   :session (car engine) xesam-path-search
		   xesam-interface-search "GetHits" search hits)))))

Michael Albinus's avatar
Michael Albinus committed
703 704 705 706
(defun xesam-refresh-search-buffer (engine search)
  "Refreshes the buffer, presenting results of SEARCH."
  (with-current-buffer (xesam-buffer-name (car engine) search)
    ;; Work only if nobody else is here.
707
    (unless (or xesam-refreshing (>= xesam-current xesam-to))
Michael Albinus's avatar
Michael Albinus committed
708 709
      (setq xesam-refreshing t)
      (unwind-protect
710 711 712 713 714 715 716 717 718 719
	  (let (widget)

	    ;; Retrieve needed hits for visualization.
	    (while (> (min xesam-to xesam-count) (length xesam-objects))
	      (xesam-get-hits
	       engine search
	       (min xesam-hits-per-page
		    (- (min xesam-to xesam-count) (length xesam-objects)))))

	    ;; Add all result widgets.
720
	    (while (< xesam-current (min xesam-to xesam-count))
721
	      (setq xesam-current (1+ xesam-current))
722
	      (xesam-refresh-entry engine search))
Michael Albinus's avatar
Michael Albinus committed
723 724

	    ;; Add "NEXT" widget.
725
	    (when (> xesam-count xesam-to)
Michael Albinus's avatar
Michael Albinus committed
726 727 728 729
	      (goto-char (point-max))
	      (widget-create
	       'link
	       :notify
730 731 732 733
	       (lambda (widget &rest ignore)
		 (setq xesam-to (+ xesam-to xesam-hits-per-page))
		 (widget-delete widget)
		 (xesam-refresh-search-buffer xesam-engine xesam-search))
Michael Albinus's avatar
Michael Albinus committed
734
	       "NEXT")
735 736 737 738 739 740 741 742 743
	      (widget-beginning-of-line))

	    ;; Prefetch next hits.
	    (when (> (min (+ xesam-hits-per-page xesam-to) xesam-count)
		     (length xesam-objects))
	      (xesam-get-hits
	       engine search
	       (min xesam-hits-per-page
		    (- (min (+ xesam-hits-per-page xesam-to) xesam-count)
744
		       (length xesam-objects)))))
Michael Albinus's avatar
Michael Albinus committed
745

746 747 748 749
	    ;; Add "DONE" widget.
	    (when (= xesam-current xesam-count)
	      (goto-char (point-max))
	      (widget-create 'link :notify 'ignore "DONE")
750
	      (widget-beginning-of-line)))
751

Michael Albinus's avatar
Michael Albinus committed
752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
	;; Return with save settings.
	(setq xesam-refreshing nil)))))


;;; Search functions.

(defun xesam-signal-handler (&rest args)
  "Handles the different D-Bus signals of a Xesam search."
  (let* ((service (dbus-event-service-name last-input-event))
	 (member (dbus-event-member-name last-input-event))
	 (search (nth 0 args))
	 (buffer (xesam-buffer-name service search)))

    (when (get-buffer buffer)
      (with-current-buffer buffer
	(cond

	 ((string-equal member "HitsAdded")
770
	  (setq xesam-count (+ xesam-count (nth 1 args)))
Michael Albinus's avatar
Michael Albinus committed
771 772 773 774 775 776 777 778
	  ;; We use `run-at-time' in order to not block the event queue.
	  (run-at-time
	   0 nil
	   'xesam-refresh-search-buffer
	   (assoc service xesam-search-engines) search))

	 ((string-equal member "SearchDone")
	  (setq mode-line-process
779
		(propertize " Done" 'face 'xesam-mode-line))
Michael Albinus's avatar
Michael Albinus committed
780 781
	  (force-mode-line-update)))))))

782 783 784
(defun xesam-kill-buffer-function ()
  "Send the CloseSearch indication."
  (when (and (eq major-mode 'xesam-mode) (stringp xesam-search))
785 786 787 788
    (ignore-errors ;; The D-Bus service could have disappeared.
      (xesam-dbus-call-method
       :session (car xesam-engine) xesam-path-search
       xesam-interface-search "CloseSearch" xesam-search))))
789

790
(defun xesam-new-search (engine type query)
Michael Albinus's avatar
Michael Albinus committed
791
  "Create a new search session.
792 793 794 795
ENGINE identifies the search engine.  TYPE is the query type, it
can be either `fulltext-query', or `user-query'.  QUERY is a
string in the Xesam query language.  A string, identifying the
search, is returned."
Michael Albinus's avatar
Michael Albinus committed
796
  (let* ((service (car engine))
797
	 (session (xesam-get-cached-property engine "session"))
798 799 800
	 (xml-string
	  (format
	   (if (eq type 'user-query) xesam-user-query xesam-fulltext-query)
801
	   (url-insert-entities-in-string query)))
802
	 (search (xesam-dbus-call-method
Michael Albinus's avatar
Michael Albinus committed
803
		  :session service xesam-path-search
804
		  xesam-interface-search "NewSearch" session xml-string)))
805

Michael Albinus's avatar
Michael Albinus committed
806 807 808 809 810 811 812 813 814 815 816
    ;; Let us notify for relevant signals.  We ignore "HitsRemoved",
    ;; "HitsModified" and "StateChanged"; there is nothing to do for
    ;; us.
    (dbus-register-signal
     :session service xesam-path-search
     xesam-interface-search "HitsAdded"
     'xesam-signal-handler search)
    (dbus-register-signal
     :session service xesam-path-search
     xesam-interface-search "SearchDone"
     'xesam-signal-handler search)
817

Michael Albinus's avatar
Michael Albinus committed
818 819 820 821
    ;; Create the search buffer.
    (with-current-buffer
	(generate-new-buffer (xesam-buffer-name service search))
      (switch-to-buffer-other-window (current-buffer))
822 823 824 825
      ;; Inialize buffer with `xesam-mode'.  `xesam-vendor' must be
      ;; set before calling `xesam-mode', because we want to give the
      ;; hook functions a chance to identify their search engine.
      (setq xesam-vendor (xesam-get-cached-property engine "vendor.id"))
Michael Albinus's avatar
Michael Albinus committed
826 827 828
      (xesam-mode)
      (setq xesam-engine engine
	    xesam-search search
829 830 831 832 833
	    ;; `xesam-type', `xesam-query' and `xesam-xml-string'
	    ;; are displayed in the header line.
	    xesam-type (symbol-name type)
	    xesam-query query
	    xesam-xml-string xml-string
834
	    xesam-objects nil
835 836 837
	    ;; The buffer identification shall indicate the search
	    ;; engine.  The `help-echo' property is used for debug
	    ;; information, when applicable.
Michael Albinus's avatar
Michael Albinus committed
838
	    mode-line-buffer-identification
839
	    (if (not xesam-debug)
840
		(list 12 (propertized-buffer-identification xesam-vendor))
841
	      (propertize
842
	       xesam-vendor
843
	       'help-echo
844
	       (mapconcat
845 846
		(lambda (x)
		  (format "%s: %s" x (xesam-get-cached-property engine x)))
847 848 849 850
		'("vendor.id" "vendor.version" "vendor.display" "vendor.xesam"
		  "vendor.ontology.fields" "vendor.ontology.contents"
		  "vendor.ontology.sources" "vendor.extensions"
		  "vendor.ontologies" "vendor.maxhits")
851
		"\n"))))
852 853
      (add-hook 'kill-buffer-hook 'xesam-kill-buffer-function)
      (force-mode-line-update))
854 855

    ;; Start the search.
856
    (xesam-dbus-call-method
857 858
     :session (car engine) xesam-path-search
     xesam-interface-search "StartSearch" search)
Michael Albinus's avatar
Michael Albinus committed
859 860 861 862

    ;; Return search id.
    search))

863
;;;###autoload
Michael Albinus's avatar
Michael Albinus committed
864 865 866 867 868 869 870 871 872 873 874 875 876
(defun xesam-search (engine query)
  "Perform an interactive search.
ENGINE is the Xesam search engine to be applied, it must be one of the
entries of `xesam-search-engines'.  QUERY is the search string in the
Xesam user query language.  If the search engine does not support
the Xesam user query language, a Xesam fulltext search is applied.

The default search engine is the first entry in `xesam-search-engines'.
Example:

  (xesam-search (car (xesam-search-engines)) \"emacs\")"
  (interactive
   (let* ((vendors (mapcar
877
		    (lambda (x) (xesam-get-cached-property x "vendor.display"))
Michael Albinus's avatar
Michael Albinus committed
878 879 880 881 882 883 884 885 886 887 888
		    (xesam-search-engines)))
	  (vendor
	   (if (> (length vendors) 1)
	       (completing-read
		"Enter search engine: " vendors nil t
		(try-completion "" vendors) 'xesam-minibuffer-vendor-history)
	     (car vendors))))
     (list
      ;; ENGINE.
      (when vendor
	(dolist (elt (xesam-search-engines) engine)
889 890
	  (when (string-equal
		 (xesam-get-cached-property elt "vendor.display") vendor)
Michael Albinus's avatar
Michael Albinus committed
891 892 893 894 895 896 897
	    (setq engine elt))))
      ;; QUERY.
      (when vendor
	(read-from-minibuffer
	 "Enter search string: " nil nil nil
	 'xesam-minibuffer-query-history)))))

898 899 900 901 902
  (if (null engine)
      (message "No search engine running")
    (if (zerop (length query))
	(message "No query applied")
      (xesam-new-search engine xesam-query-type query))))
Michael Albinus's avatar
Michael Albinus committed
903 904 905 906 907

(provide 'xesam)

;;; TODO:

908
;; * Buffer highlighting needs better analysis of query string.
909
;; * Accept input while retrieving prefetched hits. `run-at-time'?
910
;; * With prefix, let's choose search engine.
Michael Albinus's avatar
Michael Albinus committed
911
;; * Minibuffer completion for user queries.
912 913
;; * `revert-buffer-function' implementation.
;;
Michael Albinus's avatar
Michael Albinus committed
914 915 916 917
;; * Mid term
;;   - If available, use ontologies for field selection.
;;   - Search engines for Emacs bugs database, wikipedia, google,
;;     yahoo, ebay, ...
918
;;   - Construct complex queries via widgets, like in mairix.el.
Michael Albinus's avatar
Michael Albinus committed
919 920

;;; xesam.el ends here