Remove junk from end of file.

[gnus] / contrib / vcard.el

;;; vcard.el --- vcard parsing and display routines

;; Copyright (C) 1997, 1999, 2000 Noah S. Friedman

;; Author: Noah Friedman <friedman@splode.com>
;; Maintainer: friedman@splode.com
;; Keywords: vcard, mail, news
;; Created: 1997-09-27

;; <http://www.splode.com/users/friedman/software/emacs-lisp/>
;; Id: vcard.el,v 1.11 2000/06/29 17:07:55 friedman Exp

;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This program 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
;; along with this program; if not, you can either send email to this
;; program's maintainer or write to: The Free Software Foundation,
;; Inc.; 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

;;; Commentary:

;; Unformatted vcards are just plain ugly.  But if you live in the MIME
;; world, they are a better way of exchanging contact information than
;; freeform signatures since the former can be automatically parsed and
;; stored in a searchable index.
;;
;; This library of routines provides the back end necessary for parsing
;; vcards so that they can eventually go into an address book like BBDB
;; (although this library does not implement that itself).  Also included
;; is a sample pretty-printer which MUAs can use which do not provide their
;; own vcard formatters.

;; This library does not interface directly with any mail user agents.  For
;; an example of bindings for the VM MUA, see vm-vcard.el available from
;;
;;    http://www.splode.com/~friedman/software/emacs-lisp/index.html#mail
;;
;; Updates to vcard.el should be available there too.

;; The main entry point to this package is `vcard-pretty-print' although
;; any documented variable or function is considered part of the API for
;; operating on vcard data.

;; The vcard 2.1 format is defined by the versit consortium.
;; See http://www.imc.org/pdi/vcard-21.ps
;;
;; RFC 2426 defines the vcard 3.0 format.
;; See ftp://ftp.rfc-editor.org/in-notes/rfc2426.txt

;; A parsed vcard is a list of attributes of the form
;;
;;     (proplist value1 value2 ...)
;;
;; Where proplist is a list of property names and parameters, e.g.
;;
;;     (property1 (property2 . parameter2) ...)
;;
;; Each property has an associated implicit or explicit parameter value
;; (not to be confused with attribute values; in general this API uses
;; `parameter' to refer to property values and `value' to refer to attribute
;; values to avoid confusion).  If a property has no explicit parameter value,
;; the parameter value is considered to be `t'.  Any property which does not
;; exist for an attribute is considered to have a nil parameter.

;; TODO:
;;   * Finish supporting the 3.0 extensions.
;;     Currently, only the 2.1 standard is supported.
;;   * Handle nested vcards and grouped attributes?
;;     (I've never actually seen one of these in use.)
;;   * Handle multibyte charsets.
;;   * Inverse of vcard-parse-string: write .VCF files from alist
;;   * Implement a vcard address book?  Or is using BBDB preferable?
;;   * Improve the sample formatter.

;;; Code:

(defgroup vcard nil
  "Support for the vCard electronic business card format."
  :group 'vcard
  :group 'mail
  :group 'news)

;;;###autoload
(defcustom vcard-pretty-print-function 'vcard-format-sample-box
  "*Formatting function used by `vcard-pretty-print'."
  :type 'function
  :group 'vcard)

;;;###autoload
(defcustom vcard-standard-filters
  '(vcard-filter-html
    vcard-filter-adr-newlines
    vcard-filter-tel-normalize
    vcard-filter-textprop-cr)
  "*Standard list of filters to apply to parsed vcard data.
These filters are applied sequentially to vcard attributes when
the function `vcard-standard-filter' is supplied as the second argument to
`vcard-parse'."
  :type 'hook
  :group 'vcard)

\f
;;; No user-settable options below.

;; XEmacs 21 ints and chars are disjoint types.
;; For all else, treat them as the same.
(defalias 'vcard-char-to-int
  (if (fboundp 'char-to-int) 'char-to-int 'identity))

;; This is just the version number for this package; it does not refer to
;; the vcard format specification.  Currently, this package does not yet
;; support the full vcard 3.0 specification.
;;
;; Whenever any part of the API defined in this package change in a way
;; that is not backward-compatible, the major version number here should be
;; incremented.  Backward-compatible additions to the API should be
;; indicated by increasing the minor version number.
(defconst vcard-api-version "2.0")

;; The vcard standards allow specifying the encoding for an attribute using
;; these values as immediate property names, rather than parameters of the
;; `encoding' property.  If these are encountered while parsing, associate
;; them as parameters of the `encoding' property in the returned structure.
(defvar vcard-encoding-tags
  '("quoted-printable" "base64" "8bit" "7bit"))

;; The vcard parser will auto-decode these encodings when they are
;; encountered.  These methods are invoked via vcard-parse-region-value.
(defvar vcard-region-decoder-methods
  '(("quoted-printable" . vcard-region-decode-quoted-printable)
    ("base64"           . vcard-region-decode-base64)))

;; This is used by vcard-region-decode-base64
(defvar vcard-region-decode-base64-table
  (let* ((a "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/")
         (len (length a))
         (tbl (make-vector 123 nil))
         (i 0))
    (while (< i len)
      (aset tbl (vcard-char-to-int (aref a i)) i)
      (setq i (1+ i)))
    tbl))

\f
;;; This function can be used generically by applications to obtain
;;; a printable representation of a vcard.

;;;###autoload
(defun vcard-pretty-print (vcard)
  "Format VCARD into a string suitable for display to user.
VCARD can be an unparsed string containing raw VCF vcard data
or a parsed vcard alist as returned by `vcard-parse-string'.

The result is a string with formatted vcard information suitable for
insertion into a mime presentation buffer.

The function specified by the variable `vcard-pretty-print-function'
actually performs the formatting.  That function will always receive a
parsed vcard alist."
  (and (stringp vcard)
       (setq vcard (vcard-parse-string vcard)))
  (funcall vcard-pretty-print-function vcard))

\f
;;; Parsing routines

;;;###autoload
(defun vcard-parse-string (raw &optional filter)
  "Parse RAW vcard data as a string, and return an alist representing data.

If the optional function FILTER is specified, apply that filter to each
attribute.  If no filter is specified, `vcard-standard-filter' is used.

Filters should accept two arguments: the property list and the value list.
Modifying in&n