cgit.sxemacs.org Git - gnus/blob - lisp/gnus-gl.el

   1 ;;; gnus-gl.el --- an interface to GroupLens for Gnus
   2
   3 ;; Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000
   4 ;;      Free Software Foundation, Inc.
   5
   6 ;; Author: Brad Miller <bmiller@cs.umn.edu>
   7 ;; Keywords: news, score
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  24 ;; Boston, MA 02111-1307, USA.
  25
  26 ;;; Commentary:
  27
  28 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  29 ;; GroupLens software and documentation is copyright (c) 1995 by Paul
  30 ;; Resnick (Massachusetts Institute of Technology); Brad Miller, John
  31 ;; Riedl, Jon Herlocker, and Joseph Konstan (University of Minnesota),
  32 ;; and David Maltz (Carnegie-Mellon University).
  33 ;;
  34 ;; Permission to use, copy, modify, and distribute this documentation
  35 ;; for non-commercial and commercial purposes without fee is hereby
  36 ;; granted provided that this copyright notice and permission notice
  37 ;; appears in all copies and that the names of the individuals and
  38 ;; institutions holding this copyright are not used in advertising or
  39 ;; publicity pertaining to this software without specific, written
  40 ;; prior permission.  The copyright holders make no representations
  41 ;; about the suitability of this software and documentation for any
  42 ;; purpose.  It is provided ``as is'' without express or implied
  43 ;; warranty.
  44 ;;
  45 ;; The copyright holders request that they be notified of
  46 ;; modifications of this code.  Please send electronic mail to
  47 ;; grouplens@cs.umn.edu for more information or to announce derived
  48 ;; works.
  49 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  50 ;; Author: Brad Miller
  51 ;;
  52 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  53 ;;
  54 ;; User Documentation:
  55 ;; To use GroupLens you must load this file.
  56 ;; You must also register a pseudonym with the Better Bit Bureau.
  57 ;; http://www.cs.umn.edu/Research/GroupLens
  58 ;;
  59 ;;    ---------------- For your .emacs or .gnus file ----------------
  60 ;;
  61 ;; As of version 2.5, grouplens now works as a minor mode of
  62 ;; gnus-summary-mode.  To get make that work you just need a couple of
  63 ;; hooks.
  64 ;; (setq gnus-use-grouplens t)
  65 ;; (setq grouplens-pseudonym "")
  66 ;; (setq grouplens-bbb-host "grouplens.cs.umn.edu")
  67 ;;
  68 ;; (setq gnus-summary-default-score 0)
  69 ;;
  70 ;;                              USING GROUPLENS
  71 ;; How do I Rate an article??
  72 ;;   Before you type n to go to the next article, hit a number from 1-5
  73 ;;   Type r in the summary buffer and you will be prompted.
  74 ;;   Note that when you're in grouplens-minor-mode 'r' masks the
  75 ;;   usual reply binding for 'r'
  76 ;;
  77 ;; What if, Gasp, I find a bug???
  78 ;; Please type M-x gnus-gl-submit-bug-report.  This will set up a
  79 ;; mail buffer with the  state of variables and buffers that will help
  80 ;; me debug the problem.  A short description up front would help too!
  81 ;;
  82 ;; How do I display the prediction for an article:
  83 ;;  If you set the gnus-summary-line-format as shown above, the score
  84 ;;  (prediction) will be shown automatically.
  85 ;;
  86 ;;
  87 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  88 ;; Programmer  Notes
  89 ;; 10/9/95
  90 ;; gnus-scores-articles contains the articles
  91 ;; When scoring is done, the call tree looks something like:
  92 ;; gnus-possibly-score-headers
  93 ;;  ==> gnus-score-headers
  94 ;;      ==> gnus-score-load-file
  95 ;;          ==> get-all-mids  (from the eval form)
  96 ;;
  97 ;; it would be nice to have one that gets called after all the other
  98 ;; headers have been scored.
  99 ;; we may want a variable gnus-grouplens-scale-factor
 100 ;; and gnus-grouplens-offset  this would probably be either -3 or 0
 101 ;; to make the scores centered around zero or not.
 102 ;; Notes 10/12/95
 103 ;; According to Lars, Norse god of gnus, the simple way to insert a
 104 ;; call to an external function is to have a function added to the
 105 ;; variable gnus-score-find-files-function  This new function
 106 ;; gnus-grouplens-score-alist will return a core alist that
 107 ;; has (("message-id" ("<message-id-xxxx>" score) ("<message-id-xxxy>" score))
 108 ;; This seems like it would be pretty inefficient, though workable.
 109 ;;
 110 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 111 ;;  TODO
 112 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 113 ;;
 114 ;; 3. Add some more ways to rate messages
 115 ;; 4. Better error handling for token timeouts.
 116 ;;
 117 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 118 ;; bugs
 119 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 120 ;;
 121
 122 ;;; Code:
 123
 124 (eval-when-compile (require 'cl))
 125
 126 (require 'gnus-score)
 127 (require 'gnus)
 128
 129 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 130 ;;;; User variables
 131 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 132
 133 (defvar gnus-summary-grouplens-line-format
 134   "%U\%R\%z%l%I\%(%[%4L: %-23,23n%]%) %s\n"
 135   "*The line format spec in summary GroupLens mode buffers.")
 136
 137 (defvar grouplens-pseudonym ""
 138   "User's pseudonym.
 139 This pseudonym is obtained during the registration process")
 140
 141 (defvar grouplens-bbb-host "grouplens.cs.umn.edu"
 142   "Host where the bbbd is running.")
 143
 144 (defvar grouplens-bbb-port 9000
 145   "Port where the bbbd is listening.")
 146
 147 (defvar grouplens-newsgroups
 148   '("comp.groupware" "comp.human-factors" "comp.lang.c++"
 149     "comp.lang.java" "comp.os.linux.admin" "comp.os.linux.advocacy"
 150     "comp.os.linux.announce" "comp.os.linux.answers"
 151     "comp.os.linux.development" "comp.os.linux.development.apps"
 152     "comp.os.linux.development.system" "comp.os.linux.hardware"
 153     "comp.os.linux.help" "comp.os.linux.m68k" "comp.os.linux.misc"
 154     "comp.os.linux.networking" "comp.os.linux.setup" "comp.os.linux.x"
 155     "mn.general" "rec.arts.movies" "rec.arts.movies.current-films"
 156     "rec.food.recipes" "rec.humor")
 157   "*Groups that are part of the GroupLens experiment.")
 158
 159 (defvar grouplens-prediction-display 'prediction-spot
 160   "valid values are:
 161       prediction-spot -- an * corresponding to the prediction between 1 and 5,
 162       confidence-interval -- a numeric confidence interval
 163       prediction-bar --  |#####     | the longer the bar, the better the article,
 164       confidence-bar --  |  -----   } the prediction is in the middle of the bar,
 165       confidence-spot -- )  *       | the spot gets bigger with more confidence,
 166       prediction-num  --   plain-old numeric value,
 167       confidence-plus-minus  -- prediction +/i confidence")
 168
 169 (defvar grouplens-score-offset 0
 170   "Offset the prediction by this value.
 171 Setting this variable to -2 would have the following effect on
 172 GroupLens scores:
 173
 174    1   -->   -2
 175    2   -->   -1
 176    3   -->    0
 177    4   -->    1
 178    5   -->    2
 179
 180 The reason is that a user might want to do this is to combine
 181 GroupLens predictions with scores calculated by other score methods.")
 182
 183 (defvar grouplens-score-scale-factor 1
 184   "This variable allows the user to magnify the effect of GroupLens scores.
 185 The scale factor is applied after the offset.")
 186
 187 (defvar gnus-grouplens-override-scoring 'override
 188   "Tell GroupLens to override the normal Gnus scoring mechanism.
 189 GroupLens scores can be combined with gnus scores in one of three ways.
 190 'override -- just use grouplens predictions for grouplens groups
 191 'combine  -- combine grouplens scores with gnus scores
 192 'separate -- treat grouplens scores completely separate from gnus")
 193
 194
 195 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 196 ;;;; Program global variables
 197 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 198 (defvar grouplens-bbb-token nil
 199   "Current session token number.")
 200
 201 (defvar grouplens-bbb-process nil
 202   "Process Id of current bbbd network stream process.")
 203
 204 (defvar grouplens-bbb-buffer nil
 205   "Buffer associated with the BBBD process.")
 206
 207 (defvar grouplens-rating-alist nil
 208   "Current set of  message-id rating pairs.")
 209
 210 (defvar grouplens-current-hashtable nil
 211   "A hashtable to hold predictions from the BBB.")
 212
 213 (defvar grouplens-current-group nil)
 214
 215 ;;(defvar bbb-alist nil)
 216
 217 (defvar bbb-timeout-secs 10
 218   "Number of seconds to wait for some response from the BBB.
 219 If this times out we give up and assume that something has died..." )
 220
 221 (defvar grouplens-previous-article nil
 222   "Message-ID of the last article read.")
 223
 224 (defvar bbb-read-point)
 225 (defvar bbb-response-point)
 226
 227 (defun bbb-renew-hash-table ()
 228   (setq grouplens-current-hashtable (make-vector 100 0)))
 229
 230 (bbb-renew-hash-table)
 231
 232 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 233 ;;;;  Utility Functions
 234 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 235
 236 (defun bbb-connect-to-bbbd (host port)
 237   (unless grouplens-bbb-buffer
 238     (setq grouplens-bbb-buffer
 239           (gnus-get-buffer-create (format " *BBBD trace: %s*" host)))
 240     (save-excursion
 241       (set-buffer grouplens-bbb-buffer)
 242       (make-local-variable 'bbb-read-point)
 243       (make-local-variable 'bbb-response-point)
 244       (setq bbb-read-point (point-min))))
 245
 246   ;; if an old process is still running for some reason, kill it
 247   (when grouplens-bbb-process
 248     (ignore-errors
 249       (when (eq 'open (process-status grouplens-bbb-process))
 250         (set-process-buffer grouplens-bbb-process nil)
 251         (delete-process grouplens-bbb-process))))
 252
 253   ;; clear the trace buffer of old output
 254   (save-excursion
 255     (set-buffer grouplens-bbb-buffer)
 256     (erase-buffer))
 257
 258   ;; open the connection to the server
 259   (catch 'done
 260     (condition-case error
 261         (setq grouplens-bbb-process
 262               (open-network-stream "BBBD" grouplens-bbb-buffer host port))
 263       (error (gnus-message 3 "Error: Failed to connect to BBB")
 264              nil))
 265     (and (null grouplens-bbb-process)
 266          (throw 'done nil))
 267     (save-excursion
 268       (set-buffer grouplens-bbb-buffer)
 269       (setq bbb-read-point (point-min))
 270       (or (bbb-read-response grouplens-bbb-process)
 271           (throw 'done nil))))
 272
 273   ;; return the process
 274   grouplens-bbb-process)
 275
 276 (defun bbb-send-command (process command)
 277   (goto-char (point-max))
 278   (insert command)
 279   (insert "\r\n")
 280   (setq bbb-read-point (point))
 281   (setq bbb-response-point (point))
 282   (set-marker (process-mark process) (point)) ; process output also comes here
 283   (process-send-string process command)
 284   (process-send-string process "\r\n")
 285   (process-send-eof process))
 286
 287 (defun bbb-read-response (process)
 288   "This function eats the initial response of OK or ERROR from the BBB."
 289   (let ((case-fold-search nil)
 290         match-end)
 291     (goto-char bbb-read-point)
 292     (while (and (not (search-forward "\r\n" nil t))
 293                 (accept-process-output process bbb-timeout-secs))
 294       (goto-char bbb-read-point))
 295     (setq match-end (point))
 296     (goto-char bbb-read-point)
 297     (setq bbb-read-point match-end)
 298     (looking-at "OK")))
 299
 300 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 301 ;;;;       Login Functions
 302 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 303 (defun bbb-login ()
 304   "return the token number if login is successful, otherwise return nil."
 305   (interactive)
 306   (setq grouplens-bbb-token nil)
 307   (if (not (equal grouplens-pseudonym ""))
 308       (let ((bbb-process
 309              (bbb-connect-to-bbbd grouplens-bbb-host grouplens-bbb-port)))
 310         (if bbb-process
 311             (save-excursion
 312               (set-buffer (process-buffer bbb-process))
 313               (bbb-send-command bbb-process
 314                                 (concat "login " grouplens-pseudonym))
 315               (if (bbb-read-response bbb-process)
 316                   (setq grouplens-bbb-token (bbb-extract-token-number))
 317                 (gnus-message 3 "Error: GroupLens login failed")))))
 318     (gnus-message 3 "Error: you must set a pseudonym"))
 319   grouplens-bbb-token)
 320
 321 (defun bbb-extract-token-number ()
 322   (let ((token-pos (search-forward "token=" nil t)))
 323     (when (looking-at "[0-9]+")
 324       (buffer-substring token-pos (match-end 0)))))
 325
 326 (gnus-add-shutdown 'bbb-logout 'gnus)
 327
 328 (defun bbb-logout ()
 329   "logout of bbb session."
 330   (when grouplens-bbb-token
 331     (let ((bbb-process
 332            (bbb-connect-to-bbbd grouplens-bbb-host grouplens-bbb-port)))
 333       (when bbb-process
 334         (save-excursion
 335           (set-buffer (process-buffer bbb-process))
 336           (bbb-send-command bbb-process (concat "logout " grouplens-bbb-token))
 337           (bbb-read-response bbb-process))))))
 338
 339 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 340 ;;;;       Get Predictions
 341 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 342
 343 (defun bbb-build-mid-scores-alist (groupname)
 344   "this function can be called as part of the function to return the list of score files to use.
 345 See the gnus variable gnus-score-find-score-files-function.
 346
 347 *Note:*  If you want to use grouplens scores along with calculated scores,
 348 you should see the offset and scale variables.  At this point, I don't
 349 recommend using both scores and grouplens predictions together."
 350   (setq grouplens-current-group groupname)
 351   (when (member groupname grouplens-newsgroups)
 352     (setq grouplens-previous-article nil)
 353     ;; scores-alist should be a list of lists:
 354     ;;  ((("message-id" ("<mid1>" score1 nil s) ("<mid2> score2 nil s))))
 355     ;;`((("message-id" . ,predict-list))) ; Yes, this is the return value
 356     (list
 357      (list
 358       (list (append (list "message-id")
 359                     (bbb-get-predictions (bbb-get-all-mids) groupname)))))))
 360
 361 (defun bbb-get-predictions (midlist groupname)
 362   "Ask the bbb for predictions, and build up the score alist."
 363   (gnus-message 5 "Fetching Predictions...")
 364   (if grouplens-bbb-token
 365       (let ((bbb-process (bbb-connect-to-bbbd grouplens-bbb-host
 366                                               grouplens-bbb-port)))
 367         (when bbb-process
 368           (save-excursion
 369             (set-buffer (process-buff