[elpa] externals/ebdb 3a918eb 09/21: Provide better instructions for BBDB migration

[Eric Abrahamsen]

branch: externals/ebdb
commit 3a918eb086b7843ba82373c806db8de80f87e995
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>

    Provide better instructions for BBDB migration
    
    Fixes #50
    
    * ebdb.el (ebdb-load): Also check for the presence of a BBDB file,
      even if bbdb-file isn't set.
    * ebdb-migrate.el (ebdb-migrate-from-bbdb): Do the same here.
    * ebdb.org: Mention in manual that you should set bbdb-file to
      migrate.
---
 ebdb-migrate.el |  15 ++++--
 ebdb.el         |  37 ++++++-------
 ebdb.info       | 165 +++++++++++++++++++++++++++++++++++---------------------
 ebdb.org        |  16 +++---
 ebdb.texi       |  56 ++++++++++++++++---
 5 files changed, 192 insertions(+), 97 deletions(-)

diff --git a/ebdb-migrate.el b/ebdb-migrate.el
index f811f8c..851786a 100644
--- a/ebdb-migrate.el
+++ b/ebdb-migrate.el
@@ -367,19 +367,26 @@ checked for a score to add to the mail addresses in the 
same record."
   :type 'symbol)
 
 ;;;###autoload
-(defun ebdb-migrate-from-bbdb ()
+(defun ebdb-migrate-from-bbdb (&optional file)
   "Migrate from BBDB to EBDB.
 
 This upgrade is extreme enough that we can't really use the
 existing migration mechanisms.  They are still there, though, in
 case someone's going from, say, version 2 to 4 in one jump.
 
-Assume that the variable `bbdb-file' points to an existing file
-holding valid contacts in a previous BBDB format."
+Migrate from FILE, if non-nil.  Otherwise, assume that the
+variable `bbdb-file' points to an existing file holding valid
+contacts in a previous BBDB format.  If that variable isn't set
+use \(locate-user-emacs-file \"bbdb\" \".bbdb\"\), which is how
+BBDB sets the default of that option."
   (require 'url-handlers)
   (require 'ebdb-org)
   (require 'ebdb-gnus)
-  (with-current-buffer (find-file-noselect bbdb-file)
+  (with-current-buffer (find-file-noselect
+                       (or file
+                           (and (bound-and-true-p bbdb-file)
+                                bbdb-file)
+                           (locate-user-emacs-file "bbdb" ".bbdb")))
     (when (and (/= (point-min) (point-max))
               (yes-or-no-p "Upgrade from previous version of BBDB? "))
       (let ((v-records (ebdb-migrate-parse-records))
diff --git a/ebdb.el b/ebdb.el
index c5cd6ae..7db7cb2 100644
--- a/ebdb.el
+++ b/ebdb.el
@@ -4897,22 +4897,22 @@ important work is done by the `ebdb-db-load' method."
     (run-hooks 'ebdb-before-load-hook)
     (dolist (s sources)
       (cond ((stringp s)
-             (if (file-exists-p s)
-                 ;; Handle auto-saved databases.
-                 (let ((auto-save-file (ebdb-db-make-auto-save-file-name s))
-                       (orig-filename s))
-                   (if (and (file-exists-p auto-save-file)
-                            (yes-or-no-p (format "Recover auto-save file for 
%s? " s)))
-                       (progn (setq s (eieio-persistent-read auto-save-file 
'ebdb-db t))
-                              (setf (slot-value s 'file) orig-filename)
-                              (setf (slot-value s 'dirty) t))
-                     (setq s (eieio-persistent-read s 'ebdb-db t)))
-                     (cl-pushnew s ebdb-db-list))
-               ;; Handle new/nonexistent databases.
-               (when (yes-or-no-p (format "%s does not exist, create? " s))
-                 (setq s (make-instance 'ebdb-db-file :file s :dirty t))
-                 ;; Try to get it on disk first.
-                 (ebdb-db-save s))))
+            (if (file-exists-p s)
+                ;; Handle auto-saved databases.
+                (let ((auto-save-file (ebdb-db-make-auto-save-file-name s))
+                      (orig-filename s))
+                  (if (and (file-exists-p auto-save-file)
+                           (yes-or-no-p (format "Recover auto-save file for 
%s? " s)))
+                      (progn (setq s (eieio-persistent-read auto-save-file 
'ebdb-db t))
+                             (setf (slot-value s 'file) orig-filename)
+                             (setf (slot-value s 'dirty) t))
+                    (setq s (eieio-persistent-read s 'ebdb-db t)))
+                  (cl-pushnew s ebdb-db-list))
+              ;; Handle new/nonexistent databases.
+              (when (yes-or-no-p (format "%s does not exist, create? " s))
+                (setq s (make-instance 'ebdb-db-file :file s :dirty t))
+                ;; Try to get it on disk first.
+                (ebdb-db-save s))))
            ((null (object-of-class-p s 'ebdb-db))
             (error "Source %s must be a filename or instance of `ebdb-db'." 
s)))
       ;; Now load it.
@@ -4927,8 +4927,9 @@ important work is done by the `ebdb-db-load' method."
        (error "Object %s is not a EBDB database" s)))
     (if (and
         (null ebdb-record-tracker)
-        (bound-and-true-p bbdb-file)
-        (file-exists-p bbdb-file))
+        (or (and (bound-and-true-p bbdb-file)
+                 (file-exists-p bbdb-file))
+            (file-exists-p (locate-user-emacs-file "bbdb" ".bbdb"))))
        ;; We're migrating from a version of BBDB.
        (ebdb-migrate-from-bbdb))
     (message "Initializing EBDB records...")
diff --git a/ebdb.info b/ebdb.info
index a4c1243..b8ca680 100644
--- a/ebdb.info
+++ b/ebdb.info
@@ -129,6 +129,7 @@ Field Classes
 * The Singleton Field Class::
 * Actions::
 * Custom Field Searching::
+* Fast Lookups::
 * Formatting in the EBDB Buffer::
 
 
@@ -172,12 +173,14 @@ File: ebdb.info,  Node: Record Migration,  Next: 
Variables and Options,  Up: Mig
 1.1.1 Record Migration
 ----------------------
 
-It’s possible to migrate records from a BBDB file.  With your BBDB
-customizations still in place, set ‘ebdb-sources’ to a non-existent file
-name, and then run ‘ebdb-load’ (or any of the other EBDB entry
-commands).  You’ll be prompted to create the new database, and upgrade
-from BBDB. If any records could not be upgraded, they will be displayed
-in an *EBDB Migration* buffer.  Migration bug reports are very welcome.
+It’s possible to migrate records from a BBDB database.  The ‘bbdb-file’
+variable should point to your current BBDB file; alternately EBDB will
+look in the default location, found using ‘(locate-user-emacs-file
+"bbdb" ".bbdb)’.  Then set ‘ebdb-sources’ to a non-existent file name,
+and then run ‘ebdb-load’ (or any of the other EBDB entry commands).
+You’ll be prompted to create the new database, and upgrade from BBDB. If
+any records could not be upgraded, they will be displayed in an *EBDB
+Migration* buffer.  Migration bug reports are very welcome.
 
 
 File: ebdb.info,  Node: Variables and Options,  Prev: Record Migration,  Up: 
Migration from BBDB
@@ -1443,6 +1446,7 @@ default values for the new object.
 * The Singleton Field Class::
 * Actions::
 * Custom Field Searching::
+* Fast Lookups::
 * Formatting in the EBDB Buffer::
 
 
@@ -1530,7 +1534,7 @@ prefix arg to be prompted for which action to take.
 and the field instance under point.
 
 
-File: ebdb.info,  Node: Custom Field Searching,  Next: Formatting in the EBDB 
Buffer,  Prev: Actions,  Up: Field Classes
+File: ebdb.info,  Node: Custom Field Searching,  Next: Fast Lookups,  Prev: 
Actions,  Up: Field Classes
 
 15.1.5 Custom Field Searching
 -----------------------------
@@ -1591,9 +1595,45 @@ method handles that lambda, simply by calling it.  The 
second
 EBDB code would create this search, external code conceivably might.
 
 
-File: ebdb.info,  Node: Formatting in the EBDB Buffer,  Prev: Custom Field 
Searching,  Up: Field Classes
+File: ebdb.info,  Node: Fast Lookups,  Next: Formatting in the EBDB Buffer,  
Prev: Custom Field Searching,  Up: Field Classes
 
-15.1.6 Formatting in the EBDB Buffer
+15.1.6 Fast Lookups
+-------------------
+
+Usually, searches of the database are conducted by looping over all the
+records and testing each search clause against each record.
+Theoretically, this could be a slow process.
+
+   By contrast, “fast lookups” use a central hashtable, the
+‘ebdb-hashtable’, to look up search strings quickly.  By default,
+records names, email addresses, and tags are indexed in this central
+hashtable.  To short-circuit the usual slow lookup and use the fast
+hashtable lookup, specify one of those three field names as the ‘car’ of
+the search criteria, and prefix the string ‘cdr’ of the criteria with a
+“^” (the behavior of ‘all-completions’ requires a string prefix):
+
+     (ebdb-search (ebdb-records) '((ebdb-field-tag "^client")))
+
+   It’s possible to use these fast lookups in interactive searches, when
+selecting a specific field type to search on, but the time spent typing
+a “^” will undoubtedly outweigh the time saved in the search.  This is
+mostly useful in non-interactive searches.
+
+   It’s also possible to specify additional field types which can be
+used with fast lookups.  The first step is to write ‘ebdb-init-field’
+and ‘ebdb-delete-field’ methods that hash and unhash the record against
+the field string in the ‘ebdb-hashtable’.
+
+   Next, add an element to the ‘ebdb-hash-extra-predicates’ variable.
+The element should be a cons cell where the ‘car’ is the field class
+name, as a symbol, and the ‘cdr’ is a lambda which accepts the search
+string and a record, and returns ‘t’ if the search string does indeed
+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
+
+15.1.7 Formatting in the EBDB Buffer
 ------------------------------------
 
 Most fields will be displayed in the *EBDB* buffer simply using
@@ -1950,6 +1990,8 @@ Index
                                                               (line  20)
 * ebdb-format-to-tmp-buffer:             Exporting/Formatting.
                                                               (line  15)
+* ebdb-hash-extra-predicates:            Fast Lookups.        (line  30)
+* ebdb-hashtable:                        Fast Lookups.        (line  10)
 * ebdb-help:                             The Basics of ebdb-mode.
                                                               (line 102)
 * ebdb-i18n-countries:                   Internationalization.
@@ -2131,58 +2173,59 @@ Index
 
 Tag Table:
 Node: Top806
-Node: Getting Started2386
-Node: Migration from BBDB3009
-Node: Record Migration3184
-Node: Variables and Options3762
-Node: The EBDB Database4248
-Node: Creating Records7800
-Node: Record classes8881
-Node: Record names9226
-Node: Record Fields9901
-Node: Inserting New Fields10145
-Node: Editing Existing Fields10941
-Node: Deleting Records and Fields11541
-Node: Field Types11937
-Node: Role fields14128
-Node: Tag field15816
-Node: Mail folder field16460
-Node: MUA Interaction16788
-Node: Loading MUA Code17312
-Node: Display and Updating18021
-Node: Pop-up Buffers18787
-Node: Auto-Updating Records19625
-Node: Noticing and Automatic Rules22025
-Node: Interactive Commands23358
-Node: EBDB and MUA summary buffers25720
-Node: Sender name display26206
-Node: Summary buffer marks27433
-Node: EBDB Buffers28612
-Node: Searching29794
-Node: Changing Search Behavior31456
-Node: The Basics of ebdb-mode32703
-Node: Marking36304
-Node: Exporting/Formatting36728
-Node: Completion37677
-Node: Snarfing38875
-Node: Internationalization40876
-Node: Diary Integration43575
-Node: Mail Aliases44440
-Node: vCard Support45154
-Node: Org Integration45653
-Node: Citing Records47551
-Node: Hacking EBDB48309
-Node: Field Classes50630
-Node: Init and Delete Methods53597
-Node: The Labeled Field Class55104
-Node: The Singleton Field Class55958
-Node: Actions56396
-Node: Custom Field Searching57068
-Node: Formatting in the EBDB Buffer59889
-Node: Writing Internationalization Libraries61912
-Node: Writing Integration For New MUAs66265
-Node: Article snarfing69684
-Node: Index70402
+Node: Getting Started2403
+Node: Migration from BBDB3026
+Node: Record Migration3201
+Node: Variables and Options3921
+Node: The EBDB Database4407
+Node: Creating Records7959
+Node: Record classes9040
+Node: Record names9385
+Node: Record Fields10060
+Node: Inserting New Fields10304
+Node: Editing Existing Fields11100
+Node: Deleting Records and Fields11700
+Node: Field Types12096
+Node: Role fields14287
+Node: Tag field15975
+Node: Mail folder field16619
+Node: MUA Interaction16947
+Node: Loading MUA Code17471
+Node: Display and Updating18180
+Node: Pop-up Buffers18946
+Node: Auto-Updating Records19784
+Node: Noticing and Automatic Rules22184
+Node: Interactive Commands23517
+Node: EBDB and MUA summary buffers25879
+Node: Sender name display26365
+Node: Summary buffer marks27592
+Node: EBDB Buffers28771
+Node: Searching29953
+Node: Changing Search Behavior31615
+Node: The Basics of ebdb-mode32862
+Node: Marking36463
+Node: Exporting/Formatting36887
+Node: Completion37836
+Node: Snarfing39034
+Node: Internationalization41035
+Node: Diary Integration43734
+Node: Mail Aliases44599
+Node: vCard Support45313
+Node: Org Integration45812
+Node: Citing Records47710
+Node: Hacking EBDB48468
+Node: Field Classes50789
+Node: Init and Delete Methods53773
+Node: The Labeled Field Class55280
+Node: The Singleton Field Class56134
+Node: Actions56572
+Node: Custom Field Searching57244
+Node: Fast Lookups60048
+Node: Formatting in the EBDB Buffer61858
+Node: Writing Internationalization Libraries63871
+Node: Writing Integration For New MUAs68224
+Node: Article snarfing71643
+Node: Index72361
 
 End Tag Table
 
diff --git a/ebdb.org b/ebdb.org
index 46e9795..8e7454e 100644
--- a/ebdb.org
+++ b/ebdb.org
@@ -42,13 +42,15 @@ make new records (see 
[[id:692cde31-73be-4faf-b436-7eae8a5d02d1][Creating Record
 ** Migration from BBDB
 #+CINDEX: Migrating from BBDB
 *** Record Migration
-It's possible to migrate records from a BBDB file.  With your BBDB
-customizations still in place, set ~ebdb-sources~ to a non-existent
-file name, and then run ~ebdb-load~ (or any of the other EBDB entry
-commands).  You'll be prompted to create the new database, and upgrade
-from BBDB.  If any records could not be upgraded, they will be
-displayed in an {{{buf(EBDB Migration)}}} buffer.  Migration bug
-reports are very welcome.
+It's possible to migrate records from a BBDB database.  The
+~bbdb-file~ variable should point to your current BBDB file;
+alternately EBDB will look in the default location, found using
+~(locate-user-emacs-file "bbdb" ".bbdb)~.  Then set ~ebdb-sources~ to
+a non-existent file name, and then run ~ebdb-load~ (or any of the
+other EBDB entry commands).  You'll be prompted to create the new
+database, and upgrade from BBDB.  If any records could not be
+upgraded, they will be displayed in an {{{buf(EBDB Migration)}}}
+buffer.  Migration bug reports are very welcome.
 *** Variables and Options
 Many of the old BBDB customization options have been changed or
 removed entirely in EBDB.  It's probably best to put your BBDB
diff --git a/ebdb.texi b/ebdb.texi
index 0635ba6..849bed5 100644
--- a/ebdb.texi
+++ b/ebdb.texi
@@ -152,6 +152,7 @@ Field Classes
 * The Singleton Field Class::
 * Actions::
 * Custom Field Searching::
+* Fast Lookups::
 * Formatting in the EBDB Buffer::
 
 
@@ -190,13 +191,15 @@ make new records (see @ref{Creating Records}).
 @node Record Migration
 @subsection Record Migration
 
-It's possible to migrate records from a BBDB file.  With your BBDB
-customizations still in place, set @code{ebdb-sources} to a non-existent
-file name, and then run @code{ebdb-load} (or any of the other EBDB entry
-commands).  You'll be prompted to create the new database, and upgrade
-from BBDB.  If any records could not be upgraded, they will be
-displayed in an *EBDB Migration* buffer.  Migration bug
-reports are very welcome.
+It's possible to migrate records from a BBDB database.  The
address@hidden variable should point to your current BBDB file;
+alternately EBDB will look in the default location, found using
address@hidden(locate-user-emacs-file "bbdb" ".bbdb)}.  Then set 
@code{ebdb-sources} to
+a non-existent file name, and then run @code{ebdb-load} (or any of the
+other EBDB entry commands).  You'll be prompted to create the new
+database, and upgrade from BBDB.  If any records could not be
+upgraded, they will be displayed in an *EBDB Migration*
+buffer.  Migration bug reports are very welcome.
 
 @node Variables and Options
 @subsection Variables and Options
@@ -1563,6 +1566,7 @@ provide default values for the new object.
 * The Singleton Field Class::
 * Actions::
 * Custom Field Searching::
+* Fast Lookups::
 * Formatting in the EBDB Buffer::
 @end menu
 
@@ -1720,6 +1724,44 @@ The second @code{ebdb-field-search} method handles a 
string search
 criterion; though no EBDB code would create this search, external code
 conceivably might.
 
address@hidden Fast Lookups
address@hidden Fast Lookups
+
+Usually, searches of the database are conducted by looping over all
+the records and testing each search clause against each record.
+Theoretically, this could be a slow process.
+
address@hidden ebdb-hashtable
+By contrast, ``fast lookups'' use a central hashtable, the
address@hidden, to look up search strings quickly.  By default,
+records names, email addresses, and tags are indexed in this central
+hashtable.  To short-circuit the usual slow lookup and use the fast
+hashtable lookup, specify one of those three field names as the @code{car}
+of the search criteria, and prefix the string @code{cdr} of the criteria
+with a ``^'' (the behavior of @code{all-completions} requires a string
+prefix):
+
address@hidden
+(ebdb-search (ebdb-records) '((ebdb-field-tag "^client")))
address@hidden lisp
+
+It's possible to use these fast lookups in interactive searches, when
+selecting a specific field type to search on, but the time spent
+typing a ``^'' will undoubtedly outweigh the time saved in the search.
+This is mostly useful in non-interactive searches.
+
+It's also possible to specify additional field types which can be used
+with fast lookups.  The first step is to write @code{ebdb-init-field} and
address@hidden methods that hash and unhash the record against
+the field string in the @code{ebdb-hashtable}.
+
address@hidden ebdb-hash-extra-predicates
+Next, add an element to the @code{ebdb-hash-extra-predicates} variable.
+The element should be a cons cell where the @code{car} is the field class
+name, as a symbol, and the @code{cdr} is a lambda which accepts the search
+string and a record, and returns @code{t} if the search string does indeed
+match the instance of that field (and not some other field string).
+
 @node Formatting in the EBDB Buffer
 @subsection Formatting in the EBDB Buffer