org-favtable new version 2.1 replaces org-reftable
[worg.git] / code / elisp / org-favtable.el
1 ;;; org-favtable.el --- Table of favorite references and links\r
2 \r
3 ;; Copyright (C) 2011-2013 Free Software Foundation, Inc.\r
4 \r
5 ;; Author: Marc-Oliver Ihm <org-favtable@ferntreffer.de>\r
6 ;; Keywords: hypermedia, matching\r
7 ;; Requires: org\r
8 ;; Download: http://orgmode.org/worg/code/elisp/org-favtable.el\r
9 ;; Version: 2.1.0\r
10 \r
11 ;;; License:\r
12 \r
13 ;; This program is free software; you can redistribute it and/or modify\r
14 ;; it under the terms of the GNU General Public License as published by\r
15 ;; the Free Software Foundation; either version 3, or (at your option)\r
16 ;; any later version.\r
17 ;;\r
18 ;; This program is distributed in the hope that it will be useful,\r
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of\r
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
21 ;; GNU General Public License for more details.\r
22 ;;\r
23 ;; You should have received a copy of the GNU General Public License\r
24 ;; along with GNU Emacs; see the file COPYING.  If not, write to the\r
25 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,\r
26 ;; Boston, MA 02110-1301, USA.\r
27 \r
28 ;;; Commentary:\r
29 \r
30 ;; Purpose:\r
31 ;;\r
32 ;;  Mark and find your favorite items and org-locations easily: Create and\r
33 ;;  update a lookup table of your favorite references and links. Often used\r
34 ;;  entries automatically bubble to the top of the table; entering some\r
35 ;;  keywords narrows it to just the matching entries; that way the right\r
36 ;;  one can be picked easily.\r
37 ;;\r
38 ;;  References are essentially small numbers (e.g. "R237" or "-455-"), as\r
39 ;;  created by this package; links are normal org-mode links.\r
40 ;;\r
41 ;;\r
42 ;; Setup:\r
43 ;;\r
44 ;;  - Add these lines to your .emacs:\r
45 ;;\r
46 ;;    (require 'org-favtable)\r
47 ;;    ;; Good enough to start, but later you should probably \r
48 ;;    ;; change this id, as will be explained below\r
49 ;;    (setq org-favtable-id "00e26bef-1929-4110-b8b4-7eb9c9ab1fd4")\r
50 ;;    ;; Optionally assign a key. Pick your own favorite.\r
51 ;;    (global-set-key (kbd "C-+") 'org-favtable)\r
52 ;;\r
53 ;;  - Just invoke `org-favtable', which will explain how to complete your\r
54 ;;    setup by creating the necessary table of favorites.\r
55 ;;\r
56 ;;\r
57 ;; Further reading:\r
58 ;;\r
59 ;;  Invoke `org-favtable' and pick one of its help options. You may also\r
60 ;;  read the documentation of `org-favtable-id' for setup instructions, of\r
61 ;;  `org-favtable' for regular usage and of `org-favtable--commands' for a\r
62 ;;  list of available commands.\r
63 ;;\r
64 \r
65 ;;; Change Log:\r
66 \r
67 ;;   [2013-01-25 Fr] Version 2.1.0:\r
68 ;;    - Added full support for links\r
69 ;;    - New commands "missing" and "statistics"\r
70 ;;    - Renamed the package from "org-reftable" to "org-favtable"\r
71 ;;    - Additional columns are required (e.g. "link"). Error messages will\r
72 ;;      guide you\r
73 ;;\r
74 ;;   [2012-12-07 Fr] Version 2.0.0:\r
75 ;;    - The format of the table of favorites has changed ! You need to bring\r
76 ;;      your existing table into the new format by hand (which however is\r
77 ;;      easy and explained below)\r
78 ;;    - Reference table can be sorted after usage count or date of last access\r
79 ;;    - Ask user explicitly, which command to invoke\r
80 ;;    - Renamed the package from "org-refer-by-number" to "org-reftable"\r
81 \r
82 ;;   [2012-09-22 Sa] Version 1.5.0:\r
83 ;;    - New command "sort" to sort a buffer or region by reference number\r
84 ;;    - New commands "highlight" and "unhighlight" to mark references\r
85 \r
86 ;;   [2012-07-13 Fr] Version 1.4.0:\r
87 ;;    - New command "head" to find a headline with a reference number\r
88 \r
89 ;;   [2012-04-28 Sa] Version 1.3.0:\r
90 ;;    - New commands occur and multi-occur\r
91 ;;    - All commands can now be invoked explicitly\r
92 ;;    - New documentation\r
93 ;;    - Many bugfixes\r
94 \r
95 ;;   [2011-12-10 Sa] Version 1.2.0:\r
96 ;;    - Fixed a bug, which lead to a loss of newly created reference numbers\r
97 ;;    - Introduced single and double prefix arguments\r
98 ;;    - Started this Change Log\r
99 \r
100 ;;; Code:\r
101 \r
102 (require 'org-table)\r
103 (require 'cl)\r
104 \r
105 (defvar org-favtable--version "2.1.0")\r
106 (defvar org-favtable--preferred-command nil)\r
107 \r
108 (defvar org-favtable--commands '(occur head ref link enter leave goto + help reorder fill sort update highlight unhighlight missing statistics)\r
109   "List of commands known to org-favtable:\r
110  \r
111 \r
112   occur: If you supply a keyword (text): Apply emacs standard\r
113     occur operation on the table of favorites; ask for a\r
114     string (keyword) to select lines. Occur will only show you\r
115     lines which contain the given keyword, so you can easily find\r
116     the right one. You may supply a list of words seperated by\r
117     comma (\",\"), to select lines that contain any or all of the\r
118     given words.\r
119 \r
120     If you supply a reference number: Apply emacs standard\r
121     multi-occur operation all org-mode buffers to search for a\r
122     specific reference.\r
123 \r
124     You may also read the note at the end of this help on saving\r
125     the keystroke RET to accept this frequent default command.\r
126 \r
127   head: If invoked outside the table of favorites, ask for a\r
128     reference number and search for a heading containing it. If\r
129     invoked within favtable dont ask; rather use the reference or\r
130     link from the current line.\r
131 \r
132   ref: Create a new reference, copy any previously selected text.\r
133     If already within reftable, fill in ref-column.\r
134 \r
135   link: Create a new line in reftable with a link to the current node. \r
136     Do not populate the ref column; this can later be populated by\r
137     calling the \"fill\" command from within the reftable.\r
138 \r
139   leave: Leave the table of favorites. If the last command has\r
140     been \"ref\", the new reference is copied and ready to yank.\r
141 \r
142   enter: Just enter the node with the table of favorites.\r
143 \r
144   goto: Search for a specific reference within the table of\r
145     favorites.\r
146 \r
147   help: Show this list of commands.\r
148 \r
149   +: Show all commands including the less frequently used ones\r
150     given below. If \"+\" is followd by enough letters of such a\r
151     command (e.g. \"+fi\"), then this command is invoked\r
152     directly.\r
153 \r
154   reorder: Temporarily reorder the table of favorites, e.g. by\r
155     count, reference or last access.\r
156 \r
157   fill: If either ref or link is missing, fill it.\r
158 \r
159   sort: Sort a set of lines (either the active region or the\r
160     whole buffer) by the references found in each line.\r
161 \r
162   update: For the given reference, update the line in the\r
163     favtable.\r
164 \r
165   highlight: Highlight references in region or buffer.\r
166 \r
167   unhighlight: Remove highlights.\r
168 \r
169   missing : Search for missing reference numbers (which do not\r
170     appear in the reference table). If requested, add additional\r
171     lines for them, so that the command \"new\" is able to reuse\r
172     them.\r
173 \r
174   statistics : Show some statistics (e.g. minimum and maximum\r
175     reference) about favtable.\r
176 \r
177 \r
178 When prompting for a command, org-favtable puts the most likely\r
179 chosen one (e.g. \"occur\" or \"ref\") at the front of the list,\r
180 so that you may just type RET. \r
181 \r
182 If this command needs additional input (like e.g. \"occur\"), you\r
183 may supply this input right away, although you are still beeing\r
184 prompted for the command.\r
185 \r
186 ")\r
187 \r
188 (defvar org-favtable--commands-some '(occur head ref link leave enter goto + help))\r
189 \r
190 (defvar org-favtable--columns nil)\r
191 \r
192 (defvar org-favtable-id nil \r
193   "Id of the Org-mode node, which contains the favorite table.\r
194 \r
195 Read below, on how to set up things. See the help options\r
196 \"usage\" and \"commands\" for normal usage after setup.\r
197 \r
198 Setup requires two steps:\r
199 \r
200  - Adjust your .emacs initialization file\r
201 \r
202  - Create a suitable org-mode node\r
203 \r
204 \r
205 Here are the lines, you need to add to your .emacs:\r
206 \r
207   (require 'org-favtable)\r
208   ;; Good enough to start, but later you should probably \r
209   ;; change this id, as will be explained below\r
210   (setq org-favtable-id \"00e26bef-1929-4110-b8b4-7eb9c9ab1fd4\")\r
211   ;; Optionally assign a key. Pick your own favorite.\r
212   (global-set-key (kbd \"C-+\") 'org-favtable)\r
213 \r
214 Do not forget to restart emacs to make these lines effective.\r
215 \r
216 \r
217 As a second step you need to create the org-mode node, where your\r
218 reference numbers and links will be stored. It may look like\r
219 this:\r
220 \r
221   * org-favtable\r
222     :PROPERTIES:\r
223     :ID:       00e26bef-1929-4110-b8b4-7eb9c9ab1fd4\r
224     :END:\r
225 \r
226 \r
227     |     |      | Comment, description, details  |         |         |               |\r
228     | ref | link | ;c                             | count;s | created | last-accessed |\r
229     |     | <4>  | <30>                           |         |         |               |\r
230     |-----+------+--------------------------------+---------+---------+---------------|\r
231     | R1  |      | My first reference             |         |         |               |\r
232 \r
233 \r
234 You may just copy this node into one of your org-files.  Many\r
235 things however can or should be adjusted:\r
236 \r
237  - The node needs not be a top level node.\r
238 \r
239  - Its name is completely at you choice. The node is found\r
240    through its ID.\r
241 \r
242  - There are three lines of headings above the first hline. The\r
243    first one is ignored by org-favtable, and you can use them to\r
244    give meaningful names to columns; the second line contains\r
245    configuration information for org-favtable; please read\r
246    further below for its format. The third line is optional and\r
247    may contain width-informations (e.g. <30>) only.\r
248 \r
249  - The sequence of columns does not matter. You may reorder them\r
250    any way you like; e.g. make the comment-column the last\r
251    columns within the table. Columns ar found by their name,\r
252    which appears in the second heading-line.\r
253 \r
254  - You can add further columns or even remove the\r
255    \"Comment\"-column. All other columns from the\r
256    example (e.g. \"ref\", \"link\", \"count\", \"created\" and\r
257    \"last-accessed\") are required.\r
258 \r
259  - Your references need not start at \"R1\"; However, having an\r
260    initial row is required (it serves as a template for subsequent\r
261    references).\r
262 \r
263  - Your reference need not have the form \"R1\"; you may just as\r
264    well choose any text, that contains a single number,\r
265    e.g. \"reference-{1}\" or \"#7\" or \"++17++\" or \"-344-\". The\r
266    function `org-favtable' will inspect your first reference and\r
267    create all subsequent references in the same way.\r
268     \r
269  - You may want to change the ID-Property of the node above and\r
270    create a new one, which is unique (and not just a copy of\r
271    mine). You need to change it in the lines copied to your .emacs\r
272    too. However, this is not strictly required to make things\r
273    work, so you may do this later, after trying out this package.\r
274 \r
275 \r
276 Optionally you may tweak the second header line to adjust\r
277 `org-favtable' a bit. In the example above it looks like this\r
278  (with spaces collapsed):\r
279 \r
280 \r
281     | ref | link | ;c | count;s | created | last-accessed |\r
282 \r
283 \r
284 The different fields have different meanings:\r
285 \r
286  - ref : This denotes the column which contains you references\r
287 \r
288  - link : Column for org-mode links, which can be used to access\r
289    locations within your files.\r
290 \r
291  - ;c : The flag \"c\" (\"c\" for \"copy\") denotes this column\r
292    as the one beeing copied on command \"leave\". In the example\r
293    above, it is also the comment-column.\r
294 \r
295  - count;s : this is the column which counts, how many time this\r
296    line has been accessed (which is the key-feature of this\r
297    package). The flag \"s\" stands for \"sort\", so the table is\r
298    sorted after this column. You may also sort after columns\r
299    \"ref\" or \"last-accessed\".\r
300 \r
301  - created : Date when this line was created.\r
302 \r
303  - last-accessed : Date and time, when this line was last accessed.\r
304 \r
305 \r
306 After this two-step setup process you may invoke `org-favtable'\r
307 to create a new favorite. Read the help option \"usage\" for\r
308 instructions on normal usage, read the help option \"commands\"\r
309 for help on single commands.\r
310 \r
311 ")\r
312 \r
313 \r
314 (defvar org-favtable--windowconfig-before nil)\r
315 (defvar org-favtable--marker-outside-before nil)\r
316 (defvar org-favtable--last-action nil)\r
317 (defvar org-favtable--occur-buffer nil)\r
318 (defvar org-favtable--ref-regex nil)\r
319 (defvar org-favtable--ref-format nil)\r
320 \r
321 \r
322 \r
323 (defun org-favtable  (&optional what search search-is-link) \r
324   "Mark and find your favorite items and org-locations easily:\r
325 Create and update a lookup table of your favorite references and\r
326 links. Often used entries automatically bubble to the top of the\r
327 table; entering some keywords narrows it to just the matching\r
328 entries; that way the right one can be picked easily.\r
329 \r
330 References are essentially small numbers (e.g. \"R237\" or\r
331 \"-455-\"), as created by this package; links are normal org-mode\r
332 links. Within org-favtable, both are denoted as favorites.\r
333 \r
334 \r
335 Read below for a detailed description of this function. See the\r
336 help option \"setup\" or read the documentation of\r
337 `org-favtable-id' for setup instructions.\r
338 \r
339 The function `org-favtable' operates on a dedicated table (called\r
340 the table or favorites or favtable, for short) within a special\r
341 Org-mode node. The node has to be created as part of your initial\r
342 setup. Each line of the favorite table contains:\r
343 \r
344  - A reference (optional)\r
345 \r
346  - A link (optional)\r
347 \r
348  - A number; counting, how often each reference has been\r
349    used. This number is updated automatically and the table can\r
350    be sorted according to it, so that most frequently used\r
351    references appear at the top of the table and can be spotted\r
352    easily.\r
353 \r
354  - Its respective creation date\r
355 \r
356  - Date and time of last access. This column can alternatively be\r
357    used to sort the table.\r
358 \r
359 To be useful, your table of favorites should probably contain a\r
360 column with comments too, which allows lines to be selected by\r
361 keywords.\r
362 \r
363 The table of favorites is found through the id of the containing\r
364 node; this id should be stored within `org-favtable-id' (see there\r
365 for details).\r
366 \r
367 \r
368 The function `org-favtable' is the only interactive function of\r
369 this package and its sole entry point; it offers several commands\r
370 to create, find and look up these favorites (references and\r
371 links). All of them are explained within org-favtable's help.\r
372 \r
373 \r
374 Finally, org-favtable can also be invoked from elisp; the two\r
375 optional arguments accepted are:\r
376 \r
377          search : string to search for\r
378            what : symbol of the command to invoke\r
379  search-is-link : t, if argument search is actually a link\r
380 \r
381 An example would be:\r
382 \r
383  (org-favtable \"237\" 'head)   ;; find heading with ref 237\r
384 \r
385 "\r
386 \r
387   (interactive "P")\r
388 \r
389 (let (within-node        ; True, if we are within node with favtable\r
390       result-is-visible  ; True, if node or occur is visible in any window\r
391       ref-node-buffer-and-point ; cons with buffer and point of favorites node\r
392       below-cursor              ; word below cursor\r
393       active-region             ; active region (if any)\r
394       link-id                   ; link of starting node, if required\r
395       guarded-search            ; with guard against additional digits\r
396       search-is-ref             ; true, if search is a reference\r
397       commands                ; currently active set of selectable commands\r
398       what-adjusted           ; True, if we had to adjust what\r
399       what-input    ; Input on what question (need not necessary be "what")\r
400       reorder-once  ; Column to use for single time sorting\r
401       parts         ; Parts of a typical reference number (which\r
402                     ; need not be a plain number); these are:\r
403       head               ; Any header before number (e.g. "R")\r
404       maxref             ; Maximum number from reference table (e.g. "153")\r
405       tail               ; Tail after number (e.g. "}" or "")\r
406       ref-regex          ; Regular expression to match a reference\r
407       has-reuse          ; True, if table contains a line for reuse\r
408       numcols            ; Number of columns in favtable\r
409       kill-new-text      ; Text that will be appended to kill ring\r
410       message-text       ; Text that will be issued as an explanation,\r
411                                                   ; what we have done\r
412       initial-ref-or-link                    ; initial position in reftable\r
413       )\r
414 \r
415   ;;\r
416   ;; Examine current buffer and location, before turning to favtable\r
417   ;;\r
418 \r
419   ;; Get the content of the active region or the word under cursor\r
420   (if (and transient-mark-mode\r
421            mark-active)\r
422       (setq active-region (buffer-substring (region-beginning) (region-end))))\r
423   (setq below-cursor (thing-at-point 'symbol))\r
424 \r
425 \r
426   ;; Find out, if we are within favable or not\r
427   (setq within-node (string= (org-id-get) org-favtable-id))\r
428 \r
429   ;; Find out, if point in any window is within node with favtable\r
430   (mapc (lambda (x) (with-current-buffer (window-buffer x)\r
431                       (when (or \r
432                              (string= (org-id-get) org-favtable-id)\r
433                              (eq (window-buffer x) \r
434                                  org-favtable--occur-buffer))\r
435                         (setq result-is-visible t))))\r
436         (window-list))\r
437         \r
438 \r
439 \r
440   ;;\r
441   ;; Get decoration of references and highest reference from favtable\r
442   ;;\r
443 \r
444 \r
445   ;; Save initial ref or link\r
446   (if (and within-node\r
447            (org-at-table-p))\r
448       (setq initial-ref-or-link \r
449             (or (org-favtable--get-field 'ref)\r
450                 (org-favtable--get-field 'link))))\r
451 \r
452   ;; Find node\r
453   (setq ref-node-buffer-and-point (org-favtable--id-find))\r
454   (unless ref-node-buffer-and-point\r
455     (org-favtable--report-setup-error \r
456      (format "Cannot find node with id \"%s\"" org-favtable-id)))\r
457 \r
458   ;; Get configuration of reftable; catch errors\r
459   (let ((error-message\r
460          (catch 'content-error\r
461 \r
462            (with-current-buffer (car ref-node-buffer-and-point)\r
463              (unless (string= (org-id-get) org-favtable-id)\r
464 \r
465                ;; Get marker for point within reftable-buffer, but only if outside\r
466                ;; of reftable (if point is within reftable, we will try to stay at\r
467                ;; the same ref)\r
468                (setq org-favtable--marker-outside-before (point-marker))\r
469                (goto-char (cdr ref-node-buffer-and-point)))\r
470 \r
471              ;; parse table while still within buffer\r
472              (save-excursion\r
473                (setq parts (org-favtable--parse-and-adjust-table)))\r
474               \r
475              nil))))\r
476     (when error-message \r
477       (org-pop-to-buffer-same-window (car ref-node-buffer-and-point))\r
478       (org-reveal)\r
479       (error error-message)))\r
480 \r
481   ;; Give names to parts of configuration\r
482   (setq head (nth 0 parts))\r
483   (setq maxref (nth 1 parts))\r
484   (setq tail (nth 2 parts))\r
485   (setq numcols (nth 3 parts))\r
486   (setq ref-regex (nth 4 parts))\r
487   (setq has-reuse (nth 5 parts))\r
488   (setq org-favtable--ref-regex ref-regex)\r
489   (setq org-favtable--format (concat head "%d" tail))\r
490 \r
491   ;;\r
492   ;; Find out, what we are supposed to do\r
493   ;;\r
494 \r
495   (if (equal what '(4)) (setq what 'leave))\r
496 \r
497   ;; Set preferred action, that will be the default choice\r
498   (setq org-favtable--preferred-command\r
499         (if within-node\r
500             (if (memq org-favtable--last-action '(ref link))\r
501                 'leave\r
502               'occur)\r
503           (if active-region\r
504               'ref\r
505             (if (and below-cursor (string-match ref-regex below-cursor))\r
506                 'occur\r
507               nil))))\r
508     \r
509   ;; Ask user, what to do\r
510   (unless what\r
511     (setq commands (copy-list org-favtable--commands-some))\r
512     (while (progn\r
513              (setq what-input\r
514                    (org-icompleting-read \r
515                     "Please choose: " \r
516                     (mapcar 'symbol-name \r
517                             ;; Construct unique list of commands with\r
518                             ;; preferred one at front\r
519                             (delq nil (delete-dups \r
520                                        (append \r
521                                         (list org-favtable--preferred-command)\r
522                                         commands))))\r
523                     nil nil))\r
524 \r
525 \r
526              ;; if input starts with "+" any command (not only some) may follow\r
527              (when (string= (substring what-input 0 1) "+")\r
528                ;; make all commands available for selection\r
529                (setq commands (copy-list org-favtable--commands))\r
530                (unless (string= what-input "+") \r
531                  ;; not just "+", use following string\r
532                  (setq what-input (substring what-input 1))\r
533                  \r
534                  (let ((completions\r
535                         ;; get list of possible completions for what-input\r
536                         (all-completions what-input (mapcar 'symbol-name org-favtable--commands))))\r
537                    ;; use it, if unambigously\r
538                    (if (= (length completions) 1)\r
539                        (setq what-input (car completions))))))\r
540 \r
541 \r
542              (setq what (intern what-input))\r
543                \r
544              ;; user is not required to input one of the commands; if\r
545              ;; not, take the first one and use the original input for\r
546              ;; next question\r
547              (if (memq what commands)\r
548                  ;; input matched one element of list, dont need original\r
549                  ;; input any more\r
550                  (setq what-input nil)\r
551                ;; what-input will be used for next question, use first\r
552                ;; command for what\r
553                (setq what (or org-favtable--preferred-command\r
554                               (first commands)))\r
555                ;; remove any trailing dot, that user might have added to\r
556                ;; disambiguate his input\r
557                (if (equal (substring what-input -1) ".")\r
558                    ;; but do this only, if dot was really necessary to\r
559                    ;; disambiguate\r
560                    (let ((shortened-what-input (substring what-input 0 -1)))\r
561                      (unless (test-completion shortened-what-input \r
562                                               (mapcar 'symbol-name \r
563                                                       commands))\r
564                        (setq what-input shortened-what-input)))))\r
565                      \r
566              ;; ask for reorder in loop, because we have to ask for\r
567              ;; what right again\r
568              (if (eq what 'reorder)\r
569                  (setq reorder-once\r
570                        (intern\r
571                         (org-icompleting-read \r
572                          "Please choose column to reorder reftable once: " \r
573                          (mapcar 'symbol-name '(ref count last-accessed))\r
574                          nil t))))\r
575                \r
576              ;; maybe ask initial question again\r
577              (memq what '(reorder +)))))\r
578 \r
579 \r
580   ;;\r
581   ;; Get search, if required\r
582   ;;\r
583 \r
584   ;; These actions need a search string:\r
585   (when (memq what '(goto occur head update))\r
586 \r
587     ;; Maybe we've got a search string from the arguments\r
588     (unless search\r
589       (let (search-from-table\r
590             search-from-cursor)\r
591           \r
592         ;; Search string can come from several sources:\r
593         ;; From ref column of table\r
594         (when within-node\r
595           (setq search-from-table (org-favtable--get-field 'ref)))      \r
596         ;; From string below cursor\r
597         (when (and (not within-node)\r
598                    below-cursor\r
599                    (string-match (concat "\\(" ref-regex "\\)") \r
600                                  below-cursor))\r
601           (setq search-from-cursor (match-string 1 below-cursor)))\r
602           \r
603         ;; Depending on requested action, get search from one of the sources above\r
604         (cond ((eq what 'goto)\r
605                (setq search (or what-input search-from-cursor)))\r
606               ((memq what '(head occur))\r
607                (setq search (or what-input search-from-table search-from-cursor))))))\r
608 \r
609 \r
610     ;; If we still do not have a search string, ask user explicitly\r
611     (unless search\r
612         \r
613       (if what-input \r
614           (setq search what-input)\r
615         (setq search (read-from-minibuffer\r
616                       (cond ((memq what '(occur head))\r
617                              "Text or reference number to search for: ")\r
618                             ((eq what 'goto)\r
619                              "Reference number to search for, or enter \".\" for id of current node: ")\r
620                             ((eq what 'update)\r
621                              "Reference number to update: ")))))\r
622 \r
623       (if (string-match "^\\s *[0-9]+\\s *$" search)\r
624           (setq search (format "%s%s%s" head (org-trim search) tail))))\r
625       \r
626     ;; Clean up and examine search string\r
627     (if search (setq search (org-trim search)))\r
628     (if (string= search "") (setq search nil))\r
629     (setq search-is-ref (string-match ref-regex search))\r
630 \r
631     ;; Check for special case\r
632     (when (and (memq what '(head goto))\r
633                (string= search "."))\r
634       (setq search (org-id-get))\r
635       (setq search-is-link t))\r
636 \r
637     (when search-is-ref\r
638       (setq guarded-search (org-favtable--make-guarded-search search)))\r
639 \r
640     ;;\r
641     ;; Do some sanity checking before really starting\r
642     ;;\r
643 \r
644     ;; Correct requested action, if nothing to search\r
645     (when (and (not search)\r
646                (memq what '(search occur head)))\r
647       (setq what 'enter)\r
648       (setq what-adjusted t))\r
649 \r
650     ;; For a proper reference as input, we do multi-occur\r
651     (if (and (string-match ref-regex search)\r
652              (eq what 'occur))\r
653         (setq what 'multi-occur))\r
654 \r
655     ;; Check for invalid combinations of arguments; try to be helpful\r
656     (when (and (memq what '(head goto))\r
657                (not search-is-link)\r
658                (not search-is-ref))\r
659       (error "Can do '%s' only for a reference or link (not '%s'), try 'occur' to search for text" what search)))\r
660 \r
661     \r
662   ;;\r
663   ;; Prepare\r
664   ;;\r
665 \r
666   ;; Get link if required before moving in\r
667   (if (eq what 'link)\r
668       (setq link-id (org-id-get-create)))\r
669 \r
670   ;; Move into table, if outside\r
671   (when (memq what '(enter ref link goto occur multi-occur missing statistics))\r
672     ;; Save current window configuration\r
673     (when (or (not result-is-visible)\r
674               (not org-favtable--windowconfig-before))\r
675       (setq org-favtable--windowconfig-before (current-window-configuration)))\r
676 \r
677     ;; Switch to favtable\r
678     (org-pop-to-buffer-same-window (car ref-node-buffer-and-point))\r
679     (goto-char (cdr ref-node-buffer-and-point))\r
680     (show-subtree)\r
681     (org-show-context)\r
682 \r
683     ;; sort favtable\r
684     (org-favtable--sort-table reorder-once))\r
685 \r
686   ;; Goto back to initial ref, because reformatting of table above might\r
687   ;; have moved point\r
688   (when initial-ref-or-link\r
689     (while (and (org-at-table-p)\r
690                 (not (or\r
691                       (string= initial-ref-or-link (org-favtable--get-field 'ref))\r
692                       (string= initial-ref-or-link (org-favtable--get-field 'link)))))\r
693       (forward-line))\r
694     ;; did not find ref, go back to top\r
695     (if (not (org-at-table-p)) (goto-char top)))\r
696 \r
697 \r
698   ;;\r
699   ;; Actually do, what is requested\r
700   ;;\r
701 \r
702   (cond\r
703 \r
704 \r
705    ((eq what 'help)\r
706       \r
707     (let ((help-what\r
708            ;; which sort of help ?\r
709            (intern\r
710             (concat \r
711              "help-"\r
712              (org-icompleting-read \r
713               "Help on: "\r
714               (mapcar 'symbol-name '(commands usage setup version example)) \r
715               nil t)))))\r
716 \r
717       ;; help is taken from docstring of functions or variables\r
718       (cond ((eq help-what 'help-commands)\r
719              (org-favtable--show-help 'org-favtable--commands))\r
720             ((eq help-what 'help-usage)\r
721              (org-favtable--show-help 'org-favtable))\r
722             ((eq help-what 'help-setup)\r
723              (org-favtable--show-help 'org-favtable-id))\r
724             ((eq help-what 'help-version)\r
725              (org-favtable-version)))))\r
726 \r
727 \r
728    ((eq what 'multi-occur) \r
729       \r
730     ;; Conveniently position cursor on number to search for\r
731     (org-favtable--goto-top)\r
732     (let (found (initial (point)))\r
733       (while (and (not found)\r
734                   (forward-line)\r
735                   (org-at-table-p))\r
736         (save-excursion \r
737           (setq found (string= search \r
738                                (org-favtable--get-field 'ref)))))\r
739       (if found \r
740           (org-favtable--update-line nil)\r
741         (goto-char initial)))\r
742 \r
743     ;; Construct list of all org-buffers\r
744     (let (buff org-buffers)\r
745       (dolist (buff (buffer-list))\r
746         (set-buffer buff)\r
747         (if (string= major-mode "org-mode")\r
748             (setq org-buffers (cons buff org-buffers))))\r
749 \r
750       ;; Do multi-occur\r
751       (multi-occur org-buffers guarded-search)\r
752       (if (get-buffer "*Occur*")\r
753           (progn \r
754             (setq message-text (format "multi-occur for '%s'" search))\r
755             (setq org-favtable--occur-buffer (get-buffer "*Occur*"))\r
756             (other-window 1)\r
757             (toggle-truncate-lines 1))\r
758         (setq message-text (format "Did not find '%s'" search)))))\r
759 \r
760 \r
761    ((eq what 'head)\r
762 \r
763     (let (link)\r
764       ;; link either from table or passed in as argument\r
765         \r
766       ;; try to get link\r
767       (if search-is-link \r
768           (setq link (org-trim search))\r
769         (if (and within-node\r
770                  (org-at-table-p))\r
771             (setq link (org-favtable--get-field 'link))))\r
772 \r
773       ;; use link if available\r
774       (if (and link\r
775                (not (string= link "")))\r
776           (progn \r
777             (org-id-goto link)\r
778             (org-favtable--update-line search)\r
779             (setq message-text "Followed link"))\r
780 \r
781         (message (format "Scanning headlines for '%s' ..." search))\r
782         (let (buffer point)\r
783           (if (catch 'found\r
784                 (progn\r
785                   ;; loop over all headlines, stop on first match\r
786                   (org-map-entries \r
787                    (lambda () \r
788                      (when (looking-at (concat ".*" guarded-search))\r
789                        ;; remember location and bail out\r
790                        (setq buffer (current-buffer))\r
791                        (setq point (point))\r
792                        (throw 'found t)))          \r
793                    nil 'agenda)\r
794                   nil))\r
795 \r
796               (progn\r
797                 (org-favtable--update-line search)\r
798                 (setq message-text (format "Found '%s'" search))\r
799                 (org-pop-to-buffer-same-window buffer)\r
800                 (goto-char point)\r
801                 (org-reveal))\r
802             (setq message-text (format "Did not find '%s'" search)))))))\r
803 \r
804 \r
805    ((eq what 'leave)\r
806 \r
807     (when result-is-visible\r
808 \r
809       ;; If we are within the occur-buffer, switch over to get current line\r
810       (if (and (string= (buffer-name) "*Occur*")\r
811                (eq org-favtable--last-action 'occur))\r
812           (occur-mode-goto-occurrence))\r
813 \r
814       (let (copy-column)              \r
815         ;; Try to copy requested column\r
816         (setq copy-column (org-favtable--column-num (if (eq org-favtable--last-action 'ref)\r
817                                                         'goto\r
818                                                       'copy)))\r
819             \r
820         ;; Add to kill ring\r
821         (if (memq org-favtable--last-action '(ref enter goto occur))\r
822             (setq kill-new-text \r
823                   (org-trim (org-table-get-field copy-column))))))\r
824 \r
825     ;; Restore position within buffer with favtable\r
826     (with-current-buffer (car ref-node-buffer-and-point)\r
827       (when org-favtable--marker-outside-before\r
828         (goto-char (marker-position org-favtable--marker-outside-before))\r
829         (move-marker org-favtable--marker-outside-before nil)))\r
830 \r
831     ;; Restore windowconfig\r
832     (if org-favtable--windowconfig-before \r
833         (progn  \r
834           ;; Restore initial window configuration\r
835           (set-window-configuration org-favtable--windowconfig-before)\r
836           (setq org-favtable--windowconfig-before nil)\r
837           ;; Goto initial position\r
838           (recenter)\r
839           (setq message-text "Back"))\r
840       ;; We did not have a window-configuration to restore, so we cannot\r
841       ;; pretend we have returned back\r
842       (setq message-text "Cannot leave; nowhere to go to")\r
843       (setq kill-new-text nil)))\r
844 \r
845 \r
846    ((eq what 'goto)\r
847 \r
848     ;; Go downward in table to requested reference\r
849     (let (found (initial (point)))\r
850       (org-favtable--goto-top)\r
851       (while (and (not found)\r
852                   (forward-line)\r
853                   (org-at-table-p))\r
854         (save-excursion \r
855           (setq found \r
856                 (string= search \r
857                          (org-favtable--get-field \r
858                           (if search-is-link 'link 'ref))))))\r
859       (if found\r
860           (progn\r
861             (setq message-text (format "Found '%s'" search))\r
862             (org-favtable--update-line nil)\r
863             (org-table-goto-column (org-favtable--column-num 'ref))\r
864             (if (looking-back " ") (backward-char)))\r
865         (setq message-text (format "Did not find '%s'" search))\r
866         (goto-char initial)\r
867         (forward-line)\r
868         (setq what 'missed))))\r
869 \r
870 \r
871    ((eq what 'occur)\r
872 \r
873     ;; search for string: occur\r
874     (let (search-regexp\r
875           all-or-any\r
876           (search-words (split-string search "," t)))\r
877             \r
878       (if (< (length search-words) 2)\r
879           ;; only one word to search; use it as is\r
880           (setq search-regexp search)\r
881         ;; construct regexp to match any of the words (maybe throw out some matches later)\r
882         (setq search-regexp \r
883               (mapconcat (lambda (x) (concat "\\(" x "\\)")) search-words "\\|"))\r
884         (setq all-or-any\r
885               (intern \r
886                (org-icompleting-read \r
887                 "Two or more words have been specified; show lines, that match: " '("all" "any")))))\r
888             \r
889       (save-restriction\r
890         (org-narrow-to-subtree)\r
891         (occur search-regexp)\r
892         (widen)\r
893         (if (get-buffer "*Occur*")\r
894             (with-current-buffer "*Occur*"\r
895 \r
896               ;; install helpful keyboard-shortcuts within occur-buffer\r
897               (let ((keymap (make-sparse-keymap)))\r
898                 (set-keymap-parent keymap occur-mode-map)\r
899 \r
900                 (define-key keymap (kbd "RET") \r
901                   (lambda () (interactive) \r
902                     (org-favtable--occur-helper 'head)))\r
903 \r
904                 (define-key keymap (kbd "<C-return>") \r
905                   (lambda () (interactive) \r
906                     (org-favtable--occur-helper 'multi-occur)))\r
907 \r
908                 (define-key keymap (kbd "<M-return>") \r
909                   (lambda () (interactive) \r
910                     (org-favtable--occur-helper 'goto)))\r
911 \r
912                 (define-key keymap (kbd "<C-M-return>") \r
913                   (lambda () (interactive) \r
914                     (org-favtable--occur-helper 'update)))\r
915 \r
916                 (use-local-map keymap))\r
917 \r
918               ;; Brush up occur buffer\r
919               (other-window 1)\r
920               (toggle-truncate-lines 1)\r
921               (let ((inhibit-read-only t)) \r
922                 ;; insert some help text\r
923                 (insert (substitute-command-keys \r
924                          "Type RET to find heading, C-RET for multi-occur, M-RET to go to occurence and C-M-RET to update line in reftable.\n\n"))\r
925                 (forward-line 1)\r
926 \r
927                 ;; when matching all of multiple words, remove all lines that do not match one of the words\r
928                 (when (eq all-or-any 'all)\r
929                   (mapc (lambda (x) (keep-lines x)) search-words))\r
930 \r
931                 ;; replace description from occur\r
932                 (when all-or-any \r
933                   (forward-line -1)\r
934                   (kill-line)\r
935                   (let ((count (- (count-lines (point) (point-max)) 1)))\r
936                     (insert (format "%d %s for %s of %s" \r
937                                     count \r
938                                     (if (= count 1) "match" "matches")\r
939                                     all-or-any\r
940                                     search)))\r
941                   (forward-line)\r
942                   (beginning-of-line))\r
943                   \r
944                 ;; Record link or reference for each line in\r
945                 ;; occur-buffer, that is linked into reftable. Because if\r
946                 ;; we later realign the reftable and then reuse the occur\r
947                 ;; buffer, the original links might point nowehere.\r
948                 (save-excursion\r
949                   (while (not (eq (point) (point-max)))\r
950                     (let ((beg (line-beginning-position))\r
951                           (end (line-end-position))\r
952                           pos ref link)\r
953 \r
954                       ;; occur has saved the position into a special property\r
955                       (setq pos (get-text-property (point) 'occur-target))\r
956                       (when pos \r
957                         ;; but this property might soon point nowhere; so retrieve ref-or-link instead\r
958                         (with-current-buffer (marker-buffer pos)\r
959                           (goto-char pos)\r
960                           (setq ref (org-favtable--get-field 'ref))\r
961                           (setq link (org-favtable--get-field 'link))))\r
962                       ;; save as text property\r
963                       (put-text-property beg end 'org-favtable--ref ref)\r
964                       (put-text-property beg end 'org-favtable--link link))\r
965                     (forward-line))))\r
966                   \r
967               (setq message-text\r
968                     (format  "Occur for '%s'" search)))\r
969           (setq message-text\r
970                 (format "Did not find any matches for '%s'" search))))))\r
971 \r
972 \r
973    ((memq what '(ref link))\r
974 \r
975     ;; add a new row (or reuse existing one)\r
976     (let (new)\r
977 \r
978       ;; go through table to find first entry to be reused\r
979       (when has-reuse\r
980         (org-favtable--goto-top)\r
981         ;; go through table\r
982         (while (and (org-at-table-p)\r
983                     (not new))\r
984           (when (string= \r
985                  (org-favtable--get-field 'count)\r
986                  ":reuse:")\r
987             (setq new (org-favtable--get-field 'ref))\r
988             (if new (org-table-kill-row)))\r
989           (forward-line)))\r
990         \r
991       ;; no ref to reuse; construct new reference\r
992       (unless new \r
993         (setq new (format "%s%d%s" head (1+ maxref) tail)))\r
994 \r
995       ;; insert ref as very first row\r
996       (org-favtable--goto-top)\r
997       (org-table-insert-row)\r
998         \r
999       ;; fill special columns with standard values\r
1000       (when (eq what 'ref)\r
1001         (org-table-goto-column (org-favtable--column-num 'ref))\r
1002         (insert new))\r
1003       (when (eq what 'link)\r
1004         (org-table-goto-column (org-favtable--column-num 'link))\r
1005         (insert link-id))\r
1006       (org-table-goto-column (org-favtable--column-num 'created))\r
1007       (org-insert-time-stamp nil nil t)\r
1008 \r
1009       ;; goto first nonempty field\r
1010       (catch 'empty\r
1011         (dotimes (col numcols)\r
1012           (org-table-goto-column (+ col 1))\r
1013           (if (string= (org-trim (org-table-get-field)) "")\r
1014               (throw 'empty t)))\r
1015         ;; none found, goto first\r
1016         (org-table-goto-column 1))\r
1017 \r
1018       (org-table-align)\r
1019       (if active-region (setq kill-new-text active-region))\r
1020       (if (eq what 'ref)\r
1021           (setq message-text (format "Adding a new row with ref '%s'" new))\r
1022         (setq message-text (format "Adding a new row linked to '%s'" link-id)))))\r
1023 \r
1024 \r
1025    ((eq what 'enter)\r
1026 \r
1027     ;; simply go into table\r
1028     (org-favtable--goto-top)\r
1029     (show-subtree)\r
1030     (recenter)\r
1031     (if what-adjusted\r
1032         (setq message-text "Nothing to search for; at favtable")\r
1033       (setq message-text "At favtable")))\r
1034 \r
1035      \r
1036    ((eq what 'fill)\r
1037 \r
1038     ;; check if within reftable\r
1039     (unless (and within-node\r
1040                  (org-at-table-p))\r
1041       (error "Not within table of favorites"))\r
1042 \r
1043     ;; applies to missing refs and missing links alike\r
1044     (let ((ref (org-favtable--get-field 'ref))\r
1045           (link (org-favtable--get-field 'link)))\r
1046 \r
1047       (if (and (not ref)\r
1048                (not link))\r
1049           ;; have already checked this during parse, check here anyway\r
1050           (error "Columns ref and link are both empty in this line"))\r
1051 \r
1052       ;; fill in new ref\r
1053       (if (not ref)\r
1054           (progn \r
1055             (setq kill-new-text (format "%s%d%s" head (1+ maxref) tail))\r
1056             (org-favtable--get-field 'ref kill-new-text)\r
1057             (org-id-goto link)\r
1058             (setq message-text "Filled reftable field with new reference"))\r
1059 \r
1060         ;; fill in new link\r
1061         (if (not link)\r
1062             (progn\r
1063               (setq guarded-search (org-favtable--make-guarded-search ref))\r
1064               (message (format "Scanning headlines for '%s' ..." ref))\r
1065               (let (link)\r
1066                 (if (catch 'found\r
1067                       (org-map-entries \r
1068                        (lambda () \r
1069                          (when (looking-at (concat ".*" guarded-search))\r
1070                            (setq link (org-id-get-create))\r
1071                            (throw 'found t)))   \r
1072                        nil 'agenda)\r
1073                       nil)\r
1074 \r
1075                     (progn\r
1076                       (org-favtable--get-field 'link link)\r
1077                       (setq message-text "Inserted link"))\r
1078 \r
1079                   (setq message-text (format "Did not find reference '%s'" ref)))))\r
1080           \r
1081           ;; nothing is missing\r
1082           (setq message-text "Columns 'ref' and 'link' are already filled; nothing to do")))))\r
1083      \r
1084 \r
1085    ((eq what 'sort)\r
1086 \r
1087     ;; sort lines according to contained reference\r
1088     (let (begin end where)\r
1089       (catch 'aborted\r
1090         ;; either active region or whole buffer\r
1091         (if (and transient-mark-mode\r
1092                  mark-active)\r
1093             ;; sort only region\r
1094             (progn\r
1095               (setq begin (region-beginning))\r
1096               (setq end (region-end))\r
1097               (setq where "region"))\r
1098           ;; sort whole buffer\r
1099           (setq begin (point-min))\r
1100           (setq end (point-max))\r
1101           (setq where "whole buffer")\r
1102           ;; make sure\r
1103           (unless (y-or-n-p "Sort whole buffer ")\r
1104             (setq message-text "Sort aborted")\r
1105             (throw 'aborted nil)))\r
1106           \r
1107         (save-excursion\r
1108           (save-restriction\r
1109             (goto-char (point-min))\r
1110             (narrow-to-region begin end)\r
1111             (sort-subr nil 'forward-line 'end-of-line \r
1112                        (lambda ()\r
1113                          (if (looking-at (concat ".*" \r
1114                                                  (org-favtable--make-guarded-search ref-regex 'dont-quote)))\r
1115                              (string-to-number (match-string 1))\r
1116                            0))))\r
1117           (highlight-regexp ref-regex)\r
1118           (setq message-text (format "Sorted %s from character %d to %d, %d lines" \r
1119                                      where begin end\r
1120                                      (count-lines begin end)))))))\r
1121     \r
1122 \r
1123    ((eq what 'update)\r
1124 \r
1125     ;; simply update line in reftable\r
1126     (save-excursion\r
1127       (let ((ref-or-link (if search-is-link "link" "reference")))\r
1128         (beginning-of-line)\r
1129         (if (org-favtable--update-line search)\r
1130             (setq message-text (format "Updated %s '%s'" ref-or-link search))\r
1131           (setq message-text (format "Did not find %s '%s'" ref-or-link search))))))\r
1132 \r
1133 \r
1134    ((memq what '(highlight unhighlight))\r
1135 \r
1136     (let ((where "buffer"))\r
1137       (save-excursion\r
1138         (save-restriction\r
1139           (when (and transient-mark-mode\r
1140                      mark-active)\r
1141             (narrow-to-region (region-beginning) (region-end))\r
1142             (setq where "region"))\r
1143 \r
1144           (if (eq what 'highlight)\r
1145               (progn\r
1146                 (highlight-regexp ref-regex)\r
1147                 (setq message-text (format "Highlighted references in %s" where)))\r
1148             (unhighlight-regexp ref-regex)\r
1149             (setq message-text (format "Removed highlights for references in %s" where)))))))\r
1150 \r
1151 \r
1152    ((memq what '(missing statistics))\r
1153 \r
1154     (org-favtable--goto-top)\r
1155     (let (missing \r
1156           ref-field\r
1157           ref\r
1158           min\r
1159           max \r
1160           (total 0))\r
1161 \r
1162       ;; start with list of all references\r
1163       (setq missing (mapcar (lambda (x) (format "%s%d%s" head x tail)) \r
1164                             (number-sequence 1 maxref)))\r
1165 \r
1166       ;; go through table and remove all refs, that we see\r
1167       (while (and (forward-line)\r
1168                   (org-at-table-p))\r
1169 \r
1170         ;; get ref-field and number\r
1171         (setq ref-field (org-favtable--get-field 'ref))\r
1172         (if (and ref-field \r
1173                  (string-match ref-regex ref-field))\r
1174             (setq ref (string-to-number (match-string 1 ref-field))))\r
1175 \r
1176         ;; remove existing refs from list\r
1177         (if ref-field (setq missing (delete ref-field missing)))\r
1178 \r
1179         ;; record min and max            \r
1180         (if (or (not min) (< ref min)) (setq min ref))\r
1181         (if (or (not max) (> ref max)) (setq max ref))\r
1182 \r
1183         ;; count\r
1184         (setq total (1+ total)))\r
1185 \r
1186       ;; insert them, if requested\r
1187       (forward-line -1)\r
1188       (if (eq what 'statistics)\r
1189             \r
1190           (setq message-text (format "Found %d references from %s to %s. %d references below highest do not appear in table. "\r
1191                                      total \r
1192                                      (format org-favtable--format min)   \r
1193                                      (format org-favtable--format max)\r
1194                                      (length missing)))\r
1195 \r
1196         (if (y-or-n-p (format "Found %d missing references; do you wish to append them to the table of favorites" \r
1197                               (length missing)))\r
1198             (let (type)\r
1199               (setq type (org-icompleting-read \r
1200                           "Insert new lines for reuse by command \"new\" or just as missing ? " '("reuse" "missing")))\r
1201               (mapc (lambda (x) \r
1202                       (let (org-table-may-need-update) (org-table-insert-row t))\r
1203                       (org-favtable--get-field 'ref x)\r
1204                       (org-favtable--get-field 'count (format ":%s:" type)))\r
1205                     missing)\r
1206               (org-table-align)\r
1207               (setq message-text (format "Inserted %d new lines for missing refernces" (length missing))))\r
1208           (setq message-text (format "%d missing references." (length missing)))))))\r
1209      \r
1210       \r
1211    (t (error "This is a bug: unmatched case '%s'" what)))\r
1212 \r
1213 \r
1214   ;; remember what we have done for next time\r
1215   (setq org-favtable--last-action what)\r
1216     \r
1217   ;; tell, what we have done and what can be yanked\r
1218   (if kill-new-text (setq kill-new-text \r
1219                           (substring-no-properties kill-new-text)))\r
1220   (if (string= kill-new-text "") (setq kill-new-text nil))\r
1221   (let ((m (concat \r
1222             message-text\r
1223             (if (and message-text kill-new-text) \r
1224                 " and r" \r
1225               (if kill-new-text "R" ""))\r
1226             (if kill-new-text (format "eady to yank '%s'" kill-new-text) ""))))\r
1227     (unless (string= m "") (message m)))\r
1228   (if kill-new-text (kill-new kill-new-text))))\r
1229 \r
1230 \r
1231 \r
1232 (defun org-favtable--parse-and-adjust-table ()\r
1233 \r
1234   (let ((maxref 0)\r
1235         top\r
1236         bottom\r
1237         ref-field\r
1238         link-field\r
1239         parts\r
1240         numcols\r
1241         head\r
1242         tail\r
1243         ref-regex\r
1244         has-reuse\r
1245         initial-point)\r
1246 \r
1247     (setq initial-point (point))\r
1248     (org-favtable--goto-top)\r
1249     (setq top (point))\r
1250     \r
1251     (goto-char top)\r
1252     \r
1253     ;; count columns\r
1254     (org-table-goto-column 100)\r
1255     (setq numcols (- (org-table-current-column) 1))\r
1256     \r
1257     ;; get contents of columns\r
1258     (forward-line -2)\r
1259     (unless (org-at-table-p)\r
1260       (org-favtable--report-setup-error \r
1261        "Table of favorites starts with a hline" t))\r
1262 \r
1263     ;; check for optional line consisting solely of width specifications\r
1264     (beginning-of-line)\r
1265     (if (looking-at "\\s *|\\(\\(\\s *|\\)\\|\\(\\s *<[0-9]+>\\s *|\\)\\)+\\s *$")\r
1266         (forward-line -1))\r
1267     (org-table-goto-column 1)\r
1268 \r
1269     (setq org-favtable--columns (org-favtable--parse-headings numcols))\r
1270     \r
1271     ;; Go beyond end of table\r
1272     (while (org-at-table-p) (forward-line 1))\r
1273     \r
1274     ;; Kill all empty rows at bottom\r
1275     (while (progn\r
1276              (forward-line -1)\r
1277              (org-table-goto-column 1)\r
1278              (and\r
1279               (not (org-favtable--get-field 'ref))\r
1280               (not (org-favtable--get-field 'link))))\r
1281       (org-table-kill-row))\r
1282     (forward-line)\r
1283     (setq bottom (point))\r
1284     (forward-line -1)\r
1285     \r
1286     ;; Retrieve any decorations around the number within the first nonempty ref-field\r
1287     (goto-char top)\r
1288     (while (and (org-at-table-p)\r
1289                 (not (setq ref-field (org-favtable--get-field 'ref))))\r
1290       (forward-line))\r
1291 \r
1292     ;; Some Checking\r
1293     (unless ref-field\r
1294       (org-favtable--report-setup-error \r
1295        "No line of reference column contains a number" t))\r
1296     \r
1297     (unless (string-match "^\\([^0-9]*\\)\\([0-9]+\\)\\([^0-9]*\\)$" ref-field)\r
1298       (org-favtable--report-setup-error \r
1299        (format "First reference in table table of favorites ('%s') does not contain a number" ref-field) t))\r
1300     \r
1301 \r
1302     ;; These are the decorations used within the first row of favtable\r
1303     (setq head (match-string 1 ref-field))\r
1304     (setq tail (match-string 3 ref-field))\r
1305     (setq ref-regex (concat (regexp-quote head)\r
1306                             "\\([0-9]+\\)" \r
1307                             (regexp-quote tail)))\r
1308 \r
1309     ;; Go through table to find maximum number and do some checking\r
1310     (let ((ref 0))\r
1311 \r
1312       (while (org-at-table-p) \r
1313 \r
1314         (setq ref-field (org-favtable--get-field 'ref))\r
1315         (setq link-field (org-favtable--get-field 'link))\r
1316 \r
1317         (if (and (not ref-field)\r
1318                  (not link-field))\r
1319             (throw 'content-error "Columns ref and link are both empty in this line"))\r
1320 \r
1321         (if ref-field\r
1322             (if (string-match ref-regex ref-field)\r
1323                 ;; grab number\r
1324                 (setq ref (string-to-number (match-string 1 ref-field)))\r
1325               (throw 'content-error "Column ref does not contain a number")))\r
1326 \r
1327         ;; check, if higher ref\r
1328         (if (> ref maxref) (setq maxref ref))\r
1329 \r
1330         ;; check if ref is ment for reuse\r
1331         (if (string= (org-favtable--get-field 'count) ":reuse:")\r
1332             (setq has-reuse 1))\r
1333 \r
1334         (forward-line 1)))\r
1335     \r
1336     ;; sort used to be here\r
1337     \r
1338     (setq parts (list head maxref tail numcols ref-regex has-reuse))\r
1339         \r
1340     ;; go back to top of table\r
1341     (goto-char top)\r
1342 \r
1343     parts))\r
1344 \r
1345 \r
1346 \r
1347 (defun org-favtable--sort-table (sort-column)\r
1348 \r
1349   (unless sort-column (setq sort-column (org-favtable--column-num 'sort)))\r
1350 \r
1351   (let (top \r
1352         bottom\r
1353         ref-field\r
1354         count-field\r
1355         count-special)\r
1356 \r
1357 \r
1358     ;; get boundaries of table\r
1359     (org-favtable--goto-top)\r
1360     (forward-line 0)\r
1361     (setq top (point))\r
1362     (while (org-at-table-p) (forward-line))\r
1363     (setq bottom (point))\r
1364     \r
1365     (save-restriction\r
1366       (narrow-to-region top bottom)\r
1367       (goto-char top)\r
1368       (sort-subr t\r
1369                  'forward-line \r
1370                  'end-of-line \r
1371                  (lambda ()\r
1372                    (let (ref\r
1373                          (ref-field (or (org-favtable--get-field 'ref) ""))\r
1374                          (count-field (or (org-favtable--get-field 'count) ""))\r
1375                          (count-special 0))\r
1376 \r
1377                      ;; get reference with leading zeroes, so it can be\r
1378                      ;; sorted as text\r
1379                      (string-match org-favtable--ref-regex ref-field)\r
1380                      (setq ref (format \r
1381                                 "%06d" \r
1382                                 (string-to-number \r
1383                                  (or (match-string 1 ref-field)\r
1384                                      "0"))))\r
1385 \r
1386                      ;; find out, if special token in count-column\r
1387                      (setq count-special (format "%d" \r
1388                                                  (- 2\r
1389                                                     (length (member count-field '(":missing:" ":reuse:"))))))\r
1390                    \r
1391                      ;; Construct different sort-keys according to\r
1392                      ;; requested sort column; prepend count-special to\r
1393                      ;; sort special entries at bottom of table, append ref\r
1394                      ;; as a secondary sort key\r
1395                      (cond \r
1396 \r
1397                       ((eq sort-column 'count)\r
1398                        (concat count-special\r
1399                                (format \r
1400                                 "%08d" \r
1401                                 (string-to-number (or (org-favtable--get-field 'count)\r
1402                                                       ""))) \r
1403                                ref))\r
1404                     \r
1405                       ((eq sort-column 'last-accessed)\r
1406                        (concat count-special\r
1407                                (org-favtable--get-field 'last-accessed) \r
1408                                " " \r
1409                                ref))\r
1410                     \r
1411                       ((eq sort-column 'ref)\r
1412                        (concat count-special\r
1413                                ref))\r
1414                     \r
1415                       (t (error "This is a bug: unmatched case '%s'" sort-column)))))\r
1416                \r
1417                  nil 'string<)))\r
1418     \r
1419   ;; align table\r
1420   (org-table-align)) \r
1421 \r
1422 \r
1423 (defun org-favtable--goto-top ()\r
1424 \r
1425   ;; go to heading of node\r
1426   (while (not (org-at-heading-p)) (forward-line -1))\r
1427   (forward-line 1)\r
1428   ;; go to table within node, but make sure we do not get into another node\r
1429   (while (and (not (org-at-heading-p))\r
1430               (not (org-at-table-p))\r
1431               (not (eq (point) (point-max)))) \r
1432     (forward-line 1))\r
1433      \r
1434   ;; check, if there really is a table\r
1435   (unless (org-at-table-p)\r
1436     (org-favtable--report-setup-error \r
1437      (format "Cannot find favtable within node %s" org-favtable-id) t))\r
1438 \r
1439   ;; go to first hline\r
1440   (while (and (not (org-at-table-hline-p))\r
1441               (org-at-table-p))\r
1442     (forward-line 1))\r
1443      \r
1444   ;; and check\r
1445   (unless (org-at-table-hline-p)\r
1446     (org-favtable--report-setup-error \r
1447      "Cannot find hline within table of favorites" t))      \r
1448 \r
1449   (forward-line 1)\r
1450   (org-table-goto-column 1))\r
1451 \r
1452 \r
1453 \r
1454 (defun org-favtable--id-find ()\r
1455   "Find org-favtable-id"\r
1456   (let ((marker (org-id-find org-favtable-id 'marker))\r
1457         marker-and-buffer)\r
1458 \r
1459     (if marker \r
1460         (progn \r
1461           (setq marker-and-buffer (cons (marker-buffer marker) (marker-position marker)))\r
1462           (move-marker marker nil)\r
1463           marker-and-buffer)\r
1464       nil)))\r
1465 \r
1466 \r
1467 \r
1468 (defun org-favtable--parse-headings (numcols)\r
1469 \r
1470   (let (columns)\r
1471 \r
1472     ;; Associate names of special columns with column-numbers\r
1473     (setq columns (copy-tree '((ref . 0) (link . 0) (created . 0) (last-accessed . 0) \r
1474                                (count . 0) (sort . nil) (copy . nil))))\r
1475 \r
1476     ;; For each column\r
1477     (dotimes (col numcols)\r
1478       (let* (field-flags ;; raw heading, consisting of file name and maybe\r
1479                          ;; flags (seperated by ";")\r
1480              field       ;; field name only\r
1481              field-symbol ;; and as a symbol\r
1482              flags       ;; flags from field-flags\r
1483              found)\r
1484 \r
1485         ;; parse field-flags into field and flags\r
1486         (setq field-flags (org-trim (org-table-get-field (+ col 1))))\r
1487         (if (string-match "^\\([^;]*\\);\\([a-z]+\\)$" field-flags)\r
1488             (progn \r
1489               (setq field (downcase (or (match-string 1 field-flags) "")))\r
1490               ;; get flags as list of characters\r
1491               (setq flags (mapcar 'string-to-char \r
1492                                   (split-string \r
1493                                    (downcase (match-string 2 field-flags)) \r
1494                                    "" t))))\r
1495           ;; no flags\r
1496           (setq field field-flags))\r
1497 \r
1498         (unless (string= field "") (setq field-symbol (intern (downcase field))))\r
1499 \r
1500         ;; Check, that no flags appear twice\r
1501         (mapc (lambda (x)\r
1502                 (when (memq (car x) flags)\r
1503                   (if (cdr (assoc (cdr x) columns))\r
1504                       (org-favtable--report-setup-error \r
1505                        (format "More than one heading is marked with flag '%c'" (car x)) t))))\r
1506               '((?s . sort)\r
1507                 (?c . copy)))\r
1508         \r
1509         ;; Process flags\r
1510         (if (memq ?s flags)\r
1511             (setcdr (assoc 'sort columns) field-symbol))\r
1512         (if (memq ?c flags)\r
1513             (setcdr (assoc 'copy columns) (+ col 1)))\r
1514         \r
1515         ;; Store columns in alist\r
1516         (setq found (assoc field-symbol columns))\r
1517         (when found\r
1518           (if (> (cdr found) 0) \r
1519               (org-favtable--report-setup-error \r
1520                (format "'%s' appears two times as column heading" (downcase field)) t))\r
1521           (setcdr found (+ col 1)))))\r
1522 \r
1523     ;; check if all necessary informations have been specified\r
1524     (mapc (lambda (col) \r
1525             (unless (> (cdr (assoc col columns)) 0)\r
1526               (org-favtable--report-setup-error \r
1527                (format "column '%s' has not been set" col) t)))\r
1528           '(ref link count created last-accessed))\r
1529 \r
1530     ;; use ref as a default sort-column\r
1531     (unless (cdr (assoc 'sort columns))\r
1532       (setcdr (assoc 'sort columns) 'ref))\r
1533     columns))\r
1534 \r
1535 \r
1536 \r
1537 (defun org-favtable--report-setup-error (text &optional switch-to-node)\r
1538 \r
1539   (when switch-to-node \r
1540     (org-id-goto org-favtable-id)\r
1541     (delete-other-windows))\r
1542   \r
1543   (when (y-or-n-p (concat\r
1544                    text \r
1545                    ";\n"\r
1546                    "the correct setup is explained in the documentation of 'org-favtable-id'.\n" \r
1547                    "Do you want to read it ? "))\r
1548     (org-favtable--show-help 'org-favtable-id))\r
1549 \r
1550   (error "")\r
1551   (setq org-favtable--windowconfig-before nil)\r
1552   (move-marker org-favtable--marker-outside-before nil)\r
1553   (setq org-favtable--last-action 'leave))\r
1554 \r
1555 \r
1556 \r
1557 (defun org-favtable--show-help (function-or-variable)\r
1558 \r
1559   (let ((isfun (functionp function-or-variable)))\r
1560     ;; bring up help-buffer for function or variable\r
1561     (if isfun\r
1562         (describe-function function-or-variable)\r
1563       (describe-variable function-or-variable))\r
1564 \r
1565     \r
1566     ;; clean up help-buffer\r
1567     (pop-to-buffer "*Help*")\r
1568     (let ((inhibit-read-only t)) \r
1569       (goto-char (point-min))\r
1570       (while (progn\r
1571                (kill-line 1)\r
1572                (not (looking-at \r
1573                      (if isfun\r
1574                          "(" \r
1575                        "Documentation:")))))\r
1576       (kill-line (if isfun 2 3))\r
1577       (goto-char (point-max))\r
1578       (kill-line -2)\r
1579       (goto-char (point-min)))))\r
1580                  \r
1581 \r
1582 \r
1583 (defun org-favtable--update-line (ref-or-link)\r
1584 \r
1585   (let (initial\r
1586         found\r
1587         count-field\r
1588         (ref-node-buffer-and-point (org-favtable--id-find)))\r
1589 \r
1590     (with-current-buffer (car ref-node-buffer-and-point)\r
1591       \r
1592       ;; search reference or link, if given (or assume, that we are already positioned right)\r
1593       (when ref-or-link\r
1594         (setq initial (point))\r
1595         (goto-char (cdr ref-node-buffer-and-point))\r
1596         (org-favtable--goto-top)\r
1597         (while (and (org-at-table-p)\r
1598                     (not (or (string= ref-or-link (org-favtable--get-field 'ref))\r
1599                              (string= ref-or-link (org-favtable--get-field 'link)))))\r
1600           (forward-line)))\r
1601       \r
1602       (if (not (org-at-table-p))\r
1603           (error "Did not find reference or link '%s'" ref-or-link)\r
1604         (setq count-field (org-favtable--get-field 'count))\r
1605 \r
1606         ;; update count field only if number or empty; leave :missing: and :reuse: as is\r
1607         (if (or (not count-field)\r
1608                 (string-match "^[0-9]+$" count-field))\r
1609             (org-favtable--get-field 'count\r
1610                                     (number-to-string \r
1611                                      (+ 1 (string-to-number (or count-field "0"))))))\r
1612 \r
1613         ;; update timestamp\r
1614         (org-table-goto-column (org-favtable--column-num 'last-accessed))\r
1615         (org-table-blank-field)\r
1616         (org-insert-time-stamp nil t t)\r
1617 \r
1618         (setq found t))\r
1619       \r
1620       (if initial (goto-char initial))\r
1621       \r
1622       found)))\r
1623 \r
1624 \r
1625 \r
1626 (defun org-favtable--occur-helper (action)\r
1627   (let ((line-beg (line-beginning-position))\r
1628         key search link ref)\r
1629 \r
1630     ;; extract reference or link from text property (as put there before)\r
1631     (setq ref (get-text-property line-beg 'org-favtable--ref))\r
1632     (if (string= ref "") (setq ref nil))\r
1633     (setq link (get-text-property line-beg 'org-favtable--link))\r
1634     (if (string= link "") (setq link nil))\r
1635       \r
1636     (org-favtable action \r
1637                   (or link ref) ;; prefer link\r
1638                   (if link t nil))))\r
1639 \r
1640 \r
1641 (defun org-favtable--get-field (key &optional value)\r
1642   (let (field)\r
1643     (setq field (org-trim (org-table-get-field (cdr (assoc key org-favtable--columns)) value)))\r
1644     (if (string= field "") (setq field nil))\r
1645     \r
1646     field))\r
1647 \r
1648 \r
1649 (defun org-favtable--column-num (key)\r
1650   (cdr (assoc key org-favtable--columns)))\r
1651 \r
1652 \r
1653 (defun org-favtable-version ()\r
1654   "Show version of org-favtable"\r
1655   (message "org-favtable %s" org-favtable--version))\r
1656 \r
1657 \r
1658 (defun org-favtable--make-guarded-search (ref &optional dont-quote)\r
1659   (concat "\\b" (if dont-quote ref (regexp-quote ref)) "\\b"))\r
1660 \r
1661 \r
1662 (provide 'org-favtable)\r
1663 \r
1664 ;; Local Variables:\r
1665 ;; fill-column: 75\r
1666 ;; comment-column: 50\r
1667 ;; End:\r
1668 \r
1669 ;;; org-favtable.el ends here\r