[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/ebdb d822c99: Add two convenience functions for editing
|
From: |
Stefan Monnier |
|
Subject: |
[elpa] externals/ebdb d822c99: Add two convenience functions for editing record fields |
|
Date: |
Mon, 15 Mar 2021 22:19:54 -0400 (EDT) |
branch: externals/ebdb
commit d822c9982d2f6287dc74358f6c2564760311d31d
Author: Eric Abrahamsen <eric@ericabrahamsen.net>
Commit: Eric Abrahamsen <eric@ericabrahamsen.net>
Add two convenience functions for editing record fields
* ebdb.el (ebdb-record-update-notes, ebdb-record-add-tag): Two "quick"
functions for common editing jobs.
* ebdb.org: Document these, and also provide a little more guidance on
how to edit record fields from within a function.
---
ebdb.el | 36 +++++++++++
ebdb.info | 204 +++++++++++++++++++++++++++++++++++++++++---------------------
ebdb.org | 60 ++++++++++++++++++
ebdb.texi | 53 ++++++++++++++++
4 files changed, 283 insertions(+), 70 deletions(-)
diff --git a/ebdb.el b/ebdb.el
index 651869d..4fe87fb 100644
--- a/ebdb.el
+++ b/ebdb.el
@@ -2077,6 +2077,27 @@ The result looks like this:
&optional slots)
(cl-call-next-method class str (plist-put slots :notes str)))
+(cl-defgeneric ebdb-record-update-notes (record note &optional replace)
+ "Convenience function for updating a record's notes field.
+NOTE will appended to REC's existing notes field (or added as a
+new notes field, if REC didn't already have one.
+
+If optional arg REPLACE is non-nil, replace any existing notes.")
+
+(cl-defmethod ebdb-record-update-notes ((rec ebdb-record)
+ (note string)
+ &optional replace)
+ (let ((existing (ebdb-record-field rec 'notes)))
+ (if existing
+ (ebdb-record-change-field
+ rec existing
+ (ebdb-parse ebdb-default-notes-class
+ (if replace
+ note
+ (concat (ebdb-string existing) note))))
+ (ebdb-record-insert-field
+ rec (ebdb-parse ebdb-default-notes-class note)))))
+
;;; Timestamp field
;; For both these fields, I'd actually prefer to store
@@ -2675,6 +2696,21 @@ See `ebdb-url-valid-schemes' for a list of acceptable
schemes."
(dolist (tag (slot-value field 'tags))
(ebdb-remhash tag record)))
+(cl-defgeneric ebdb-record-add-tag (record tag)
+ "Convenience function for tagging a record.
+Adds string TAG to RECORD's list of tags.")
+
+(cl-defmethod ebdb-record-add-tag ((rec ebdb-record)
+ (tag string))
+ (let ((existing (car-safe (ebdb-record-field rec 'ebdb-field-tags))))
+ (if existing
+ (ebdb-record-change-field
+ rec existing
+ (make-instance 'ebdb-field-tags :tags
+ (cons tag (slot-value existing 'tags))))
+ (ebdb-record-insert-field
+ rec (ebdb-parse 'ebdb-field-tags tag)))))
+
;;; Fields that change EBDB's behavior.
;;; Mail aliases
diff --git a/ebdb.info b/ebdb.info
index cf55ae0..79eca58 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -134,6 +134,7 @@ Hacking EBDB
Field Classes
* Init and Delete Methods::
+* Manipulating Field Data Programmatically::
* The Labeled Field Class::
* The Singleton Field Class::
* Actions::
@@ -837,6 +838,16 @@ say that the first argument is the field instance being
noticed, the
second argument is one of the symbols ‘sender’ or ‘recipient’, and the
third argument is the record being noticed.
+ A useful function here is ‘ebdb-mua-message-header’, which can be
+used to extract the value of arbitrary headers from the current message.
+The header should be provided as a string, for example
+‘(ebdb-mua-message-header "Subject")’. There is currently no shortcut
+for extracting the text of the message body; code to do this will have
+to be written per-MUA.
+
+ For functions that can be used to edit a record’s field data, *note
+Manipulating Field Data Programmatically::.
+
File: ebdb.info, Node: Interactive Commands, Prev: Noticing and Automatic
Rules, Up: Display and Updating
@@ -1852,6 +1863,7 @@ default values for the new object.
* Menu:
* Init and Delete Methods::
+* Manipulating Field Data Programmatically::
* The Labeled Field Class::
* The Singleton Field Class::
* Actions::
@@ -1860,7 +1872,7 @@ default values for the new object.
* Formatting in the EBDB Buffer::
-File: ebdb.info, Node: Init and Delete Methods, Next: The Labeled Field
Class, Up: Field Classes
+File: ebdb.info, Node: Init and Delete Methods, Next: Manipulating Field
Data Programmatically, Up: Field Classes
16.1.1 Init and Delete Methods
------------------------------
@@ -1898,9 +1910,48 @@ must not change the database: they may not edit records
or their fields.
UNLOAD argument will be non-nil).
-File: ebdb.info, Node: The Labeled Field Class, Next: The Singleton Field
Class, Prev: Init and Delete Methods, Up: Field Classes
+File: ebdb.info, Node: Manipulating Field Data Programmatically, Next: The
Labeled Field Class, Prev: Init and Delete Methods, Up: Field Classes
+
+16.1.2 Manipulating Field Data Programmatically
+-----------------------------------------------
+
+While ebdb-mode provides interactive commands for editing record data in
+an *EBDB* buffer, it can also be useful to do this inside Elisp
+functions, especially as a part of *note Noticing and Automatic Rules::.
+Instead of manipulating field data directly, it’s important to go
+through accessors that give a record’s database(s) a chance to handle,
+persist, or update the field data. There are three functions for doing
+this:
+
+ -- Function: ebdb-record-insert-field rec field &optional slot
+ Insert FIELD into REC.
+
+ -- Function: ebdb-record-delete-field rec field &optional slot
+ Delete FIELD from REC. You’ll need to get a handle to FIELD first,
+ probably with ‘ebdb-record-field’.
+
+ -- Function: ebdb-record-change-field rec old-field &optional new-field
+ Editing a field in EBDB is actually a delete-then-insert operation.
+ If the NEW-FIELD argument is nil, the user will be prompted for a
+ value for the new field, using the OLD-FIELD’s value as a default.
+
+ The optional SLOT argument to the first two functions can almost
+always be omitted.
-16.1.2 The Labeled Field Class
+ Two convenience functions are provided for common editing operations:
+
+ -- Function: ebdb-record-add-tag rec tag
+ Add string TAG to REC’s list of tags.
+
+ -- Function: ebdb-record-update rec note &optional replace
+ Add string NOTE to REC’s note field. The text will be appended to
+ any existing notes, unless the optional argument REPLACE is
+ non-nil.
+
+
+File: ebdb.info, Node: The Labeled Field Class, Next: The Singleton Field
Class, Prev: Manipulating Field Data Programmatically, Up: Field Classes
+
+16.1.3 The Labeled Field Class
------------------------------
Many field classes maintain their own list of labels: ie, anniversary
@@ -1919,7 +1970,7 @@ used to hold labels, and pointing to it in the
class-allocated
File: ebdb.info, Node: The Singleton Field Class, Next: Actions, Prev: The
Labeled Field Class, Up: Field Classes
-16.1.3 The Singleton Field Class
+16.1.4 The Singleton Field Class
--------------------------------
Another abstract mix-in class is the ‘ebdb-field-singleton’ class. Its
@@ -1930,7 +1981,7 @@ existing instance is deleted.
File: ebdb.info, Node: Actions, Next: Custom Field Searching, Prev: The
Singleton Field Class, Up: Field Classes
-16.1.4 Actions
+16.1.5 Actions
--------------
All field classes have a class-allocated slot called “actions”. The
@@ -1946,7 +1997,7 @@ and the field instance under point.
File: ebdb.info, Node: Custom Field Searching, Next: Fast Lookups, Prev:
Actions, Up: Field Classes
-16.1.5 Custom Field Searching
+16.1.6 Custom Field Searching
-----------------------------
In most cases, searching the EBDB database is a matter of prompting for
@@ -2007,7 +2058,7 @@ EBDB code would create this search, external code
conceivably might.
File: ebdb.info, Node: Fast Lookups, Next: Formatting in the EBDB Buffer,
Prev: Custom Field Searching, Up: Field Classes
-16.1.6 Fast Lookups
+16.1.7 Fast Lookups
-------------------
Usually, searches of the database are conducted by looping over all the
@@ -2043,7 +2094,7 @@ match the instance of that field (and not some other
field string).
File: ebdb.info, Node: Formatting in the EBDB Buffer, Prev: Fast Lookups,
Up: Field Classes
-16.1.7 Formatting in the EBDB Buffer
+16.1.8 Formatting in the EBDB Buffer
------------------------------------
Most fields will be displayed in the *EBDB* buffer simply using
@@ -2499,7 +2550,9 @@ File: ebdb.info, Node: Index, Prev: Hacking EBDB, Up:
Top
(line 67)
* ebdb-mua-make-summary-mark on ebdb-record: Summary buffer marks.
(line 15)
-* ebdb-mua-message-header: Writing Integration For New MUAs.
+* ebdb-mua-message-header: Noticing and Automatic Rules.
+ (line 28)
+* ebdb-mua-message-header <1>: Writing Integration For New MUAs.
(line 22)
* ebdb-mua-pop-up: Pop-up Buffers. (line 11)
* ebdb-mua-prepare-article: Writing Integration For New MUAs.
@@ -2547,9 +2600,19 @@ File: ebdb.info, Node: Index, Prev: Hacking EBDB, Up:
Top
(line 13)
* ebdb-record-action: The Basics of ebdb-mode.
(line 50)
+* ebdb-record-add-tag: Manipulating Field Data
Programmatically.
+ (line 31)
+* ebdb-record-change-field: Manipulating Field Data
Programmatically.
+ (line 21)
+* ebdb-record-delete-field: Manipulating Field Data
Programmatically.
+ (line 17)
+* ebdb-record-insert-field: Manipulating Field Data
Programmatically.
+ (line 14)
* ebdb-record-self: Creating Records. (line 21)
* ebdb-record-self <1>: Auto-Updating Records.
(line 77)
+* ebdb-record-update: Manipulating Field Data
Programmatically.
+ (line 34)
* ebdb-reformat-records: The Basics of ebdb-mode.
(line 82)
* ebdb-rename-buffer: EBDB Buffers. (line 23)
@@ -2663,67 +2726,68 @@ File: ebdb.info, Node: Index, Prev: Hacking EBDB,
Up: Top
Tag Table:
Node: Top807
-Node: Getting Started2635
-Node: Starting a New Database4585
-Node: Migration from BBDB5409
-Node: Record Migration5652
-Node: Variables and Options6292
-Node: Migration from Org Contacts6779
-Node: The EBDB Database7539
-Node: Creating Records11730
-Node: Record classes12811
-Node: Record names13156
-Node: Record Fields13831
-Node: Inserting New Fields14075
-Node: Editing Existing Fields14871
-Node: Deleting Records and Fields15471
-Node: Field Types15867
-Node: Role fields18153
-Node: Tag field20134
-Node: Mail folder field20703
-Node: MUA Interaction21031
-Node: Loading MUA Code21584
-Node: Display and Updating22297
-Node: Pop-up Buffers23063
-Node: Auto-Updating Records25061
-Node: Noticing and Automatic Rules29855
-Node: Interactive Commands31188
-Node: EBDB and MUA summary buffers33662
-Node: Sender name display34180
-Node: Summary buffer marks35407
-Node: Mail Address Completion36586
-Node: A Note on Completion39095
-Node: Specific MUAs39718
-Node: Gnus39866
-Node: Posting Styles40088
-Node: EBDB Buffers41644
-Node: Searching42855
-Node: Changing Search Behavior44569
-Node: The Basics of ebdb-mode45816
-Node: Customizing Record Display50164
-Node: Marking54484
-Node: Exporting/Formatting54911
-Node: Completion55846
-Node: Snarfing56642
-Node: Internationalization58659
-Node: Diary Integration61360
-Node: Mail Aliases62225
-Node: vCard Support62939
-Node: Org Integration63438
-Node: Citing Records65336
-Node: Hacking EBDB66094
-Node: Field Classes68687
-Node: Init and Delete Methods71823
-Node: The Labeled Field Class73330
-Node: The Singleton Field Class74184
-Node: Actions74622
-Node: Custom Field Searching75294
-Node: Fast Lookups78161
-Node: Formatting in the EBDB Buffer79971
-Node: Writing Internationalization Libraries82047
-Node: Writing Integration For New MUAs86463
-Node: Article snarfing89911
-Node: Index90629
+Node: Getting Started2680
+Node: Starting a New Database4630
+Node: Migration from BBDB5454
+Node: Record Migration5697
+Node: Variables and Options6337
+Node: Migration from Org Contacts6824
+Node: The EBDB Database7584
+Node: Creating Records11775
+Node: Record classes12856
+Node: Record names13201
+Node: Record Fields13876
+Node: Inserting New Fields14120
+Node: Editing Existing Fields14916
+Node: Deleting Records and Fields15516
+Node: Field Types15912
+Node: Role fields18198
+Node: Tag field20179
+Node: Mail folder field20748
+Node: MUA Interaction21076
+Node: Loading MUA Code21629
+Node: Display and Updating22342
+Node: Pop-up Buffers23108
+Node: Auto-Updating Records25106
+Node: Noticing and Automatic Rules29900
+Node: Interactive Commands31722
+Node: EBDB and MUA summary buffers34196
+Node: Sender name display34714
+Node: Summary buffer marks35941
+Node: Mail Address Completion37120
+Node: A Note on Completion39629
+Node: Specific MUAs40252
+Node: Gnus40400
+Node: Posting Styles40622
+Node: EBDB Buffers42178
+Node: Searching43389
+Node: Changing Search Behavior45103
+Node: The Basics of ebdb-mode46350
+Node: Customizing Record Display50698
+Node: Marking55018
+Node: Exporting/Formatting55445
+Node: Completion56380
+Node: Snarfing57176
+Node: Internationalization59193
+Node: Diary Integration61894
+Node: Mail Aliases62759
+Node: vCard Support63473
+Node: Org Integration63972
+Node: Citing Records65870
+Node: Hacking EBDB66628
+Node: Field Classes69221
+Node: Init and Delete Methods72402
+Node: Manipulating Field Data Programmatically73926
+Node: The Labeled Field Class75638
+Node: The Singleton Field Class76509
+Node: Actions76947
+Node: Custom Field Searching77619
+Node: Fast Lookups80486
+Node: Formatting in the EBDB Buffer82296
+Node: Writing Internationalization Libraries84372
+Node: Writing Integration For New MUAs88788
+Node: Article snarfing92236
+Node: Index92954
End Tag Table
diff --git a/ebdb.org b/ebdb.org
index 6477405..c096f07 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -650,6 +650,9 @@ brackets. Domains to be ignored should start with the "@"
symbol.
The addresses are matched literally (though case-insensitively); it's
not possible to use regexps.
*** Noticing and Automatic Rules
+:PROPERTIES:
+:ID: 0e6d846d-de48-498f-99a3-25ceef0b6fde
+:END:
#+CINDEX: Automatic Rules
In addition to updating records' name and mail fields, it's possible
@@ -680,6 +683,17 @@ field instance being noticed, the second argument is one
of the
symbols ~sender~ or ~recipient~, and the third argument is the record
being noticed.
+#+FINDEX: ebdb-mua-message-header
+A useful function here is ~ebdb-mua-message-header~, which can be used
+to extract the value of arbitrary headers from the current message.
+The header should be provided as a string, for example
+~(ebdb-mua-message-header "Subject")~. There is currently no shortcut
+for extracting the text of the message body; code to do this will have
+to be written per-MUA.
+
+For functions that can be used to edit a record's field data,
+[[id:4a6d956e-54ee-4b67-a462-5b826678aa97][Manipulating Field Data
Programmatically]].
+
*** Interactive Commands
:PROPERTIES:
:ID: 38166454-6750-48e9-a5e5-313ff9264c6d
@@ -1810,6 +1824,52 @@ Both methods should always end with a call to
~cl-call-next-method~.
delete-and-create operation).
4. When unloading a record from the database (the optional third
@@texinfo:@var{unload}@@ argument will be non-nil).
+*** Manipulating Field Data Programmatically
+:PROPERTIES:
+:ID: 4a6d956e-54ee-4b67-a462-5b826678aa97
+:END:
+While ebdb-mode provides interactive commands for editing record data
+in an {{{buf(EBDB)}}} buffer, it can also be useful to do this inside
+Elisp functions, especially as a part of
[[id:0e6d846d-de48-498f-99a3-25ceef0b6fde][Noticing and Automatic Rules]].
+Instead of manipulating field data directly, it's important to go
+through accessors that give a record's database(s) a chance to handle,
+persist, or update the field data. There are three functions for
+doing this:
+
+#+ATTR_TEXINFO: :options ebdb-record-insert-field rec field &optional slot
+#+BEGIN_defun
+Insert FIELD into REC.
+#+END_defun
+
+#+ATTR_TEXINFO: :options ebdb-record-delete-field rec field &optional slot
+#+BEGIN_defun
+Delete FIELD from REC. You'll need to get a handle to FIELD first,
+probably with ~ebdb-record-field~.
+#+END_defun
+
+#+ATTR_TEXINFO: :options ebdb-record-change-field rec old-field &optional
new-field
+#+BEGIN_defun
+Editing a field in EBDB is actually a delete-then-insert operation.
+If the NEW-FIELD argument is nil, the user will be prompted for a
+value for the new field, using the OLD-FIELD's value as a default.
+#+END_defun
+
+The optional SLOT argument to the first two functions can almost
+always be omitted.
+
+Two convenience functions are provided for common editing operations:
+
+#+ATTR_TEXINFO: :options ebdb-record-add-tag rec tag
+#+begin_defun
+Add string TAG to REC's list of tags.
+#+end_defun
+
+#+ATTR_TEXINFO: :options ebdb-record-update rec note &optional replace
+#+begin_defun
+Add string NOTE to REC's note field. The text will be appended to any
+existing notes, unless the optional argument REPLACE is non-nil.
+#+end_defun
+
*** The Labeled Field Class
Many field classes maintain their own list of labels: ie, anniversary
fields can be labeled "birthday", "wedding", etc. This functionality
diff --git a/ebdb.texi b/ebdb.texi
index c26194d..c563f56 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -157,6 +157,7 @@ Hacking EBDB
Field Classes
* Init and Delete Methods::
+* Manipulating Field Data Programmatically::
* The Labeled Field Class::
* The Singleton Field Class::
* Actions::
@@ -892,6 +893,17 @@ field instance being noticed, the second argument is one
of the
symbols @code{sender} or @code{recipient}, and the third argument is the record
being noticed.
+@findex ebdb-mua-message-header
+A useful function here is @code{ebdb-mua-message-header}, which can be used
+to extract the value of arbitrary headers from the current message.
+The header should be provided as a string, for example
+@code{(ebdb-mua-message-header "Subject")}. There is currently no shortcut
+for extracting the text of the message body; code to do this will have
+to be written per-MUA@.
+
+For functions that can be used to edit a record's field data,
+@ref{Manipulating Field Data Programmatically}.
+
@node Interactive Commands
@subsection Interactive Commands
@@ -2018,6 +2030,7 @@ provide default values for the new object.
@menu
* Init and Delete Methods::
+* Manipulating Field Data Programmatically::
* The Labeled Field Class::
* The Singleton Field Class::
* Actions::
@@ -2076,6 +2089,46 @@ When unloading a record from the database (the optional
third
@var{unload} argument will be non-nil).
@end enumerate
+@node Manipulating Field Data Programmatically
+@subsection Manipulating Field Data Programmatically
+
+While ebdb-mode provides interactive commands for editing record data
+in an *EBDB* buffer, it can also be useful to do this inside
+Elisp functions, especially as a part of @ref{Noticing and Automatic Rules}.
+Instead of manipulating field data directly, it's important to go
+through accessors that give a record's database(s) a chance to handle,
+persist, or update the field data. There are three functions for
+doing this:
+
+@defun ebdb-record-insert-field rec field &optional slot
+Insert FIELD into REC@.
+@end defun
+
+@defun ebdb-record-delete-field rec field &optional slot
+Delete FIELD from REC@. You'll need to get a handle to FIELD first,
+probably with @code{ebdb-record-field}.
+@end defun
+
+@defun ebdb-record-change-field rec old-field &optional new-field
+Editing a field in EBDB is actually a delete-then-insert operation.
+If the NEW-FIELD argument is nil, the user will be prompted for a
+value for the new field, using the OLD-FIELD's value as a default.
+@end defun
+
+The optional SLOT argument to the first two functions can almost
+always be omitted.
+
+Two convenience functions are provided for common editing operations:
+
+@defun ebdb-record-add-tag rec tag
+Add string TAG to REC's list of tags.
+@end defun
+
+@defun ebdb-record-update rec note &optional replace
+Add string NOTE to REC's note field. The text will be appended to any
+existing notes, unless the optional argument REPLACE is non-nil.
+@end defun
+
@node The Labeled Field Class
@subsection The Labeled Field Class
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [elpa] externals/ebdb d822c99: Add two convenience functions for editing record fields,
Stefan Monnier <=