[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/ebdb 639694c 4/9: Docstring changes
|
From: |
Eric Abrahamsen |
|
Subject: |
[elpa] externals/ebdb 639694c 4/9: Docstring changes |
|
Date: |
Sun, 18 Feb 2018 22:56:25 -0500 (EST) |
branch: externals/ebdb
commit 639694c3c8f7f57ed54e66a9b5193ab1e1fe8e08
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>
Docstring changes
Inspired by checkdoc.
---
ebdb-com.el | 163 ++++++++++++++++++++++-----------------
ebdb-mua.el | 96 ++++++++++++-----------
ebdb.el | 252 ++++++++++++++++++++++++++----------------------------------
3 files changed, 257 insertions(+), 254 deletions(-)
diff --git a/ebdb-com.el b/ebdb-com.el
index d9b49ce..c7afbff 100644
--- a/ebdb-com.el
+++ b/ebdb-com.el
@@ -71,9 +71,8 @@ windows by other splitting/display code."
:group 'ebdb-record-display
:type 'boolean)
-(defcustom ebdb-fill-field-values 't
- "If t, fill particularly long field values so that they fit
-within the *EBDB* buffer."
+(defcustom ebdb-fill-field-values t
+ "When non-nil, fill long field values."
:group 'ebdb-record-display
:type '(choice (const :tag "Always fill" nil)
(const :tag "Never fill" t)))
@@ -100,8 +99,8 @@ Used by `ebdb-mouse-menu'."
(defcustom ebdb-name-face-alist '((ebdb-record-person . ebdb-person-name)
(ebdb-record-organization .
ebdb-organization-name))
- "Alist matching record class types to the face that should be
- used to font-lock their names in the *EBDB* buffer."
+ "Alist of record class types to the face names.
+Faces are used to font-lock their names in the *EBDB* buffer."
:group 'ebdb-faces
:type '(repeat (cons (ebdb-record :tag "Record type") (face :tag "Face"))))
@@ -177,13 +176,11 @@ Used by `ebdb-mouse-menu'."
;;; Buffer-local variables for the database.
(defvar-local ebdb-records nil
"EBDB records list.
-
In the *EBDB* buffers it includes the records that are actually displayed
and its elements are (RECORD DISPLAY-FORMAT MARKER-POS MARK).")
(defvar-local ebdb-search-history nil
"A list of lists of previously-displayed EBDB records in this buffer.
-
For each search in a user-initiated EBDB buffer, the
previously-displayed EBDB records are pushed here, as a list of
UUIDs. ebdb-mode keybindings make it possible to pop back to
@@ -193,11 +190,12 @@ previous records.")
"Precalculated mode line info for EBDB commands.
This is a vector [INVERT-M INVERT].
-INVERT-M is the mode line info if `ebdb-search-invert' is non-nil.")
+INVERT-M is the mode line info if variable `ebdb-search-invert' is non-nil.")
(defun ebdb-get-records (prompt)
"If inside the *EBDB* buffer get the current records.
-In other buffers ask the user."
+In other buffers ask the user.
+Argument PROMPT is passed to `ebdb-completing-read-records'."
(if (eql major-mode 'ebdb-mode)
(ebdb-do-records)
(ebdb-completing-read-records prompt)))
@@ -367,10 +365,11 @@ display information."
This is a child of `special-mode-map'.")
(defun ebdb-current-record (&optional full)
- "Return the record point is at.
-If FULL is non-nil record includes the display information."
+ "Return the record under point.
+If FULL is non-nil, return a list of (record formatter
+position-marker mark)."
(unless (eq major-mode 'ebdb-mode)
- (error "This only works while in EBDB buffers."))
+ (error "This only works while in EBDB buffers"))
(let ((num (get-text-property (if (and (not (bobp)) (eobp))
(1- (point)) (point))
'ebdb-record-number))
@@ -380,7 +379,7 @@ If FULL is non-nil record includes the display information."
(if full record (car record))))
(defun ebdb-current-field ()
- "Return current field point is on."
+ "Return record field under point."
(unless (ebdb-current-record) (error "Not a EBDB record"))
(or (get-text-property (point) 'ebdb-field)
(get-text-property
@@ -431,7 +430,6 @@ If FULL is non-nil record includes the display information."
(defun ebdb-available-ebdb-formatters ()
"A list of formatters available in the *EBDB* buffer.
-
This list is also used for toggling layouts."
(seq-filter
(lambda (f) (object-of-class-p f 'ebdb-formatter-ebdb))
@@ -445,6 +443,7 @@ This list is also used for toggling layouts."
;; *EBDB* buffer formatting.
(cl-defmethod ebdb-record-db-char-string ((record ebdb-record))
+ "Return a char string indicating RECORDs databases."
(let* ((dbs (slot-value (ebdb-record-cache record) 'database))
(char-string
(concat
@@ -1113,7 +1112,7 @@ popped up from."
;;;###autoload
(define-derived-mode ebdb-mode special-mode "EBDB"
- "Major mode for viewing and editing the Insidious Big Brother Database.
+ "Major mode for viewing and editing EBDB records.
Derives from `special-mode'; the usual `special-mode' bindings apply.
@@ -1188,7 +1187,7 @@ Derives from `special-mode'; the usual `special-mode'
bindings apply.
(eieio-object-class record)))))
(defun ebdb-mouse-menu (event)
- "EBDB mouse menu for EVENT,"
+ "EBDB mouse menu for EVENT."
(interactive "e")
(mouse-set-point event)
(let* ((record (ebdb-current-record))
@@ -1282,8 +1281,7 @@ With prefix N move backwards N (sub)fields."
(ebdb-next-field (- n)))
(defun ebdb-follow-related (record field)
- "If point is on a role or relationship field, display the
- related record."
+ "Display RECORD's related record from FIELD under point."
(interactive (list (ebdb-current-record)
(ebdb-current-field)))
(condition-case nil
@@ -1297,7 +1295,8 @@ With prefix N move backwards N (sub)fields."
(ebdb-field-readable-name field)))))
(defun ebdb-toggle-record-mark (record &optional mark)
- "Mark or unmark RECORD."
+ "Mark or unmark RECORD.
+Use the symbol `mark', or the mark provided by MARK."
(interactive
(list (ebdb-current-record)
'mark))
@@ -1310,7 +1309,7 @@ With prefix N move backwards N (sub)fields."
(ebdb-redisplay-records (mapcar #'car ebdb-records) (list 'toggle-mark
'mark)))
(defun ebdb-unmark-all-records (records)
- "Remove the mark from all records."
+ "Remove the mark from RECORDS."
(interactive (list (seq-filter (lambda (r) (nth 3 r))
ebdb-records)))
(ebdb-redisplay-records (mapcar #'car records) 'unmark))
@@ -1336,7 +1335,7 @@ With prefix N move backwards N (sub)fields."
;;;###autoload
(defun ebdb-rename-buffer (new-name)
- "Rename current *EBDB* buffer."
+ "Rename current *EBDB* buffer to NEW-NAME."
(interactive (list (read-string "New buffer name: ")))
(when (eql major-mode 'ebdb-mode)
(rename-buffer
@@ -1347,7 +1346,7 @@ With prefix N move backwards N (sub)fields."
;; Unloading/Reloading/Disabling
(defun ebdb-reload-database (db)
- "Reload all records from one database."
+ "Reload all records from database DB."
(interactive (list (ebdb-prompt-for-db)))
(let ((db-str (ebdb-string db))
(rec-uuids (mapcar #'ebdb-record-uuid (slot-value db 'records))))
@@ -1449,7 +1448,7 @@ which is probably more suited for your needs."
(mapconcat #'ebdb-string (nreverse redundant) ",
"))))
(when (and redundant
(or (not query)
- (y-or-n-p (format "Delete %s: " form))))
+ (y-or-n-p (format "Delete %s? " form))))
(unless query (message "Deleting %s" form))
(dolist (m okay)
(ebdb-record-insert-field record m 'mail))
@@ -1480,7 +1479,8 @@ is the value of field LABEL of RECORD."
;;;###autoload
(defun ebdb-timestamp-older (date &optional fmt)
"Display records with timestamp older than DATE.
-DATE must be in yyyy-mm-dd format."
+DATE must be in yyyy-mm-dd format. Records are displayed using
+formatter FMT."
(interactive (list (read-string "Older than date (yyyy-mm-dd): ")
(ebdb-formatter-prefix)))
(ebdb-search-prog (ebdb-compare-records date 'timestamp #'time-less-p) fmt))
@@ -1488,7 +1488,8 @@ DATE must be in yyyy-mm-dd format."
;;;###autoload
(defun ebdb-timestamp-newer (date &optional fmt)
"Display records with timestamp newer than DATE.
-DATE must be in yyyy-mm-dd format."
+DATE must be in yyyy-mm-dd format. Records are displayed using
+formatter FMT."
(interactive (list (read-string "Newer than date (yyyy-mm-dd): ")
(ebdb-formatter-prefix)))
(ebdb-search-prog (ebdb-compare-records date 'timestamp
@@ -1498,7 +1499,8 @@ DATE must be in yyyy-mm-dd format."
;;;###autoload
(defun ebdb-creation-older (date &optional fmt)
"Display records with creation-date older than DATE.
-DATE must be in yyyy-mm-dd format."
+DATE must be in yyyy-mm-dd format. Records are displayed using
+formatter FMT."
(interactive (list (read-string "Older than date (yyyy-mm-dd): ")
(ebdb-formatter-prefix)))
(ebdb-search-prog (ebdb-compare-records date 'creation-date #'string<) fmt))
@@ -1506,14 +1508,16 @@ DATE must be in yyyy-mm-dd format."
;;;###autoload
(defun ebdb-creation-newer (date &optional fmt)
"Display records with creation-date newer than DATE.
-DATE must be in yyyy-mm-dd format."
+DATE must be in yyyy-mm-dd format. Records are displayed using
+formatter FMT."
(interactive (list (read-string "Newer than date (yyyy-mm-dd): ")
(ebdb-formatter-prefix)))
(ebdb-search-prog (ebdb-compare-records date 'creation-date #'ebdb-string>)
fmt))
;;;###autoload
(defun ebdb-creation-no-change (&optional fmt)
- "Display records that have the same timestamp and creation-date."
+ "Display records that have the same timestamp and creation-date.
+Records are displayed using formatter FMT."
(interactive (list (ebdb-formatter-prefix)))
(ebdb-search-prog
;; RECORD is bound in `ebdb-search-prog'.
@@ -1524,7 +1528,7 @@ DATE must be in yyyy-mm-dd format."
"Run BODY on all records listed in the cdr of SPEC.
This macro checks that each record is editable; ie, that it
-doesn't belong to a read-only database. It also throws an error
+doesn't belong to a read-only database. It also throws an error
and bails out if any of the database are unsynced.
Then bind each editable record to the car of SPEC in turn, run
@@ -1592,10 +1596,10 @@ actually-editable records."
;;;###autoload
(defun ebdb-create-record (db &optional record-class)
"Create a new EBDB record.
-
-Assume that we're creating a record in the first database found
-in `ebdb-db-list', using its default record class. Use
-`ebdb-create-record-extended' to be prompted for these values."
+Add record to DB, which defaults to the first database found in
+`ebdb-db-list', using its default record class, or else
+RECORD-CLASS. Use `ebdb-create-record-extended' to be prompted
+for these values."
(interactive
(list (car ebdb-db-list)))
(unless record-class
@@ -1621,6 +1625,7 @@ in `ebdb-db-list', using its default record class. Use
;;;###autoload
(defun ebdb-create-record-extended ()
+ "Create a record, prompting for database and record class."
(interactive)
(let ((db (ebdb-prompt-for-db nil t))
(record-class
@@ -1629,6 +1634,7 @@ in `ebdb-db-list', using its default record class. Use
;;;###autoload
(defun ebdb-insert-field (records)
+ "Prompt to create a field and insert it into RECORDS."
(interactive
(list (ebdb-do-records)))
(pcase-let
@@ -1655,8 +1661,9 @@ in `ebdb-db-list', using its default record class. Use
;; TODO: Allow editing of multiple record fields simultaneously.
;;;###autoload
(defun ebdb-edit-field (record field)
- "Edit the field under point. If point is on the name header of
-the record, change the name of the record."
+ "Edit RECORD's FIELD under point.
+If point is on the name header of the record, change the name of
+the record."
(interactive
(list (ebdb-current-record)
(ebdb-current-field)))
@@ -1672,6 +1679,7 @@ the record, change the name of the record."
;;;###autoload
(defun ebdb-edit-field-customize (record field)
+ "Use the customize interface to edit FIELD of RECORD."
(interactive
(list (ebdb-current-record)
(ebdb-current-field)))
@@ -1741,7 +1749,7 @@ I and J start with zero. Return the modified LIST."
(setq a (nthcdr i list)
b (nthcdr (- j i) a)
c (car b))
- (unless b (error "Args %i, %i beyond length of list." i j))
+ (unless b (error "Args %i, %i beyond length of list" i j))
(setcar b (car a))
(setcar a c)
list)))
@@ -1781,6 +1789,8 @@ If prefix NOPROMPT is non-nil, do not confirm deletion."
;;;###autoload
(defun ebdb-move-records (records db)
+ "Move all RECORDS to database DB.
+This removes the records from their current database."
(interactive (list (ebdb-do-records)
(ebdb-prompt-for-db)))
(ebdb-with-record-edits (r records)
@@ -1788,6 +1798,8 @@ If prefix NOPROMPT is non-nil, do not confirm deletion."
;;;###autoload
(defun ebdb-copy-records (records db)
+ "Copy RECORDS to database DB.
+The records also remain in their present database(s)."
(interactive (list (ebdb-do-records)
(ebdb-prompt-for-db)))
(ebdb-with-record-edits (r records)
@@ -1796,8 +1808,9 @@ If prefix NOPROMPT is non-nil, do not confirm deletion."
;;;###autoload
(defun ebdb-display-all-records (&optional fmt)
"Show all records.
-If invoked in a *EBDB* buffer point stays on the currently visible record.
-Inverse of `ebdb-display-current-record'."
+If invoked in a *EBDB* buffer point stays on the currently
+visible record. Inverse of `ebdb-display-current-record'.
+Display using formatter FMT."
(interactive (list (ebdb-formatter-prefix)))
(let ((current (ignore-errors (ebdb-current-record))))
(ebdb-display-records (ebdb-records) fmt)
@@ -1808,7 +1821,9 @@ Inverse of `ebdb-display-current-record'."
;;;###autoload
(defun ebdb-display-current-record (&optional fmt)
- "Narrow to current record. Inverse of `ebdb-display-all-records'."
+ "Narrow to current record.
+Inverse of `ebdb-display-all-records'. Display record using
+formatter FMT."
(interactive (list (ebdb-formatter-prefix)))
(ebdb-display-records (list (ebdb-current-record)) fmt))
@@ -1848,7 +1863,7 @@ With any other non-nil ARG, RECORDS are displayed
expanded."
;;;###autoload
(defun ebdb-display-records-with-fmt (records fmt)
- "Display RECORDS using FMT. "
+ "Display RECORDS using FMT."
(interactive
(list (ebdb-do-records t)
(cdr (assoc-string
@@ -1862,7 +1877,7 @@ With any other non-nil ARG, RECORDS are displayed
expanded."
;;;###autoload
(defun ebdb-omit-records (records)
- "Remove current record from the display without deleting it from EBDB.
+ "Remove RECORDS from the display without deleting them from EBDB.
With prefix N, omit the next N records. If negative, omit backwards."
(interactive (list (ebdb-do-records)))
(ebdb-redisplay-records records 'remove))
@@ -1884,12 +1899,11 @@ results -- it does this by checking
`this-command-keys'."
(defun ebdb-search-display (style clauses &optional fmt)
"Common routine for interactive searches in the *EBDB* buffer.
-
STYLE indicates whether the results are being displayed straight,
appended to existing records, or filtered from existing records.
-TYPE is the type of search being conducted (ie, 'name, 'mail,
-'address, etc). CRIT is the search criteria; often a regexp, but
-not necessarily. FMT is the optional formatter to use."
+CLAUSES is a list of search clauses, each one holding a field
+class to search on, and a search criterion to use. FMT is the
+optional formatter to use."
(let* ((prev (mapcar #'car ebdb-records))
(pool (if (eql style 'filter)
prev
@@ -1912,8 +1926,9 @@ not necessarily. FMT is the optional formatter to use."
;;;###autoload
(defun ebdb (style regexp &optional fmt)
- "Display all records in the EBDB matching REGEXP
-in any field."
+ "Display all records in the EBDB matching REGEXP.
+Search all fields, and display using formatter FMT, using style
+STYLE: meaning display, append, or filter."
(interactive (list (ebdb-search-style)
(ebdb-search-read 'all)
(ebdb-formatter-prefix)))
@@ -1928,8 +1943,8 @@ in any field."
;;;###autoload
(defun ebdb-search-name (style regexp &optional fmt)
- "Display all records in the EBDB matching REGEXP in the name
-\(or ``alternate'' names\)."
+ "Display all records in the EBDB with name matching REGEXP.
+Searches the main name, and alternate names."
(interactive (list (ebdb-search-style)
(ebdb-search-read "names")
(ebdb-formatter-prefix)))
@@ -2025,7 +2040,7 @@ in any field."
;;;###autoload
(defun ebdb-search-tags (style tags &optional fmt)
- "Run a search of record tags."
+ "Run a search of record TAGS."
(interactive (list (ebdb-search-style)
(ebdb-search-read 'ebdb-field-tags)
(ebdb-formatter-prefix)))
@@ -2036,7 +2051,7 @@ in any field."
"Search all records that have duplicate entries for FIELDS.
The list FIELDS may contain the symbols `name', `mail', and `aka'.
If FIELDS is nil use all these fields. With prefix, query for FIELDS.
-The search results are displayed in the EBDB buffer."
+The search results are displayed in the EBDB buffer using formatter FMT."
(interactive (list (if current-prefix-arg
(list (intern (completing-read "Field: "
'("name" "mail" "aka")
@@ -2082,7 +2097,7 @@ The search results are displayed in the EBDB buffer."
;;;###autoload
(defun ebdb-search-database (style db &optional fmt)
- "Select a database and show all records from that database."
+ "Select a database DB and show all records from that database."
(interactive
(list (ebdb-search-style)
(ebdb-prompt-for-db)
@@ -2091,7 +2106,7 @@ The search results are displayed in the EBDB buffer."
;;;###autoload
(defun ebdb-search-record-class (style class &optional fmt)
- "Prompt for a record class and display all records of that class."
+ "Prompt for a record CLASS and display all records of that class."
(interactive (list (ebdb-search-style)
(eieio-read-subclass
"Use which record class? " 'ebdb-record nil t)
@@ -2100,7 +2115,7 @@ The search results are displayed in the EBDB buffer."
;;;###autoload
(defun ebdb-search-single-record (record &optional fmt)
- "Prompt for a single record, and display it."
+ "Prompt for a single RECORD, and display it."
(interactive (list (ebdb-completing-read-records "Display records: ")
(ebdb-formatter-prefix)))
(ebdb-display-records record fmt))
@@ -2126,7 +2141,6 @@ the record to be displayed or nil otherwise."
;;;###autoload
(defun ebdb-mail (records &optional subject arg)
"Compose a mail message to RECORDS (optional: using SUBJECT).
-
If ARG (interactively, the prefix arg) is nil, use the first mail
address of each record. If it is t, prompt the user for which
address to use.
@@ -2146,6 +2160,9 @@ for `ebdb-field-action'."
;;; Citing
(defun ebdb-cite-records-ebdb (arg records style)
+ "Prompt for a STYLE, and use it to cite RECORDS.
+With prefix arg ARG display the citations as a vertical list,
+otherwise inline."
(interactive
(list
current-prefix-arg
@@ -2162,7 +2179,8 @@ for `ebdb-field-action'."
;;;###autoload
(defun ebdb-completion-predicate (key records)
- "For use as the third argument to `completing-read'.
+ "Check if KEY is a value key to return RECORDS.
+For use as the third argument to `completing-read'.
Obey `ebdb-completion-list'."
(cond ((null ebdb-completion-list)
nil)
@@ -2176,8 +2194,10 @@ Obey `ebdb-completion-list'."
(defun ebdb-completing-read-records (prompt &optional omit-records)
"Read and return list of records from the ebdb.
-Completion is done according to `ebdb-completion-list'. If the user
-just hits return, nil is returned. Otherwise, a valid response is forced."
+Completion is done according to `ebdb-completion-list', with
+prompt PROMPT. If the user just hits return, nil is returned.
+Otherwise, a valid response is forced. Optional argument
+OMIT-RECORDS is a list of records that should never be returned."
(unless ebdb-record-tracker
(ebdb-load))
(let* ((completion-ignore-case t)
@@ -2193,11 +2213,12 @@ just hits return, nil is returned. Otherwise, a valid
response is forced."
(defun ebdb-completing-read-record (prompt &optional omit-records)
- "Prompt for and return a single record from the ebdb;
-completion is done according to `ebdb-completion-list'. If the user
-just hits return, nil is returned. Otherwise, a valid response is forced.
-If OMIT-RECORDS is non-nil it should be a list of records to dis-allow
-completion with."
+ "Prompt for and return a single record from the ebdb.
+Completion is done according to `ebdb-completion-list', with
+prompt PROMPT. If the user just hits return, nil is
+returned. Otherwise, a valid response is forced. If OMIT-RECORDS
+is non-nil it should be a list of records to dis-allow completion
+with."
(let ((records (ebdb-completing-read-records prompt omit-records)))
(cond ((eq (length records) 1)
(car records))
@@ -2212,7 +2233,7 @@ completion with."
;;;###autoload
(defun ebdb-completing-read-mails (prompt &optional init)
- "Like `read-string', but allows `ebdb-complete-mail' style completion."
+ "Like `read-string', but with `ebdb-complete-mail' completion."
(read-from-minibuffer prompt init
ebdb-completing-read-mails-map))
@@ -2221,7 +2242,7 @@ completion with."
(modify-syntax-entry ?\\ "\\" st)
(modify-syntax-entry ?\" "\"" st)
st)
- "Syntax-table to parse matched quotes. Used by `ebdb-complete-mail'.")
+ "Syntax-table to parse matched quotes. Used by function
`ebdb-complete-mail'.")
;;;###autoload
(defun ebdb-complete-mail (&optional beg cycle-completion-buffer)
@@ -2574,7 +2595,8 @@ of all of these people.
This function is automatically called each time an EBDB buffer is
created. Alternately, use \\[ebdb-mail-aliases] in an *EBDB*
-buffer to force an update."
+buffer to force an update. With optional argument NOISY, print a
+message when updating is done."
(interactive)
;; Build `mail-aliases' if not yet done.
@@ -2603,7 +2625,7 @@ buffer to force an update."
;; `mail-abbrev-expand-hook'. We replace this with
;; `ebdb-mail-abbrev-expand-hook'
(unless (eq (symbol-function f-alias) 'mail-abbrev-expand-hook)
- (error "mail-aliases contains unexpected hook %s"
+ (error "Mail-aliases contains unexpected hook %s"
(symbol-function f-alias)))
(fset f-alias `(lambda ()
(ebdb-mail-abbrev-expand-hook
@@ -2614,7 +2636,8 @@ buffer to force an update."
(if noisy (message "EBDB mail alias: rebuilding done")))
(defun ebdb-mail-abbrev-expand-hook (_alias records)
-; (run-hook-with-args 'ebdb-mail-abbrev-expand-hook alias records)
+ "Function substituted for `mail-abbrev-expand-hook' when expanding RECORDS.
+That hook is also run."
(mail-abbrev-expand-hook)
(when ebdb-completion-display-record
(let ((ebdb-silent-internal t))
@@ -2676,7 +2699,7 @@ actions."
"Compose and send a text message using the Signal protocol.
SENDER should be a phone number (with leading \"+\") to send
-from. If `ebdb-record-self' is set, this record will be used as
+from. If option `ebdb-record-self' is set, this record will be used as
the sender, while RECORDS will be used as the list of recipients.
In both cases, `ebdb-signal-get-number' will be used to find a
usable number from the record.
@@ -2804,11 +2827,13 @@ With prefix argument ARG, prompt for which mail address
to use."
;;;###autoload
(defun ebdb-info ()
+ "Start reading the EBDB Info manual."
(interactive)
(info (format "(%s)Top" (or ebdb-info-file "ebdb"))))
;;;###autoload
(defun ebdb-help ()
+ "Print a short help message."
(interactive)
(message (substitute-command-keys "\\<ebdb-mode-map>\
new field: \\[ebdb-insert-field]; \
diff --git a/ebdb-mua.el b/ebdb-mua.el
index a33eb4e..b9be39f 100644
--- a/ebdb-mua.el
+++ b/ebdb-mua.el
@@ -63,17 +63,15 @@
"For communication between `ebdb-update-records' and `ebdb-query-create'.")
(defvar ebdb-update-records-p nil
- "For communication between `ebdb-update-records' and
- `ebdb-query-create'.")
+ "For communication between `ebdb-update-records' and `ebdb-query-create'.")
(defvar ebdb-update-records-address nil
"For communication between `ebdb-update-records' and `ebdb-query-create'.
It is a list with elements (NAME MAIL HEADER HEADER-CLASS MUA).")
(defcustom ebdb-mua-auto-update-p 'existing
- "This option governs how EBDB handles addresses found in
- incoming mail messages. It can take one of the following
- values:
+ "Specify how EBDB handles addresses in mail messages.
+It can take one of the following values:
nil Do nothing.
existing Find existing records matching ADDRESS.
@@ -202,7 +200,7 @@ This option can be directly set to a regexp. It can also
be the
symbol 'message, in which case the value of
`message-alternative-emails' will be used, or the symbol 'self,
in which case the value will be constructed from the mail
-addresses of the record pointed to by `ebdb-record-self'.
+addresses of the record pointed to by option `ebdb-record-self'.
Several EBDB commands extract either the sender or the
recipients' email addresses from a message according to
`ebdb-message-headers'. Yet an email address will be ignored if
@@ -225,7 +223,7 @@ accordingly."
((eq ebdb-user-mail-address-re 'self)
(let ((self-rec (ebdb-record-self)))
(unless self-rec
- (user-error "`ebdb-user-mail-address-re' set to 'self, but
`ebdb-record-self' is not set."))
+ (user-error "`ebdb-user-mail-address-re' set to 'self, but
`ebdb-record-self' is not set.? "))
(setq ebdb-user-mail-address-re
(regexp-opt (slot-value
(ebdb-record-cache self-rec)
@@ -404,13 +402,16 @@ are not \"noticed\", nor is the timestamp updated."
(defcustom ebdb-mua-summary-unification-list
'(name mail message-name message-mail message-address)
"List of FIELDs considered by `ebdb-mua-summary-unify'.
-For the RECORD matching the address of a message, `ebdb-mua-summary-unify'
-returns the first non-empty field value matching an element FIELD from this
list.
-Each element FIELD may be a valid argument of `ebdb-record-field' for RECORD.
-In addition, this list may also include the following elements:
+For the RECORD matching the address of a message,
+`ebdb-mua-summary-unify' returns the first non-empty field value
+matching an element FIELD from this list. Each element FIELD may
+be a valid argument of `ebdb-record-field' for RECORD. In
+addition, this list may also include the following elements:
+
message-name The name in the address of the message
message-mail The mail in the address of the message
message-address The complete address of the message
+
These provide a fallback if a message does not have a matching RECORD
or if some FIELD of RECORD is empty."
:group 'ebdb-mua
@@ -453,33 +454,37 @@ or if some FIELD of RECORD is empty."
(defcustom ebdb-mua-summary-mark "+"
"Default mark for message addresses known to EBDB.
If nil do not mark message addresses known to EBDB.
-See `ebdb-mua-summary-mark' and `ebdb-mua-summary-unify'.
+See variable `ebdb-mua-summary-mark' and `ebdb-mua-summary-unify'.
See also the field class `ebdb-field-summary-mark'."
:group 'ebdb-mua
:type '(choice (string :tag "Mark used")
(const :tag "Do not mark known posters" nil)))
(defcustom ebdb-mua-summary-unify-format-letter "E"
- "Letter required for `ebdb-mua-summary-unify' in the MUA Summary format
string.
-For Gnus, combine it with the %u specifier in `gnus-summary-line-format'
-\(see there), for example use \"%U%R%z%I%(%[%4L: %-23,23uB%]%) %s\\n\".
-For VM, combine it with the %U specifier in `vm-summary-format' (see there),
-for example, use \"%n %*%a %-17.17UB %-3.3m %2d %4l/%-5c %I\\\"%s\\\"\\n\".
-This customization of `gnus-summary-line-format' / `vm-summary-format'
-is required to use `ebdb-mua-summary-unify'.
-Currently no other MUAs support this EBDB feature."
+ "Letter used by `ebdb-mua-summary-unify' in the MUA summary format string.
+For Gnus, combine it with the %u specifier in
+`gnus-summary-line-format' see there), for example use
+\"%U%R%z%I%(%[%4L: %-23,23uB%]%) %s\\n\". For VM, combine it
+with the %U specifier in `vm-summary-format' (see there), for
+example, use \"%n %*%a %-17.17UB %-3.3m %2d %4l/%-5c
+%I\\\"%s\\\"\\n\". This customization of
+`gnus-summary-line-format' / `vm-summary-format' is required to
+use `ebdb-mua-summary-unify'. Currently no other MUAs support
+this EBDB feature."
:group 'ebdb-mua
:type 'string)
(defcustom ebdb-mua-summary-mark-format-letter "e"
- "Letter required for `ebdb-mua-summary-mark' in the MUA Summary format
string.
-For Gnus, combine it with the %u specifier in `gnus-summary-line-format'
-\(see there), for example, use \"%U%R%z%I%(%[%4L: %ue%-23,23f%]%) %s\\n\".
-For VM, combine it with the %U specifier in `vm-summary-format' (see there),
-for example, use \"%n %*%a %Ue%-17.17F %-3.3m %2d %4l/%-5c %I\\\"%s\\\"\\n\".
-This customization of `gnus-summary-line-format' / `vm-summary-format'
-is required to use `ebdb-mua-summary-mark'.
-Currently no other MUAs support this EBDB feature."
+ "Letter used by function `ebdb-mua-summary-mark' when formatting MUA summary.
+For Gnus, combine it with the %u specifier in
+`gnus-summary-line-format' (see there), for example, use
+\"%U%R%z%I%(%[%4L: %ue%-23,23f%]%) %s\\n\". For VM, combine it
+with the %U specifier in `vm-summary-format' (see there), for
+example, use \"%n %*%a %Ue%-17.17F %-3.3m %2d %4l/%-5c
+%I\\\"%s\\\"\\n\". This customization of
+`gnus-summary-line-format' / `vm-summary-format' is required to
+use function `ebdb-mua-summary-mark'. Currently no other MUAs
+support this EBDB feature."
:group 'ebdb-mua
:type 'string)
@@ -561,6 +566,8 @@ variable should be set before EBDB is loaded.")
(and val (string-match regexp val))))
(defsubst ebdb-mua-check-header (header-type address-parts &optional invert)
+ "Check if ADDRESS-PARTS is acceptable in position HEADER-TYPE.
+When optional INVERT is non-nil, invert the sense of the check."
(let ((rest (if invert
ebdb-ignore-header-alist
ebdb-accept-header-alist))
@@ -580,10 +587,11 @@ variable should be set before EBDB is loaded.")
(throw 'done t))))
(defun ebdb-mua-test-headers (header-type address-parts &optional
ignore-address)
- "Decide if the address in ADDRESS-PARTS should be ignored or
- acted upon. Return t if the header \"passes\".
+ "Decide if the address in ADDRESS-PARTS should be acted upon.
+Return t if the header \"passes\".
-Takes into consideration the IGNORE-ADDRESS argument, as well the
+Takes into consideration where the address was seen, as
+HEADER-TYPE, as well as the IGNORE-ADDRESS argument, and the
variables `ebdb-user-mail-address-re',
`ebdb-accept-header-alist', and `ebdb-ignore-header-alist'."
(let ((name (car address-parts))
@@ -740,7 +748,7 @@ Usually this function is called by the wrapper
`ebdb-mua-auto-update'."
;;; This whole thing could probably be replaced by `map-y-or-n-p'
(defun ebdb-query-create ()
"Interactive query used by `ebdb-update-records'.
-Return t if the record should be created or `nil' otherwise.
+Return t if the record should be created or nil otherwise.
Honor previous answers such as `!'."
(let ((task ebdb-offer-to-create))
;; If we have remembered what the user typed previously,
@@ -916,7 +924,7 @@ Return the records matching ADDRESS or nil."
(sit-for ignore-redundant)))
((or (eq t ignore-redundant)
ebdb-silent
- (y-or-n-p (format "Ignore redundant mail %s?"
mail)))
+ (y-or-n-p (format "Ignore redundant mail %s? "
mail)))
(setq mail redundant))))))
(setq mail (make-instance ebdb-default-mail-class :mail mail))
;; Analyze the mail part of the new records
@@ -971,7 +979,7 @@ Return the records matching ADDRESS or nil."
(sit-for ignore-redundant)))
((or (eq t ignore-redundant)
ebdb-silent
- (y-or-n-p (format "Delete %s: " form)))
+ (y-or-n-p (format "Delete %s? " form)))
(if (eq t ignore-redundant)
(message "%s: deleting %s" name form))
(setq mails okay)))))))
@@ -1035,6 +1043,9 @@ article text. This is typically used for snarfing.")
;;;###autoload
(defun ebdb-mua-update-records (&optional header-class all)
"Update all records associated with the message under point.
+When HEADER-CLASS is present, only update records for addresses
+found in that header. When ALL is non-nil, behave as if
+`ebdb-message-all-addresses' was non-nil.
This command is meant for manually updating records when
`ebdb-mua-auto-update-p' is nil: it behaves as if that option
@@ -1162,7 +1173,6 @@ where it was in the MUA, rather than quitting the EBDB
buffer."
;;;###autoload
(defun ebdb-mua-snarf-article (&optional arg)
"Snarf the body of the current article.
-
This snarfs all available record information in the article,
first attempting to associate it with the senders and recipients
of the article, afterwards prompting for the creation of new
@@ -1171,7 +1181,7 @@ records.
In addition, if a signature is present, snarf it and attempt at
associate field information in it with the article sender.
-With a prefix arg, only snarf the signature."
+With a prefix arg ARG, only snarf the signature."
(interactive "P")
(ebdb-mua-prepare-article)
(condition-case nil
@@ -1292,15 +1302,15 @@ Keys have been chosen assuming that the keymap will be
bound to
(defun ebdb-mua-summary-unify (address)
"Unify mail ADDRESS displayed for a message in the MUA Summary buffer.
-Typically ADDRESS refers to the value of the From header of a message.
-If ADDRESS matches a record in EBDB display a unified name instead of ADDRESS
-in the MUA Summary buffer.
+Typically ADDRESS refers to the value of the From header of a
+message. If ADDRESS matches a record in EBDB display a unified
+name instead of ADDRESS in the MUA Summary buffer.
Unification uses `ebdb-mua-summary-unification-list' (see there).
The first match in this list becomes the text string displayed
-for a message in the MUA Summary buffer instead of ADDRESS.
-If variable `ebdb-mua-summary-mark' is non-nil use it to precede known
addresses.
-Return the unified mail address.
+for a message in the MUA Summary buffer instead of ADDRESS. If
+variable `ebdb-mua-summary-mark' is non-nil use it to precede
+known addresses. Return the unified mail address.
Currently this works with Gnus and VM. It requires the EBDB insinuation
of these MUAs. Also, the MUA Summary format string must use
@@ -1333,7 +1343,7 @@ of these MUAs. Also, the MUA Summary format string must
use
"In the MUA Summary buffer mark messages matching a EBDB record.
ADDRESS typically refers to the value of the From header of a message.
If ADDRESS matches a record in EBDB return a mark, \" \" otherwise.
-The mark itself is the value of `ebdb-mua-summary-mark'."
+The mark itself is the value of option `ebdb-mua-summary-mark'."
(if (not ebdb-mua-summary-mark)
"" ; for consistency
;; ADDRESS is analyzed as in `ebdb-get-address-components'.
diff --git a/ebdb.el b/ebdb.el
index 126fbc5..de396a5 100644
--- a/ebdb.el
+++ b/ebdb.el
@@ -71,17 +71,15 @@
"The list of currently-loaded EBDB databases.")
(defvar ebdb-record-tracker nil
- "A list of all the loaded records")
+ "A list of all the loaded records.")
-(defvar ebdb-hashtable (make-hash-table :test 'equal)
+(defvar ebdb-hashtable (make-hash-table :test #'equal)
"Hash table for EBDB records.
Hashes the fields first-last-name, last-first-name, organization, aka,
and mail.")
-(defvar ebdb-org-hashtable (make-hash-table :size 500 :test 'equal)
- "Hash table holding relationships between organizations and
- member records.
-
+(defvar ebdb-org-hashtable (make-hash-table :size 500 :test #'equal)
+ "Hash table of role relationships.
Keys are string UUIDs of organizations. Values are lists
of (record-uuid . role-field). Hashtable entries are created and
deleted by the `ebdb-init-field' and `ebdb-delete-field' methods
@@ -123,9 +121,7 @@ will be called on each of class instances."
)))
(defcustom ebdb-auto-merge-records nil
- "If t, EBDB will automatically merge multiple records with the
-same UUID.
-
+ "If non-nil, automatically merge multiple records with the same UUID.
If you are using multiple databases, and intend to keep some
records in more than one database at once, you can set this to t
to have EBDB treat records with identical UUIDs as \"the same\"
@@ -197,12 +193,12 @@ in the future more shrinkage may be possible."
:type 'boolean)
(defgroup ebdb nil
- "The Insidious Big Brother Database."
+ "EBDB customizations"
:group 'news
:group 'mail)
(defgroup ebdb-record-edit nil
- "Variables that affect the editing of EBDB records"
+ "Variables that affect the editing of EBDB records."
:group 'ebdb)
(defgroup ebdb-sendmail nil
@@ -210,7 +206,7 @@ in the future more shrinkage may be possible."
:group 'ebdb)
(defgroup ebdb-snarf nil
- "Customizations for EBDB snarf"
+ "Customizations for EBDB snarf."
:group 'ebdb)
(put 'ebdb-snarf-snarf 'custom-loads '(ebdb-snarf))
@@ -219,11 +215,11 @@ in the future more shrinkage may be possible."
:group 'ebdb)
(defgroup ebdb-utilities nil
- "Customizations for EBDB Utilities"
+ "Customizations for EBDB utilities."
:group 'ebdb)
(defgroup ebdb-utilities-dialing nil
- "EBDB Customizations for phone number dialing"
+ "EBDB customizations for phone number dialing."
:group 'ebdb-utilities)
(defgroup ebdb-utilities-ispell nil
@@ -239,7 +235,6 @@ in the future more shrinkage may be possible."
;;; Customizable variables
(defcustom ebdb-image nil
"The default method for displaying record images.
-
If a record is given a `ebdb-field-image' field, the value of
that field specifies how or where to find the image for the
record. This option provides a default for that value.
@@ -264,7 +259,6 @@ function should return either a filename, or actual image
data."
(defcustom ebdb-uuid-function "uuidgen"
"Function used for creating a UUID for records.
-
If a string, assume a system executable. If a symbol, assume an
elisp function for creating UUIDs. For instance, `org-id-uuid'
is a good candidate."
@@ -273,14 +267,12 @@ is a good candidate."
(defcustom ebdb-record-self nil
"The UUID of the record representing the user.
-
See the docstring of `ebdb-user-mail-address-re' for possible uses."
:group 'ebdb
:type 'string)
(defcustom ebdb-country-list nil
"A list of country names known to EBDB.
-
This is a list of simple strings, which do not change EBDB's
behavior in any way. You can also require the \"ebdb-i18n\"
library for more internationally-aware functionality, in which
@@ -327,7 +319,7 @@ class, and added with the `ebdb-diary-add-entries' function.
Each entry is a two-element list: a string representation of the
anniversary date, and the sexp (as a string):
-(diary-anniversary MM DD YYYY) (the year is optional)")
+\(diary-anniversary MM DD YYYY) (the year is optional)")
;; Dynamic var needed by `diary-sexp-entry'.
(defvar original-date)
@@ -365,8 +357,8 @@ is modified. If a new ebdb record is created,
`ebdb-create-hook' is called
first, followed by a call of this hook.")
(defcustom ebdb-time-format "%Y-%m-%d %T %z"
- "The EBDB time stamp format. Used for human-readable display
-of timestamp values."
+ "The EBDB time stamp format.
+Used for human-readable display of timestamp values."
:group 'ebdb
:type 'string)
@@ -413,9 +405,7 @@ Lisp Hackers: See also `ebdb-silent-internal'."
(const :tag "Disable silent running" nil)))
(defcustom ebdb-search-transform-functions nil
- "A list of functions used to transform strings during
- searching.
-
+ "Functions used to transform strings during searching.
Each time the user enters a search search string during
interactive search, that string will be passed through each of
the functions in this list, which have a chance to modify the
@@ -506,7 +496,7 @@ It takes one argument, the name as extracted by
:type 'function)
(defsubst ebdb-record-self ()
- "Return the \"self\" record"
+ "Return the \"self\" record."
(ebdb-gethash ebdb-record-self 'uuid))
;;; Record editing
@@ -629,9 +619,7 @@ In rare cases, this may lead to confusion with EBDB's MUA
interface."
:type '(symbol :tag "Field"))
(defcustom ebdb-url-valid-schemes '("http:" "https:" "irc:")
- "A list of strings matching schemes acceptable to
- `ebdb-field-url' instances.
-
+ "Strings matching acceptable URL schemes.
Strings should not be regular expressions. They should include
the colon character."
@@ -643,8 +631,7 @@ the colon character."
If nil, always return both name and mail. If value is mail-only
never use full name. Other non-nil values mean do not use full
-name in mail address when same as mail.
-"
+name in mail address when same as mail."
:group 'ebdb-sendmail
:type '(choice (const :tag "Allow redundancy" nil)
(const :tag "Never use full name" mail-only)
@@ -656,7 +643,7 @@ name in mail address when same as mail.
:type 'boolean)
(defcustom ebdb-completion-list t
- "Controls the behaviour of `ebdb-complete-mail'.
+ "Controls the behaviour of function `ebdb-complete-mail'.
If a list of symbols, it specifies which fields to complete. Symbols include
name (= record's display name)
alt-names (= any other names the record has)
@@ -678,7 +665,7 @@ If nil, no completion is offered."
(const mail)))))
(defcustom ebdb-complete-mail-allow-cycling nil
- "If non-nil cycle mail addresses when calling `ebdb-complete-mail'."
+ "If non-nil cycle mail addresses when calling function `ebdb-complete-mail'."
:group 'ebdb-sendmail
:type 'boolean)
@@ -696,7 +683,7 @@ of corresponding mail addresses."
:type 'function)
(defcustom ebdb-completion-display-record t
- "If non-nil `ebdb-complete-mail' displays the EBDB record after completion."
+ "If non-nil function `ebdb-complete-mail' displays the EBDB record after
completion."
:group 'ebdb-sendmail
:type '(choice (const :tag "Update the EBDB buffer" t)
(const :tag "Do not update the EBDB buffer" nil)))
@@ -773,14 +760,16 @@ if CHILD-P is non-nil, one of its subclasses."
(sit-for 2))))))
(defmacro ebdb-with-exit (&rest body)
+ "Execute BODY, returning nil on quit or an empty value."
`(condition-case nil
,@body
((quit ebdb-empty)
nil)))
(defmacro ebdb-loop-with-exit (&rest body)
- "Repeat BODY, accumulating the results in a list, until the
-user either hits C-g, or enters an empty field label."
+ "Repeat BODY, accumulating the results in a list.
+\\<minibuffer-mode-map>Return when the user either hits
+\\[keyboard-quit], or enters an empty field value."
`(let (acc)
(catch '--ebdb-loop-exit--
(condition-case nil
@@ -813,7 +802,6 @@ You really should not disable debugging. But it will speed
things up."
(cl-defgeneric ebdb-init-field (field record)
"Initialize FIELD.
-
What this means is entirely dependent upon the field class in
question. Often it involves manipulating secondary data
structures such as label lists. If RECORD is given, it may also
@@ -821,7 +809,6 @@ involve using FIELD as a hash value to get to RECORD.")
(cl-defmethod ebdb-init-field (_field-value _record)
"Catch-all `ebdb-init-field' method for fields.
-
This method may also get called on field values that aren't
actually `ebdb-field' instances -- for instance, plain strings.
In those cases, assume we don't need to do anything."
@@ -829,7 +816,6 @@ In those cases, assume we don't need to do anything."
(cl-defmethod ebdb-field-readable-name ((field (subclass ebdb-field)))
"Return a human-readable string label for this class.
-
Mostly used for allowing users to pick which field type they want
to add to a record."
;; Why is there no non-private access to this? The `class-option'
@@ -844,7 +830,6 @@ to add to a record."
(cl-defgeneric ebdb-parse (field-class str &optional slots)
"Attempt to construct an instance of FIELD-CLASS using STR.
-
Implementations should extract information from STR and put it
into SLOTS, provided that SLOTS does not already contain relevant
values (ie, parsing should not override what's already in SLOTS).
@@ -889,7 +874,6 @@ Then call `cl-call-next-method' with the new values.")
(cl-defgeneric ebdb-delete-field (field &optional record unload)
"Delete FIELD.
-
Often involves un-hashing RECORD against the field value, or
removing labels from label lists.
@@ -898,7 +882,6 @@ unloaded, not actually deleted.")
(cl-defmethod ebdb-delete-field ((field ebdb-field) &optional _record _unload)
"User-level deletion routine for FIELD.
-
Override this to do any necessary cleanup work after FIELD is
removed."
(delete-instance field))
@@ -917,7 +900,6 @@ prompting.")
(cl-defmethod ebdb-read ((class (subclass ebdb-field)) &optional slots _obj)
"Complete the read/object creation process for a field of CLASS.
-
Earlier subclasses of `ebdb-field' will have read all the
necessary values into SLOTS; this base method is simply
responsible for creating the field object.
@@ -935,10 +917,9 @@ it, and if this process is successful it will get deleted."
;; base method.
(cl-defmethod ebdb-action ((field ebdb-field) record &optional idx)
- "Do an \"action\" based on one of the functions listed in FIELD's action
slot.
-
+ "Perform an \"action\" from those listed in FIELD's action slot.
If IDX is provided, it is an index indicating which of the action
-functions to call. Otherwise, call the car of the list."
+functions to call. Otherwise, call the car of the list."
(let* ((actions (slot-value field 'actions))
(pair (when actions
(if idx (or (nth idx actions) (last actions)) (car actions)))))
@@ -947,7 +928,6 @@ functions to call. Otherwise, call the car of the list."
(cl-defgeneric ebdb-notice-field (field &optional type record)
"\"Notice\" FIELD.
-
This means that a message involving RECORD has been viewed, or
that a MUA has otherwise decided that something significant to
RECORD has taken place. It is up to the class of FIELD to decide
@@ -959,12 +939,12 @@ MUAs it is one of the symbols 'sender or 'recipient.")
(cl-defmethod ebdb-notice-field ((_field ebdb-field)
&optional _type _record)
"Ask FIELD of RECORD to react to RECORD being \"noticed\".
-
When the user receives an email from or cc'd to RECORD, that
record will call `ebdb-notice' on all its fields, and give them a
chance to react somehow. TYPE is one of the symbols 'sender or
'recipient, indicating which message header the record was found
-in." nil)
+in."
+ nil)
;;; The UUID field.
@@ -1007,8 +987,8 @@ in." nil)
:documentation "A field with a string label.")
(cl-defmethod ebdb-read :around ((class (subclass ebdb-field-labeled))
&optional slots obj)
- "Prompt for a label for a new object of class CLASS, using OBJ
- as a default, and store the result in SLOTS.
+ "Prompt for a label for a new object of class CLASS.
+OBJ is used as as a default, and the results are stored in SLOTS.
All subclasses of `ebdb-field-labeled' should have a 'label-list
slot pointing to a var holding known labels for that class. This
@@ -1018,8 +998,8 @@ if it isn't.
This method also signals the 'ebdb-empty error if the user gives
an empty string as a label, which allows interruption of the read
process."
- ;; This is an :around method so the field label can be prompted for
- ;; before the value.
+ ;; FIXME: Now that labels are read after the main class, this should
+ ;; be an :after method.
(let* ((field (cl-call-next-method class slots obj))
(labels (symbol-value (oref-default class label-list)))
(human-readable (ebdb-field-readable-name class))
@@ -1039,6 +1019,7 @@ process."
field))
(cl-defmethod ebdb-init-field ((field ebdb-field-labeled) &optional _record)
+ "Add FIELD's label to its class label list."
(let ((label-var (slot-value field 'label-list)))
(ebdb-add-to-list label-var (slot-value field 'object-name))
(cl-call-next-method)))
@@ -1130,7 +1111,6 @@ process."
(cl-defmethod ebdb-parse ((class (subclass ebdb-field-name)) str &optional
slots)
"Examine STR and try to interpret it as a name.
-
This method dispatches to the equivalent method of either the
simple or complex name class."
;; Right now, all we do is send the input to field-name-simple if
@@ -1220,7 +1200,6 @@ simple or complex name class."
(cl-defmethod ebdb-name-given ((name ebdb-field-name-complex) &optional full)
"Return the given names of this name field.
-
If FULL is t, return all the given names, otherwise just the
first one."
(let ((given (slot-value name 'given-names)))
@@ -1520,9 +1499,8 @@ first one."
(cl-call-next-method class str slots)))
(defun ebdb-sort-mails (mails)
- "Sort MAILS (being instances of `ebdb-field-mail') by their
- priority slot. Primary sorts before normal sorts before
- defunct."
+ "Sort MAILS by their priority slot.
+Primary sorts before normal sorts before defunct."
(sort
mails
(lambda (l r)
@@ -1899,7 +1877,6 @@ The result looks like this:
(cl-defmethod initialize-instance ((field ebdb-field-anniversary) &optional
slots)
"Migrate from previous single-integer date value to (day month year) list.
-
This allows for anniversaries where we don't know the year.
Eventually this method will go away."
(when (integerp (plist-get slots :date))
@@ -2082,7 +2059,6 @@ Eventually this method will go away."
(str string)
&optional slots)
"Parse a URL.
-
See `ebdb-url-valid-schemes' for a list of acceptable schemes."
(when (null (plist-get slots :url))
(if (string-match-p (regexp-opt ebdb-url-valid-schemes) str)
@@ -2310,7 +2286,6 @@ See `ebdb-url-valid-schemes' for a list of acceptable
schemes."
(defvar ebdb-mail-alias-alist nil
"An alist holding all alias definitions from EBDB.
-
Each element looks like: (alias (rec1 addr1) (rec2 addr2) ...).
Instead of actual records, the rec1, rec2 elements can also be
@@ -2417,7 +2392,7 @@ record uuids.")
;; record for information, and the cache method intercepts the call,
;; returns the value if it has it, and if not then asks the record for
;; the value then stores it. Ie, a real cache. Not all the cache
-;; slots would work that way, of course -- for instance. a record has
+;; slots would work that way, of course -- for instance, a record has
;; no way of knowing its databases except via the cache.
(defclass ebdb-cache ()
@@ -2458,8 +2433,6 @@ record uuids.")
:initform nil
:documentation
"The database(s) this record belongs to."))
- ;; I'm not sure if a marker slot is still going to be necessary in
- ;; this setup.
:allow-nil-initform t)
;;; Records
@@ -2489,7 +2462,7 @@ record uuids.")
:type (list-of ebdb-field-user)
:initform nil
:documentation "This slot contains all record fields except
- those built-in to record subclasses.")
+ those built in to record subclasses.")
(image
:initarg :image
:type (or null ebdb-field-image)
@@ -2508,7 +2481,6 @@ record uuids.")
:initarg :cache
:type (or null ebdb-cache)
:initform nil
- ;:accessor ebdb-record-cache
))
:abstract t
:allow-nil-initform t
@@ -2517,7 +2489,6 @@ record uuids.")
(cl-defgeneric ebdb-init-record (record)
"Initialize RECORD.
-
Specific behavior is determined by subclass, but usually involves
setting up RECORD's cache, and calling `ebdb-init-field' on the
record's fields.
@@ -2528,7 +2499,6 @@ database(s).")
(cl-defgeneric ebdb-delete-record (record &optional db unload)
"Delete RECORD.
-
This goes through a series of deletion routines, removing RECORD
from its respective databases, un-hashing its uuid, running
`ebdb-delete-field' on its fields, etc.
@@ -2540,7 +2510,6 @@ altogether.")
(cl-defgeneric ebdb-record-change-name (record name)
"Change RECORD's name to NAME.
-
NAME can be an instance of `ebdb-field-name' or one of its
subclasses, or it can be a string, in which case the class of
RECORD is responsible for parsing it correctly.")
@@ -2551,7 +2520,7 @@ RECORD is responsible for parsing it correctly.")
(slot-value uuid-field 'uuid))))
(cl-defmethod ebdb-read ((class (subclass ebdb-record)) &optional slots)
- "Create a new record from the values collected into SLOTS."
+ "Create a new record of class CLASS from the values in SLOTS."
;; All the other `ebdb-read' methods for record subclasses "bottom
;; out" here, and create a record.
(let ((notes (ebdb-with-exit (ebdb-read ebdb-default-notes-class))))
@@ -2594,8 +2563,7 @@ RECORD is responsible for parsing it correctly.")
(cl-call-next-method record slots)))
(cl-defmethod ebdb-init-record ((record ebdb-record))
- "Initiate a record after loading a database or creating a new
-record."
+ "Initiate RECORD after loading or creation."
(dolist (field (ebdb-record-user-fields record))
(ebdb-init-field field record))
(ebdb-record-set-sortkey record))
@@ -2636,7 +2604,6 @@ record."
(cl-defgeneric ebdb-record-field-slot-query (record-class &optional query
alist)
"Ask RECORD-CLASS for information about its interactively-settable fields.
-
If QUERY is nil, simply return ALIST, which is a full list of
acceptable fields. Each list element is a cons of the form (SLOT
. FIELDCLASS), meaning that RECORD-CLASS can accept fields of
@@ -2650,19 +2617,16 @@ either case is a cons with both slot and fieldclass
filled in.")
(cl-defgeneric ebdb-record-insert-field (record field &optional slot)
"Insert FIELD into RECORD.
-
If SLOT is given, insert FIELD into that slot. Otherwise, the
slot will be found programmatically.")
(cl-defgeneric ebdb-record-delete-field (record field &optional slot)
"Delete FIELD from RECORD.
-
If SLOT is given, delete FIELD from that slot. Otherwise, the
slot will be found programmatically.")
(cl-defgeneric ebdb-record-change-field (record old-field &optional new-field)
"Change RECORD's field OLD-FIELD.
-
If NEW-FIELD is given, OLD-FIELD will be replaced with NEW-FIELD.
Otherwise, the user will be prompted to create a new field, using
OLD-FIELD's values as defaults.")
@@ -2679,6 +2643,8 @@ OLD-FIELD's values as defaults.")
(setq field (ebdb-db-add-record-field db record slot field))))
(when field
(condition-case nil
+ ;; We don't know if slot holds a single field, or a list of
+ ;; fields. This is a hack.
(object-add-to-list record slot field)
(invalid-slot-type
(setf (slot-value record slot) field)))
@@ -2756,7 +2722,6 @@ OLD-FIELD's values as defaults.")
(cl-defgeneric ebdb-record-current-fields (record &optional f-list all)
"Return an alist of all RECORD's current fields.
-
Each element of the alist is a cons of (slot-name
. field-instance), where slot-name is a symbol, and
field-instance is an instance of a subclass of `ebdb-field'.
@@ -2816,6 +2781,7 @@ by the field, or else raising the error
`ebdb-related-unfound'.")
(cl-defmethod ebdb-record-insert-field ((record ebdb-record)
(field ebdb-field-singleton)
&optional _slot)
+ "Prevent RECORD from having more than one instance of FIELD."
(let ((existing (ebdb-record-field record (eieio-object-class field))))
(when existing
(ebdb-record-delete-field record existing))
@@ -2826,7 +2792,6 @@ by the field, or else raising the error
`ebdb-related-unfound'.")
(cl-defmethod ebdb-field-image-get ((field ebdb-field-image) (record
ebdb-record))
"Return the image for image field FIELD.
-
This function returns an actual image, suitable for display with
`insert-image'."
(let* ((image-slot (slot-value field 'image))
@@ -2848,7 +2813,6 @@ This function returns an actual image, suitable for
display with
(cl-defmethod ebdb-field-image-function ((_field ebdb-field-image) (_record
ebdb-record))
"Return image data for RECORD from image field FIELD.
-
The return value of this function will be passed to
`create-image', which see. It can either be an image file name,
or actual image data."
@@ -2875,7 +2839,6 @@ or actual image data."
(cl-defmethod ebdb-field-anniversary-calendar ((_record ebdb-record)
(field ebdb-field-anniversary))
"Go to the date of anniversary FIELD in the calendar.
-
If FIELD doesn't specify a year, use the current year."
;; This and the next function should be rethought. Do people really
;; want to look at the original date? Won't they usually want to
@@ -2892,7 +2855,6 @@ If FIELD doesn't specify a year, use the current year."
(cl-defmethod ebdb-field-anniversary-agenda ((_record ebdb-record)
(field ebdb-field-anniversary))
"Go to the date of anniversary FIELD in the Org agenda.
-
If FIELD doesn't specify a year, use the current year."
(let ((date (slot-value field 'date)))
(org-agenda-list
@@ -3023,7 +2985,8 @@ priority."
(setf (slot-value record 'mail) sorted)))
(defun ebdb-compose-mail (&rest args)
- "Start composing a mail message to send."
+ "Start composing a mail message to send.
+ARGS is passed to `compose-mail'."
(apply 'compose-mail args))
(cl-defmethod ebdb-field-mail-compose ((record ebdb-record-entity)
@@ -3470,7 +3433,7 @@ instances to add as part of the role."
:documentation "A record class representing a mailing list.")
(cl-defmethod ebdb-read ((_class (subclass ebdb-record-mailing-list))
&optional _db _slots)
- (error "Mailing list records haven't been implemented yet."))
+ (error "Mailing list records haven't been implemented yet"))
;;; Merging
@@ -3483,8 +3446,9 @@ instances to add as part of the role."
;; 'timestamp
(defun ebdb-check-uuid (uuid)
- "Ensure that UUID hasn't been seen before. If it has, raise an
-error containing the record that already has that uuid."
+ "Ensure that UUID hasn't been seen before.
+If it has, raise an error containing the record that already has
+that uuid."
(let ((dup (ebdb-gethash uuid 'uuid)))
(when dup
(signal 'ebdb-duplicate-uuid
@@ -3492,10 +3456,11 @@ error containing the record that already has that uuid."
(defun ebdb-make-uuid (&optional prefix)
"Create and return a new UUID.
-
This depends on the value of `ebdb-uuid-function'. When that
variable is a string, assume the string refers to a system
-executable. When a symbol, assume an Elisp function."
+executable. When a symbol, assume an Elisp function. If
+optional argument PREFIX is given, add that prefix to the uuid
+string."
(let ((prefix-string (unless (string-empty-p prefix)
(concat prefix "-")))
(uid
@@ -3670,7 +3635,6 @@ not be instantiated directly, subclass it instead."
(defun ebdb-auto-save-databases ()
"Auto-save all EBDB databases.
-
Run as a hook in the `auto-save-hook"
(dolist (d ebdb-db-list)
(with-slots (auto-save disabled read-only) d
@@ -3689,7 +3653,8 @@ Run as a hook in the `auto-save-hook"
;;; should call `cl-call-next-method' to run the methods below.
(cl-defmethod ebdb-db-unsynced ((db ebdb-db))
- "Return t if DB's persistence file has been accessed since the
+ "Check if DB is out of sync.
+Returns t if DB's persistence file has been accessed since the
last time DB was loaded.
This is the base implementation, which only checks if DB's
@@ -3725,7 +3690,6 @@ overwrite data somewhere."
(cl-defgeneric ebdb-db-load-records (db records)
"Load RECORDS into DB.
-
This method is responsible for adding DB to records' caches,
checking their uuid, and hashing the uuid. It happens at two
different points: after loading DB, and when adding a record to
@@ -3799,7 +3763,6 @@ DB.")
(cl-defmethod ebdb-db-unload ((db ebdb-db))
"Unload database DB.
-
This involves going through DB's records and removing each one
that doesn't belong to a different database."
(dolist (r (slot-value db 'records))
@@ -3811,7 +3774,6 @@ that doesn't belong to a different database."
(defun ebdb-db-reload (db)
"Reload DB.
-
This consists of unloading all DB's records, re-reading its
database definition from file, and then reloading all the
records."
@@ -3842,9 +3804,8 @@ records."
(run-hook-with-args 'ebdb-before-read-db-hook db))
(cl-defgeneric ebdb-db-editable (db &optional noerror reload)
- "Check that DB is in an editable state, and signal an error if
-it isn't. This method is called before most operations that
-would alter DB.
+ "If DB can't be edited, signal an error.
+This method is called before most operations that would alter DB.
With optional argument NOERROR, return nil instead of signalling
an error. With optional argument RELOAD, reload DB if it is out
@@ -4066,7 +4027,6 @@ process.")
(defun ebdb-class-in-list-p (class list)
"Check if CLASS is a member of LIST.
-
Both CLASS and the members of LIST should be class-name symbols.
CLASS is \"in\" list if the symbol appears directly in the list,
or if CLASS is a subclass of one of the classes in LIST. The
@@ -4099,7 +4059,7 @@ in the second."
(defun ebdb-prompt-for-record (&optional records class)
"Prompt for a single record, and return it.
-If RECORDS is a list of records, offer choices from that list. If
+If RECORDS is a list of records, offer choices from that list. If
CLASS is given, only offer choices that are an instance of that
class, or its subclasses."
(let* ((recs (or records (ebdb-records)))
@@ -4125,7 +4085,6 @@ class, or its subclasses."
(defun ebdb-prompt-for-field-type (fields)
"Prompt the user for a field from FIELDS.
-
Returns a list of (\"label\" slot . field-class)."
;; Fields that have labels will provide those labels as a sort of
;; "second level" of choice. So our top-level choices should be:
@@ -4173,6 +4132,8 @@ prompting if there's only one database."
(object-assoc db-string 'object-name collection))))
(defun ebdb-prompt-for-mail (record)
+ "Prompt for one of RECORD's mail addresses.
+If RECORD only has one address, return that directly."
(let ((mail-alist (mapcar
(lambda (m) (cons (ebdb-string m) m))
(ebdb-record-mail record t))))
@@ -4185,7 +4146,6 @@ prompting if there's only one database."
(defun ebdb-dirty-records (&optional records)
"Return all records with unsaved changes.
-
If RECORDS are given, only search those records."
(seq-filter
(lambda (r)
@@ -4222,7 +4182,6 @@ If RECORDS are given, only search those records."
(defun ebdb-record-mail (record &optional roles label defunct)
"Return a list of all RECORD's mail fields.
-
If ROLES is non-nil, also consider mail fields from RECORD's
roles. If LABEL is a string, return the mail with that label.
If DEFUNCT is non-nil, also consider RECORD's defunct mail
@@ -4248,7 +4207,6 @@ addresses."
(defun ebdb-dwim-mail (record &optional mail)
;; Do What I Mean!
"Return a string to use as the mail address of RECORD.
-
However, if both the first name and last name are constituents of
the address as in address@hidden, and
`ebdb-mail-avoid-redundancy' is non-nil, then the address is used
@@ -4297,7 +4255,6 @@ RECORD. If MAIL is nil use RECORD's primary mail
address."
(defun ebdb-signal-get-number (record &optional no-prompt)
"Extract a usable Signal number from RECORD.
-
If any of RECORD's phone numbers have \"signal\" label, use that.
Alternately, if there is only one phone labeled \"cell\" or
\"mobile\", use that. Alternately, if NO-PROMPT is nil, prompt
@@ -4328,8 +4285,7 @@ leading \"+\"."
(cl-defmethod ebdb-field-phone-signal-text ((_record ebdb-record-entity)
(phone-field ebdb-field-phone))
- "Use the Signal protocol to compose a text message to RECORD.
-
+ "Use the Signal protocol to compose a text message.
PHONE-FIELD will be the number used as the recipient.
This is a field action version of `ebdb-signal-text', see that
@@ -4358,7 +4314,9 @@ command's docstring for more details."
(message "Please set `ebdb-signal-program'"))))
(defun ebdb--signal-text (sender message recipients &optional attachments)
- "Internal function for actually sending the SMS."
+ "Internal function for actually sending the SMS.
+Arguments SENDER, MESSAGE, RECIPIENTS and optional ATTACHMENTS
+are passed directly to the Signal executable."
(let ((command
(concat ebdb-signal-program
(format " -u %s -m %s" sender message)
@@ -4416,7 +4374,8 @@ The inverse function of `ebdb-split'."
(mapconcat 'identity
(delete "" (apply 'append (mapcar (lambda (x) (if (stringp x)
(list x) x))
- strings))) separator))
+ strings)))
+ separator))
(defun ebdb-list-strings (list)
"Remove all elements from LIST which are not non-empty strings."
@@ -4428,9 +4387,9 @@ The inverse function of `ebdb-split'."
(defun ebdb-read-string (prompt &optional init collection require-match)
"Read a string, trimming whitespace and text properties.
-PROMPT is a string to prompt with.
-INIT appears as initial input which is useful for editing existing records.
-COLLECTION and REQUIRE-MATCH have the same meaning as in `completing-read'."
+PROMPT is a string to prompt with. INIT appears as initial input
+which is useful for editing existing records. COLLECTION and
+REQUIRE-MATCH have the same meaning as in `completing-read'."
(ebdb-string-trim
(if collection
;; Hack: In `minibuffer-local-completion-map' remove
@@ -4462,6 +4421,7 @@ The return value is the new value of LIST-VAR."
(symbol-value list-var)
(set list-var (cons element (symbol-value list-var)))))
+;; FIXME: Get rid of this add-job and eval-spec stuff.
(defsubst ebdb-add-job (spec record string)
"Internal function: Evaluate SPEC for RECORD and STRING.
If SPEC is a function call it with args RECORD and STRING. Return value.
@@ -4503,7 +4463,10 @@ and CANONICAL-ADDRESS through
`ebdb-canonicalize-mail-function'."
"Given an RFC-822 address ADDRESS, extract full name and canonical address.
This function behaves like `mail-extract-address-components', but it passes
its return value through `ebdb-clean-address-components'.
-See also `ebdb-decompose-ebdb-address'."
+See also `ebdb-decompose-ebdb-address'.
+
+If optional argument ALL is non-nil, pass it to
+`mail-extract-address-components' to extract multiple addresses."
(if all
(mapcar 'ebdb-clean-address-components
(mail-extract-address-components address t))
@@ -4554,9 +4517,10 @@ and canonical addresses in the mail field of EBDB
records."
;;; Massage of mail addresses
(defun ebdb-canonicalize-mail-1 (address)
- "Example of `ebdb-canonicalize-mail-function'.
-However, this function is too specific to be useful for the general user.
-Take it as a source of inspiration for what can be done."
+ "Canonicalize ADDRESS.
+This is an example of `ebdb-canonicalize-mail-function'. It's
+probably too specific to be useful for the general user, but can
+be taken as a source of inspiration for what's possible."
(setq address (ebdb-string-trim address))
(cond
;; Rewrite mail-drop hosts.
@@ -4675,11 +4639,11 @@ KEY must be a string or nil. Empty strings and nil are
ignored."
ebdb-hashtable))))
(defun ebdb-gethash (key &optional predicate)
- "Return list of records associated with KEY in
-`ebdb-hashtable'. KEY must be a string or nil. Empty strings
-and nil are ignored. PREDICATE may take the same values as
-`ebdb-completion-list'. If predicate is the single symbol uuid,
-this function returns a single record."
+ "Return records associated with KEY in `ebdb-hashtable'.
+KEY must be a string or nil. Empty strings and nil are ignored.
+PREDICATE may take the same values as `ebdb-completion-list'. If
+predicate is the single symbol uuid, this function returns a
+single record, otherwise returns a list."
(when (and key (not (string-empty-p key)))
(let* ((key (downcase key))
(all-records (gethash key ebdb-hashtable))
@@ -4738,8 +4702,8 @@ KEY must be a string or nil. Empty strings and nil are
ignored."
(remhash key ebdb-hashtable))))))
(defun ebdb-hash-update (record old new)
- "Update hash for RECORD. Remove OLD, insert NEW.
-Both OLD and NEW are lists of values."
+ "Update hash for RECORD.
+Remove OLD, insert NEW. Both OLD and NEW are lists of values."
(dolist (elt old)
(ebdb-remhash elt record))
(dolist (elt new)
@@ -4777,7 +4741,6 @@ Set and store it if necessary."
(cl-defgeneric ebdb-record-field (record field)
"For RECORD return the value of FIELD.
-
FIELD may be a slot-name symbol, in which case the value of that
slot, if any, is returned. It can be a string, in which case it
is interpreted as a label for one of RECORD's user fields. It
@@ -4812,17 +4775,17 @@ also be one of the special symbols below.
(slot-value record field)))))
(cl-defmethod ebdb-record-field ((record ebdb-record)
- (field (subclass ebdb-field-user)))
- "If FIELD is a class name subclassing `ebdb-user-field', return
- all instances of that field."
+ (f-class (subclass ebdb-field-user)))
+ "Return all RECORD's fields that are of class F-CLASS."
(seq-filter
(lambda (f)
- (object-of-class-p f field))
+ (object-of-class-p f f-class))
(ebdb-record-user-fields record)))
(cl-defmethod ebdb-record-field ((record ebdb-record)
- (field string))
- (ebdb-record-user-field record field))
+ (label string))
+ "Return all RECORD's fields that have label LABEL."
+ (ebdb-record-user-field record label))
;;; Parsing other things
@@ -4867,8 +4830,8 @@ be nil."
;;;###autoload
(defun ebdb-load ()
- "Load all databases listed in `ebdb-sources'. All the
-important work is done by the `ebdb-db-load' method."
+ "Load all databases listed in `ebdb-sources'.
+All the important work is done by the `ebdb-db-load' method."
(let ((sources (if (listp ebdb-sources)
ebdb-sources
(list ebdb-sources)))
@@ -4877,7 +4840,7 @@ important work is done by the `ebdb-db-load' method."
(when (and ebdb-db-list
(object-assoc t 'dirty ebdb-db-list))
;; Later we'll give users the option to discard unsaved data.
- (error "Databases have unsaved data, save first."))
+ (error "Databases have unsaved data, save first"))
(message "Loading EBDB sources...")
(ebdb-clear-vars)
(run-hooks 'ebdb-before-load-hook)
@@ -4900,7 +4863,7 @@ important work is done by the `ebdb-db-load' method."
(ebdb-db-save s))))
((null (and (eieio-object-p s)
(object-of-class-p s 'ebdb-db)))
- (error "Source %s must be a filename or instance of `ebdb-db'."
s)))
+ (error "Source %s must be a filename or instance of `ebdb-db'" s)))
;; Now load it.
(if (null (slot-value s 'disabled))
(ebdb-db-load s)
@@ -4949,7 +4912,8 @@ important work is done by the `ebdb-db-load' method."
"After all databases are loaded, initialize the records.
This results in the creation of all the secondary data
structures: label lists, `ebdb-org-hashtable', record caches,
-etc."
+etc. If optional argument RECORDS is given, only initialize
+those records."
(mapcar #'ebdb-init-record (or records ebdb-record-tracker)))
(defun ebdb-initialize-threadwise (&optional records)
@@ -4959,7 +4923,8 @@ in its own thread, and the thread will be yielded after
every ten
record initializations. Note that by itself this will have no
impact whatsoever on EBDB load times. It's up to the user to
interleave it with other thread-yielding operations to create an
-actual speedup."
+actual speedup. If optional argument RECORDS is given, only
+initialize those records."
(let ((c 0))
(mapcar
(lambda (r)
@@ -4977,6 +4942,11 @@ actual speedup."
;; record(s) into the current buffer.
(defun ebdb-cite-records (&optional records arg kill)
+ "Insert a string representation of RECORDS at point.
+If ARG (the prefix arg) is given, strings are in \"list style\",
+ie separated by newlines. Otherwise they are \"inline style\".
+If KILL is non-nil, put the string on the kill ring instead of
+inserting it."
(interactive (list (ebdb-prompt-for-record)
current-prefix-arg))
(let ((recs (if (listp records) records (list records)))
@@ -4995,8 +4965,7 @@ actual speedup."
(insert str))))
(cl-defgeneric ebdb-records-cite (style records)
- "Insert mode-appropriate mail strings for RECORDS.
-
+ "Return mode-appropriate mail strings for RECORDS.
STYLE is a symbol, one of 'inline or 'list. This is interpreted
differently by different major modes.
@@ -5077,7 +5046,7 @@ This is a generic function that dispatches on the value of
(defun ebdb-save (&optional prompt)
"Save the EBDB if it is modified.
-If PROMPT is non-nil prompt before saving."
+If PROMPT is non-nil, prompt before saving."
(interactive (list nil))
;; TODO: Reimplement ebdb-remote-file, or otherwise do something
;; about that.
@@ -5139,7 +5108,8 @@ key character.")
(defun ebdb-char-fold-to-regexp (string)
"A highly simplified version of `char-fold-to-regexp'.
-Only converts characters that decompose to the range [a-zA-Z]."
+Only converts characters in STRING that decompose to the range
+[a-zA-Z]."
(let ((out nil)
(end (length string))
char
@@ -5187,7 +5157,6 @@ See `ebdb-search' for searching records with regexps."
(defun ebdb-search (records clauses &optional invert)
"Search RECORDS for records matching CLAUSES.
-
Each element of CLAUSES is either a two-element list of (symbol
criteria), which will be used to make a call to
`ebdb-record-search', or it is a callable, which will be called
@@ -5199,7 +5168,9 @@ If the car of a clause is one of `ebdb-field-name',
list `ebdb-hash-extra-predicates', this function will try to use
the `ebdb-hashtable' to do a fast lookup. The criteria must be a
string, and must begin with a leading \"^\", ie, the search
-string must be a prefix of the sought string."
+string must be a prefix of the sought string.
+
+With optional argument INVERT, invert the search results."
;; In the following "fast lookup" means we use the search criteria
;; to pull results from the `ebdb-hashtable'. "Slow lookup" means
;; we loop over all the records and test each one.
@@ -5298,7 +5269,6 @@ string must be a prefix of the sought string."
(cl-defmethod ebdb-field-search ((_field ebdb-field-name-complex) _regex)
"Short-circuit the plain field search for names.
-
The record itself performs more complex searches on cached name
values, by default the search is not handed to the name field itself."
nil)
@@ -5414,9 +5384,7 @@ values, by default the search is not handed to the name
field itself."
(cl-defgeneric ebdb-search-read (field-class)
- "Prompt the user for a search string to match against instances
- of FIELD-CLASS.
-
+ "Prompt user for a string to match against instances of FIELD-CLASS.
In most cases this is a simple regexp, but field classes can
prompt users for more complex search criteria, if necessary.")
- [elpa] externals/ebdb updated (5735686 -> 2c71ef9), Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb c07f50b 2/9: Get rid of ebdb-version, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 6395a75 1/9: Manipulation of ebdb-db-list *still* in the wrong place, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 4796722 3/9: Fix mail sorting, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 7f51a4e 5/9: Make explicit "full" formatter, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 2c71ef9 9/9: Bump EBDB version to 0.4.3, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 2a25117 6/9: New option ebdb-print-object-name, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 9102219 7/9: Re-work ebdb-records-cite, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 44cce48 8/9: Absorb helm-ebdb package, rename to ebdb-helm, Eric Abrahamsen, 2018/02/18
- [elpa] externals/ebdb 639694c 4/9: Docstring changes,
Eric Abrahamsen <=