Commit 39354756 authored by Max Rottenkolber's avatar Max Rottenkolber

Apply formal documentation conventions.

parent 3469d2e0
......@@ -75,7 +75,21 @@
(:q (q-decode encoded-string charset)))))
(defun decode (string &key (start 0) end)
"Decode encoded word in STRING from START to END."
"*Arguments and Values:*
_string_—a _string_.
_start_, _end_—_bounding index designators_ of _string_. The default
for _start_ is 0 and the default for _end_ is {nil}.
*Description*:
{decode} returns the decoded word in _string_.
*Exceptional Situations:*
If {decode} fails an _error condition_ is signaled."
(decode-word (subseq string start end)))
(defun crlfsp-p (string start end)
......@@ -104,10 +118,24 @@
while (and from to))))
(defun decode* (string &key (start 0) end (errorp t))
"Decode mixed STRING (possibly containing encoded as well as unencoded
words) from START to END. If an error occurs during decoding and ERRORP
is NIL, DECODE* will return the string unmodified. ERRORP is bound to {T}
by default."
"*Arguments and Values:*
_string_—a _string_.
_start_, _end_—_bounding index designators_ of _string_. The default
for _start_ is 0 and the default for _end_ is {nil}.
_error-p_—a _generalized boolean_. The default is _true_.
*Description*:
{decode*} returns a decoded copy of _string_ containing encoded as
well as unencoded words.
*Exceptional Situations:*
If {decode*} fails and _error-p_ is _true_ an _error condition_ is
signaled."
(handler-case (decode-word* (subseq string start end))
(error (error) (if errorp
(error error)
......
......@@ -75,7 +75,14 @@ destructively."
(= code *ascii-underscore*))))
(defun should-encode-p (string)
"Predicate to test if STRING should be encoded."
"*Arguments and Values:*
_string_—a _string_.
*Description*:
{should-encode-p} returns _true_ if _string_ contains characters that
need to be encoded, otherwise, returns _false_."
(when (find-if (lambda (char)
(let ((code (character-ascii char)))
(or (not code)
......@@ -106,7 +113,22 @@ destructively."
'string))
(defun encode (string &key (encoding :b) (charset :utf-8))
"Return encoded STRING using ENCODING and CHARSET."
"*Arguments and Values:*
_string_—a _string_.
_encoding_—a _keyword_. Can either be {:b} or {:q}. The default is
{:b}.
_charset_—a _keyword_ denoting the character encoding used. The
default is {:utf-8}.
*Description*:
{encode} returns an encoded copy of _string_. Words will be encoded
using _encoding_ and _charset_. If _encoding_ is {:b} then the \"B\"
encoding is used. If _encoding_ is {:q} then the \"Q\" encoding is
used."
(encoded-words encoding charset (ecase encoding
(:b (b-encode string charset))
(:q (q-encode string charset)))))
;;;; Package definition for Cl-RFC2047
(defpackage cl-rfc2047
(:documentation "Implmentation of RFC2047.")
(:documentation
"Implementation of the Email header encoding defined in
[RFC 2047](http://tools.ietf.org/html/rfc2047).")
(:use :cl
:babel
:cl-base64)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment