branch: externals/clipboard-collector
commit 7bbdece8318859a05af274c726e05a367b27d07a
Author: Clemens Radermacher <[email protected]>
Commit: Clemens Radermacher <[email protected]>
Update docs
---
README.org | 46 +++++++++++++++++++++++++---------------------
clipboard-collector.el | 17 ++++++++++++-----
2 files changed, 37 insertions(+), 26 deletions(-)
diff --git a/README.org b/README.org
index 51f487e..6c992a1 100644
--- a/README.org
+++ b/README.org
@@ -1,16 +1,29 @@
* Introduction
When collecting information using copy/paste, it would be useful if one could
-stay at one place to copy things instead of constantly switching between the
-place where you copy and the place where you paste.
+stay at one place to copy things and later insert them all at once at another
+place. Emacs has =append-next-kill= but it only works inside Emacs and it only
+applies to the very next command. Further it would be great if Emacs could
+detect specific clipboard entries and transform them to a different format
+automatically. =clipboard-collector= provides you with those features.
-Further it would be great if Emacs could detect clipboard entries and adjust
-them to the format one would like to have them.
+You can use it to simply collect multiple entries by binding
+=clipboard-collector-mode= to a key:
-This is what clipboard-collector is about. Here is an example for collecting
-contact information from a website for org capture (contact info gets
-transformed to be used as org property drawer items).
+#+BEGIN_SRC elisp
+(global-set-key (kbd "C-M-w") 'clipboard-collector-mode)
+#+END_SRC
+
+Once called the clipboard is observed and any text that is copied/killed gets
+collected (even when done outside of Emacs). To finish use =C-c C-c= in any
+buffer to insert the collected items separated by newlines.
+
+If you want to have specific rules which items are added and maybe transform
+them before collecting them you can create you own commands using
+=clipboard-collector-create= macro.
+Here is an example for collecting contact information from a website for org
+capture (contact info gets transformed to be used as org property drawer
items).
#+BEGIN_SRC elisp
(clipboard-collector-create cc-capture-rss
@@ -35,20 +48,11 @@ When done collecting, you can press =C-c C-c= to call the
finalize function (in
the above example it would inserts the collected items separated by newlines
and
finish org-capture).
-If you would like to simply collect items as they are and paste them at some
-other place you could use:
-
-#+BEGIN_SRC elisp
-(global-set-key (kbd "C-M-w")
- (clipboard-collector-create cc-all
- ((".*" "%s"))))
-#+END_SRC
-
-It's also possible to provide a function to transform the contents before
-applying the format string. For example to upcase all collected items you could
-use something like this:
+Rules can also contain a function which gets applied to the clipboard entry
+before the format string is applied. You can use match-data of your matching
+regex in that function, too:
#+BEGIN_SRC elisp
-(clipboard-collector-create cc-all-up
- ((".*" "Upcased: %s" upcase)))
+(clipboard-collector-create cc-url
+ (("https?://\\(.*\\)" "Url: %s" (lambda (item) (match-string 1 item)))))
#+END_SRC
diff --git a/clipboard-collector.el b/clipboard-collector.el
index e987316..a980b83 100644
--- a/clipboard-collector.el
+++ b/clipboard-collector.el
@@ -38,6 +38,7 @@
"This keymap sets up the exit binding for clipboard collection
commands.")
+;;;###autoload
(define-minor-mode clipboard-collector-mode
"Start collecting clipboard items.
@@ -46,6 +47,10 @@ Rules used are defined in `clipboard-collector--rules'."
:global t
(if clipboard-collector-mode
(progn
+ ;; set defaults
+ (setq clipboard-collector--finish-function
+ #'clipboard-collector-finish-default)
+ (setq clipboard-collector--rules '((".*" "%s")))
(setq clipboard-collector--last-clip "")
(funcall interprogram-cut-function "")
(setq clipboard-collector--items nil)
@@ -108,7 +113,7 @@ ITEM is added to `clipboard-collector--items'."
;; configure those for collecting
-(defvar clipboard-collector--rules nil
+(defvar clipboard-collector--rules '((".*" "%s"))
"Clipboard collection rules.
Uses the following list format:
@@ -126,7 +131,8 @@ specify TRANSFORM-CLIPBOARD-FUNC. This is applied before
contents
are applied to TRANSFORM-FORMAT-STRING and can use match-data of
the matched regex.")
-(defvar clipboard-collector--finish-function nil
+(defvar clipboard-collector--finish-function
+ #'clipboard-collector-finish-default
"Default function used by `clipboard-collector-finish'.")
(defvar clipboard-collector--timer nil)
@@ -138,7 +144,7 @@ Uses `clipboard-collector--finish-function' ."
(interactive)
(clipboard-collector-mode -1)
(funcall clipboard-collector--finish-function
- (nreverse (mapcar #'cdr clipboard-collector--items)))))
+ (nreverse (mapcar #'cdr clipboard-collector--items))))
(defvar clipboard-collector-display-function
#'clipboard-collector-display
@@ -157,6 +163,7 @@ Called with collected item.")
(insert (pop items)
(if items "\n" "")))))
+;;;###autoload
(defmacro clipboard-collector-create (name rules &optional finishf)
"Create clipboard collector command named NAME.
@@ -183,10 +190,10 @@ This command enables `clipboard-collector-mode' which
binds
on the collected items. "
(pp rules) (pp finishf))
(interactive)
+ (clipboard-collector-mode 1)
(setq clipboard-collector--finish-function
(or ',finishf #'clipboard-collector-finish-default))
- (setq clipboard-collector--rules ',rules)
- (clipboard-collector-mode 1)))
+ (setq clipboard-collector--rules ',rules)))
(provide 'clipboard-collector)
