[bpt/emacs.git] / lisp / gnus / utf7.el

;;; utf7.el --- UTF-7 encoding/decoding for Emacs   -*-coding: iso-8859-1;-*-

;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004,
;;   2005, 2006, 2007 Free Software Foundation, Inc.

;; Author: Jon K Hellan <hellan@acm.org>
;; Maintainer: bugs@gnus.org
;; Keywords: mail

;; This file is part of GNU Emacs.

;; GNU Emacs 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.

;; 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
;; along with GNU Emacs; see the file COPYING.  If not, write to
;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.

;;; Commentary:

;; UTF-7 - A Mail-Safe Transformation Format of Unicode - RFC 2152
;; This is a transformation format of Unicode that contains only 7-bit
;; ASCII octets and is intended to be readable by humans in the limiting
;; case that the document consists of characters from the US-ASCII
;; repertoire.
;; In short, runs of characters outside US-ASCII are encoded as base64
;; inside delimiters.
;; A variation of UTF-7 is specified in IMAP 4rev1 (RFC 2060) as the way
;; to represent characters outside US-ASCII in mailbox names in IMAP.
;; This library supports both variants, but the IMAP variation was the
;; reason I wrote it.
;; The routines convert UTF-7 -> UTF-16 (16 bit encoding of Unicode)
;; -> current character set, and vice versa.
;; However, until Emacs supports Unicode, the only Emacs character set
;; supported here is ISO-8859.1, which can trivially be converted to/from
;; Unicode.
;; When decoding results in a character outside the Emacs character set,
;; an error is thrown.  It is up to the application to recover.

;; UTF-7 should be done by providing a coding system.  Mule-UCS does
;; already, but I don't know if it does the IMAP version and it's not
;; clear whether that should really be a coding system.  The UTF-16
;; part of the conversion can be done with coding systems available
;; with Mule-UCS or some versions of Emacs.  Unfortunately these were
;; done wrongly (regarding handling of byte-order marks and how the
;; variants were named), so we don't have a consistent name for the
;; necessary coding system.  The code below doesn't seem to DTRT
;; generally.  E.g.:
;;
Commit	Line	Data
23f87bed	1	;;; utf7.el --- UTF-7 encoding/decoding for Emacs --coding: iso-8859-1;--
e84b4b86	2
61e1e4e8	3	;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004,
d7a0267c	4	;; 2005, 2006, 2007 Free Software Foundation, Inc.
c113de23 GM	5
c113de23 GM	6	;; Author: Jon K Hellan <hellan@acm.org>
23f87bed	7	;; Maintainer: bugs@gnus.org
c113de23 GM	8	;; Keywords: mail
	9
	10	;; This file is part of GNU Emacs.
	11
	12	;; GNU Emacs is free software; you can redistribute it and/or modify
	13	;; it under the terms of the GNU General Public License as published by
5a9dffec	14	;; the Free Software Foundation; either version 3, or (at your option)
c113de23 GM	15	;; any later version.
	16
	17	;; GNU Emacs is distributed in the hope that it will be useful,
	18	;; but WITHOUT ANY WARRANTY; without even the implied warranty of
	19	;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	20	;; GNU General Public License for more details.
	21
	22	;; You should have received a copy of the GNU General Public License
	23	;; along with GNU Emacs; see the file COPYING. If not, write to
3a35cf56 LK	24	;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
3a35cf56 LK	25	;; Boston, MA 02110-1301, USA.
c113de23 GM	26
c113de23 GM	27	;;; Commentary:
23f87bed MB	28
	29	;; UTF-7 - A Mail-Safe Transformation Format of Unicode - RFC 2152
	30	;; This is a transformation format of Unicode that contains only 7-bit
	31	;; ASCII octets and is intended to be readable by humans in the limiting
	32	;; case that the document consists of characters from the US-ASCII
	33	;; repertoire.
	34	;; In short, runs of characters outside US-ASCII are encoded as base64
	35	;; inside delimiters.
	36	;; A variation of UTF-7 is specified in IMAP 4rev1 (RFC 2060) as the way
	37	;; to represent characters outside US-ASCII in mailbox names in IMAP.
	38	;; This library supports both variants, but the IMAP variation was the
	39	;; reason I wrote it.
	40	;; The routines convert UTF-7 -> UTF-16 (16 bit encoding of Unicode)
	41	;; -> current character set, and vice versa.
	42	;; However, until Emacs supports Unicode, the only Emacs character set
	43	;; supported here is ISO-8859.1, which can trivially be converted to/from
	44	;; Unicode.
	45	;; When decoding results in a character outside the Emacs character set,
	46	;; an error is thrown. It is up to the application to recover.
	47
	48	;; UTF-7 should be done by providing a coding system. Mule-UCS does
	49	;; already, but I don't know if it does the IMAP version and it's not
	50	;; clear whether that should really be a coding system. The UTF-16
	51	;; part of the conversion can be done with coding systems available
	52	;; with Mule-UCS or some versions of Emacs. Unfortunately these were
	53	;; done wrongly (regarding handling of byte-order marks and how the
	54	;; variants were named), so we don't have a consistent name for the
	55	;; necessary coding system. The code below doesn't seem to DTRT
	56	;; generally. E.g.:
	57	;;
	58