Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the darts.lib.email-address Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:49:19 2021 GMT+0.
| • Introduction | What darts.lib.email-address is all about | |
| • Systems | The systems documentation | |
| • Modules | The modules documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
This library provides a fully RFC 5322 compliant parser for email addresses. Also provided are a few tiny helper functions, which allow the formatting of email addresses in ways, which ensures, that they are RFC 5322 compliant.
This library has been tested under
Variable: *allow-unicode*
If true, the parser functions accept arbitrary characters (with char-code > 127)
in addition to what they accept otherwise. This affects the productions
of ctext, atext, qtext, and dtext. In other words: something like
Däsiree Äßeldahl <d.äßeldahl@secret-äskulap.com>
becomes a valid email address. All base parser functions take a :allow-unicode
keyword argument, whose default value is the value of this variable.
Variable: *allow-obsolete-syntax*
If true, enable support for a few of the obs-... productions in the
RFC. This is disabled by default. Right now, enabling this option makes
R. L. Stephenson <r.l.stephenson@literature-and-coffee.cookies>
a well-formed mailbox spec. Without this option enabled, the address must be written as (e.g.)
"R. L. Stephenson" <r.l.stephenson@literature-and-coffee.cookies>
Function: parse-rfc5322-addr-spec string &key start end allow-unicode allow-trailing-junk → local-part domain error position
Parse string (or a subequence of it) as an RFC 5322 addr-spec. If
allow-unicode, characters outside of the ASCII range (i.e., with codes
> 127) are allowed virtually anywhere. See *ALLOW-UNICODE* for details,
whose value also is the default for this argument.
The values of start and end are bounding index designators for the part of string to work on.
If allow-trailing-garbage is false (the default), the parser function makes sure, that no unprocessed characters remain in the designated input region of string after a full address has successfully been parsed. If the value is true, this function does not check for unprocessed characters; the caller may inspect the returned position value to determine, whether the string was processed fully, or whether unprocessed characters remain.
This function returns four values:
local-part is the value of the address' local part. If parsing fails
early enough, this value is nil.
domain is the value of the address' domain part. If parsing fails,
before the domain is encountered, this value is nil.
error is a nil, if the string could be parsed successfully. Otherwise,
it is a keyword symbol, which indicates, why the parser stopped.
position is an integer, which identifies the first character in string, which has not been processed by this function.
Function: parse-rfc5322-mailbox string &key start end allow-unicode allow-obsolete-syntax allow-trailing-junk → local-part domain display-name error
Parse string (or a subequence of it) as an RFC 5322 mailbox. If
allow-unicode, characters outside of the ASCII range (i.e., with codes
> 127) are allowed virtually anywhere. See *ALLOW-UNICODE* for details,
whose value also is the default for this argument.
If allow-obsolete-syntax is false (the default), this function is
very strict with respect to the accepted input. In particular, none of
the obs- productions is recognized in any of the address components.
By supplying a value of true for this argument, the parser becomes more
lenient, accepting values, which have historically been accepted as
well-formed addresses. See *ALLOW-OBSOLETE-SYNTAX* for details.
The values of start and end are bounding index designators for the part of string to work on.
If allow-trailing-garbage is false (the default), the parser function makes sure, that no unprocessed characters remain in the designated input region of string after a full address has successfully been parsed. If the value is true, this function does not check for unprocessed characters; the caller may inspect the returned position value to determine, whether the string was processed fully, or whether unprocessed characters remain.
This function returns five values:
local-part is the value of the address' local part. If parsing fails
early enough, this value is nil.
domain is the value of the address' domain part. If parsing fails,
before the domain is encountered, this value is nil.
display-name is the display name found, or nil, if the address
did not contain a display name part.
error is a nil, if the string could be parsed successfully. Otherwise,
it is a keyword symbol, which indicates, why the parser stopped.
position is an integer, which identifies the first character in string, which has not been processed by this function.
Function: parse-rfc5322-mailbox-list string &key start end allow-unicode allow-obsolete-syntax → list error position
Parse string (or a subequence of it) as a comma separated list of RFC
5322 mailbox specifications. If allow-unicode, characters outside of the
ASCII range (i.e., with codes > 127) are allowed virtually anywhere.
See *ALLOW-UNICODE* for details, whose value also is the default for
this argument.
If allow-obsolete-syntax is false (the default), this function is
very strict with respect to the accepted input. In particular, none of
the obs- productions is recognized in any of the address components.
By supplying a value of true for this argument, the parser becomes more
lenient, accepting values, which have historically been accepted as
well-formed addresses. See *ALLOW-OBSOLETE-SYNTAX* for details.
The values of start and end are bounding index designators for the part of string to work on.
If allow-trailing-garbage is false (the default), the parser function makes sure, that no unprocessed characters remain in the designated input region of string after a full address has successfully been parsed. If the value is true, this function does not check for unprocessed characters; the caller may inspect the returned position value to determine, whether the string was processed fully, or whether unprocessed characters remain.
This function returns three values:
list is a list of sub-lists of the form (local-part domain display-name),
one sublist for each successfully parsed mailbox specification in the
input string. The elements appear in the order, they are found in the
input.
error is a nil, if the string could be parsed successfully. Otherwise,
it is a keyword symbol, which indicates, why the parser stopped.
position is an integer, which identifies the first character in string, which has not been processed by this function.
Function: escape-local-part string &key start end → result
Ensures, that string is properly escaped for use as the local part of an email address. If necessary, this function adds quotes and backslashes. Note, that non-ASCII characters with codes > 127 are not special cased by this function, i.e., they are implicitly allowed.
The values of start and end are bounding index designators for the part of string to work on.
Function: escape-display-name string &key start end → result
Ensures, that string is properly escaped for use as the display name of a mailbox. If necessary, this function adds quotes and backslashes. Note, that non-ASCII characters with codes > 127 are not special cased by this function, i.e., they are implicitly allowed.
The values of start and end are bounding index designators for the part of string to work on.
Structure: address
Instances of this structure represent email addresses. Basically, an address
is a pair of "local part" and "domain". After construction, address instances
are immutable.
This library defines a total ordering over all addresses, which is derived
from the lexicographic orderings of the components. When comparing for order
(i.e., using address<, address<=, address>= or address>) the domain
part is always compared first. If ambigous (i.e., if both address instances
have equal domains), the local parts are compared.
Regardless of whether the comparison is for order or for equality, the domain parts are always compared disregarding the letter case, and the local parts are always compared case-sensitively.
Function: address object → address
Tries to coerce its argument object into an instance of structure class
address, according to the following rules:
if object is already an instance of address, it is returned directly
if object is a string, it is parsed according to the RFC mailbox
production, and the results are used to construct a new address. If a
display name part is present in object, it will be ignored.
If this function cannot convert its argument into an address, it signals
an error of type type-error.
Function: address-local-part object → string
Answers the string, which is the local part of email address object
Function: address-domain object → string
Answers the string, which is the domain part of email address object
Function: address-string object → string
Answers the fully escaped string representation of email address object.
The string returned by this function may be parsed back into an address
instance (e.g. by calling the address function), and the resulting
address instance should be equivalent with object under address=.
Function: address-hash object → result
Answers a hash code for address instance object
Function: address= address1 address2 → result
Compares the addresses address1 and address2, and answers true, if both represent the same email address, and false otherwise.
Function: address/= address1 address2 → result
Compares the addresses address1 and address2, and answers true, if both represent different email addresses, and false otherwise.
Function: address< address1 address2 → result
Compares the addresses address1 and address2, and answers true, if
address1 is strictly less than address2. See the description of
structure class address for details about address ordering.
Function: address<= address1 address2 → result
Compares the addresses address1 and address2, and answers true, if
address1 is less than or equal to address2. See the description of
structure class address for details about address ordering.
Function: address>= address1 address2 → result
Compares the addresses address1 and address2, and answers true, if
address1 is greater than or equal to address2. See the description of
structure class address for details about address ordering.
Function: address> address1 address2 → result
Compares the addresses address1 and address2, and answers true, if
address1 is strictly greater than address2. See the description of
structure class address for details about address ordering.
Class: mailbox
A mailbox is basically an address combined with a display name.
This class itself does not actually provide anything interesting. It
merely exists for the purpose of type discrimination.
Class: basic-mailbox
This is a concrete implementation of the mailbox protocol.
Instances have two slots mailbox-address and mailbox-display-name.
Function: mailbox object → mailbox
Tries to coerce its argument object into an instance of class mailbox,
according to the following rules:
if object is already an instance of mailbox, it is returned directly
if object is an address, a new basic-mailbox is created, whose address
part is object, and whose display name is nil.
if object is a string, it is parsed according to the RFC mailbox
production, and the results are used to construct a new basic-mailbox.
If this function cannot convert its argument into a mailbox, it signals
an error of type type-error.
Generic Function: mailboxp object → result
Tests, whether object fulfills the mailbox protocol. This condition is
always true by definition for subclasses of class mailbox. It may additionally
be true for other objects.
Generic Function: mailbox-address object → address
Answers the address instance, which describes the actual
email address associated with mailbox object. This method is part of the
core mailbox protocol, and must be implemented by all objects, which want
to participate in that protocol.
Generic Function: mailbox-display-name object → result
Answers the display name associated with the given mailbox instance object. This function is part of the core mailbox protocol and must be implemented by all objects, which want to participate in that protocol.
Generic Function: mailbox-local-part object → result
Answers the local part string of this mailbox's address.
The default method simply extracts the address-local-part from the object
returned by mailbox-address when applied to the given object.
Generic Function: mailbox-domain object → result
Answers the domain string of this mailbox's address.
The default method simply extracts the address-domain from the object
returned by mailbox-address when applied to the given object.
Generic Function: mailbox-string object → result
Constructs a string representation of the given mailbox
instance. The result is required to be a well-formed RFC 5322 email address
parsable using the mailbox production. The default method should be usable
by almost all concrete mailbox implementat
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The darts.lib.email-address system |
Dirk Eßer
Dirk Esser
MIT
Parsing and formatting email addresses (RFC 5322 compliant)
0.1
darts.lib.email-address.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
| • The darts.lib.email-address/src module |
darts.lib.email-address (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The darts.lib.email-address.asd file | ||
| • The darts.lib.email-address/src/package.lisp file | ||
| • The darts.lib.email-address/src/parser.lisp file | ||
| • The darts.lib.email-address/src/objects.lisp file |
Next: The darts․lib․email-address/src/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
darts.lib.email-address.asd
darts.lib.email-address (system)
Next: The darts․lib․email-address/src/parser․lisp file, Previous: The darts․lib․email-address․asd file, Up: Lisp files [Contents][Index]
src (module)
src/package.lisp
Next: The darts․lib․email-address/src/objects․lisp file, Previous: The darts․lib․email-address/src/package․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/parser.lisp
Previous: The darts․lib․email-address/src/parser․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/objects.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The darts.asdf package | ||
| • The darts.lib.email-address package |
Next: The darts․lib․email-address package, Previous: Packages, Up: Packages [Contents][Index]
darts.lib.email-address.asd
Previous: The darts․asdf package, Up: Packages [Contents][Index]
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported structures | ||
| • Exported classes |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
parser.lisp (file)
parser.lisp (file)
Next: Exported generic functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
escape-display-name STRING &optional START END => ANSWER
Returns a copy of the portion of STRING between START (incl.) and END (excl.). If necessary, this function adds quotes around the result, and makes sure, that it satisfies the rules of an email display name.
parser.lisp (file)
escape-local-part STRING &optional START END => ANSWER
Returns a copy of the portion of STRING between START (incl.) and END (excl.). If necessary, this function adds quotes around the result, and makes sure, that internal occurrences of #\\ and #\" are properly escaped.
parser.lisp (file)
Coerces the given ‘value’ into an instance of class ‘mailbox’ or
a suitable subclass.
- if ‘value’ is already a ‘mailbox’, it is directly returned
- if ‘value’ is an ‘address’, a new mailbox instance is created,
using that address and a display name value of nil.
- if ‘value’ is a string, it is parsed according to the RFC 5322
‘mailbox’ production and a mailbox instance is created from the
results.
If the value cannot be coerced, signals a condition of type ‘type-error’.
objects.lisp (file)
Creates a new address from the given component values ‘local-part’ and ‘domain’. Both arguments must be strings. Note, that this function currently does not validate the contents of the given local part and domain values.
objects.lisp (file)
parse-rfc5322-addr-spec STRING &key START END => LOCAL-PART DOMAIN POSITION
Parses an email address (rule addr-spec in RFC 5322) from STRING, starting at
index START (inclusive, defaults to 0), and stopping at index END (exclusive,
defaults to the length of STRING).
Returns four values
1. the local part of the email address
2. the domain part of the email address
3. an error code, or nil, if the parsing was successful
4. the index of the first character not processed
This function stops after finding a complete email address, when it encounters an error, or when reaching the END index. The following error codes are defined:
nil no error, a full email address has been found
:bad-local-part no valid local part could be found
:missing-separator the ‘@´ was not found
:bad-domain no valid domain part could be found
:trailing-garbage unprocessed characters remain after the address
parser.lisp (file)
parse-rfc5322-mailbox STRING &optional START END => LOCAL-PART DOMAIN DISPLAY-NAME ERROR POSITION
parser.lisp (file)
parser.lisp (file)
Next: Exported structures, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Answers the ‘address’ instance, which describes the actual
email address associated with mailbox ‘object’. This method is part of the
core mailbox protocol, and must be implemented by all objects, which want
to participate in that protocol.
objects.lisp (file)
automatically generated reader method
Answers the display name associated with the given mailbox
instance ‘object’. This function is part of the core mailbox protocol and
must be implemented by all objects, which want to participate in that
protocol.
objects.lisp (file)
automatically generated reader method
Answers the domain string of this mailbox’s address.
The default method simply extracts the ‘address-domain’ from the object
returned by ‘mailbox-address’ when applied to the given ‘object’.
objects.lisp (file)
Answers the local part string of this mailbox’s address.
The default method simply extracts the ‘address-local-part’ from the object
returned by ‘mailbox-address’ when applied to the given ‘object’.
objects.lisp (file)
Constructs a string representation of the given mailbox
instance. The result is required to be a well-formed RFC 5322 email address
parsable using the ‘mailbox’ production. The default method should be usable
by almost all concrete ‘mailbox’ implementations.
objects.lisp (file)
Tests, whether ‘object’ fulfills the ‘mailbox’ protocol.
This condition is always true by definition for subclasses of class ‘mailbox’.
It may additionally be true for other objects.
objects.lisp (file)
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Plain email address, composed of the local part (a string) and the domain (another string). Instances of this structure class are immutable after construction. This structure class fully supports the mailbox protocol.
objects.lisp (file)
structure-object (structure)
simple-string
(error "missing local part")
address-local-part (function)
(setf address-local-part) (function)
simple-string
(error "missing domain")
address-domain (function)
(setf address-domain) (function)
(or null simple-string)
address-%string (function)
(setf address-%string) (function)
fixnum
-1
address-%hash (function)
(setf address-%hash) (function)
Previous: Exported structures, Up: Exported definitions [Contents][Index]
A simple concrete implementation of ‘mailbox’, which
stores the address and display name information in dedicated slots.
objects.lisp (file)
mailbox (class)
darts.lib.email-address:address
mailbox-address (generic function)
(or null string)
:display-name
mailbox-display-name (generic function)
A mailbox is basically an email address combined with an
optional display name for that address. This class itself is only a protocol
class, and exists for the purpose of type discrimination only.
objects.lisp (file)
standard-object (class)
basic-mailbox (class)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal macros | ||
| • Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
parser.lisp (file)
Previous: Internal macros, Up: Internal definitions [Contents][Index]
objects.lisp (file)
objects.lisp (file)
objects.lisp (file)
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
parser.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | D F L M |
|---|
| Jump to: | D F L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | %
(
A C D E F G M N P Q R |
|---|
| Jump to: | %
(
A C D E F G M N P Q R |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | %
*
D L M S |
|---|
| Jump to: | %
*
D L M S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | A B C D M P S |
|---|
| Jump to: | A B C D M P S |
|---|