Update CL port manual

And split-string with uiop:split-string

.dir-locals.el

@@ -4,7 +4,7 @@
 ;; for some reason, setting `nameless-current-name' to "chronometrist"
 ;; makes all aliases not take effect - probably specific to Org
 ;; literate programs
-((nil . ((nameless-aliases . (("c" . "chronometrist")
+((nil . ((nameless-aliases . (("cb" . "chronometrist-backend")
                               ("cc" . "chronometrist-common")
                               ("cd" . "chronometrist-details")
                               ("ce" . "chronometrist-events")
@@ -13,7 +13,9 @@
                               ("cp" . "chronometrist-plist-pp")
                               ("cr" . "chronometrist-report")
                               ("cs" . "chronometrist-statistics")
-                              ("cx" . "chronometrist-sexp")))))
+                              ("cx" . "chronometrist-sexp")
+                              ("c" . "chronometrist")))
+         (sentence-end-double-space . t)))
  (org-mode
   . ((org-html-self-link-headlines . t)
      (eval . (org-indent-mode))
@@ -21,16 +23,4 @@
       . (concat "<link rel=\"stylesheet\" "
                 "type=\"text/css\" "
                 "href=\"../org-doom-molokai.css\" />"))
-     (eval
-      . (add-hook
-         'after-save-hook
-         (lambda ()
-           (let ((fn (buffer-file-name)))
-             (when (y-or-n-p (format "Tangle file %s?" fn))
-               (compile
-                (mapconcat #'shell-quote-argument
-                           `("emacs" "-q" "-Q" "--batch" "--eval=(require 'ob-tangle)"
-                             ,(format "--eval=(org-babel-tangle-file \"%s\")" fn))
-                           " ")))))
-         nil t))
-     (eval . (add-hook 'before-save-hook (lambda nil (org-align-all-tags)) nil t)))))
+     (org-babel-tangle-use-relative-file-links . t))))

CHANGELOG.md

@@ -4,13 +4,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [unreleased]
+## unreleased
+### Added
+1. `chronometrist-third`, an extension to add support for the [Third Time](https://www.lesswrong.com/posts/RWu8eZqbwgB9zaerh/third-time-a-better-way-to-work) system.
+2. New custom variable `chronometrist-key-value-preset-alist`, to define completion suggestions in advance.
+3. New custom variable `chronometrist-key-value-use-database-history`, to control whether database history is used for key-value suggestions.
+
+## [0.10.0] - 2022-02-15
+### Changed
+1. The value of `chronometrist-file` must now be a file path _without extension._ Please update your configurations.
+2. The existing file format used by Chronometrist is now called the `plist` format.
+3. The extension for files in the `plist` format is now `.plist`. Update the extension of your file to use it with the `plist` backend.
+
+### Added
+1. Multiple backend support - new custom variable `chronometrist-active-backend` to determine active backend, new command `chronometrist-switch-backend` to temporarily select a backend (with completion).
+2. New `plist-group` backend, reducing time taken in startup and after changes to the file.
+3. Unified migration interface with command `chronometrist-migrate`.
+4. New custom variable `chronometrist-task-list`, to add/hide tasks without modifying the database. Setting it also disables generation of the task list from the database, speeding up many operations.
+5. New command `chronometrist-discard-active`, to discard the active interval.
+6. Debug logging messages - to view them, set `chronometrist-debug-enable`.
+
+### Fixed
+1. Code to detect the type of change made to the file has been rewritten, hopefully fixing some uncommon `read` errors and `args out of range` errors.
+
+### Deprecated
+1. The plist backend is deprecated and may be removed in a future release. The `plist-group` backend is more performant and extensible - please use `chronometrist-migrate` to convert your data to the `plist-group` backend.
+
+## [0.9.0] - 2021-07-08
 ### Added
 1. New commands `chronometrist-restart-task`, `chronometrist-extend-task`
-2. Menus for `chronometrist` and `chronometrist-key-values`
+2. Menus for `chronometrist`, `chronometrist-key-values`, and `chronometrist-details`
+3. Custom ranges and filters for `chronometrist-details`. See command `chronometrist-details-set-range` and `chronometrist-details-set-filter`.
 ### Changed
-3. Display graph ranges in `chronometrist-spark` column
-4. `chronometrist-tags-add` and `chronometrist-key-values-unified-prompt` now also work interactively.
+4. Display graph ranges in `chronometrist-spark` column
+5. `chronometrist-tags-add` and `chronometrist-key-values-unified-prompt` now also work interactively.
 
 ## [0.8.1] - 2021-06-01
 ### Changed

Cask

@@ -1,23 +0,0 @@
-(source gnu)
-(source melpa)
-
-(package
- "Chronometrist"
- "0.7.2"
- "A time tracker for Emacs with a nice interface")
-
-(depends-on "cl-lib")
-(depends-on "literate-elisp" "0.1")
-(depends-on "dash" "2.16.0")
-(depends-on "seq" "2.20")
-(depends-on "ts" "0.2")
-
-(files "elisp/*.el")
-
-(development
- (depends-on "f")
- (depends-on "ecukes")
- (depends-on "ert-runner")
- (depends-on "el-mock")
- (depends-on "elsa")
- (depends-on "buttercup"))

Makefile

@@ -0,0 +1,82 @@
+.phony: all setup tangle compile lint
+
+all: clean-elc manual.md setup tangle compile lint
+
+setup:
+	emacs --batch --eval="(package-initialize)" \
+	--eval="(mapcar #'package-install '(indent-lint package-lint relint))"
+
+manual.md:
+	emacs -q -Q --batch --eval="(require 'ox-md)" \
+	"manual.org" -f 'org-md-export-to-markdown'
+
+# No -q or -Q without ORG_PATH - if the user has a newer version of
+# Org, we want to use it.
+tangle:
+	cd elisp/ && \
+	emacs --batch \
+	--eval="(progn (package-initialize) (require 'ob-tangle))" \
+	--eval='(org-babel-tangle-file "chronometrist.org")' \
+	--eval='(org-babel-tangle-file "chronometrist-key-values.org")' \
+	--eval='(org-babel-tangle-file "chronometrist-spark.org")' \
+	--eval='(org-babel-tangle-file "chronometrist-third.org")' \
+        --eval='(org-babel-tangle-file "chronometrist-sqlite.org")' ; \
+	cd ..
+
+compile: tangle
+	cd elisp/ && \
+	emacs --batch \
+	--eval="(progn (package-initialize) (require 'dash) (require 'ts))" \
+	--eval='(byte-compile-file "chronometrist.el")' \
+	--eval='(byte-compile-file "chronometrist-key-values.el")' \
+	--eval='(byte-compile-file "chronometrist-spark.el")' \
+	--eval='(byte-compile-file "chronometrist-third.el")' \
+        --eval='(byte-compile-file "chronometrist-sqlite.el")' ; \
+	cd ..
+
+lint-check-declare: tangle
+	cd elisp/ && \
+	emacs -q --batch \
+	--eval='(check-declare-file "chronometrist.el")' \
+	--eval='(check-declare-file "chronometrist-key-values.el")' \
+	--eval='(check-declare-file "chronometrist-spark.el")' \
+	--eval='(check-declare-file "chronometrist-third.el")' \
+        --eval='(check-declare-file "chronometrist-sqlite.el")' ; \
+	cd ..
+
+lint-checkdoc: tangle
+	cd elisp/ && \
+	emacs -q -Q --batch \
+	--eval='(checkdoc-file "chronometrist.el")' \
+	--eval='(checkdoc-file "chronometrist-key-values.el")' \
+	--eval='(checkdoc-file "chronometrist-spark.el")' \
+	--eval='(checkdoc-file "chronometrist-third.el")' \
+        --eval='(checkdoc-file "chronometrist-sqlite.el")' ; \
+	cd ..
+
+lint-package-lint: setup tangle
+	cd elisp/ && \
+	emacs --batch \
+	--eval="(progn (package-initialize) (require 'dash) (require 'ts) (require 'package-lint))" \
+	-f 'package-lint-batch-and-exit' chronometrist.el \
+	-f 'package-lint-batch-and-exit' chronometrist-key-values.el \
+	-f 'package-lint-batch-and-exit' chronometrist-spark.el \
+	-f 'package-lint-batch-and-exit' chronometrist-third.el \
+        -f 'package-lint-batch-and-exit' chronometrist-sqlite.el ; \
+	cd ..
+
+lint-relint: setup tangle
+	cd elisp/ && \
+	emacs --batch \
+	--eval="(progn (package-initialize) (require 'relint))" \
+	--eval='(relint-file "chronometrist.el")' \
+	--eval='(relint-file "chronometrist-key-values.el")' \
+	--eval='(relint-file "chronometrist-spark.el")' \
+	--eval='(relint-file "chronometrist-third.el")' \
+        --eval='(relint-file "chronometrist-sqlite.el")' ; \
+	cd ..
+
+lint: lint-check-declare lint-checkdoc lint-package-lint lint-relint
+
+clean-elc:
+	rm elisp/*.elc

TODO.org

@@ -1,3 +1,4 @@
+# -*- eval: (add-hook 'org-insert-heading-hook #'(lambda nil (save-excursion (org-set-property "CREATED" (format-time-string "%FT%T%z")))) nil t); -*-
 #+TITLE: The Chronometrist TODO List
 #+AUTHOR: contrapunctus
 
@@ -7,10 +8,12 @@
 * v0.3.0 [100%]
   1. [X] +Release or+ bundle plist-pp.el
   2. [X] -report - error opening when clocked in
+
 * MELPA, hosting [0%]
 1. [ ] merge =chronometrist-goal= into this repository
 2. [X] move project to codeberg.org or tildegit.org
 3. [X] ...and then, update the MELPA recipes.
+
 * Chronometrist
 1. implement point restore for =chronometrist=/=chronometrist-report=/=chronometrist-statistics= in a kill-buffer-hook, so it works whenever the buffer is killed, not just when we call the command.
 
@@ -33,18 +36,13 @@
         5. Delete =:stop= time and save
         6. Clock out again
         7. Accept the already-inserted key-value. Duplicate!
-** Features [33%]
-   1. [ ] New commands
-      1. [ ] *Kill/discard* (bind to 'k') - which will delete the interval currently being recorded.
-         - Most conservative option - it will only operate on the project at point, and will only kill for a clocked-in project.
-         - Somewhat less conservative option - it will operate on the currently clocked-in project, no matter where point is.
-         - It _should_ ask for confirmation.
-         - Alternatively, or as a complement - an *undo command*, which will undo your last action (clock in or clock out).
-           - Undo and redo seem like the best bets.
-   2. [ ] Hook enhancement - can we supply the whole plist (including tags and key-values) to the task-start hooks, so users can have even smarter hook functions?
+
+** Features [50%]
+   1. [ ] Hook enhancement - can we supply the whole plist (including tags and key-values) to the task-start hooks, so users can have even smarter hook functions?
       * That would mean ensuring that -kv-read runs before other hooks.
       * Actually, it should be trivial to access the last expression in the file, so maybe this is unnecessary.
-   3. [X] Revisit 'no reason' commands - maybe we should ask for tags and key-values with the regular commands, and skip them with the 'no reason' variants?
+   2. [X] Revisit 'no reason' commands - maybe we should ask for tags and key-values with the regular commands, and skip them with the 'no reason' variants?
+
 *** Key-values [66%]
     1. [X] bug - value-history appears in chronological rather than reverse chronological order
     2. [X] generate history hash table from chronometrist-file.
@@ -76,6 +74,7 @@
     15. [X] bug - tag history starts at the beginning (wtf?), value history is empty (wtf?)
         * Does not occur on master, only on dev
         * Does not occur if you disable lexical binding (introduced in 4e89836)
+
 **** Values
      What forms can they take?
      1. Integers, floating point numbers - easy to identify via regexp
@@ -115,31 +114,62 @@
 ** Maybe
 1. Add a new kind of plist - =(:name "NAME" :time "TIME" ...)=
    To record events for which the time interval is not relevant. These won't be shown in =chronometrist= - perhaps in a different buffer.
-* Optimization [33%]
-Some options and ideas -
-1. [X] Defer (tag/key/value) history generation from file-change-time to prompt-time, and make it per-task instead of all tasks at once
-   * The biggest resource hog is splitting of midnight-spanning intervals, however.
-   * Reduce memory use by allowing user to restrict number of s-expressions read.
-   * Per-task history generation will create problems - e.g. values for a given key for one task won't be suggested for values for the same key in another 🤦
-     + Tags and keys are already task-sensitive; just don't make values task-sensitive.
-2. [X] Compare partial hashes of file to know what has changed - only update memory when necessary.
-3. [ ] In-memory cache - don't store entire file into memory; instead, split midnight-spanning intervals just for the requested data.
-   * Will increase load time for each forward/backward command in =chronometrist-report= and =chronometrist-statistics=
-   * Will reduce memory used by =chronometrist-events=.
-     + Further reductions can take place, if we automatically discard cache entries past a certain limit. (perhaps excluding data for the current day, week, or month)
-4. [ ] Mix of 2 and 3 - in-memory cache with partial updates
-5. [ ] Split and save midnight-spanning intervals to disk - remove the need for an in-memory version of data with split midnight-spanning intervals.
-   * Least memory use?
-   * Might make the file harder for a user to edit.
-6. [ ] Save timestamps as UNIX epoch time.
-   * Will (probably) greatly speed up time parsing and interval splitting.
-   * Will greatly impede human editing of the file, too. 🤔
-     + An editing UI could help - pretty sure every timestamp edit I've ever made has been for the last interval, or at most an interval in today's data.
-7. [ ] Use an SQL database instead of a text file. Assuming SQL can
-   1. find the difference between ISO-8601 timestamps
-   2. compare ISO-8601 timestamps, and
-   3. do 1 and 2 faster than Elisp.
-8. [ ] Change data structure - instead of storing each plist as-is, split each into two, one with the =:start= and one with the =:end=. Now we have the elegance of the one-plist-is-a-complete-interval schema in the file, and the ease and speed of detection of midnight spanning intervals in memory.
+
+* Optimization
+** DONE Don't update task list from data when user has set their own
+:PROPERTIES:
+:CREATED:  2022-01-06T22:53:20+0530
+:END:
+
+** When clocking in/out, do not save file until hooks are run
+:PROPERTIES:
+:CREATED:  2022-01-03T16:09:36+0530
+:END:
+Currently, the file is probably being saved twice - once when we insert/update the record, and once again when a hook function modifies and saves the file. If this is the case, the file-notify callback is probably called twice.
+
+See branch =reduce-saves=
+
+** Don't save file until exit and/or Emacs idle
+:PROPERTIES:
+:CREATED:  2022-01-03T16:09:04+0530
+:END:
+A risky strategy - if there is unsaved data during an unclean exit, it will be lost.
+
+** DONE Deferred (tag/key/value) history generation
+Defer (tag/key/value) history generation from file-change-time to prompt-time, and make it per-task instead of all tasks at once
++ The biggest resource hog is splitting of midnight-spanning intervals, however.
++ Reduce memory use by allowing user to restrict number of s-expressions read.
++ Per-task history generation will create problems - e.g. values for a given key for one task won't be suggested for values for the same key in another 🤦
+  * Tags and keys are already task-sensitive; just don't make values task-sensitive.
+
+** DONE Hash file contents to optimize for common changes
+Compare partial hashes of file to know what has changed - only update memory when necessary.
+
+** In-memory cache
+Don't store entire file into memory; instead, split midnight-spanning intervals just for the requested data.
++ Will increase load time for each forward/backward command in =chronometrist-report= and =chronometrist-statistics=
++ Will reduce memory used by =chronometrist-events=.
+  * Further reductions can take place, if we automatically discard cache entries past a certain limit. (perhaps excluding data for the current day, week, or month)
+
+** Split and save midnight-spanning intervals to disk
+It will remove the need for an in-memory version of data with split midnight-spanning intervals.
++ Least memory use?
++ Might make the file harder for a user to edit.
+
+** Save timestamps as UNIX epoch time
++ Will (probably) greatly speed up time parsing and interval splitting.
++ Will greatly impede human editing of the file, too. 🤔
+  * An editing UI could help - pretty sure every timestamp edit I've ever made has been for the last interval, or at most an interval in today's data.
+    - The editing UI could have commands for next/previous interval; one could also have a command which, in the file, opens the plist at point for editing.
+
+** Use an SQL database instead of a text file
+That is, assuming SQL can
+1. find the difference between ISO-8601 timestamps
+2. compare ISO-8601 timestamps, and
+3. do 1 and 2 faster than Elisp.
+
+** Change data structure
+Instead of storing each plist as-is, split each into two, one with the =:start= and one with the =:end=. Now we have the elegance of the one-plist-is-a-complete-interval schema in the file, and the ease and speed of detection of midnight spanning intervals in memory.
 
    So this
    : (:name "Task" ... :start "<timestamp>" :stop "<timestamp>")
@@ -149,17 +179,57 @@ Some options and ideas -
     (:stop "<timestamp>")
     ...)
    #+END_SRC
-9. [ ] Change file timestamp format to =("<iso-date>" "<iso-time>")=
-10. [ ] Change file schema to be date-aware -
-    #+BEGIN_SRC emacs-lisp
+
+** Change file timestamp format to =("<iso-date>" "<iso-time>")=
+** Change file schema
+Pros
+1. Easy to read data for a single date - Chronometrist's most common operation.
+2. No more expensive operations on each startup (date checking, splitting of midnight spanning intervals).
+3. May be easier to check for midnight-spanning intervals - plists are already grouped by date, just check the first and the last plist per date. Which means, if a user neglects to split a midnight-spanning interval, we can do it for them.
+   * Make this checking - and also checking for ordering of keys and plists - a command which the user can run at will, rather than something being run automatically.
+4. May reduce memory and disk space used - hash table keys are already dates, so =:start= and =:stop= can just be ISO times rather than date-times.
+
+Cons
+1. Opting to remove dates from intervals might make it difficult for users to recover from erroneous edits.
+
+*** Store plists grouped by date
+#+BEGIN_SRC emacs-lisp
 (:date "YYYY-MM-DD"
        (:name "task 1"
               ...
               :start "HH:MM:SSZ"
               :stop "HH:MM:SSZ")
        ...)
-    #+END_SRC
-    1. Users will have to be disciplined while editing, and ensure that events are split on day boundaries. If not, we will have to check each time the file changes, defeating the entire optimization.
+;; or
+("YYYY-MM-DD"
+ (:name "task 1"
+        ...
+        :start "HH:MM:SSZ"
+        :stop "HH:MM:SSZ")
+ ...)
+#+END_SRC
+
+Cons
+1. Users will have to be disciplined while editing, and ensure that events are split on day boundaries. If not, we will have to check each time the file changes, defeating the entire optimization.
+   * Not quite - it's less work to test that, when the intervals are grouped by date.
+
+*** Persist hash table to file
+Instead of storing plists in the file, persist the hash table itself.
+
+Pros
++ When editing manually, the whole file can be reindented with a single =sp-indent-defun=.
++ Stored data can be modified by any Emacs Lisp functions rather than functions specific to our file format.
+  - This may also be possible with [[*Store plists grouped by date][plists grouped by date]], if we serialize the hash table as plists rather than - as we do now - directly adding individual plists to the file.
+
+Cons
+1. Read syntax not portable to other dialects or languages, e.g. if one wants to make an Android frontend in LambdaNative (Gambit Scheme)
+   * A language with reader macros, such as Common Lisp, might work.
+   * Or, use [[*Store plists grouped by date][plists grouped by date]].
+2. Slightly noisier syntax than plain plists.
+3. Users cannot create comments within the hash table expression.
+   * Couldn't they use plist keys for comments instead? 🤔
+4. May increase memory consumption - the entire hash table will be loaded into memory.
+
 ** Cache
    + Lessons from the parsimonious-reading branch - iterating =read= over the whole file is fast; splitting the intervals is not.
    + Things we need to read the whole file for - task list, tag/key/value history.
@@ -167,7 +237,8 @@ Some options and ideas -
    + Anything requiring split intervals will first look in =chronometrist-events=, and if not found, will read from the file and update =chronometrist-events=.
    + When the file changes, use the file byte length and hash strategy described below to know whether to keep the cache.
    + Save cache to a file, so that event splitting is avoided by reading from that.
-** Ideas to make -refresh-file faster
+
+** (old) ideas to make -refresh-file faster
    1. Support multiple files, so we read and process lesser data when one of them changes.
    2. Make file writing async
    3. Don't refresh from file when clocking in.
@@ -178,7 +249,6 @@ Some options and ideas -
           * Or even the first expression of the current date. That way, we just re-read the intervals for today. Because chronometrist-events uses dates as keys, it's easy to work on the basis of dates.
    6. [ ] Don't generate tag/keyword/value history from the entire log, just from the last N days (where N is user-customizable).
    7. [ ] Just why are we reading the whole file? ~chronometrist~ should not read more than a day; ~chronometrist-report~ should not read more than a week at a time, and so on. Make a branch which works on this logic, see if it is faster.
-** Clocking in/out might be too slow for my liking
 
 * Certain
 1. [ ] statistics UI for arbitrary queries
@@ -186,6 +256,7 @@ Some options and ideas -
    * we show buffer with
      + matched unique tag groups, and sparklines for time spent on each
      + matched key-values, and sparklines for time spent on each
+
 ** plist-pp [66%]
 1. [X] plist-pp - work recursively for plist/alist values
 2. [ ] Fix alignment of alist dots
@@ -317,7 +388,7 @@ Some options and ideas -
 4. [ ] Fix heading link to "midnight-spanning intervals" - jumps to the correct heading in HTML export, but jumps to its own self in Org mode.
 5. [ ] Figure out some way to hide package prefixes in identifiers in Org mode (without actually affecting the contents, a la nameless-mode)
 
-** UX [30%]
+** UX [33%]
    1. [X] Optimization - (jonasw) store length and hash of previous file, see if the new file has the same hash until old-length bytes.
       * [X] Check for type of change to file
         + [X] Handle last expression being removed
@@ -325,30 +396,18 @@ Some options and ideas -
       * [X] BUG - if something was removed from the last expression (thereby decreasing the length of the file), =chronometrist-file-change-type= returns =t= instead of =:last=
       * [X] BUG - args out of range error when last plist is removed
    2. [X] Optimization - generate history before querying, not when the file changes.
-   3. [ ] Don't suggest nil when asking for first project on first run
-   4. [ ] When starting a project with time of "-" (i.e. not worked on today until now), immediately set time to 0 instead of waiting for the first timer refresh
-   5. [ ] Mouse commands should work only on buttons.
-   6. [X] Button actions should accept prefix arguments and behave exactly like their keyboard counterparts.
-   7. [ ] mouse-3 should clock-out without asking for reason.
-   8. [ ] Some way to ask for the reason just before starting a project. Even when clocking out, the reason is asked /before/ clocking out, which adds time to the project.
-   9. [ ] Allow calling chronometrist-in/out from anywhere-within-Emacs (a la timeclock) as well as from the chronometrist buffer.
-   10. [ ] =chronometrist-timer= - if =chronometrist-file= is being edited (buffer exists and modified), don't refresh - this will (hopefully) prevent Emacs from going crazy with errors in trying to parse malformed data.
+   3. [ ] When starting a project with time of "-" (i.e. not worked on today until now), immediately set time to 0 instead of waiting for the first timer refresh
+   4. [ ] Mouse commands should work only on buttons.
+   5. [X] Button actions should accept prefix arguments and behave exactly like their keyboard counterparts.
+   6. [ ] mouse-3 should clock-out without asking for reason.
+   7. [ ] Some way to ask for the reason just before starting a project. Even when clocking out, the reason is asked /before/ clocking out, which adds time to the project.
+   8. [ ] Allow calling chronometrist-in/out from anywhere-within-Emacs (a la timeclock) as well as from the chronometrist buffer.
+   9. [ ] =chronometrist-timer= - if =chronometrist-file= is being edited (buffer exists and modified), don't refresh - this will (hopefully) prevent Emacs from going crazy with errors in trying to parse malformed data.
 
 * Maybe
-** New features [14%]
+** New features
 1. [ ] Interact with Chronometrist from phone, tablet, or smart watches. (Help needed, I'm a total strange to mobile development and don't own any wearables.)
-2. [ ] Some way to use markup (Markdown, Org, etc) for certain plist values.
-
-   Implementation ideas -
-   * A list of keys whose values are to be edited in a user-specified major mode.
-     + Multiple windows - instead of a single key-value buffer, we'll have multiple buffers in multiple visible windows, somewhat like =ediff=. The =accept= command will use the data from all involved buffers.
-       - The buffer and window will be created when a keyword associated with that mode is selected at the prompt.
-     + Alternatively, the whole plist goes into a single buffer of the markup's major mode - the markup bits as markup, the rest of the plist in a code block 🤷‍
-     + poly-mode to mix different modes
-     + see [[info:elisp#Swapping Text][swapping text]]
-   * "Input frontends" - a way to represent s-expressions as Markdown, Org, etc, so the entire plist can be edited in that mode. As a side-effect, this will permit use of Markdown, Org, etc in keyword-values - e.g. to use markup in comments or notes.
-   * A binding in the key-value buffer, which will insert the string at point in a buffer of a certain mode.
-3. [ ] /Task List/ - a custom variable containing a list of tasks
+2. [ ] /Task List/ - a custom variable containing a list of tasks
    #+BEGIN_SRC emacs-lisp
    ("A Task Name"
     ("Another Task Name" :key-prompt nil)
@@ -373,11 +432,11 @@ Some options and ideas -
    1. Adding tasks without clocking into them (the list is stored in a separate file)
    2. Not asking for tags and/or key-values for a particular task, or having a special behaviour for a task. (e.g. some tasks I use follow certain patterns, which I'd like to automate away)
    3. defining goals (subsume =chronometrist-goal-list=), priorities, etc
-4. [ ] Completion for sub-plists - if the value of a user keyword-value pair is itself a plist, can we reuse the keyword-value prompt for it? 🤔
+3. [ ] Completion for sub-plists - if the value of a user keyword-value pair is itself a plist, can we reuse the keyword-value prompt for it? 🤔
    * Maybe generate the completion hash table when the plist is created, since this is likely to be less-used.
-5. [ ] Create a debug mode
-6. [ ] Create a verification command to test =chronometrist-file= for errors.
-7. [X] Display task's weekly progress using ASCII/sparklines
+4. [ ] Create a debug mode
+5. [ ] Create a verification command to test =chronometrist-file= for errors.
+6. [X] Display task's weekly progress using ASCII/sparklines
    * Extension to add new column in =chronometrist= buffer
    * without goals - show dashes for days on which task was not touched, x for days on which it was done. e.g.
      + =- x x x - - *= means today is a Saturday, that I did the task on three days (Mo, Tu, We), and that I'm doing it right now.
@@ -413,7 +472,27 @@ Some options and ideas -
    - untouched project with target defined - red
    - target ±5 minutes - green
    - target*2 and above - red
-* documentation discoverability                                    :doc:
+
+* viewing/editing frontends
+:PROPERTIES:
+:CUSTOM_ID: viewing-editing-frontends
+:END:
+1. Some way to use markup (Markdown, Org, etc) for certain plist values
+2. Some way to enter/edit key-values and other data, for people who don't know Lisp
+
+** Implementation ideas
+*** "Input frontends"
+A way to represent s-expressions as Markdown, Org, etc, so the entire plist can be edited in that mode. As a side-effect, this will permit use of Markdown, Org, etc in keyword-values - e.g. to use markup in comments or notes.
+
+*** A list of keys whose values are to be edited in a user-specified major mode.
+ * Multiple windows - instead of a single key-value buffer, we'll have multiple buffers in multiple visible windows, somewhat like =ediff=. The =accept= command will use the data from all involved buffers.
+   + The buffer and window will be created when a keyword associated with that mode is selected at the prompt.
+ * Alternatively, the whole plist goes into a single buffer of the markup's major mode - the markup bits as markup, the rest of the plist in a code block 🤷‍
+ * poly-mode to mix different modes
+ * see [[info:elisp#Swapping Text][swapping text]]
+
+*** A binding in the key-value buffer, which will insert the string at point in a buffer of a certain mode.
+* documentation discoverability                                         :doc:
 Ensure that the user manual is easily discoverable.
 
 #+BEGIN_QUOTE
@@ -427,9 +506,15 @@ Ensure that the user manual is easily discoverable.
 [2021-06-02 13:53:37] rnkn: although you will probably need a function link instead to find the org file \\
 [2021-06-02 13:54:30] contrapunctus: Although I guess the manual.org does not really need those fancy features...info export could work for it. \\
 #+END_QUOTE
-* macro for extensions                                  :code:extension:
-<2021-06-07T16:33:54+0530>
 
+1. [X] command (and menu item) to launch Org LP
+2. provide =:link= argument to =defgroup=
+3. open changelog on update
+
+* macro for extensions                                       :code:extension:
+:PROPERTIES:
+:CREATED:  2021-06-07T16:33:54+0530
+:END:
 A macro to create new columns for Chronometrist.
 
 Extension writer specifies
@@ -452,9 +537,32 @@ Benefits -
 + easier creation of such extensions
 + users can easily replace the function used to generate the cells, without having to deal with how the string is inserted into the row specifier.
 
-* unified format-duration function                  :code:customization:
-<2021-06-08T11:17:54+0530>
+Current uses -
+1. =chronometrist-goal=
+2. =chronometrist-spark=
 
+* macro for frontends                                                  :code:
+:PROPERTIES:
+:CREATED:  2021-06-26T08:49:25+0530
+:END:
+A macro to create Chronometrist frontends (based on =tabulated-list-mode=). If implemented, would shorten code for all four existing and two planned frontends.
+
+Programmer specifies -
+1. frontend command name (a symbol)
+2. name (string, passed to =define-derived-mode=)
+3. rows function
+4. schema value
+5. name of buffer created by command
+
+Macro creates -
+1. =frontend= interactive command, which behaves like a toggle
+2. function =frontend-rows=
+3. custom variables =frontend-schema=, =frontend-row-transformers=, =frontend-schema-transformers=, =frontend-buffer-name=
+
+* unified format-duration function                       :code:customization:
+:PROPERTIES:
+:CREATED:  2021-06-08T11:17:54+0530
+:END:
 Currently we have at least three ways of displaying durations - ="HH:MM:SS"= , ="XhYm"= , and =X hour(s), Y minutes(s)"= . Make a single function similar to =format-time-string=, but for durations. =ts-human-format-duration= from =ts.el= is not nearly as flexible as I'd like. When completed, we can have a single custom variable accepting a format string, which can be used to customize display of durations for the entire application at once.
 
 + user provides a duration (in seconds), a format string, and an optional separator string
@@ -490,8 +598,10 @@ Alternative syntax
 + to display only values, use ="%<code>"=
 + to display long units, use ="~[<separator>]<code>"=
 
-* DONE error - =min= called with nil                         :spark:bug:
-<2021-06-11T03:44:17+0530>
+* DONE error - =min= called with nil                              :spark:bug:
+:PROPERTIES:
+:CREATED:  2021-06-11T03:44:17+0530
+:END:
 1. clock in
 2. change =:start= of active interval to another time on the same date
 3. error
@@ -544,8 +654,10 @@ Debugger entered--Lisp error: (wrong-number-of-arguments #<subr min> 0)
   command-execute(file-notify-handle-event nil [(file-notify ((1 . 1) (modify) "chronometrist.sexp" 0) file-notify--callback-inotify)] t)
 #+END_SRC
 
-* STARTED discoverability and mouse-accessibility of commands [33%] :ux:
-<2021-06-15T16:18:49+0530>
+* STARTED discoverability and mouse-accessibility of commands [33%]      :ux:
+:PROPERTIES:
+:CREATED:  2021-06-15T16:18:49+0530
+:END:
 Goals
 1. discoverability of commands
 2. discoverability of default keybindings
@@ -560,33 +672,573 @@ Strategies
    * Perhaps I needn't worry too much. =menu-bar-mode= is enabled by default, and it makes #1 and #2 easy. I think a significant amount of the userbase disables =menu-bar-mode=, but they also have things like =counsel-M-x=, =describe-=.
      + The menu does not make the behavior of the numeric argument discoverable. Doesn't make sense to put it there, either.
 
-* query-editing the file buffer                                :feature:
-<2021-06-16T07:50:21+0530>
-
+* querying the file buffer and editing the results                  :feature:
+:PROPERTIES:
+:CREATED:  2021-06-16T07:50:21+0530
+:END:
 =chronometrist-loop-file= can be used to run queries against user data. It would be cool to be able to edit the file directly from the query results.
-1. The result data may just be plists, which could be displayed/edited directly from the search results ([[info:elisp#Invisible Text][invisible text]] or [[info:elisp#Selective Display][selective display]] +
- [[info:elisp#Narrowing][narrowing]]?)
+1. The result data may just be plists, which could be displayed/edited directly from the search results ([[info:elisp#Invisible Text][invisible text]] or [[info:elisp#Selective Display][selective display]] + [[info:elisp#Narrowing][narrowing]]?)
 2. The result data may be something which corresponds to the input data, in which case we could jump to the corresponding plist.
 3. The result data may be impossible to trace back to the input data (e.g. a sum of intervals from many plists), in which case we cannot provide direct editing.
 
-* error in change type detection                              :core:bug:
-<2021-06-16T18:40:18+0530>
+* error in change type detection                     :core:bug:plist_backend:
+:PROPERTIES:
+:CREATED:  2021-06-16T18:40:18+0530
+:END:
 Steps
 1. Clock in
 2. Delete active task plist, but don't save
 3. Clock in to different task. Error.
 
 Might have to do with there being 2 empty lines between the last-but-one plist and the new last plist.
-* spark monthly view                                     :spark:feature:
-:PROPERTIES:
-:feature:  frontend
-:END:
-<2021-06-17T00:08:08+0530>
-Frontend to show one or more months for a specific task, calendar-style, with each day being a single sparkline block.
 
-* Task-specific detailed view                                  :feature:
+* STARTED New frontends and enhancements                            :feature:
+** Existing frontends
+*** chronometrist (overview for a day)
+list of tasks, one day, durations and graphs
++ commands [0%]
+  1. [ ] previous/next day
+  2. [ ] set day (blank input to reset to today's date)
+  3. [ ] set duration format
+  4. [ ] display sparkline for total time
+
+*** report
+list of tasks, one week, durations only
+
+*** statistics
+list of tasks, one week/month/year [fn:1]
+
+*** details (intervals for a day) [16%]
+list of intervals, one day [fn:1]
++ [-] commands [50%]
+  1. [X] set [task/key-value] filter [fn:2]
+  2. [X] set range
+     1. implement timestamp ranges (e.g. =2021-06-01T12:00+05:30= to =2021-07-03T00:10:29+0530=)
+  3. [ ] previous/next day
+  4. [ ] set duration format
++ [ ] with =spark= - vertical sparkline for each interval
++ [ ] non-tabular text [fn:3]
++ [X] when range is a pair with the =car= or the =cdr= being blank, set the start/stop date to the earliest/latest date available.
+  * not possible with =completing-read-multiple=, which removes blank strings; the simplest solution was to allow "begin"/"end" as inputs.
++ [ ] when range is bigger than a day, you also want to see the date of each interval
+
+Bugs
+1. [ ] day-crossing events have the wrong duration and time. e.g. ~1   Exercise  walking  30 minutes   from 23:37 to 00:07~
+
+** New frontends I want
+*** task-key-values
+list of unique key-values for a task, one day [fn:1], durations and graphs
++ commands [0%]
+  1. [ ] set task
+  2. [ ] set range
+
+*** task-graph [0%]
+list of days, weeks, or months [fn:1], one task (with optional key-value filter [fn:2]), horizontal graph (and durations/stats?)
++ columns
+  1. range (ISO date, week, or year-month)
+  2. per-range graph (vertical/interals if days, horizontal/days if weeks or months)
++ [ ] commands [0%]
+  1. [ ] toggle week/month
+  2. [ ] set [task/key-value] filter
+  3. [ ] set range
++ [ ] non-tabular text [fn:3]
+
+[fn:1] variable range
+[fn:2] keys - show intervals with those keys; key-values - intervals with those values; or predicate
+[fn:3]
+#+BEGIN_SRC
+"(Showing intervals|No intervals to show)
+[(with (<keyword>*|<keyword-value>*)|
+matching <predicate>)]
+(for <date>|
+between (<date>|<datetime>) and (<date>|<datetime>)|
+for <predicate>)"
+#+END_SRC
+
+* STARTED customizable duration output                              :feature:
 :PROPERTIES:
-:feature:  frontend
+:branch:   format-seconds
 :END:
-<2021-06-22T04:57:06+0530>
-Frontend similar to =chronometrist=, but specific to one task - displays its unique tag/key-value combinations and their sparklines. Time period (day, week, etc) could be customizable.
+1. [X] define =chronometrist-duration-formats= to hold duration formats for different use cases in Chronometrist.
+2. [ ] define customization type for =chronometrist-duration-formats= to create user-friendly Custom interface
+3. [ ] make non-tabular parts of Chronometrist buffers adapt to column widths, to accomodate changes in duration formats
+
+* Incorrect time displayed when midnight crossed with a task active     :bug:
+Midnight-spanning intervals are split in the hash table when the file is read, but not when a task is started and not stopped before midnight. Run a function to check at midnight?
+
+* Duplication - accessing the latest-record                            :code:
+Many functions use the latest record. A =(chronometrist-with-latest-record var &rest body)= might help...
+
+* STARTED Plist-group backend [71%]                    :feature:optimization:
+See branch =grouped-plist-format=
+1. [X] Migrate backend code to use CLOS
+2. [-] Implement plist-group backend methods
+3. [ ] <<dates-in-timestamps>> Omit dates from plists
+4. +[ ] Mark split intervals with =:split t=+
+   * Not required, since we can detect them with enough certainty for my liking. (See =chronometrist-plists-split-p=)
+5. [X] make generic =cl-loop= backend interface - =chronometrist-loop-sexp-file=
+6. [X] =chronometrist-loop-sexp-file= - optimize grouped-plist iterator
+7. [X] key-values code is not yet generic
+8. [ ] update plist-pp to indent tagged lists differently
+9. [X] optimize program startup and file change callback
+10. [X] remove all references to =chronometrist-events= (hash table)
+11. [X] create new tagged list if required when clocking in
+12. [X] split midnight-spanning intervals when clocking out
+13. [X] interactive backend-switching command with completion; reset backend state after switching to account for changes made to the file in the meantime
+14. [ ] (maybe) handle existing (in-file) split tasks. Currently, if an interval is split, commands such as =chronometrist-key-values-unified-prompt= operate on the second split interval, but not the first. Instead, plist-group methods for =chronometrist-replace-last= and =chronometrist-remove-last= could check if the last interval is split, and operate on both of them. (=chronometrist-insert= already splits plists when inserting.)
+    * Don't modify =chronometrist-latest-record=; code using it generally only wants the latter half of a split plist.
+    * See branch =plist-group-handle-split-plists=
+15. [X] use file-change-detection optimization
+    * [X] fix bugs in change-type detection
+16. [ ] fix bug - extra newlines in file
+
+Optional
+1. define generic backend protocol for key-values package
+
+protocol implementation progress
+1. [X] chronometrist-latest-date-records
+2. [X] chronometrist-latest-record
+3. [X] chronometrist-task-records-for-date
+4. [X] chronometrist-active-days
+5. [X] chronometrist-insert
+6. [X] chronometrist-remove-last
+7. [X] chronometrist-replace-last
+8. [X] [superclass] chronometrist-create-file
+9. [ ] chronometrist-view-file
+10. [X] [superclass] chronometrist-edit-file
+11. [ ] chronometrist-count-records
+12. [X] chronometrist-to-list
+13. [X] chronometrist-to-hash-table
+14. [X] chronometrist-to-file
+15. [X] chronometrist-on-change
+16. [X] [superclass] chronometrist-reset-internal
+17. [ ] chronometrist-backend-empty-p
+18. [X] [superclass] chronometrist-memory-layer-empty-p
+19. [ ] chronometrist-verify
+20. [ ] [superclass] chronometrist-timer
+
+* New backends                                                      :feature:
+** Org time tracking
+** timeclock
+See docstring of =timeclock-log-data=
+
+** [[https://klog.jotaen.net/][klog]]
+:PROPERTIES:
+:CUSTOM_ID: new-backends-klog
+:END:
+
+** SQLite [0%]
+Chronometrist allows the user to add arbitrary key-values. There are a few ways to do this in SQL, but [[https://mariadb.com/kb/en/entity-attribute-value-implementation/][this solution]] seems well-suited to Chronometrist - put commonly-queried keys (name, start, stop) into SQL columns, and put user key-values in a JSON/s-exp TEXT column. The latter can be queried separately. SQLite has support for [[https://www.sqlite.org/json1.html][JSON columns]].
+
+1. [ ] Use =string-remove-prefix= rather than =s-chop-prefix=
+2. [-] =to-file=
+   * [X] insert intervals
+   * [ ] insert date properties
+   * [ ] insert events
+
+** Project Hamster
+https://github.com/projecthamster/hamster
++ https://github.com/projecthamster/hamster/wiki/Our-datamodel
+
+** [[https://gitlab.com/Harag/cl-naive-store][cl-naive-store]]
+:PROPERTIES:
+:CREATED:  2022-04-16T21:11:07+0530
+:END:
+Reimplementing the plist/plist-group backends in Common Lisp, without the buffer visualisation and buffer-movement commands provided by Emacs/Elisp, is not something I'm very enthusiastic about. Even if those turn out to not be major factors, implementing these backends in Elisp taught me that making your own database can be a lot of work. Especially if you just care about your application, and writing a database was not what you set out to do (I severely underestimated the work involved).
+
+Yet, some may prefer the plist-group backend to an SQLite database. I trust that a cl-naive-store backend could have the same capabilities as the plist-group backend, but without the maintenance burden of an /ad hoc/ s-expression store.
+
+* Functions doing similar things                                       :code:
+1. =task-time-one-day=
+2. =interval= (unused)
+3. =events-to-durations=
+
+* Use ISO date for functions operating on dates                 :time:format:
+* STARTED customizable task list [33%]                              :feature:
+1. [X] Make =chronometrist-task-list= customizable
+2. [ ] Interactive, buffer-local modification of task list, with completion (=completing-read-multiple=)
+3. [ ] Adding a task? We can modify the task list, but how to persist it?
+
+* Extend time range prompt                                          :feature:
+Support inputs like "today", "yesterday", "5 days ago", etc.
+ * =date(1)= does something like this, right? Maybe we could shell out to it.
+
+A general library for this could convert between (both to and from) such strings and TS structs.
+ * today, yesterday, day before yesterday, tomorrow, day after tomorrow
+ * N <seconds/minutes/hours/days/weeks/months/years> (ago|from now/today)
+   + plus multiples of those units e.g. "1 year, 5 months, ... from now"
+
+* DONE Kill/discard command                                         :feature:
+Command to delete the interval currently being recorded. (bind to 'k')
++ Most conservative option - it will only operate on the project at point, and will only kill for a clocked-in project.
++ Somewhat less conservative option - it will operate on the currently clocked-in project, no matter where point is.
++ It _should_ ask for confirmation.
++ Alternatively, or as a complement - an *undo command*, which will undo your last action (clock in or clock out).
+  - Undo and redo seem like the best bets.
+
+* pretty printer
+** fix handling of tagged alist group values                           :bug:
+** put each list element on its own line if length of list exceeds fill-column :feature:
+* verify command [20%]                                              :feature:
+:PROPERTIES:
+:CUSTOM_ID: verify-command
+:END:
+With different checks, for different levels of speed/thoroughness -
+1. [X] (plist group) Sequence of plist group dates
+2. [ ] Check that every record (except the last) has a =:stop=
+3. [ ] Intersecting timestamps
+4. [ ] Sequence of records
+5. [ ] (plist group) Midnight spanning interval check (first and last intervals)
+6. [ ] (plist group) Check that plist timestamps have the correct date. Only applicable [[dates-in-timestamps][as long as they have a date.]]
+
+* format changes
+** multiple intervals per record                                   :feature:
+:PROPERTIES:
+:CUSTOM_ID: multiple-intervals-per-record
+:END:
+#+BEGIN_SRC emacs-lisp
+(:name "<name>"
+ [<keyword-value pair>] ...
+ :intervals
+ (("<start>" . "<stop>")
+  ...))
+#+END_SRC
+
+It doesn't do anything not already possible in the current formats. At best, it removes some duplication when the same task is "paused" and "resumed".
++ Sometimes you pause and resume a task and don't want to split your key-values between >1 intervals (to avoid messing up completion suggestions for the future). An alternative means to the same end could be to add a key like =:deduct "<duration>"= or =:deduct ("<start time>" . "<stop time>")=.
+  - This will also make it easier to support formats like [[#new-backends-klog][klog]], which support this feature.
+  - It will probably complicate all data consuming code, though...think of =chronometrist-details= 🤔
+  - An alternative idea could be to define a custom variable to hold the user's key values. If this variable is defined, it would be used instead of generating suggestions from past key-values. That way, such situations will not affect key-value suggestions.
+
+** "event records" - records with only a timestamp                 :feature:
+:PROPERTIES:
+:CREATED:  2021-12-18T11:48:53+0530
+:END:
+Records not used for time tracking, but to store data associated with a date or timestamp. More than one record may exist for the same date.
+#+BEGIN_SRC emacs-lisp
+(event "<date or timestamp>"
+ [<keyword-value pair>] ...)
+#+END_SRC
+
+** STARTED tagging dates with key-values [0%]                      :feature:
+:PROPERTIES:
+:CREATED:  2022-02-10T22:59:45+0530
+:CUSTOM_ID: date-key-values
+:branch:   date-properties
+:END:
+Straightforward enough for the plist group backend -
+#+BEGIN_SRC elisp
+("<date>"
+ [<keyword> <value>]*
+ <plist>+)
+#+END_SRC
+
+Alternatively, this would be easier to work with - easier to select the key-values or the plists, as required -
+#+BEGIN_SRC elisp
+("<date>"
+ (key-values
+  [<keyword> <value>]+)
+ <plist>+)
+#+END_SRC
+
+=to-list= could omit the date key-values, since it has no concept of dates. =to-hash-table= could have them at the start of the lists of plists, i.e. hash values would still be =(cdr <plist group>)=.
+
+The plist backend could theoretically be extended to support it, but I'd rather deprecate that format (since it suffers from performance issues) and not deal with it again.
+
+1. [ ] Update call sites of =chronometrist-latest-date-records= (which may now also contain key-values)
+2. [ ] Update code accessing the hash table
+3. [ ] Update =plist-pp= to handle
+
+* undesired file watcher created after literate-elisp-load              :bug:
+:PROPERTIES:
+:CREATED:  2021-12-18T15:13:35+0530
+:END:
+1. Type =M-x chronometrist=; =(chronometrist-backend-file-watch (chronometrist-active-backend))= probably returns a descriptor
+2. Visit literate source and type =M-x literate-elisp-load=; =(chronometrist-backend-file-watch (chronometrist-active-backend))= returns nil
+3. Type =M-x chronometrist=; =file-notify-descriptors= likely contains two descriptors for the same file and the same function (=chronometrist-file-refresh=)
+
+=chronometrist-register-backend= removes the old backend object and replaces it with a new one.
+
+* backend migration [0%]
+:PROPERTIES:
+:CREATED:  2022-01-08T23:32:37+0530
+:END:
+1. [ ] Use active backend as the suggested input backend when migrating
+2. [ ] Conserve file local variables prop line for text backends
+
+** make migrate command async [33%]
+:PROPERTIES:
+:CREATED:  2022-04-01T18:02:03+0530
+:END:
+=chronometrist-migrate= / =chronometrist-to-file= can take a long time to run, freezing Emacs until completion if run synchronously.
+
+1. [X] basic async export
+2. [ ] display message on start and completion
+3. [ ] test the INPUT-FILE argument
+
+* STARTED Support for the Third Time System [57%]                 :extension:
+:PROPERTIES:
+:CREATED:  2022-02-10T14:12:12+0530
+:branch:   third-time
+:END:
+[[https://www.lesswrong.com/posts/RWu8eZqbwgB9zaerh/third-time-a-better-way-to-work][Third Time: a better way to work]]
+#+BEGIN_QUOTE
+Lastly, here in one place are all the steps for using Third Time:
+1. Note the time, or start a stopwatch
+2. /Work/ until you want or need to break
+3. Divide how long you’ve just worked by 3 (or use your chosen fraction), and add any minutes left over from previous breaks
+4. Set an alarm for that long
+5. /Break/ until the alarm goes off, or you decide to resume work
+6. If you resume early, note how much time was left, to add to your next break
+7. Go back to step 1.
+
+Additional rules:
++ If you have to stop work for a /non-work-related interruption/, start a break immediately.
++ You can (optionally) take a /big break/ for lunch and/or dinner, lasting as long as you like. Set an alarm at the start for when you’ll resume work. A big break uses up any saved break minutes, so you can’t carry them over to the afternoon/evening.
++ /Avoid taking other unearned breaks/ if possible — so try to do personal tasks during normal or big breaks, or before/after your work day.
+#+END_QUOTE
+
+1. [X] =chronometrist-third-fraction=
+2. [X] =chronometrist-third-break-time=
+3. [X] on clock out, increment =break-time= and start timed notification
+4. [X] on clock in, calculate duration of latest break (duration between last =:stop= and now), and subtract it from =break-time=; if the resulting time is negative, set it to zero.
+5. [ ] "big break" command - user enters a time, for which we set an alarm. User must resume working around that time.
+6. [ ] Define work hours
+   * [ ] Custom variable for default work hours.
+   * [ ] Hook function which inserts default work hours.
+   * [ ] Hook function which prompts for work hours whenever you first clock in on a date. If work hours are defined in the custom variable, ask whether to use them - on negative answer, prompt for today's work hours. If work hours are not defined, prompt for today's work hours.
+7. [ ] Displaying/recording breaks. Probably done implicitly - when work hours are defined, any time not spent working can be interpreted as break time.
+
+** Example flow
+1. work for 30m
+2. clock out - add 10m to =break-time=
+3. clock in after a 5m break - subtract 5m from =break-time=
+
+** Extras
+1. persist =break-time= between Emacs sessions
+2. audible alerts
+3. handle user edits to the database
+   * last record modified - ?
+   * remove last record - ?
+   * example - interval extended
+     1. work 10 minutes and clock out - +3m break time
+     2. edit stop time to add +20 minutes of work (30m total)
+        * compare with old data in hash table - decrement break time added by old plist, increment break time added by new plist
+
+* STARTED Customizable alerts [50%]                            :feature:code:
+:PROPERTIES:
+:CREATED:  2022-02-14T08:22:36+0530
+:CUSTOM_ID: customizable-alerts
+:branch:   alert-macro
+:END:
+=chronometrist-third= and =chronometrist-goal= have nearly identical alert code; additionally, users cannot customize the alert style per-alert without basically rewriting the alert functions.
+
+Convert =chronometrist-third-alert-functions= and =chronometrist-goal-alert-functions= to customizable alists[fn:4] whose entries take the form =(SYMBOL FUNCTION ALERT-FN &rest ALERT-ARGS)=, where
++ =SYMBOL= uniquely identifies the alert,
++ =FUNCTION= is a function calling =chronometrist-*-run-at-time= and =ALERT-FN=, and
++ =ALERT-ARGS= are passed to =ALERT-FN=.
+
+=ALERT-FN= will usually be =alert=, and =ALERT-ARGS= will usually be keyword arguments passed to =alert=.
+Similar to how they behave now, these packages will start/stop functions for all entries provided in these alists. (So the user can still control which alerts are run.)
+
+Also define =chronometrist--timer-alist=, which associates =symbol= with a timer object.
+
+1. [X] write macro
+2. [ ] use in =chronometrist-goal= and =chronometrist-third=
+
+[fn:4] Actually, make a macro to define such alists, since the docstrings are likely to be near-identical.
+
+* DONE Predefined key-values for tasks
+:PROPERTIES:
+:CREATED:  2022-02-17T23:34:17+0530
+:END:
+Benefits
+1. Speeds up key-value completion for very large data sets.
+2. Prevents key-value suggestions from being affected by [[#multiple-intervals-per-record][splitting of tasks across multiple intervals]].
+
+#+BEGIN_SRC emacs-lisp
+'(("Task" <plist> ...)
+  ...)
+#+END_SRC
+
+* no-goal-alert - "You have spent  on <task>" [0%]                      :bug:
+:PROPERTIES:
+:CREATED:  2022-02-25T00:19:49+0530
+:END:
+=chronometrist-goal-no-goal-alert= uses =chronometrist-task-time-one-day=, which calls =chronometrist-task-records-for-date= with the /current/ date.
+
+1. [ ] Use the data for the latest date recorded in the database, rather than the current date.
+
+* better error reporting
+:PROPERTIES:
+:CREATED:  2022-02-28T11:35:37+0530
+:END:
+Similar to [[#verify-command][verify command]], perhaps, but this is really about making error messages thrown by the program more meaningful to the user.
+
+** record does not contain intervals
+:PROPERTIES:
+:CREATED:  2022-02-28T11:35:47+0530
+:END:
+
+* User-defined categories
+:PROPERTIES:
+:CREATED:  2022-03-31T22:44:34+0530
+:END:
+A task can be part of any number of categories. A category may also contain other categories. The categories, and the total time spent on each one, could be displayed in the main view, separate from the tasks.
+
+* First run behaviour                                                    :ux:
+:PROPERTIES:
+:CREATED:  2022-04-02T17:28:33+0530
+:END:
+1. [ ] Look for any existing Chronometrist database in the default location. If one is found, use it to determine the default active backend. Otherwise, offer to import from one of the supported backends.
+   + Some backends may not be installed - "see MELPA for more formats"
+2. [ ] Don't suggest nil when asking for first project on first run
+
+* STARTED Common Lisp port
+:PROPERTIES:
+:CREATED:  2022-04-03T09:36:53+0530
+:END:
+** DONE Replace =add-variable-watcher=
+Common Lisp does not have Elisp's =add-variable-watcher=. The Elisp code used that to automatically update the =file= slot of the active backend object when the user changes the value of =chronometrist-file=. The new solution is to remove direct accesses to the =file= slot, define a =backend-file= method which returns the value of =file= if non-nil (it's usually nil), or derives a file path from =*user-data-file*= and the backend's extension.
+
+It seems that the =file= slot is now unnecessary - =backend-file= can check =path= instead of =file=, and use either =path= or =*user-data-file*= to derive the full path.
+
+1. [X] Remove the =file= slot
+
+** DONE Use pathnames instead of namestrings
+:PROPERTIES:
+:CREATED:  2022-04-03T12:30:24+0530
+:END:
+
+** CLIM UI design
+*** One-day task-duration table
+:PROPERTIES:
+:CREATED:  2022-04-10T08:09:18+0530
+:END:
+columns
+1. index (for numeric argument)
+2. task name
+3. task duration today
+4. task activity indicator
+   * click to clock in/out (hover to show icon)
+5. graph of daily task durations
+   * Click on a point in the graph to view that day in the Details View.
+
+click on row to show taller graph and inline display of either key-value breakdown, or interval breakdown.
+
+commands
+1. clock in, clock out, etc
+2. toggle details for row
+3. toggle details for all rows
+4. next/previous day
+5. set displayed day
+6. cycle graph heights (self/comparative)
+   * the height of the graphs can be based on the range of each individual graph's own data ('self') or based on the range of all data ('comparative').
+
+settings
+1. default graph height
+
+*** One-day category-duration table
+:PROPERTIES:
+:CREATED:  2022-04-10T08:11:20+0530
+:END:
+1. category
+2. time duration today
+
+commands
+1. toggle details for row (show tasks in each category)
+2. toggle details for all rows
+
+*** One-day event-occurrence table
+:PROPERTIES:
+:CREATED:  2022-04-10T08:12:58+0530
+:END:
+("Useful for recording things like weight, medication, waist circumference, etc.")
+1. index (prefix argument)
+2. event name
+3. time of occurrence
+4. graph of past occurrences
+
+commands
+1. add event
+2. record event
+
+*** 1+ day editable log
+:PROPERTIES:
+:CREATED:  2022-04-08T18:23:42+0530
+:END:
+Displays tables of day properties, intervals, and events, grouped by day, in date/week/month/year range (default - today)
+
+can select a day property/interval/event to edit its data
+
+buttons to add new day properties, intervals, and events
+
+When there are no intervals/events/day properties, show placeholder text - "No intervals recorded on this day." / "No events recorded on this day." / "No properties for this day."
+
+Commands
+1. filter contents
+2. next/previous day (or range)
+3. set displayed day (or range)
+
+*** Line chart views
+:PROPERTIES:
+:CREATED:  [2022-04-10 Sun 14:35]
+:END:
+Line chart with one or more (adjustable) metrics -
+ * duration for task
+ * task-property combinations
+ * numeric property value/function with numeric output
+...over a time range (adjustable), with points for days/weeks/months/years (adjustable)
+
+User can switch between single graph vs separate graphs, different types of graphs, etc.
+
+Commands
+1. new/open/save/delete view
+2. add/remove metric (a line on the graph)
+3. increase/decrease/set range, next/previous range
+4. increase/decrease/set granularity
+
+*** Default view (overview for a day)
+Default view is a tiled composition of the one-day task-duration table, one-day grouped log, and the one-day category-duration table.
+
+*** view/edit database as
+:PROPERTIES:
+:CREATED:  2022-04-08T19:56:38+0530
+:END:
+some way to view/edit the database in a different format, e.g. Lisp plists
+
+* Documentation restructuring                                           :doc:
+:PROPERTIES:
+:CREATED:  2022-04-14T18:04:21+0530
+:END:
+1. Move documentation from LPs to manual.org
+2. Revamp tutorials - https://diataxis.fr/tutorials/#the-language-of-tutorials
+3. Make how-to guides more general?
+4. Move some how-to guide code into a contrib directory?
+
+** tutorial and how-to topic revamp
+tutorials
+1. installation (MELPA) -> first run
+2. adding the first task
+3. clocking in, clocking out
+4. customization - open a file when starting a task (move from how-to)
+5. customization - warn when exiting with an active task
+6. clocking in/out without running hooks
+7. restarting or discarding an activity
+8. key-value extension - installation -> customization -> testing/results
+9. graph extension - installation -> customization -> testing/results
+
+how-to guides
+1. how to install (Git, MELPA, Quelpa, etc)
+2. how to attach tags and properties to time intervals (cover different commands)
+3. how to configure Emacs for Chronometrist development
+
+* Concurrent tasks
+:PROPERTIES:
+:CREATED:  2022-04-19T22:12:54+0530
+:END:
+I'm not interested in using this myself, so it must be possible to enable/disable it.
++ Enabling/disabling it would just affect how the clock-in command works. Perhaps data verification, too.
+
+How might it affect the data consumer?
+1. Calculation of total time tracked (in any range, e.g. a day) will definitely require a more complex algorithm.

cl/backend-sqlite.asd

@@ -0,0 +1,9 @@
+(defsystem     chronometrist-sqlite
+  :version     "0.0.1"
+  :serial      t
+  :license     "Unlicense"
+  :author      "contrapunctus <contrapunctus at disroot dot org>"
+  :description "SQLite backend for Chronometrist"
+  :defsystem-depends-on ("literate-lisp")
+  :depends-on  (:trivia :clsql-sqlite3)
+  :components  ((:org "chronometrist")))

cl/lib.asd

@@ -0,0 +1,9 @@
+(defsystem     chronometrist
+  :version     "0.0.1"
+  :serial      t
+  :license     "Unlicense"
+  :author      "contrapunctus <contrapunctus at disroot dot org>"
+  :description "Friendly and extensible personal time tracker - common library"
+  :defsystem-depends-on ("literate-lisp")
+  :depends-on  (:trivia)
+  :components  ((:org "chronometrist")))

cl/manual.org

@@ -0,0 +1,32 @@
+* Explanation
+:PROPERTIES:
+:CUSTOM_ID: explanation
+:END:
+This is a port of Chronometrist to Common Lisp.
+
+Currently, it contains
+1. a read-only plist-group backend
+2. an incomplete SQLite backend
+3. an incomplete CLIM frontend
+
+** Source code overview
+:PROPERTIES:
+:CUSTOM_ID: source-code-overview
+:END:
+*** CLIM frontend
+:PROPERTIES:
+:CUSTOM_ID: clim-frontend
+:END:
+The CLIM frontend uses CLIM panes for each view of data Chronometrist provides. Each pane has a [[file:chronometrist.org::#display-pane][=display-pane=]] method to display its contents.
+
+Currently, only one CLIM pane has been implemented, called the [[file:chronometrist.org::#task-duration-table-pane][task-duration table]]. By default, it displays a list of tasks, and each of their durations for today.
+
+**** Tables
+:PROPERTIES:
+:CUSTOM_ID: tables
+:END:
+The tables in the CLIM frontend are designed with ease of extensibility in mind. Thus -
+1. The columns displayed in this table are controlled by [[file:chronometrist.org::#*task-duration-table-spec*][=*task-duration-table-spec*=]], which contains a list of [[file:chronometrist.org::#column-specifier][=column-specifier=]] objects.
+2. Each [[file:chronometrist.org::#column-specifier][=column-specifier=]] has two methods specializing on it, a [[file:chronometrist.org::#cell-data][=cell-data=]] method and a [[file:chronometrist.org::#cell-print][=cell-print=]] method. These determine the data contained by the cells of the column, and how that data is printed in the CLIM pane.
+
+The function [[file:chronometrist.org::#task-duration-table-function][=task-duration-table-function=]] uses the [[file:chronometrist.org::#cell-data][=cell-data=]] methods to return the data of the table as a list of lists. This data is used by [[file:chronometrist.org::#display-pane][=display-pane=]] in conjunction with [[file:chronometrist.org::#cell-print][=cell-print=]] methods to display the data in the pane.

cl/ui-clim.asd

@@ -0,0 +1,9 @@
+(defsystem     chronometrist-clim
+  :version     "0.0.1"
+  :serial      t
+  :license     "Unlicense"
+  :author      "contrapunctus <contrapunctus at disroot dot org>"
+  :description "Friendly and extensible personal time tracker - CLIM GUI"
+  :defsystem-depends-on ("literate-lisp")
+  :depends-on  (:trivia :mcclim)
+  :components  ((:org "chronometrist")))

elisp/chronometrist-key-values.el

@@ -90,13 +90,13 @@ Each value is a list of tag combinations, in reverse
 chronological order. Each combination is a list containing tags
 as symbol and/or strings.")
 
-(defun chronometrist-tags-history-populate (task history-table file)
+(defun chronometrist-tags-history-populate (task history-table backend)
   "Store tag history for TASK in HISTORY-TABLE from FILE.
 Return the new value inserted into HISTORY-TABLE.
 
 HISTORY-TABLE must be a hash table. (see `chronometrist-tags-history')"
   (puthash task nil history-table)
-  (chronometrist-loop-file for plist in file do
+  (cl-loop for plist in (chronometrist-to-list backend) do
     (let ((new-tag-list  (plist-get plist :tags))
           (old-tag-lists (gethash task history-table)))
       (and (equal task (plist-get plist :name))
@@ -167,10 +167,10 @@ INITIAL-INPUT is as used in `completing-read'."
 _ARGS are ignored. This function always returns t, so it can be
 used in `chronometrist-before-out-functions'."
   (interactive)
-  (let* ((last-expr (chronometrist-last))
+  (let* ((backend   (chronometrist-active-backend))
+         (last-expr (chronometrist-latest-record backend))
          (last-name (plist-get last-expr :name))
-         (_history  (chronometrist-tags-history-populate last-name
-                                             chronometrist-tags-history chronometrist-file))
+         (_history  (chronometrist-tags-history-populate last-name chronometrist-tags-history backend))
          (last-tags (plist-get last-expr :tags))
          (input     (->> (chronometrist-maybe-symbol-to-string last-tags)
                          (-interpose ",")
@@ -179,18 +179,42 @@ used in `chronometrist-before-out-functions'."
                          (chronometrist-maybe-string-to-symbol))))
     (when input
       (--> (append last-tags input)
-        (reverse it)
-        (cl-remove-duplicates it :test #'equal)
-        (reverse it)
-        (list :tags it)
-        (chronometrist-plist-update (chronometrist-sexp-last) it)
-        (chronometrist-sexp-replace-last it)))
+           (reverse it)
+           (cl-remove-duplicates it :test #'equal)
+           (reverse it)
+           (list :tags it)
+           (chronometrist-plist-update
+            (chronometrist-latest-record backend) it)
+           (chronometrist-replace-last backend it)))
     t))
 
 (defgroup chronometrist-key-values nil
   "Add key-values to Chronometrist time intervals."
   :group 'chronometrist)
 
+(defcustom chronometrist-key-value-use-database-history t
+  "If non-nil, use database to generate key-value suggestions.
+If nil, only `chronometrist-key-value-preset-alist' is used."
+  :type 'boolean
+  :group 'chronometrist-key-value)
+
+(defcustom chronometrist-key-value-preset-alist nil
+  "Alist of key-value suggestions for `chronometrist-key-value' prompts.
+Each element must be in the form (\"TASK\" <KEYWORD> <VALUE> ...)"
+  :type
+  '(repeat
+    (cons
+     (string :tag "Task name")
+     (repeat :tag "Property preset"
+             (plist :tag "Property"
+                    ;; :key-type 'keyword :value-type 'sexp
+                    ))))
+  :group 'chronometrist-key-values)
+
+(defun chronometrist-key-value-get-presets (task)
+  "Return presets for TASK from `chronometrist-key-value-preset-alist' as a list of plists."
+  (alist-get task chronometrist-key-value-preset-alist nil nil #'equal))
+
 (defcustom chronometrist-kv-buffer-name "*Chronometrist-Key-Values*"
   "Name of buffer in which key-values are entered."
   :group 'chronometrist-key-values
@@ -204,20 +228,20 @@ containing keywords used with that task, in reverse chronological
 order. The keywords are stored as strings and their leading \":\"
 is removed.")
 
-(defun chronometrist-key-history-populate (task history-table file)
+(defun chronometrist-key-history-populate (task history-table backend)
   "Store key history for TASK in HISTORY-TABLE from FILE.
 Return the new value inserted into HISTORY-TABLE.
 
 HISTORY-TABLE must be a hash table (see `chronometrist-key-history')."
   (puthash task nil history-table)
-  (chronometrist-loop-file for plist in file do
+  (cl-loop for plist in backend do
     (catch 'quit
       (let* ((name     (plist-get plist :name))
              (_check   (unless (equal name task) (throw 'quit nil)))
              (keys     (--> (chronometrist-plist-key-values plist)
-                         (seq-filter #'keywordp it)
-                         (cl-loop for key in it collect
-                           (chronometrist-keyword-to-string key))))
+                            (seq-filter #'keywordp it)
+                            (cl-loop for key in it collect
+                              (chronometrist-keyword-to-string key))))
              (_check   (unless keys (throw 'quit nil)))
              (old-keys (gethash name history-table)))
         (puthash name
@@ -231,13 +255,13 @@ HISTORY-TABLE must be a hash table (see `chronometrist-key-history')."
 The hash table keys are user-key names (as strings), and the
 values are lists containing values (as strings).")
 
-(defun chronometrist-value-history-populate (history-table file)
+(defun chronometrist-value-history-populate (history-table backend)
   "Store value history in HISTORY-TABLE from FILE.
 HISTORY-TABLE must be a hash table. (see `chronometrist-value-history')"
   (clrhash history-table)
   ;; Note - while keys are Lisp keywords, values may be any Lisp
   ;; object, including lists
-  (chronometrist-loop-file for plist in file do
+  (cl-loop for plist in (chronometrist-to-list backend) do
     ;; We call them user-key-values because we filter out Chronometrist's
     ;; reserved key-values
     (let ((user-key-values (chronometrist-plist-key-values plist)))
@@ -288,7 +312,7 @@ It currently supports ido, ido-ubiquitous, ivy, and helm."
   "Prompt the user to enter keys.
 USED-KEYS are keys they have already added since the invocation
 of `chronometrist-kv-add'."
-  (let ((key-suggestions (--> (chronometrist-last)
+  (let ((key-suggestions (--> (chronometrist-latest-record (chronometrist-active-backend))
                            (plist-get it :name)
                            (gethash it chronometrist-key-history))))
     (completing-read (format "Key (%s to quit): "
@@ -335,18 +359,19 @@ used in `chronometrist-before-out-functions'."
   (interactive)
   (let* ((buffer      (get-buffer-create chronometrist-kv-buffer-name))
          (first-key-p t)
-         (last-sexp   (chronometrist-last))
+         (backend     (chronometrist-active-backend))
+         (last-sexp   (chronometrist-latest-record backend))
          (last-name   (plist-get last-sexp :name))
          (last-kvs    (chronometrist-plist-key-values last-sexp))
          (used-keys   (--map (chronometrist-keyword-to-string it)
                              (seq-filter #'keywordp last-kvs))))
-    (chronometrist-key-history-populate last-name chronometrist-key-history chronometrist-file)
-    (chronometrist-value-history-populate chronometrist-value-history chronometrist-file)
+    (chronometrist-key-history-populate last-name chronometrist-key-history backend)
+    (chronometrist-value-history-populate chronometrist-value-history backend)
     (switch-to-buffer buffer)
     (with-current-buffer buffer
       (erase-buffer)
       (chronometrist-kv-read-mode)
-      (if (and (chronometrist-current-task) last-kvs)
+      (if (and (chronometrist-current-task (chronometrist-active-backend)) last-kvs)
           (progn
             (funcall chronometrist-sexp-pretty-print-function last-kvs buffer)
             (down-list -1)
@@ -377,14 +402,15 @@ used in `chronometrist-before-out-functions'."
 (defun chronometrist-kv-accept ()
   "Accept the plist in `chronometrist-kv-buffer-name' and add it to `chronometrist-file'."
   (interactive)
-  (let (user-kv-expr)
+  (let* ((backend (chronometrist-active-backend))
+         (latest  (chronometrist-latest-record backend))
+         user-kv-expr)
     (with-current-buffer (get-buffer chronometrist-kv-buffer-name)
       (goto-char (point-min))
       (setq user-kv-expr (ignore-errors (read (current-buffer))))
       (kill-buffer chronometrist-kv-buffer-name))
     (if user-kv-expr
-        (chronometrist-sexp-replace-last
-         (chronometrist-plist-update (chronometrist-sexp-last) user-kv-expr))
+        (chronometrist-replace-last backend (chronometrist-plist-update latest user-kv-expr))
       (chronometrist-refresh))))
 
 (defun chronometrist-kv-reject ()
@@ -401,25 +427,35 @@ used in `chronometrist-before-out-functions'."
     ["Change tags and key-values for active/last interval"
      chronometrist-key-values-unified-prompt]))
 
-(cl-defun chronometrist-key-values-unified-prompt (&optional (task (plist-get (chronometrist-sexp-last) :name)))
+(cl-defun chronometrist-key-values-unified-prompt
+    (&optional (task (plist-get (chronometrist-latest-record (chronometrist-active-backend)) :name)))
   "Query user for tags and key-values to be added for TASK.
 Return t, to permit use in `chronometrist-before-out-functions'."
   (interactive)
-  (let ((key-values (chronometrist-loop-file for plist in chronometrist-file
-                      when (equal (plist-get plist :name) task)
-                      collect
-                      (let ((plist (chronometrist-plist-remove plist :name :start :stop)))
-                        (when plist (format "%S" plist)))
-                      into key-value-plists
-                      finally return
-                      (--> (seq-filter #'identity key-value-plists)
-                        (cl-remove-duplicates it :test #'equal :from-end t)))))
-    (if (null key-values)
+  (let* ((backend (chronometrist-active-backend))
+         (presets (--map (format "%S" it)
+                         (chronometrist-key-value-get-presets task)))
+         (key-values
+          (when chronometrist-key-value-use-database-history
+            (cl-loop for plist in (chronometrist-to-list backend)
+              when (equal (plist-get plist :name) task)
+              collect
+              (let ((plist (chronometrist-plist-remove plist :name :start :stop)))
+                (when plist (format "%S" plist)))
+              into key-value-plists
+              finally return
+              (--> (seq-filter #'identity key-value-plists)
+                   (cl-remove-duplicates it :test #'equal :from-end t)))))
+         (latest (chronometrist-latest-record backend)))
+    (if (and (null presets) (null key-values))
         (progn (chronometrist-tags-add) (chronometrist-kv-add))
-      (chronometrist-sexp-replace-last
-       (chronometrist-plist-update (chronometrist-sexp-last)
-                       (read (completing-read (format "Key-values for %s: " task)
-                                              key-values))))))
+      (let* ((candidates (append presets key-values))
+             (input      (completing-read
+                          (format "Key-values for %s: " task)
+                          candidates nil nil nil 'chronometrist-key-values-unified-prompt-history)))
+        (chronometrist-replace-last backend
+                        (chronometrist-plist-update latest
+                                        (read input))))))
   t)
 
 (provide 'chronometrist-key-values)

elisp/chronometrist-key-values.org

@@ -191,13 +191,13 @@ as symbol and/or strings.")
 #+END_SRC
 *** tags-history-populate                                          :writer:
 #+BEGIN_SRC emacs-lisp
-(defun chronometrist-tags-history-populate (task history-table file)
+(defun chronometrist-tags-history-populate (task history-table backend)
   "Store tag history for TASK in HISTORY-TABLE from FILE.
 Return the new value inserted into HISTORY-TABLE.
 
 HISTORY-TABLE must be a hash table. (see `chronometrist-tags-history')"
   (puthash task nil history-table)
-  (chronometrist-loop-file for plist in file do
+  (cl-loop for plist in (chronometrist-to-list backend) do
     (let ((new-tag-list  (plist-get plist :tags))
           (old-tag-lists (gethash task history-table)))
       (and (equal task (plist-get plist :name))
@@ -209,6 +209,7 @@ HISTORY-TABLE must be a hash table. (see `chronometrist-tags-history')"
                     history-table))))
   (chronometrist-history-prep task history-table))
 #+END_SRC
+
 **** tests
 #+BEGIN_SRC emacs-lisp :tangle chronometrist-key-values-tests.el :load test
 (ert-deftest chronometrist-tags-history ()
@@ -301,10 +302,10 @@ INITIAL-INPUT is as used in `completing-read'."
 _ARGS are ignored. This function always returns t, so it can be
 used in `chronometrist-before-out-functions'."
   (interactive)
-  (let* ((last-expr (chronometrist-last))
+  (let* ((backend   (chronometrist-active-backend))
+         (last-expr (chronometrist-latest-record backend))
          (last-name (plist-get last-expr :name))
-         (_history  (chronometrist-tags-history-populate last-name
-                                             chronometrist-tags-history chronometrist-file))
+         (_history  (chronometrist-tags-history-populate last-name chronometrist-tags-history backend))
          (last-tags (plist-get last-expr :tags))
          (input     (->> (chronometrist-maybe-symbol-to-string last-tags)
                          (-interpose ",")
@@ -313,12 +314,13 @@ used in `chronometrist-before-out-functions'."
                          (chronometrist-maybe-string-to-symbol))))
     (when input
       (--> (append last-tags input)
-        (reverse it)
-        (cl-remove-duplicates it :test #'equal)
-        (reverse it)
-        (list :tags it)
-        (chronometrist-plist-update (chronometrist-sexp-last) it)
-        (chronometrist-sexp-replace-last it)))
+           (reverse it)
+           (cl-remove-duplicates it :test #'equal)
+           (reverse it)
+           (list :tags it)
+           (chronometrist-plist-update
+            (chronometrist-latest-record backend) it)
+           (chronometrist-replace-last backend it)))
     t))
 #+END_SRC
 ** Key-Values
@@ -328,6 +330,39 @@ used in `chronometrist-before-out-functions'."
   "Add key-values to Chronometrist time intervals."
   :group 'chronometrist)
 #+END_SRC
+
+*** use-database-history                                  :custom:variable:
+#+BEGIN_SRC emacs-lisp
+(defcustom chronometrist-key-value-use-database-history t
+  "If non-nil, use database to generate key-value suggestions.
+If nil, only `chronometrist-key-value-preset-alist' is used."
+  :type 'boolean
+  :group 'chronometrist-key-value)
+#+END_SRC
+
+*** preset-alist                                          :custom:variable:
+#+BEGIN_SRC emacs-lisp
+(defcustom chronometrist-key-value-preset-alist nil
+  "Alist of key-value suggestions for `chronometrist-key-value' prompts.
+Each element must be in the form (\"TASK\" <KEYWORD> <VALUE> ...)"
+  :type
+  '(repeat
+    (cons
+     (string :tag "Task name")
+     (repeat :tag "Property preset"
+             (plist :tag "Property"
+                    ;; :key-type 'keyword :value-type 'sexp
+                    ))))
+  :group 'chronometrist-key-values)
+#+END_SRC
+
+**** get-presets
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-key-value-get-presets (task)
+  "Return presets for TASK from `chronometrist-key-value-preset-alist' as a list of plists."
+  (alist-get task chronometrist-key-value-preset-alist nil nil #'equal))
+#+END_SRC
+
 *** kv-buffer-name                                        :custom:variable:
 #+BEGIN_SRC emacs-lisp
 (defcustom chronometrist-kv-buffer-name "*Chronometrist-Key-Values*"
@@ -335,6 +370,7 @@ used in `chronometrist-before-out-functions'."
   :group 'chronometrist-key-values
   :type 'string)
 #+END_SRC
+
 *** key-history                                                  :variable:
 :PROPERTIES:
 :VALUE:    hash table
@@ -350,20 +386,20 @@ is removed.")
 #+END_SRC
 *** key-history-populate                                           :writer:
 #+BEGIN_SRC emacs-lisp
-(defun chronometrist-key-history-populate (task history-table file)
+(defun chronometrist-key-history-populate (task history-table backend)
   "Store key history for TASK in HISTORY-TABLE from FILE.
 Return the new value inserted into HISTORY-TABLE.
 
 HISTORY-TABLE must be a hash table (see `chronometrist-key-history')."
   (puthash task nil history-table)
-  (chronometrist-loop-file for plist in file do
+  (cl-loop for plist in backend do
     (catch 'quit
       (let* ((name     (plist-get plist :name))
              (_check   (unless (equal name task) (throw 'quit nil)))
              (keys     (--> (chronometrist-plist-key-values plist)
-                         (seq-filter #'keywordp it)
-                         (cl-loop for key in it collect
-                           (chronometrist-keyword-to-string key))))
+                            (seq-filter #'keywordp it)
+                            (cl-loop for key in it collect
+                              (chronometrist-keyword-to-string key))))
              (_check   (unless keys (throw 'quit nil)))
              (old-keys (gethash name history-table)))
         (puthash name
@@ -396,13 +432,13 @@ values are lists containing values (as strings).")
 *** value-history-populate                                         :writer:
 We don't want values to be task-sensitive, so this does not have a KEY parameter similar to TASK for =chronometrist-tags-history-populate= or =chronometrist-key-history-populate=.
 #+BEGIN_SRC emacs-lisp
-(defun chronometrist-value-history-populate (history-table file)
+(defun chronometrist-value-history-populate (history-table backend)
   "Store value history in HISTORY-TABLE from FILE.
 HISTORY-TABLE must be a hash table. (see `chronometrist-value-history')"
   (clrhash history-table)
   ;; Note - while keys are Lisp keywords, values may be any Lisp
   ;; object, including lists
-  (chronometrist-loop-file for plist in file do
+  (cl-loop for plist in (chronometrist-to-list backend) do
     ;; We call them user-key-values because we filter out Chronometrist's
     ;; reserved key-values
     (let ((user-key-values (chronometrist-plist-key-values plist)))
@@ -419,6 +455,7 @@ HISTORY-TABLE must be a hash table. (see `chronometrist-value-history')"
              (chronometrist-history-prep key history-table))
            history-table))
 #+END_SRC
+
 **** tests
 #+BEGIN_SRC emacs-lisp :tangle chronometrist-key-values-tests.el :load test
 (ert-deftest chronometrist-value-history ()
@@ -475,7 +512,7 @@ It currently supports ido, ido-ubiquitous, ivy, and helm."
   "Prompt the user to enter keys.
 USED-KEYS are keys they have already added since the invocation
 of `chronometrist-kv-add'."
-  (let ((key-suggestions (--> (chronometrist-last)
+  (let ((key-suggestions (--> (chronometrist-latest-record (chronometrist-active-backend))
                            (plist-get it :name)
                            (gethash it chronometrist-key-history))))
     (completing-read (format "Key (%s to quit): "
@@ -528,18 +565,19 @@ used in `chronometrist-before-out-functions'."
   (interactive)
   (let* ((buffer      (get-buffer-create chronometrist-kv-buffer-name))
          (first-key-p t)
-         (last-sexp   (chronometrist-last))
+         (backend     (chronometrist-active-backend))
+         (last-sexp   (chronometrist-latest-record backend))
          (last-name   (plist-get last-sexp :name))
          (last-kvs    (chronometrist-plist-key-values last-sexp))
          (used-keys   (--map (chronometrist-keyword-to-string it)
                              (seq-filter #'keywordp last-kvs))))
-    (chronometrist-key-history-populate last-name chronometrist-key-history chronometrist-file)
-    (chronometrist-value-history-populate chronometrist-value-history chronometrist-file)
+    (chronometrist-key-history-populate last-name chronometrist-key-history backend)
+    (chronometrist-value-history-populate chronometrist-value-history backend)
     (switch-to-buffer buffer)
     (with-current-buffer buffer
       (erase-buffer)
       (chronometrist-kv-read-mode)
-      (if (and (chronometrist-current-task) last-kvs)
+      (if (and (chronometrist-current-task (chronometrist-active-backend)) last-kvs)
           (progn
             (funcall chronometrist-sexp-pretty-print-function last-kvs buffer)
             (down-list -1)
@@ -572,14 +610,15 @@ used in `chronometrist-before-out-functions'."
 (defun chronometrist-kv-accept ()
   "Accept the plist in `chronometrist-kv-buffer-name' and add it to `chronometrist-file'."
   (interactive)
-  (let (user-kv-expr)
+  (let* ((backend (chronometrist-active-backend))
+         (latest  (chronometrist-latest-record backend))
+         user-kv-expr)
     (with-current-buffer (get-buffer chronometrist-kv-buffer-name)
       (goto-char (point-min))
       (setq user-kv-expr (ignore-errors (read (current-buffer))))
       (kill-buffer chronometrist-kv-buffer-name))
     (if user-kv-expr
-        (chronometrist-sexp-replace-last
-         (chronometrist-plist-update (chronometrist-sexp-last) user-kv-expr))
+        (chronometrist-replace-last backend (chronometrist-plist-update latest user-kv-expr))
       (chronometrist-refresh))))
 #+END_SRC
 *** kv-reject                                                     :command:
@@ -642,14 +681,17 @@ Types of prompts planned (#1 and #2 are meant to be mixed and matched)
 
   LIST should be a list, with all elements being either a plists,
   or lists of symbols."
-  (cl-loop with num = 0
+  (cl-loop with backend = (chronometrist-active-backend)
+    with num = 0
+    with last = (chronometrist-latest-record backend)
     for elt in (-take 7 list)
     do (incf num)
     if (= num 10) do (setq num 0)
     collect
     (list (format "%s" num)
-          `(chronometrist-sexp-replace-last
-            (chronometrist-plist-update (chronometrist-sexp-last)
+          `(chronometrist-replace-last
+            backend
+            (chronometrist-plist-update last
                             ',(cl-case type
                                 (:tags (list :tags elt))
                                 (:key-values elt))))
@@ -665,7 +707,7 @@ Types of prompts planned (#1 and #2 are meant to be mixed and matched)
   "Query user for tags to be added to TASK.
   Return t, to permit use in `chronometrist-before-out-functions'."
   (let ((table chronometrist-tags-history))
-    (chronometrist-tags-history-populate task table chronometrist-file)
+    (chronometrist-tags-history-populate task table (chronometrist-active-backend))
     (if (hash-table-empty-p table)
         (chronometrist-tags-add)
       (chronometrist-defchoice "tag" :tag (gethash task table))
@@ -678,7 +720,7 @@ Types of prompts planned (#1 and #2 are meant to be mixed and matched)
   "Query user for keys to be added to TASK.
 Return t, to permit use in `chronometrist-before-out-functions'."
   (let ((table chronometrist-key-history))
-    (chronometrist-key-history-populate task table chronometrist-file)
+    (chronometrist-key-history-populate task table (chronometrist-active-backend))
     (if (hash-table-empty-p table)
         (chronometrist-kv-add)
       (chronometrist-defchoice :key task table)
@@ -695,32 +737,52 @@ Return t, to permit use in `chronometrist-before-out-functions'."
         ())))
 #+END_SRC
 *** WIP unified-prompt                                        :hook:writer:
+:PROPERTIES:
+:CUSTOM_ID: unified-prompt
+:END:
 1. [ ] Improve appearance - is there an easy way to syntax highlight the plists?
+
 #+BEGIN_SRC emacs-lisp
-(cl-defun chronometrist-key-values-unified-prompt (&optional (task (plist-get (chronometrist-sexp-last) :name)))
+(cl-defun chronometrist-key-values-unified-prompt
+    (&optional (task (plist-get (chronometrist-latest-record (chronometrist-active-backend)) :name)))
   "Query user for tags and key-values to be added for TASK.
 Return t, to permit use in `chronometrist-before-out-functions'."
   (interactive)
-  (let ((key-values (chronometrist-loop-file for plist in chronometrist-file
-                      when (equal (plist-get plist :name) task)
-                      collect
-                      (let ((plist (chronometrist-plist-remove plist :name :start :stop)))
-                        (when plist (format "%S" plist)))
-                      into key-value-plists
-                      finally return
-                      (--> (seq-filter #'identity key-value-plists)
-                        (cl-remove-duplicates it :test #'equal :from-end t)))))
-    (if (null key-values)
+  (let* ((backend (chronometrist-active-backend))
+         (presets (--map (format "%S" it)
+                         (chronometrist-key-value-get-presets task)))
+         (key-values
+          (when chronometrist-key-value-use-database-history
+            (cl-loop for plist in (chronometrist-to-list backend)
+              when (equal (plist-get plist :name) task)
+              collect
+              (let ((plist (chronometrist-plist-remove plist :name :start :stop)))
+                (when plist (format "%S" plist)))
+              into key-value-plists
+              finally return
+              (--> (seq-filter #'identity key-value-plists)
+                   (cl-remove-duplicates it :test #'equal :from-end t)))))
+         (latest (chronometrist-latest-record backend)))
+    (if (and (null presets) (null key-values))
         (progn (chronometrist-tags-add) (chronometrist-kv-add))
-      (chronometrist-sexp-replace-last
-       (chronometrist-plist-update (chronometrist-sexp-last)
-                       (read (completing-read (format "Key-values for %s: " task)
-                                              key-values))))))
+      (let* ((candidates (append presets key-values))
+             (input      (completing-read
+                          (format "Key-values for %s: " task)
+                          candidates nil nil nil 'chronometrist-key-values-unified-prompt-history)))
+        (chronometrist-replace-last backend
+                        (chronometrist-plist-update latest
+                                        (read input))))))
   t)
-
 #+END_SRC
+
 * Provide
 #+BEGIN_SRC emacs-lisp
 (provide 'chronometrist-key-values)
 ;;; chronometrist-key-values.el ends here
 #+END_SRC
+
+* Local variables                                                  :noexport:
+# Local Variables:
+# my-org-src-default-lang: "emacs-lisp"
+# eval: (when (package-installed-p 'literate-elisp) (require 'literate-elisp) (literate-elisp-load (buffer-file-name)))
+# End:

elisp/chronometrist-spark.el

@@ -1,10 +1,10 @@
-;;; chronometrist-spark.el --- Show sparklines in Chronometrist -*- lexical-binding: t; -*-
+;;; chronometrist-spark.el --- Show sparklines in Chronometrist buffers -*- lexical-binding: t; -*-
 
 ;; Author: contrapunctus <xmpp:contrapunctus@jabjab.de>
 ;; Maintainer: contrapunctus <xmpp:contrapunctus@jabjab.de>
 ;; Keywords: calendar
 ;; Homepage: https://tildegit.org/contrapunctus/chronometrist
-;; Package-Requires: ((emacs "24.3") (chronometrist "0.7.0") (spark "0.1"))
+;; Package-Requires: ((emacs "25.1") (chronometrist "0.7.0") (spark "0.1"))
 ;; Version: 0.1.0
 
 ;; This is free and unencumbered software released into the public domain.
@@ -21,6 +21,7 @@
 ;; This package adds a column to Chronometrist displaying sparklines for each task.
 
 ;;; Code:
+;; This file was automatically generated from chronometrist-spark.org.
 (require 'chronometrist)
 (require 'spark)
 
@@ -52,6 +53,12 @@ DURATIONS must be a list of integer seconds."
            ;; have a minimum and maximum range.
            (format "(%sm)" (apply #'max duration-minutes))))))
 
+(defun chronometrist-spark-durations (task length stop-ts)
+  "Return a list of durations for time tracked for TASK in the last LENGTH days before STOP-TS."
+  (cl-loop for day from (- (- length 1)) to 0
+    collect
+    (chronometrist-task-time-one-day task (ts-adjust 'day day stop-ts))))
+
 (defun chronometrist-spark-row-transformer (row)
   "Add a sparkline cell to ROW.
 Used to add a sparkline column to `chronometrist-rows'.
@@ -59,20 +66,11 @@ Used to add a sparkline column to `chronometrist-rows'.
 ROW must be a valid element of the list specified by
 `tabulated-list-entries'."
   (-let* (((task vector) row)
-          (sparkline
-           (cl-loop with today = (ts-now)
-             with duration with active-p
-             for day from (- (- chronometrist-spark-length 1)) to 0
-             collect
-             (setq duration
-                   (chronometrist-task-time-one-day task
-                                        (ts-adjust 'day day today)))
-             into durations
-             unless (zerop duration) do (setq active-p t)
-             finally return
-             (if (and active-p chronometrist-spark-show-range)
-                 (format "%s %s" (spark durations) (chronometrist-spark-range durations))
-               (format "%s" (spark durations))))))
+          (durations (chronometrist-spark-durations task chronometrist-spark-length (ts-now)))
+          (sparkline (if (and (not (seq-every-p #'zerop durations))
+                              chronometrist-spark-show-range)
+                         (format "%s %s" (spark durations) (chronometrist-spark-range durations))
+                       (format "%s" (spark durations)))))
     (list task (vconcat vector `[,sparkline]))))
 
 (defun chronometrist-spark-schema-transformer (schema)

elisp/chronometrist-spark.org

@@ -5,13 +5,13 @@
 
 * Library headers and commentary
 #+BEGIN_SRC emacs-lisp
-;;; chronometrist-spark.el --- Show sparklines in Chronometrist -*- lexical-binding: t; -*-
+;;; chronometrist-spark.el --- Show sparklines in Chronometrist buffers -*- lexical-binding: t; -*-
 
 ;; Author: contrapunctus <xmpp:contrapunctus@jabjab.de>
 ;; Maintainer: contrapunctus <xmpp:contrapunctus@jabjab.de>
 ;; Keywords: calendar
 ;; Homepage: https://tildegit.org/contrapunctus/chronometrist
-;; Package-Requires: ((emacs "24.3") (chronometrist "0.7.0") (spark "0.1"))
+;; Package-Requires: ((emacs "25.1") (chronometrist "0.7.0") (spark "0.1"))
 ;; Version: 0.1.0
 
 ;; This is free and unencumbered software released into the public domain.
@@ -31,12 +31,15 @@
 ;;
 ;; This package adds a column to Chronometrist displaying sparklines for each task.
 #+END_SRC
+
 * Dependencies
 #+BEGIN_SRC emacs-lisp
 ;;; Code:
+;; This file was automatically generated from chronometrist-spark.org.
 (require 'chronometrist)
 (require 'spark)
 #+END_SRC
+
 * Code
 ** custom group                              :custom:group:
 #+BEGIN_SRC emacs-lisp
@@ -86,6 +89,15 @@ DURATIONS must be a list of integer seconds."
   (should (equal (chronometrist-spark-range '(60 0 0))   "(1m)"))
   (should (equal (chronometrist-spark-range '(60 0 120)) "(1m~2m)")))
 #+END_SRC
+** durations                                                      :function:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-spark-durations (task length stop-ts)
+  "Return a list of durations for time tracked for TASK in the last LENGTH days before STOP-TS."
+  (cl-loop for day from (- (- length 1)) to 0
+    collect
+    (chronometrist-task-time-one-day task (ts-adjust 'day day stop-ts))))
+#+END_SRC
+
 ** TODO row-transformer                          :function:
 if larger than 7
 add space after (% length 7)th element
@@ -103,20 +115,11 @@ Used to add a sparkline column to `chronometrist-rows'.
 ROW must be a valid element of the list specified by
 `tabulated-list-entries'."
   (-let* (((task vector) row)
-          (sparkline
-           (cl-loop with today = (ts-now)
-             with duration with active-p
-             for day from (- (- chronometrist-spark-length 1)) to 0
-             collect
-             (setq duration
-                   (chronometrist-task-time-one-day task
-                                        (ts-adjust 'day day today)))
-             into durations
-             unless (zerop duration) do (setq active-p t)
-             finally return
-             (if (and active-p chronometrist-spark-show-range)
-                 (format "%s %s" (spark durations) (chronometrist-spark-range durations))
-               (format "%s" (spark durations))))))
+          (durations (chronometrist-spark-durations task chronometrist-spark-length (ts-now)))
+          (sparkline (if (and (not (seq-every-p #'zerop durations))
+                              chronometrist-spark-show-range)
+                         (format "%s %s" (spark durations) (chronometrist-spark-range durations))
+                       (format "%s" (spark durations)))))
     (list task (vconcat vector `[,sparkline]))))
 
 #+END_SRC
@@ -167,3 +170,8 @@ SCHEMA should be a vector as specified by `tabulated-list-format'."
 (provide 'chronometrist-spark)
 ;;; chronometrist-spark.el ends here
 #+END_SRC
+
+* Local variables                                                  :noexport:
+# Local Variables:
+# eval: (when (package-installed-p 'literate-elisp) (require 'literate-elisp) (literate-elisp-load (buffer-file-name)))
+# End:

elisp/chronometrist-sqlite.el

@@ -0,0 +1,210 @@
+;;; chronometrist-sqlite.el --- SQLite backend for Chronometrist -*- lexical-binding: t; -*-
+
+;; Author: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Maintainer: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Keywords: calendar
+;; Homepage: https://tildegit.org/contrapunctus/chronometrist
+;; Package-Requires: ((emacs "24.3") (chronometrist "0.9.0") (emacsql-sqlite "1.0.0"))
+;; Version: 0.1.0
+
+;; This is free and unencumbered software released into the public domain.
+;;
+;; Anyone is free to copy, modify, publish, use, compile, sell, or
+;; distribute this software, either in source code form or as a compiled
+;; binary, for any purpose, commercial or non-commercial, and by any
+;; means.
+;;
+;; For more information, please refer to <https://unlicense.org>
+
+;;; Commentary:
+;;
+;; This package provides an SQLite 3 backend for Chronometrist.
+
+;;; Code:
+(require 'chronometrist)
+(require 'emacsql-sqlite)
+
+(defclass chronometrist-sqlite-backend (chronometrist-backend chronometrist-file-backend-mixin)
+  ((extension :initform "sqlite"
+              :accessor chronometrist-backend-ext
+              :custom 'string)
+   (connection :initform nil
+               :initarg :connection
+               :accessor chronometrist-backend-connection)))
+
+(chronometrist-register-backend
+ :sqlite "Store records in SQLite database."
+ (make-instance 'chronometrist-sqlite-backend :path chronometrist-file))
+
+(cl-defmethod initialize-instance :after ((backend chronometrist-sqlite-backend)
+                                          &rest _initargs)
+  "Initialize connection for BACKEND based on its file."
+  (with-slots (file connection) backend
+    (when (and file (not connection))
+      (setf connection (emacsql-sqlite file)))))
+
+(cl-defmethod chronometrist-create-file ((backend chronometrist-sqlite-backend) &optional file)
+  "Create file for BACKEND if it does not already exist.
+Return the connection object from `emacsql-sqlite'."
+  (let* ((file (or file (chronometrist-backend-file backend)))
+         (db   (or (chronometrist-backend-connection backend)
+                   (setf (chronometrist-backend-connection backend)
+                         (emacsql-sqlite file)))))
+    (cl-loop
+      for query in
+      '(;; Properties are user-defined key-values stored as JSON.
+        [:create-table properties
+         ([(prop-id integer :primary-key)
+           (properties text :unique :not-null)])]
+        ;; An event is a timestamp with a name and optional properties.
+        [:create-table event-names
+         ([(name-id integer :primary-key)
+           (name text :unique :not-null)])]
+        [:create-table events
+         ([(event-id integer :primary-key)
+           (name-id integer :not-null :references event-names [name-id])])]
+        ;; An interval is a time range with a name and optional properties.
+        [:create-table interval-names
+         ([(name-id integer :primary-key)
+           (name text :unique :not-null)])]
+        [:create-table intervals
+         ([(interval-id integer :primary-key)
+           (name-id integer :not-null :references interval-names [name-id])
+           (start-time integer :not-null)
+           ;; The latest interval may be ongoing, so the stop time may be NULL.
+           (stop-time integer)
+           (prop-id integer :references properties [prop-id])]
+          (:unique [name-id start-time stop-time]))]
+        ;; A date contains one or more events and intervals. It may
+        ;; also contain properties.
+        [:create-table dates
+         ([(date-id integer :primary-key)
+           (date integer :unique :not-null)
+           (prop-id integer :references properties [prop-id])])]
+        [:create-table date-events
+         ([(date-id integer :not-null :references dates [date-id])
+           (event-id integer :not-null :references events [event-id])])]
+        [:create-table date-intervals
+         ([(date-id integer :not-null :references dates [date-id])
+           (interval-id integer :not-null :references intervals [interval-id])])])
+      do (emacsql db query)
+      finally return db)))
+
+(defun chronometrist-iso-to-unix (timestamp)
+  (truncate (float-time (parse-iso8601-time-string timestamp))))
+
+(cl-defmethod chronometrist-to-file (hash-table (backend chronometrist-sqlite-backend) file)
+  (with-slots (connection) backend
+    (delete-file file)
+    (when connection (emacsql-close connection))
+    (setf connection nil)
+    (chronometrist-create-file backend file)
+    (cl-loop for date in (sort (hash-table-keys hash-table) #'string-lessp) do
+      ;; insert date if it does not exist
+      (emacsql connection [:insert-or-ignore-into dates [date] :values [$s1]]
+               (chronometrist-iso-to-unix date))
+      (cl-loop for plist in (gethash date hash-table) do
+        (chronometrist-insert backend plist)))))
+
+(defun chronometrist-sqlite-insert-properties (backend plist)
+  "Insert properties from PLIST to (SQLite) BACKEND.
+Properties are key-values excluding :name, :start, and :stop.
+
+Insert nothing if the properties already exist. Return the
+prop-id of the inserted or existing property."
+  (with-slots (connection) backend
+    (let* ((plist (chronometrist-plist-key-values plist))
+           (props (if (functionp chronometrist-sqlite-properties-function)
+                      (funcall chronometrist-sqlite-properties-function plist)
+                    plist)))
+      (emacsql connection
+               [:insert-or-ignore-into properties [properties] :values [$s1]]
+               props)
+      (caar (emacsql connection [:select [prop-id]
+                                 :from properties
+                                 :where (= properties $s1)]
+                     props)))))
+
+(defun chronometrist-sqlite-properties-to-json (plist)
+  "Return PLIST as a JSON string."
+  (json-encode
+   ;; `json-encode' throws an error when it thinks
+   ;; it sees "alists" which have numbers as
+   ;; "keys", so we convert any cons cells and any
+   ;; lists starting with a number to vectors
+   (-tree-map (lambda (elt)
+                (cond ((chronometrist-pp-pair-p elt)
+                       (vector (car elt) (cdr elt)))
+                      ((consp elt)
+                       (vconcat elt))
+                      (t elt)))
+              plist)))
+
+(defcustom chronometrist-sqlite-properties-function nil
+  "Function used to control the encoding of user key-values.
+The function must accept a single argument, the plist of key-values.
+
+Any non-function value results in key-values being inserted as
+s-expressions in a text column."
+  :type '(choice function (sexp :tag "Insert as s-expressions")))
+
+(cl-defmethod chronometrist-insert ((backend chronometrist-sqlite-backend) plist)
+  (-let (((plist-1 plist-2)  (chronometrist-split-plist plist))
+         (db  (chronometrist-backend-connection backend)))
+    (cl-loop for plist in (if (and plist-1 plist-2)
+                              (list plist-1 plist-2)
+                            (list plist))
+      do
+      (-let* (((&plist :name name :start start :stop stop) plist)
+              (date-unix   (chronometrist-iso-to-unix (chronometrist-iso-to-date start)))
+              (start-unix  (chronometrist-iso-to-unix start))
+              (stop-unix   (and stop (chronometrist-iso-to-unix stop)))
+              name-id interval-id prop-id)
+        ;; insert name if it does not exist
+        (emacsql db [:insert-or-ignore-into interval-names [name]
+                     :values [$s1]]
+                 name)
+        ;; insert interval properties if they do not exist
+        (setq prop-id (chronometrist-sqlite-insert-properties backend plist))
+        ;; insert interval and associate it with the date
+        (setq name-id
+              (caar (emacsql db [:select [name-id]
+                                 :from interval-names
+                                 :where (= name $s1)]
+                             name)))
+        (emacsql db [:insert-or-ignore-into intervals
+                     [name-id start-time stop-time prop-id]
+                     :values [$s1 $s2 $s3 $s4]]
+                 name-id start-unix stop-unix prop-id)
+        (emacsql db [:insert-or-ignore-into dates [date]
+                     :values [$s1]] date-unix)
+        (setq date-id
+              (caar (emacsql db [:select [date-id] :from dates
+                                 :where (= date $s1)]
+                             date-unix))
+              interval-id
+              (caar (emacsql db [:select (funcall max interval-id) :from intervals])))
+        (emacsql db [:insert-into date-intervals [date-id interval-id]
+                     :values [$s1 $s2]]
+                 date-id interval-id)))))
+
+(cl-defmethod chronometrist-edit-backend ((backend chronometrist-sqlite-backend))
+  (require 'sql)
+  (switch-to-buffer
+   (sql-comint-sqlite 'sqlite (list file))))
+
+;; SELECT * FROM TABLE WHERE ID = (SELECT MAX(ID) FROM TABLE);
+;; SELECT * FROM tablename ORDER BY column DESC LIMIT 1;
+(cl-defmethod chronometrist-latest-record ((backend chronometrist-sqlite-backend) db)
+  (emacsql db [:select * :from events :order-by rowid :desc :limit 1]))
+
+(cl-defmethod chronometrist-task-records-for-date ((backend chronometrist-sqlite-backend) task date-ts))
+
+(cl-defmethod chronometrist-active-days ((backend chronometrist-sqlite-backend) task))
+
+(cl-defmethod chronometrist-replace-last ((backend chronometrist-sqlite-backend) plist)
+  (emacsql db [:delete-from events :where ]))
+
+(provide 'chronometrist-sqlite)
+
+;;; chronometrist-sqlite.el ends here

elisp/chronometrist-sqlite.org

@@ -0,0 +1,277 @@
+#+TITLE: chronometrist-sqlite
+#+AUTHOR: contrapunctus
+#+SUBTITLE: SQLite backend for Chronometrist
+#+PROPERTY: header-args :tangle yes :load yes
+
+* Library headers and commentary
+#+BEGIN_SRC emacs-lisp
+;;; chronometrist-sqlite.el --- SQLite backend for Chronometrist -*- lexical-binding: t; -*-
+
+;; Author: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Maintainer: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Keywords: calendar
+;; Homepage: https://tildegit.org/contrapunctus/chronometrist
+;; Package-Requires: ((emacs "24.3") (chronometrist "0.9.0") (emacsql-sqlite "1.0.0"))
+;; Version: 0.1.0
+
+;; This is free and unencumbered software released into the public domain.
+;;
+;; Anyone is free to copy, modify, publish, use, compile, sell, or
+;; distribute this software, either in source code form or as a compiled
+;; binary, for any purpose, commercial or non-commercial, and by any
+;; means.
+;;
+;; For more information, please refer to <https://unlicense.org>
+
+#+END_SRC
+
+"Commentary" is displayed when the user clicks on the package's entry in =M-x list-packages=.
+#+BEGIN_SRC emacs-lisp
+;;; Commentary:
+;;
+;; This package provides an SQLite 3 backend for Chronometrist.
+#+END_SRC
+
+* Dependencies
+#+BEGIN_SRC emacs-lisp
+;;; Code:
+(require 'chronometrist)
+(require 'emacsql-sqlite)
+#+END_SRC
+
+* Code
+** class
+#+BEGIN_SRC emacs-lisp
+(defclass chronometrist-sqlite-backend (chronometrist-backend chronometrist-file-backend-mixin)
+  ((extension :initform "sqlite"
+              :accessor chronometrist-backend-ext
+              :custom 'string)
+   (connection :initform nil
+               :initarg :connection
+               :accessor chronometrist-backend-connection)))
+
+(chronometrist-register-backend
+ :sqlite "Store records in SQLite database."
+ (make-instance 'chronometrist-sqlite-backend :path chronometrist-file))
+#+END_SRC
+
+** initialize-instance                                              :method:
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod initialize-instance :after ((backend chronometrist-sqlite-backend)
+                                          &rest _initargs)
+  "Initialize connection for BACKEND based on its file."
+  (with-slots (file connection) backend
+    (when (and file (not connection))
+      (setf connection (emacsql-sqlite file)))))
+#+END_SRC
+
+** create-file
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod chronometrist-create-file ((backend chronometrist-sqlite-backend) &optional file)
+  "Create file for BACKEND if it does not already exist.
+Return the connection object from `emacsql-sqlite'."
+  (let* ((file (or file (chronometrist-backend-file backend)))
+         (db   (or (chronometrist-backend-connection backend)
+                   (setf (chronometrist-backend-connection backend)
+                         (emacsql-sqlite file)))))
+    (cl-loop
+      for query in
+      '(;; Properties are user-defined key-values stored as JSON.
+        [:create-table properties
+         ([(prop-id integer :primary-key)
+           (properties text :unique :not-null)])]
+        ;; An event is a timestamp with a name and optional properties.
+        [:create-table event-names
+         ([(name-id integer :primary-key)
+           (name text :unique :not-null)])]
+        [:create-table events
+         ([(event-id integer :primary-key)
+           (name-id integer :not-null :references event-names [name-id])])]
+        ;; An interval is a time range with a name and optional properties.
+        [:create-table interval-names
+         ([(name-id integer :primary-key)
+           (name text :unique :not-null)])]
+        [:create-table intervals
+         ([(interval-id integer :primary-key)
+           (name-id integer :not-null :references interval-names [name-id])
+           (start-time integer :not-null)
+           ;; The latest interval may be ongoing, so the stop time may be NULL.
+           (stop-time integer)
+           (prop-id integer :references properties [prop-id])]
+          (:unique [name-id start-time stop-time]))]
+        ;; A date contains one or more events and intervals. It may
+        ;; also contain properties.
+        [:create-table dates
+         ([(date-id integer :primary-key)
+           (date integer :unique :not-null)
+           (prop-id integer :references properties [prop-id])])]
+        [:create-table date-events
+         ([(date-id integer :not-null :references dates [date-id])
+           (event-id integer :not-null :references events [event-id])])]
+        [:create-table date-intervals
+         ([(date-id integer :not-null :references dates [date-id])
+           (interval-id integer :not-null :references intervals [interval-id])])])
+      do (emacsql db query)
+      finally return db)))
+#+END_SRC
+
+** iso-to-unix                                                    :function:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-iso-to-unix (timestamp)
+  (truncate (float-time (parse-iso8601-time-string timestamp))))
+#+END_SRC
+
+** to-file                                                          :method:
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod chronometrist-to-file (hash-table (backend chronometrist-sqlite-backend) file)
+  (with-slots (connection) backend
+    (delete-file file)
+    (when connection (emacsql-close connection))
+    (setf connection nil)
+    (chronometrist-create-file backend file)
+    (cl-loop for date in (sort (hash-table-keys hash-table) #'string-lessp) do
+      ;; insert date if it does not exist
+      (emacsql connection [:insert-or-ignore-into dates [date] :values [$s1]]
+               (chronometrist-iso-to-unix date))
+      (cl-loop for plist in (gethash date hash-table) do
+        (chronometrist-insert backend plist)))))
+#+END_SRC
+
+** insert-properties                                                :writer:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-sqlite-insert-properties (backend plist)
+  "Insert properties from PLIST to (SQLite) BACKEND.
+Properties are key-values excluding :name, :start, and :stop.
+
+Insert nothing if the properties already exist. Return the
+prop-id of the inserted or existing property."
+  (with-slots (connection) backend
+    (let* ((plist (chronometrist-plist-key-values plist))
+           (props (if (functionp chronometrist-sqlite-properties-function)
+                      (funcall chronometrist-sqlite-properties-function plist)
+                    plist)))
+      (emacsql connection
+               [:insert-or-ignore-into properties [properties] :values [$s1]]
+               props)
+      (caar (emacsql connection [:select [prop-id]
+                                 :from properties
+                                 :where (= properties $s1)]
+                     props)))))
+#+END_SRC
+
+*** properties-to-json                                           :function:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-sqlite-properties-to-json (plist)
+  "Return PLIST as a JSON string."
+  (json-encode
+   ;; `json-encode' throws an error when it thinks
+   ;; it sees "alists" which have numbers as
+   ;; "keys", so we convert any cons cells and any
+   ;; lists starting with a number to vectors
+   (-tree-map (lambda (elt)
+                (cond ((chronometrist-pp-pair-p elt)
+                       (vector (car elt) (cdr elt)))
+                      ((consp elt)
+                       (vconcat elt))
+                      (t elt)))
+              plist)))
+#+END_SRC
+
+*** properties-function                                   :custom:variable:
+#+BEGIN_SRC emacs-lisp
+(defcustom chronometrist-sqlite-properties-function nil
+  "Function used to control the encoding of user key-values.
+The function must accept a single argument, the plist of key-values.
+
+Any non-function value results in key-values being inserted as
+s-expressions in a text column."
+  :type '(choice function (sexp :tag "Insert as s-expressions")))
+#+END_SRC
+
+** insert
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod chronometrist-insert ((backend chronometrist-sqlite-backend) plist)
+  (-let (((plist-1 plist-2)  (chronometrist-split-plist plist))
+         (db  (chronometrist-backend-connection backend)))
+    (cl-loop for plist in (if (and plist-1 plist-2)
+                              (list plist-1 plist-2)
+                            (list plist))
+      do
+      (-let* (((&plist :name name :start start :stop stop) plist)
+              (date-unix   (chronometrist-iso-to-unix (chronometrist-iso-to-date start)))
+              (start-unix  (chronometrist-iso-to-unix start))
+              (stop-unix   (and stop (chronometrist-iso-to-unix stop)))
+              name-id interval-id prop-id)
+        ;; insert name if it does not exist
+        (emacsql db [:insert-or-ignore-into interval-names [name]
+                     :values [$s1]]
+                 name)
+        ;; insert interval properties if they do not exist
+        (setq prop-id (chronometrist-sqlite-insert-properties backend plist))
+        ;; insert interval and associate it with the date
+        (setq name-id
+              (caar (emacsql db [:select [name-id]
+                                 :from interval-names
+                                 :where (= name $s1)]
+                             name)))
+        (emacsql db [:insert-or-ignore-into intervals
+                     [name-id start-time stop-time prop-id]
+                     :values [$s1 $s2 $s3 $s4]]
+                 name-id start-unix stop-unix prop-id)
+        (emacsql db [:insert-or-ignore-into dates [date]
+                     :values [$s1]] date-unix)
+        (setq date-id
+              (caar (emacsql db [:select [date-id] :from dates
+                                 :where (= date $s1)]
+                             date-unix))
+              interval-id
+              (caar (emacsql db [:select (funcall max interval-id) :from intervals])))
+        (emacsql db [:insert-into date-intervals [date-id interval-id]
+                     :values [$s1 $s2]]
+                 date-id interval-id)))))
+#+END_SRC
+
+** open-file
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod chronometrist-edit-backend ((backend chronometrist-sqlite-backend))
+  (require 'sql)
+  (switch-to-buffer
+   (sql-comint-sqlite 'sqlite (list file))))
+#+END_SRC
+
+** latest-record
+#+BEGIN_SRC emacs-lisp
+;; SELECT * FROM TABLE WHERE ID = (SELECT MAX(ID) FROM TABLE);
+;; SELECT * FROM tablename ORDER BY column DESC LIMIT 1;
+(cl-defmethod chronometrist-latest-record ((backend chronometrist-sqlite-backend) db)
+  (emacsql db [:select * :from events :order-by rowid :desc :limit 1]))
+#+END_SRC
+
+** task-records-for-date
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod chronometrist-task-records-for-date ((backend chronometrist-sqlite-backend) task date-ts))
+#+END_SRC
+
+** active-days
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod chronometrist-active-days ((backend chronometrist-sqlite-backend) task))
+#+END_SRC
+
+** replace-last
+#+BEGIN_SRC emacs-lisp
+(cl-defmethod chronometrist-replace-last ((backend chronometrist-sqlite-backend) plist)
+  (emacsql db [:delete-from events :where ]))
+#+END_SRC
+
+** Provide
+#+BEGIN_SRC emacs-lisp
+(provide 'chronometrist-sqlite)
+
+;;; chronometrist-sqlite.el ends here
+#+END_SRC
+
+* Local variables                                                  :noexport:
+# Local Variables:
+# eval: (when (or (package-installed-p 'emacsql) (featurep 'emacsql)) (require 'emacsql) (emacsql-fix-vector-indentation))
+# eval: (when (or (package-installed-p 'literate-elisp) (featurep 'literate-elisp)) (require 'literate-elisp) (literate-elisp-load (buffer-file-name)))
+# End:

elisp/chronometrist-third.el

@@ -0,0 +1,178 @@
+;;; chronometrist-third.el --- Third Time support for Chronometrist -*- lexical-binding: t; -*-
+
+;; Author: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Maintainer: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Keywords: calendar
+;; Homepage: https://tildegit.org/contrapunctus/chronometrist
+;; Package-Requires: ((emacs "25.1") (alert "1.2") (chronometrist "0.6.0"))
+;; Version: 0.0.1
+
+;; This is free and unencumbered software released into the public domain.
+;;
+;; Anyone is free to copy, modify, publish, use, compile, sell, or
+;; distribute this software, either in source code form or as a compiled
+;; binary, for any purpose, commercial or non-commercial, and by any
+;; means.
+;;
+;; For more information, please refer to <https://unlicense.org>
+
+;;; Commentary:
+;; Add support for the Third Time system to Chronometrist.  In Third
+;; Time, you work for any length of time you like, and "earn" a third
+;; of the work time as break time.  For a more detailed explanation,
+;; see
+;; https://www.lesswrong.com/posts/RWu8eZqbwgB9zaerh/third-time-a-better-way-to-work
+
+;; For information on usage and customization, see https://tildegit.org/contrapunctus/chronometrist-goal/src/branch/production/README.md
+
+;;; Code:
+(require 'chronometrist)
+(require 'alert)
+
+;; [[file:chronometrist-third.org::*group][group:1]]
+(defgroup chronometrist-third nil
+  "Third Time support for Chronometrist."
+  :group 'chronometrist)
+;; group:1 ends here
+
+;; [[file:chronometrist-third.org::*divisor][divisor:1]]
+(defcustom chronometrist-third-divisor 3
+  "Number to determine accumulation of break time relative to work time."
+  :type 'number)
+;; divisor:1 ends here
+
+;; [[file:chronometrist-third.org::*duration-format][duration-format:1]]
+(defcustom chronometrist-third-duration-format "%H, %M and %S%z"
+  "Format string for durations, passed to `format-seconds'."
+  :type 'string)
+;; duration-format:1 ends here
+
+;; [[file:chronometrist-third.org::*break-time][break-time:1]]
+(defvar chronometrist-third-break-time 0
+  "Accumulated break time in seconds.")
+;; break-time:1 ends here
+
+;; [[file:chronometrist-third.org::*alert-functions][alert-functions:1]]
+(defcustom chronometrist-third-alert-functions '(chronometrist-third-half-alert chronometrist-third-quarter-alert chronometrist-third-break-over-alert)
+  "List of timed alerts for the Third Time system.
+
+Typically, each function in this list should call
+`chronometrist-third-run-at-time' to run another function, which
+in turn should call `alert' to notify the user.
+
+All functions in this list are started when the user clocks out,
+and stopped when they clock in."
+  :group 'chronometrist-third
+  :type 'hook)
+;; alert-functions:1 ends here
+
+;; [[file:chronometrist-third.org::*timer-list][timer-list:1]]
+(defvar chronometrist-third-timer-list nil)
+;; timer-list:1 ends here
+
+;; [[file:chronometrist-third.org::*run-at-time][run-at-time:1]]
+(defun chronometrist-third-run-at-time (time repeat function &rest args)
+  "Like `run-at-time', but store timer objects in `chronometrist-third-timer-list'."
+  (cl-pushnew (apply #'run-at-time time repeat function args) chronometrist-third-timer-list))
+;; run-at-time:1 ends here
+
+;; [[file:chronometrist-third.org::*half-alert][half-alert:1]]
+(defun chronometrist-third-half-alert ()
+  "Display an alert when half the break time is consumed."
+  (let ((half-time (/ chronometrist-third-break-time 2.0)))
+    (and (not (zerop chronometrist-third-break-time))
+         (chronometrist-third-run-at-time
+          half-time nil
+          (lambda (half-time)
+            (alert
+             (format "%s left on your break."
+                     (format-seconds chronometrist-third-duration-format half-time))))
+          half-time))))
+;; half-alert:1 ends here
+
+;; [[file:chronometrist-third.org::*quarter-alert][quarter-alert:1]]
+(defun chronometrist-third-quarter-alert ()
+  "Display an alert when 3/4ths of the break time is consumed."
+  (let ((three-fourths (* chronometrist-third-break-time 7.5)))
+    (and (not (zerop chronometrist-third-break-time))
+         (chronometrist-third-run-at-time
+          three-fourths nil
+          (lambda (three-fourths)
+            (alert
+             (format "%s left on your break."
+                     (format-seconds chronometrist-third-duration-format
+                                     (- chronometrist-third-break-time three-fourths)))))
+          three-fourths))))
+;; quarter-alert:1 ends here
+
+;; [[file:chronometrist-third.org::*break-over-alert][break-over-alert:1]]
+(defun chronometrist-third-break-over-alert ()
+  "Display an alert when break time is over."
+  (and (not (zerop chronometrist-third-break-time))
+       (chronometrist-third-run-at-time
+        chronometrist-third-break-time nil
+        (lambda () (alert (format "Break time is over!"))))))
+;; break-over-alert:1 ends here
+
+;; [[file:chronometrist-third.org::*start-alert-timers][start-alert-timers:1]]
+(defun chronometrist-third-start-alert-timers ()
+  "Run functions in `chronometrist-third-alert-functions'."
+  (mapc #'funcall chronometrist-third-alert-functions))
+;; start-alert-timers:1 ends here
+
+;; [[file:chronometrist-third.org::*stop-alert-timers][stop-alert-timers:1]]
+(defun chronometrist-third-stop-alert-timers ()
+  "Stop timers in `chronometrist-third-timer-list'."
+  (mapc (lambda (timer) (cancel-timer timer)) chronometrist-third-timer-list))
+;; stop-alert-timers:1 ends here
+
+;; [[file:chronometrist-third.org::*clock-in][clock-in:1]]
+(defun chronometrist-third-clock-in (&optional _arg)
+  "Stop alert timers and update break time."
+  (chronometrist-third-stop-alert-timers)
+  (unless (zerop chronometrist-third-break-time)
+    (-let* (((&plist :stop stop) (cl-second (chronometrist-to-list (chronometrist-active-backend))))
+            (used-break          (ts-diff (ts-now) (chronometrist-iso-to-ts stop)))
+            (used-break-string   (format-seconds chronometrist-third-duration-format used-break))
+            (new-break           (- chronometrist-third-break-time used-break))
+            (old-break           chronometrist-third-break-time))
+      (setq chronometrist-third-break-time (if (> new-break 0) new-break 0))
+      (alert
+       (if (zerop chronometrist-third-break-time)
+           (format "You have used up all %s of your break time (%s break)"
+                   (format-seconds chronometrist-third-duration-format old-break)
+                   used-break-string)
+         (format "You have used %s of your break time (%s left)"
+                 used-break-string
+                 (format-seconds chronometrist-third-duration-format chronometrist-third-break-time)))))))
+;; clock-in:1 ends here
+
+;; [[file:chronometrist-third.org::*clock-out][clock-out:1]]
+(defun chronometrist-third-clock-out (&optional _arg)
+  "Update break time based on the latest work interval.
+Run `chronometrist-third-alert-functions' to alert user when
+break time is up."
+  (let* ((latest-work-duration (chronometrist-interval (chronometrist-latest-record (chronometrist-active-backend))))
+         (break-time-increment (/ latest-work-duration chronometrist-third-divisor)))
+    (cl-incf chronometrist-third-break-time break-time-increment)
+    (alert (format "You have gained %s of break time (%s total)"
+                   (format-seconds chronometrist-third-duration-format break-time-increment)
+                   (format-seconds chronometrist-third-duration-format chronometrist-third-break-time)))
+    ;; start alert timer(s)
+    (chronometrist-third-start-alert-timers)))
+;; clock-out:1 ends here
+
+;; [[file:chronometrist-third.org::*third-minor-mode][third-minor-mode:1]]
+;;;###autoload
+(define-minor-mode chronometrist-third-minor-mode
+  nil nil nil nil
+  (cond (chronometrist-third-minor-mode
+         (add-hook 'chronometrist-after-in-functions #'chronometrist-third-clock-in)
+         (add-hook 'chronometrist-after-out-functions #'chronometrist-third-clock-out))
+        (t (remove-hook 'chronometrist-after-in-functions #'chronometrist-third-clock-in)
+           (remove-hook 'chronometrist-after-out-functions #'chronometrist-third-clock-out))))
+;; third-minor-mode:1 ends here
+
+(provide 'chronometrist-third)
+
+;;; chronometrist-third.el ends here

elisp/chronometrist-third.org

@@ -0,0 +1,213 @@
+#+TITLE: chronometrist-third
+#+SUBTITLE: Third Time System extension for Chronometrist
+#+PROPERTY: header-args :tangle yes :load yes :comments link
+
+* Program source
+** Library headers and commentary
+#+BEGIN_SRC emacs-lisp :comments no
+;;; chronometrist-third.el --- Third Time support for Chronometrist -*- lexical-binding: t; -*-
+
+;; Author: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Maintainer: contrapunctus <xmpp:contrapunctus@jabjab.de>
+;; Keywords: calendar
+;; Homepage: https://tildegit.org/contrapunctus/chronometrist
+;; Package-Requires: ((emacs "25.1") (alert "1.2") (chronometrist "0.6.0"))
+;; Version: 0.0.1
+
+;; This is free and unencumbered software released into the public domain.
+;;
+;; Anyone is free to copy, modify, publish, use, compile, sell, or
+;; distribute this software, either in source code form or as a compiled
+;; binary, for any purpose, commercial or non-commercial, and by any
+;; means.
+;;
+;; For more information, please refer to <https://unlicense.org>
+
+;;; Commentary:
+;; Add support for the Third Time system to Chronometrist.  In Third
+;; Time, you work for any length of time you like, and "earn" a third
+;; of the work time as break time.  For a more detailed explanation,
+;; see
+;; https://www.lesswrong.com/posts/RWu8eZqbwgB9zaerh/third-time-a-better-way-to-work
+
+;; For information on usage and customization, see https://tildegit.org/contrapunctus/chronometrist-goal/src/branch/production/README.md
+#+END_SRC
+
+** Dependencies
+#+BEGIN_SRC emacs-lisp :comments no
+;;; Code:
+(require 'chronometrist)
+(require 'alert)
+#+END_SRC
+
+** group                                                      :custom:group:
+#+BEGIN_SRC emacs-lisp
+(defgroup chronometrist-third nil
+  "Third Time support for Chronometrist."
+  :group 'chronometrist)
+#+END_SRC
+
+** divisor                                                 :custom:variable:
+#+BEGIN_SRC emacs-lisp
+(defcustom chronometrist-third-divisor 3
+  "Number to determine accumulation of break time relative to work time."
+  :type 'number)
+#+END_SRC
+
+** duration-format                                         :custom:variable:
+#+BEGIN_SRC emacs-lisp
+(defcustom chronometrist-third-duration-format "%H, %M and %S%z"
+  "Format string for durations, passed to `format-seconds'."
+  :type 'string)
+#+END_SRC
+
+** break-time                                                     :variable:
+#+BEGIN_SRC emacs-lisp
+(defvar chronometrist-third-break-time 0
+  "Accumulated break time in seconds.")
+#+END_SRC
+
+** alert-functions                                         :custom:variable:
+#+BEGIN_SRC emacs-lisp
+(defcustom chronometrist-third-alert-functions '(chronometrist-third-half-alert chronometrist-third-quarter-alert chronometrist-third-break-over-alert)
+  "List of timed alerts for the Third Time system.
+
+Typically, each function in this list should call
+`chronometrist-third-run-at-time' to run another function, which
+in turn should call `alert' to notify the user.
+
+All functions in this list are started when the user clocks out,
+and stopped when they clock in."
+  :group 'chronometrist-third
+  :type 'hook)
+#+END_SRC
+
+** timer-list                                                     :variable:
+#+BEGIN_SRC emacs-lisp
+(defvar chronometrist-third-timer-list nil)
+#+END_SRC
+
+** run-at-time                                                   :procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-run-at-time (time repeat function &rest args)
+  "Like `run-at-time', but store timer objects in `chronometrist-third-timer-list'."
+  (cl-pushnew (apply #'run-at-time time repeat function args) chronometrist-third-timer-list))
+#+END_SRC
+
+** half-alert                                                    :procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-half-alert ()
+  "Display an alert when half the break time is consumed."
+  (let ((half-time (/ chronometrist-third-break-time 2.0)))
+    (and (not (zerop chronometrist-third-break-time))
+         (chronometrist-third-run-at-time
+          half-time nil
+          (lambda (half-time)
+            (alert
+             (format "%s left on your break."
+                     (format-seconds chronometrist-third-duration-format half-time))))
+          half-time))))
+#+END_SRC
+
+** quarter-alert                                                 :procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-quarter-alert ()
+  "Display an alert when 3/4ths of the break time is consumed."
+  (let ((three-fourths (* chronometrist-third-break-time 7.5)))
+    (and (not (zerop chronometrist-third-break-time))
+         (chronometrist-third-run-at-time
+          three-fourths nil
+          (lambda (three-fourths)
+            (alert
+             (format "%s left on your break."
+                     (format-seconds chronometrist-third-duration-format
+                                     (- chronometrist-third-break-time three-fourths)))))
+          three-fourths))))
+#+END_SRC
+
+** break-over-alert                                              :procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-break-over-alert ()
+  "Display an alert when break time is over."
+  (and (not (zerop chronometrist-third-break-time))
+       (chronometrist-third-run-at-time
+        chronometrist-third-break-time nil
+        (lambda () (alert (format "Break time is over!"))))))
+#+END_SRC
+
+** start-alert-timers                                            :procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-start-alert-timers ()
+  "Run functions in `chronometrist-third-alert-functions'."
+  (mapc #'funcall chronometrist-third-alert-functions))
+#+END_SRC
+
+** stop-alert-timers                                             :procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-stop-alert-timers ()
+  "Stop timers in `chronometrist-third-timer-list'."
+  (mapc (lambda (timer) (cancel-timer timer)) chronometrist-third-timer-list))
+#+END_SRC
+
+** clock-in                                                 :hook:procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-clock-in (&optional _arg)
+  "Stop alert timers and update break time."
+  (chronometrist-third-stop-alert-timers)
+  (unless (zerop chronometrist-third-break-time)
+    (-let* (((&plist :stop stop) (cl-second (chronometrist-to-list (chronometrist-active-backend))))
+            (used-break          (ts-diff (ts-now) (chronometrist-iso-to-ts stop)))
+            (used-break-string   (format-seconds chronometrist-third-duration-format used-break))
+            (new-break           (- chronometrist-third-break-time used-break))
+            (old-break           chronometrist-third-break-time))
+      (setq chronometrist-third-break-time (if (> new-break 0) new-break 0))
+      (alert
+       (if (zerop chronometrist-third-break-time)
+           (format "You have used up all %s of your break time (%s break)"
+                   (format-seconds chronometrist-third-duration-format old-break)
+                   used-break-string)
+         (format "You have used %s of your break time (%s left)"
+                 used-break-string
+                 (format-seconds chronometrist-third-duration-format chronometrist-third-break-time)))))))
+#+END_SRC
+
+** clock-out                                                :hook:procedure:
+#+BEGIN_SRC emacs-lisp
+(defun chronometrist-third-clock-out (&optional _arg)
+  "Update break time based on the latest work interval.
+Run `chronometrist-third-alert-functions' to alert user when
+break time is up."
+  (let* ((latest-work-duration (chronometrist-interval (chronometrist-latest-record (chronometrist-active-backend))))
+         (break-time-increment (/ latest-work-duration chronometrist-third-divisor)))
+    (cl-incf chronometrist-third-break-time break-time-increment)
+    (alert (format "You have gained %s of break time (%s total)"
+                   (format-seconds chronometrist-third-duration-format break-time-increment)
+                   (format-seconds chronometrist-third-duration-format chronometrist-third-break-time)))
+    ;; start alert timer(s)
+    (chronometrist-third-start-alert-timers)))
+#+END_SRC
+
+** third-minor-mode                                             :minor:mode:
+#+BEGIN_SRC emacs-lisp
+;;;###autoload
+(define-minor-mode chronometrist-third-minor-mode
+  nil nil nil nil
+  (cond (chronometrist-third-minor-mode
+         (add-hook 'chronometrist-after-in-functions #'chronometrist-third-clock-in)
+         (add-hook 'chronometrist-after-out-functions #'chronometrist-third-clock-out))
+        (t (remove-hook 'chronometrist-after-in-functions #'chronometrist-third-clock-in)
+           (remove-hook 'chronometrist-after-out-functions #'chronometrist-third-clock-out))))
+#+END_SRC
+
+** Provide
+#+BEGIN_SRC emacs-lisp :comments no
+(provide 'chronometrist-third)
+
+;;; chronometrist-third.el ends here
+#+END_SRC
+
+* Local variables                                                  :noexport:
+# Local Variables:
+# my-org-src-default-lang: "emacs-lisp"
+# eval: (when (package-installed-p 'literate-elisp) (require 'literate-elisp) (literate-elisp-load (buffer-file-name)))
+# End:

manual.org

@@ -1,92 +1,201 @@
-#+TITLE: Chronometrist - an extensible time tracker for Emacs
-#+SUBTITLE: User Manual
+#+TITLE: Chronometrist
+#+SUBTITLE: Friendly and powerful personal time tracker/analyzer with Emacs and CLIM frontends
+#+DESCRIPTION: User Manual
 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />
 
-[[https://melpa.org/#/chronometrist][file:https://melpa.org/packages/chronometrist-badge.svg]]
+#+BEGIN_EXPORT html
+<a href="https://liberapay.com/contrapunctus/donate">
+  <img alt="Donate using Liberapay" src="https://img.shields.io/liberapay/receives/contrapunctus.svg?logo=liberapay">
+</a>
 
-A time tracker in Emacs with a nice interface
+<a href="https://melpa.org/#/chronometrist">
+  <img src="https://melpa.org/packages/chronometrist-badge.svg">
+</a>
+#+END_EXPORT
 
-Largely modelled after the Android application, [[https://github.com/netmackan/ATimeTracker][A Time Tracker]]
+* Explanation
+:PROPERTIES:
+:CUSTOM_ID: explanation
+:END:
+Chronometrist is a friendly and powerful personal time tracker and analyzer. It has frontends for Emacs and [[https://mcclim.common-lisp.dev/][CLIM]].
 
-* Benefits
+#+CAPTION: The main Chronometrist buffer, with the enabled extensions [[#time-goals][chronometrist-goal]] ("Targets" column + alerts) and chronometrist-spark ("Graph" column displaying the activity for the past 4 weeks).
+[[file:doc/2022-02-20 13-26-53.png]]
+
+** Benefits
+:PROPERTIES:
+:CUSTOM_ID: benefits
+:END:
 1. Extremely simple and efficient to use
-2. Displays useful information about your time usage
+2. Displays useful information about your time usage (including fancy graphs with the =chronometrist-spark= extension)
 3. Support for both mouse and keyboard
-4. Human errors in tracking are easily fixed by editing a plain text file
-5. Hooks to let you perform arbitrary actions when starting/stopping tasks
+4. Human errors in tracking can be easily fixed by editing a plain text file
+5. Hooks to integrate time tracking into your workflow
 
-* Limitations
-1. No support (yet) for adding a task without clocking into it.
-2. No support for concurrent tasks.
+** Limitations
+:PROPERTIES:
+:CUSTOM_ID: limitations
+:END:
+1. No support for concurrent tasks.
 
-* Comparisons
+** Comparisons
 :PROPERTIES:
 :CUSTOM_ID: comparisons
 :END:
-** timeclock.el
+*** timeclock.el (Emacs built-in)
 :PROPERTIES:
 :CUSTOM_ID: timeclock.el
 :END:
-
 Compared to timeclock.el, Chronometrist
 + stores data in an s-expression format rather than a line-based one
 + supports attaching tags and arbitrary key-values to time intervals
 + has commands to shows useful summaries
 + has more hooks
 
-** Org time tracking
+*** Org time tracking
 :PROPERTIES:
 :CUSTOM_ID: org-time-tracking
 :END:
-
 Chronometrist and Org time tracking seem to be equivalent in terms of capabilities, approaching the same ends through different means.
 + Chronometrist doesn't have a mode line indicator at the moment. (planned)
 + Chronometrist doesn't have Org's sophisticated querying facilities. (an SQLite backend is planned)
 + Org does so many things that keybindings seem to necessarily get longer. Chronometrist has far fewer commands than Org, so most of the keybindings are single keys, without modifiers.
-+ Chronometrist's UI makes keybindings discoverable - they are displayed in the buffers themselves.
 + Chronometrist's UI is cleaner, since the storage is separate from the display. It doesn't show tasks as trees like Org, but it uses tags and key-values to achieve that. Additionally, navigating a flat list takes fewer user operations than navigating a tree.
 + Chronometrist data is just s-expressions (plists), and may be easier to parse than a complex text format with numerous use-cases.
 
-* Installation
+** Common Lisp port
+:PROPERTIES:
+:CUSTOM_ID: common-lisp-port
+:END:
+In March 2022, work began on the long-awaited Common Lisp port of Chronometrist, which aims to create -
+1. a greater variety of backends (e.g. SQLite)
+2. a common reusable library for frontends to use,
+3. a greater variety of frontends, such as -
+   * a command line interface (CLI), for UNIX scripting;
+   * a terminal user inteface (TUI), for those so inclined;
+   * a CLIM (Common Lisp Interface Manager) GUI [fn:1],
+   * Qt and Android interfaces using [[https://gitlab.com/eql/lqml][LQML]],
+   * web frontends (possibly via [[https://common-lisp.net/project/parenscript/][Parenscript]] or [[https://github.com/rabbibotton/clog][CLOG]]),
+   * and perhaps even an interface for wearable devices!
+
+The port was also driven by the desire to have access to Common Lisp's better performance, and features such as namespaces, a /de facto/ standard build system, multithreading, SQLite bindings, a more fully-featured implementation of CLOS and MOP, and type annotations, checking, and inference.
+
+The literate sources for the Common Lisp port may be found in [[file:cl/chronometrist.org][cl/chronometrist.org]]. Currently, this port can -
+1. import from a plist-group file and export to an SQLite database
+   #+BEGIN_SRC lisp
+   (chronometrist:to-file (chronometrist:to-hash-table
+                           (make-instance 'chronometrist.plist-group:plist-group-backend
+                                          :file "/path/to/file.plg"))
+                          (make-instance 'chronometrist.sqlite:sqlite-backend)
+                          "/path/to/file.sqlite")
+   #+END_SRC
+2. display a (WIP) CLIM GUI - =(chronometrist.clim:run-chronometrist)=
+
+The Emacs Lisp codebase will probably become an Emacs frontend to a future Common Lisp CLI client.
+
+[fn:1] McCLIM also has an incomplete ncurses backend - when completed, a CLIM frontend could provide a TUI "for free".
+
+** Literate program
+:PROPERTIES:
+:CUSTOM_ID: explanation-literate-program
+:END:
+Chronometrist is written as an Org literate program, which makes it easy to obtain different views of the program source, thanks to tree- and source-block folding, tags, properties, and the =org-match= command.
+
+The canonical source file is [[file:elisp/chronometrist.org][elisp/chronometrist.org]], which contains source blocks. These are provided to users after /tangling/ (extracting the source into an Emacs Lisp file). [fn:2]
+
+The Org literate program can also be loaded directly using the [[https://github.com/jingtaozf/literate-elisp][literate-elisp]] package, so that all source links (e.g. =xref=, =describe-function=) lead to the Org file. See [[#how-to-literate-elisp][How to load the program using literate-elisp]].
+
+[fn:2] the literate source is also included in MELPA installs, although not loaded through =literate-elisp-load= by default, since doing so would interfere with automatic generation of autoloads.
+
+** Source code overview
+:PROPERTIES:
+:CUSTOM_ID: source-code-overview
+:END:
+At its most basic, we read data from a [[file:elisp/chronometrist.org::#program-backend][backend]] and [[file:elisp/chronometrist.org::#program-frontend-chronometrist][display it]] as a [[elisp:(find-library "tabulated-list")][=tabulated-list-mode=]] buffer.
+
+The plist and plist-group backends (collectively known as the s-expression backends) =read= a text file containing s-expressions into a [[file:elisp/chronometrist.org::#program-data-structures][hash table]], and query that. When the file is changed—whether by the program or the user—they [[file:elisp/chronometrist.org::refresh-file][update the hash table]] and the [[file:elisp/chronometrist.org::#program-frontend-chronometrist-refresh][buffer]]. The s-expression backends also make use of a [[file:elisp/chronometrist.org::#program-pretty-printer][plist pretty-printer]] of their own.
+
+There are also some [[file:elisp/chronometrist.org::#program-migration][migration commands]].
+
+Extensions exist for -
+1. [[file:elisp/chronometrist-key-values.org][attaching arbitrary metadata]] to time intervals,
+2. [[https://tildegit.org/contrapunctus/chronometrist-goal][time goals and alerts]], and
+3. support for the [[file:elisp/chronometrist-third.org][Third Time system]]
+
+** Contributions and contact
+:PROPERTIES:
+:CUSTOM_ID: contributions-contact
+:END:
+Feedback and MRs are very welcome. 🙂
++ [[file:TODO.org]] has a long list of tasks
++ [[file:elisp/chronometrist.org]] contains all developer-oriented documentation
+
+If you have tried using Chronometrist, I'd love to hear your experiences! Get in touch with the author and other Emacs users in the Emacs channel on the Jabber network - [[https://conversations.im/j/emacs@salas.suchat.org][xmpp:emacs@salas.suchat.org?join]] ([[https://inverse.chat/#converse/room?jid=emacs@salas.suchat.org][web chat]])
+
+(For help in getting started with Jabber, [[https://xmpp.org/getting-started/][click here]])
+
+** License
+:PROPERTIES:
+:CUSTOM_ID: license
+:END:
+I'd /like/ for all software to be liberated - transparent, trustable, and accessible for anyone to use, study, or improve.
+
+I'd /like/ anyone using my software to credit me for the work.
+
+I'd /like/ to receive financial support for my efforts, so I can spend all my time doing what I find meaningful.
+
+But I don't want to make demands or threats (e.g. via legal conditions) to accomplish all that, nor restrict my services to only those who can pay.
+
+Thus, Chronometrist is released under your choice of [[https://unlicense.org/][Unlicense]] or the [[http://www.wtfpl.net/][WTFPL]].
+
+(See files [[file:UNLICENSE][UNLICENSE]] and [[file:WTFPL][WTFPL]]).
+
+** Thanks
+:PROPERTIES:
+:CUSTOM_ID: thanks
+:END:
+The main buffer and the report buffer are copied from the Android application, [[https://github.com/netmackan/ATimeTracker][A Time Tracker]]
+
+wasamasa, bpalmer, aidalgol, pjb and the rest of #emacs for their tireless help and support
+
+jwiegley for =timeclock.el=, which we used as a backend in earlier versions
+
+blandest for helping me with the name
+
+fiete and wu-lee for testing and bug reports
+
+* Tutorials
+:PROPERTIES:
+:CUSTOM_ID: usage
+:END:
+** Installation
 :PROPERTIES:
 :CUSTOM_ID: installation
 :END:
-** from MELPA
+*** from MELPA
 :PROPERTIES:
 :CUSTOM_ID: install-from-melpa
 :END:
-
 1. Set up MELPA - https://melpa.org/#/getting-started
-
-   (Chronometrist uses semantic versioning and only releases are pushed to the master branch, so using MELPA Stable is recommended and has no effect on frequency of updates.)
 2. =M-x package-install RET chronometrist RET=
 
-** from Git
+*** from Git
 :PROPERTIES:
 :CUSTOM_ID: install-from-git
 :END:
-
-You can get =chronometrist= from https://tildegit.org/contrapunctus/chronometrist
+You can get =chronometrist= from https://tildegit.org/contrapunctus/chronometrist or https://codeberg.org/contrapunctus/chronometrist
 
 =chronometrist= requires
 + Emacs v25 or higher
 + [[https://github.com/magnars/dash.el][dash.el]]
 + [[https://github.com/alphapapa/ts.el][ts.el]]
 
-The optional extension =chronometrist-key-values= requires =choice.el=, apart from =chronometrist= itself.
-
-Add the "elisp/" subdirectory to your load-path, and =(require 'chronometrist)=.
-
-* Usage
-:PROPERTIES:
-:CUSTOM_ID: usage
-:END:
+Add the ="elisp/"= subdirectory to your load-path, and =(require 'chronometrist)=.
 
 ** chronometrist
 :PROPERTIES:
-:CUSTOM_ID: chronometrist-1
+:CUSTOM_ID: usage-chronometrist
 :END:
-
 Run =M-x chronometrist= to see your projects, the time you spent on them today, which one is active, and the total time clocked today.
 
 Click or hit =RET= (=chronometrist-toggle-task=) on a project to start tracking time for it. If it's already clocked in, it will be clocked out.
@@ -97,25 +206,29 @@ Press =r= to see a weekly report (see =chronometrist-report=)
 
 ** chronometrist-report
 :PROPERTIES:
-:CUSTOM_ID: chronometrist-report
+:CUSTOM_ID: usage-chronometrist-report
 :END:
-
 Run =M-x chronometrist-report= (or =chronometrist= with a prefix argument of 1, or press =r= in the =chronometrist= buffer) to see a weekly report.
 
 Press =b= to look at past weeks, and =f= for future weeks.
 
 ** chronometrist-statistics
 :PROPERTIES:
-:CUSTOM_ID: chronometrist-statistics
+:CUSTOM_ID: usage-chronometrist-statistics
 :END:
-
 Run =M-x chronometrist-statistics= (or =chronometrist= with a prefix argument of 2) to view statistics.
 
 Press =b= to look at past time ranges, and =f= for future ones.
 
 ** chronometrist-details
+:PROPERTIES:
+:CUSTOM_ID: chronometrist-details
+:END:
 
 ** common commands
+:PROPERTIES:
+:CUSTOM_ID: usage-common-commands
+:END:
 In the buffers created by the previous three commands, you can press =l= (=chronometrist-open-log=) to view/edit your =chronometrist-file=, which by default is =~/.emacs.d/chronometrist.sexp=.
 
 All of these commands will kill their buffer when run again with the buffer visible, so the keys you bind them to behave as a toggle.
@@ -124,23 +237,21 @@ All buffers keep themselves updated via an idle timer - no need to frequently pr
 
 ** Time goals/targets
 :PROPERTIES:
-:CUSTOM_ID: time-goalstargets
+:CUSTOM_ID: time-goals
 :END:
 
 If you wish you could define time goals for some tasks, and have Chronometrist notify you when you're approaching the goal, completing it, or exceeding it, check out the extension [[https://github.com/contrapunctus-1/chronometrist-goal/][chronometrist-goal.el]].
 
-* How-to
+* How-to Guides
 :PROPERTIES:
-:CUSTOM_ID: customization
+:CUSTOM_ID: how-to
 :END:
-
 See the Customize groups =chronometrist= and =chronometrist-report= for variables intended to be user-customizable.
 
 ** How to display a prompt when exiting with an active task
 :PROPERTIES:
-:CUSTOM_ID: prompt-when-exiting-emacs
+:CUSTOM_ID: how-to-prompt-when-exiting-emacs
 :END:
-
 Evaluate or add to your init.el the following -
 =(add-hook 'kill-emacs-query-functions 'chronometrist-query-stop)=
 
@@ -148,7 +259,9 @@ Evaluate or add to your init.el the following -
 :PROPERTIES:
 :CUSTOM_ID: how-to-literate-elisp
 :END:
+The literate Org document will automatically =literate-elisp-load= itself when opened, if =literate-elisp= is installed via =package.el=.
 
+If you want it to be loaded with =literate-elisp-load= on Emacs startup, add the following to your init.el -
 #+BEGIN_SRC emacs-lisp
 (add-to-list 'load-path "<directory containing chronometrist.org>")
 
@@ -160,8 +273,7 @@ Evaluate or add to your init.el the following -
 :PROPERTIES:
 :CUSTOM_ID: how-to-tags
 :END:
-
-1. Add =chronometrist-tags-add= to one or more of these hooks [fn:1] -
+1. Add =chronometrist-tags-add= to one or more of these hooks [fn:3] -
 
    #+BEGIN_SRC emacs-lisp
    (add-to-list 'chronometrist-after-in-functions 'chronometrist-tags-add)
@@ -172,33 +284,32 @@ Evaluate or add to your init.el the following -
 
    The prompt suggests past combinations you used for the current task, which you can browse with =M-p=/=M-n=. You can leave it blank by pressing =RET=.
 
-[fn:1] but not =chronometrist-before-in-functions=
+[fn:3] but not =chronometrist-before-in-functions=
 
 ** How to attach key-values to time intervals
 :PROPERTIES:
 :CUSTOM_ID: how-to-key-value-pairs
 :END:
+1. Add =chronometrist-kv-add= to one or more of these hooks [fn:3] -
 
-1. Add =chronometrist-kv-add= to one or more of these hooks [fn:2] -
-
-#+BEGIN_SRC emacs-lisp
+   #+BEGIN_SRC emacs-lisp
 (add-to-list 'chronometrist-after-in-functions 'chronometrist-kv-add)
 (add-to-list 'chronometrist-before-out-functions 'chronometrist-kv-add)
 (add-to-list 'chronometrist-after-out-functions 'chronometrist-kv-add)
-#+END_SRC
+   #+END_SRC
 
 To exit the prompt, press the key it indicates for quitting - you can then edit the resulting key-values by hand if required. Press =C-c C-c= to accept the key-values, or =C-c C-k= to cancel.
 
-[fn:2] but not =chronometrist-before-in-functions=
-
 ** How to skip running hooks/attaching tags and key values
+:PROPERTIES:
+:CUSTOM_ID: how-to-skip-running-hooks/attaching-tags-and-key-values
+:END:
 Use =M-RET= (=chronometrist-toggle-task-no-hooks=) to clock in/out.
 
 ** How to open certain files when you start a task
 :PROPERTIES:
-:CUSTOM_ID: open-certain-files-when-you-start-a-task
+:CUSTOM_ID: how-to-open-files-on-task-start
 :END:
-
 An idea from the author's own init -
 
 #+BEGIN_SRC emacs-lisp
@@ -214,9 +325,8 @@ An idea from the author's own init -
 
 ** How to warn yourself about uncommitted changes
 :PROPERTIES:
-:CUSTOM_ID: uncommitted-changes
+:CUSTOM_ID: how-to-warn-uncommitted-changes
 :END:
-
 Another one, prompting the user if they have uncommitted changes in a git repository (assuming they use [[https://magit.vc/][Magit]]) -
 
 #+BEGIN_SRC emacs-lisp
@@ -239,34 +349,65 @@ Return nil (and run `magit-status') if the user answers no."
 
 ** How to display the current time interval in the activity indicator
 :PROPERTIES:
-:CUSTOM_ID: current-time-interval-in-activity-indicator
+:CUSTOM_ID: how-to-activity-indicator
 :END:
-
 #+BEGIN_SRC emacs-lisp
 (defun my-activity-indicator ()
-  (thread-last (plist-put (chronometrist-last)
-                          :stop (chronometrist-format-time-iso8601))
-    list
-    chronometrist-events-to-durations
-    (-reduce #'+)
-    truncate
-    chronometrist-format-time))
+  (--> (chronometrist-latest-record (chronometrist-active-backend))
+       (plist-put it :stop (chronometrist-format-time-iso8601))
+       (list it)
+       (chronometrist-events-to-durations it)
+       (-reduce #'+ it)
+       (truncate it)
+       (chronometrist-format-duration it)))
 
 (setq chronometrist-activity-indicator #'my-activity-indicator)
 #+END_SRC
 
-* Explanation
-** Literate Program
+** How to back up your Chronometrist data
 :PROPERTIES:
-:CUSTOM_ID: explanation-literate-program
+:CUSTOM_ID: how-to-backup
 :END:
-Chronometrist is a literate program, made using Org - the canonical source is the =chronometrist.org= file, which contains source blocks. These are provided to users after /tangling/ (extracting the source into an Emacs Lisp file).
+I suggest backing up Chronometrist data on each save using the [[https://tildegit.org/contrapunctus/async-backup][async-backup]] package.[fn:4] Here's how you can do that.
 
-The Org file can also be loaded directly using the   [[https://github.com/jingtaozf/literate-elisp][literate-elisp]] package, so that all source links (e.g. =xref=, =describe-function=) lead to the Org file, within the context of the concerned documentation. See [[#how-to-literate-elisp][How to load the program using literate-elisp]].
+1. Add the following to your init.
+   #+BEGIN_SRC emacs-lisp
+(use-package async-backup)
+   #+END_SRC
+2. Open your Chronometrist file and add =async-backup= to a buffer-local =after-save-hook=.
+   : M-x chronometrist-open-log
+   : M-x add-file-local-variable-prop-line RET eval RET (add-hook 'after-save-hook #'async-backup nil t) RET
+3. Optionally, configure =async-backup-location= to set a specific directory for the backups -
+   : (setq async-backup-location "/path/to/backup/dir/")
 
-=chronometrist.org= is also included in MELPA installs, although not used directly by default, since doing so would interfere with automatic generation of autoloads.
+[fn:4] It is possible to use Emacs' built-in backup system to do it, but since it is synchronous, doing so will greatly slow down saving of the Chronometrist file.
+
+** How to configure Vertico for use with Chronometrist
+:PROPERTIES:
+:CUSTOM_ID: howto-vertico
+:END:
+By default, [[https://github.com/minad/vertico][Vertico]] uses its own sorting function - for some commands (such as =chronometrist-key-values-unified-prompt=) this results in /worse/ suggestions, since Chronometrist sorts suggestions in most-recent-first order.
+
+You can either disable Vertico's sorting entirely -
+#+BEGIN_SRC emacs-lisp
+(setq vertico-sort-function nil)
+#+END_SRC
+
+Or use =vertico-multiform= to disable sorting for only specific commands -
+#+BEGIN_SRC emacs-lisp
+(use-package vertico-multiform
+  :init (vertico-multiform-mode)
+  :config
+  (setq vertico-multiform-commands
+        '((chronometrist-toggle-task          (vertico-sort-function . nil))
+          (chronometrist-toggle-task-no-hooks (vertico-sort-function . nil))
+          (chronometrist-key-values-unified-prompt      (vertico-sort-function . nil)))))
+#+END_SRC
 
 * User's reference
+:PROPERTIES:
+:CUSTOM_ID: users-reference
+:END:
 All variables intended for user customization are listed here. They serve as the public API for this project for the purpose of semantic versioning. Any changes to these which require a user to modify their configuration are considered breaking changes.
 
 1. =chronometrist-file=
@@ -293,41 +434,10 @@ Hooks
 8. =chronometrist-file-change-hook=
 9. =chronometrist-timer-hook=
 
-* Contributions and contact
+* Local variables                                                  :noexport:
 :PROPERTIES:
-:CUSTOM_ID: contributions-and-contact
+:CUSTOM_ID: local-variables
 :END:
-
-Feedback and MRs are very welcome. 🙂
-+ [[file:TODO.org]] has a long list of tasks
-+ [[file:doc/manual.org]] contains an overview of the codebase, explains various mechanisms and decisions, and has a reference of definitions.
-
-If you have tried using Chronometrist, I'd love to hear your experiences! Get in touch with the author and other Emacs users in the Emacs channel on the Jabber network - [[https://conversations.im/j/emacs@salas.suchat.org][xmpp:emacs@salas.suchat.org?join]] ([[https://inverse.chat/#converse/room?jid=emacs@salas.suchat.org][web chat]])
-
-(For help in getting started with Jabber, [[https://xmpp.org/getting-started/][click here]])
-
-* License
-:PROPERTIES:
-:CUSTOM_ID: license
-:END:
-
-I dream of a world where all software is liberated - transparent, trustable, and accessible for anyone to use or improve. But I don't want to make demands or threats (e.g. via legal conditions) to get there.
-
-I'd rather make a request - please do everything you can to help that dream come true. Please Unlicense as much software as you can.
-
-Chronometrist is released under your choice of [[https://unlicense.org/][Unlicense]] or the [[http://www.wtfpl.net/][WTFPL]].
-
-(See files [[file:UNLICENSE]] and [[file:WTFPL]]).
-
-* Thanks
-:PROPERTIES:
-:CUSTOM_ID: thanks
-:END:
-
-wasamasa, bpalmer, aidalgol, pjb and the rest of #emacs for their tireless help and support
-
-jwiegley for timeclock.el, which we used as a backend in earlier versions
-
-blandest for helping me with the name
-
-fiete and wu-lee for testing and bug reports
+# Local Variables:
+# my-org-src-default-lang: "emacs-lisp"
+# End:

tests/chronometrist-tests.org

@@ -0,0 +1,488 @@
+#+PROPERTY: header-args :tangle yes :load yes :comments link
+#+BEGIN_SRC emacs-lisp :load no :tangle no
+(setq nameless-current-name "chronometrist")
+#+END_SRC
+
+* Setup
+** test-file-path-stem
+#+BEGIN_SRC emacs-lisp
+(defvar chronometrist-test-file-path-stem
+  (format "%stest" (file-name-directory (or load-file-name default-directory))))
+#+END_SRC
+
+** test-backends
+=chronometrist-test-backend= is just here till I finish writing the tests for a single backend. Will tackle how to apply the same tests to different backends afterwards - possibly with a [[#chronometrist-ert-deftest][wrapper macro]] around =ert-deftest=.
+
+#+BEGIN_SRC emacs-lisp
+(defvar chronometrist-test-backend
+  (make-instance 'chronometrist-plist-group-backend :path chronometrist-test-file-path-stem))
+
+(defun chronometrist-make-test-backends ()
+  (cl-loop for backend in '(chronometrist-plist-backend chronometrist-plist-group-backend)
+    collect (make-instance backend :path chronometrist-test-file-path-stem)))
+
+(defvar chronometrist-test-backends (chronometrist-make-test-backends))
+#+END_SRC
+
+** test-first-record
+#+BEGIN_SRC emacs-lisp
+(defvar chronometrist-test-first-record
+  '(:name  "Programming"
+    :start "2018-01-01T00:00:00+0530"
+    :stop  "2018-01-01T01:00:00+0530"))
+#+END_SRC
+
+** test-latest-record
+#+BEGIN_SRC emacs-lisp
+(defvar chronometrist-test-latest-record
+  '(:name  "Programming"
+    :tags  (reading)
+    :book  "Smalltalk-80: The Language and Its Implementation"
+    :start "2020-05-10T16:33:17+0530"
+    :stop  "2020-05-10T17:10:48+0530"))
+#+END_SRC
+
+** test-records
+#+BEGIN_SRC emacs-lisp
+(defvar chronometrist-test-records
+  '((:name "Programming"
+     :start "2018-01-01T00:00:00+0530"
+     :stop  "2018-01-01T01:00:00+0530")
+    (:name "Swimming"
+     :start "2018-01-01T02:00:00+0530"
+     :stop  "2018-01-01T03:00:00+0530")
+    (:name "Cooking"
+     :start "2018-01-01T04:00:00+0530"
+     :stop  "2018-01-01T05:00:00+0530")
+    (:name "Guitar"
+     :start "2018-01-01T06:00:00+0530"
+     :stop  "2018-01-01T07:00:00+0530")
+    (:name "Cycling"
+     :start "2018-01-01T08:00:00+0530"
+     :stop  "2018-01-01T09:00:00+0530")
+    (:name "Programming"
+     :start "2018-01-02T23:00:00+0530"
+     :stop  "2018-01-03T01:00:00+0530")
+    (:name "Cooking"
+     :start "2018-01-03T23:00:00+0530"
+     :stop  "2018-01-04T01:00:00+0530")
+    (:name      "Programming"
+     :tags      (bug-hunting)
+     :project   "Chronometrist"
+     :component "goals"
+     :start     "2020-05-09T20:03:25+0530"
+     :stop      "2020-05-09T20:05:55+0530")
+    (:name     "Arrangement/new edition"
+     :tags     (new edition)
+     :song     "Songs of Travel"
+     :composer "Vaughan Williams, Ralph"
+     :start    "2020-05-10T00:04:14+0530"
+     :stop     "2020-05-10T00:25:48+0530")
+    (:name  "Guitar"
+     :tags  (classical warm-up)
+     :start "2020-05-10T15:41:14+0530"
+     :stop  "2020-05-10T15:55:42+0530")
+    (:name  "Guitar"
+     :tags  (classical solo)
+     :start "2020-05-10T16:00:00+0530"
+     :stop  "2020-05-10T16:30:00+0530")
+    (:name  "Programming"
+     :tags  (reading)
+     :book  "Smalltalk-80: The Language and Its Implementation"
+     :start "2020-05-10T16:33:17+0530"
+     :stop  "2020-05-10T17:10:48+0530")))
+#+END_SRC
+
+** cleanup
+#+BEGIN_SRC emacs-lisp
+(cl-defgeneric chronometrist-backend-test-cleanup (backend)
+  "Delete any files created by BACKEND during testing.")
+
+(cl-defmethod chronometrist-backend-test-cleanup ((backend chronometrist-elisp-sexp-backend))
+  (with-slots (file hash-table) backend
+    (when file
+      (when (file-exists-p file)
+        (delete-file file))
+      (with-current-buffer (get-file-buffer file)
+        ;; (erase-buffer)
+        ;; Unsuccessful attempt to inhibit "Delete excess backup versions of <file>?" prompts
+        (defvar delete-old-versions)
+        (let ((delete-old-versions t))
+          (set-buffer-modified-p nil)
+          (kill-buffer))))
+    (setf hash-table (clrhash hash-table))))
+
+(cl-defmethod chronometrist-backend-test-cleanup :after ((backend t))
+  (setf chronometrist-test-backends (chronometrist-make-test-backends)))
+#+END_SRC
+
+** ert-deftest                                                       :macro:
+:PROPERTIES:
+:CUSTOM_ID: chronometrist-ert-deftest
+:END:
+#+BEGIN_SRC emacs-lisp
+(defmacro chronometrist-ert-deftest (name backend-var &rest test-forms)
+  "Generate test groups containing TEST-FORMS for each backend.
+BACKEND-VAR is bound to each backend in
+`chronometrist-test-backends'. TEST-FORMS are passed to
+`ert-deftest'."
+  (declare (indent defun) (debug t))
+  (cl-loop for backend in chronometrist-test-backends collect
+    (let* ((backend-name (string-remove-suffix
+                          "-backend"
+                          (string-remove-prefix "chronometrist"
+                                                (symbol-name
+                                                 (eieio-object-class-name backend)))))
+           (test-name    (concat "chronometrist-" (symbol-name name) backend-name)))
+      `(ert-deftest ,(intern test-name) ()
+         (let ((,backend-var ,backend))
+           (unwind-protect
+               (progn ,@test-forms)
+             ;; cleanup - remove test backend file
+             (chronometrist-backend-test-cleanup ,backend)))))
+    into test-groups
+    finally return (cons 'progn test-groups)))
+#+END_SRC
+
+* Tests
+** common
+*** current-task
+:PROPERTIES:
+:CUSTOM_ID: tests-common-current-task
+:END:
+#+BEGIN_SRC emacs-lisp
+(chronometrist-ert-deftest current-task b
+  ;; (message "current-task test - hash-table-count %s" (hash-table-count (chronometrist-backend-hash-table b)))
+  (chronometrist-create-file b)
+  (should (not (chronometrist-current-task b)))
+  (chronometrist-insert b (list :name "Test" :start (chronometrist-format-time-iso8601)))
+  (should (equal "Test" (chronometrist-current-task b)))
+  (chronometrist-remove-last b)
+  (should (not (chronometrist-current-task b))))
+#+END_SRC
+
+*** plist-p
+:PROPERTIES:
+:CUSTOM_ID: tests-common-plist-p
+:END:
+#+BEGIN_SRC emacs-lisp
+(ert-deftest chronometrist-plist-p ()
+  (should (eq t   (chronometrist-plist-p '(:a 1 :b 2))))
+  (should (eq nil (chronometrist-plist-p '(0 :a 1 :b 2))))
+  (should (eq nil (chronometrist-plist-p '(:a 1 :b 2 3))))
+  (should (not    (chronometrist-plist-p nil))))
+#+END_SRC
+
+*** plists-split-p
+:PROPERTIES:
+:CUSTOM_ID: tests-common-plists-split-p
+:END:
+#+BEGIN_SRC emacs-lisp
+(ert-deftest chronometrist-plists-split-p ()
+  (should
+   (chronometrist-plists-split-p
+    '(:name    "Cooking"
+               :recipe  "whole wheat penne rigate in arrabbiata sauce"
+               :start   "2021-11-30T23:01:10+0530"
+               :stop    "2021-12-01T00:00:00+0530")
+    '(:name   "Cooking"
+              :recipe "whole wheat penne rigate in arrabbiata sauce"
+              :start  "2021-12-01T00:00:00+0530"
+              :stop   "2021-12-01T00:06:22+0530")))
+  ;; without :stop
+  (should
+   (chronometrist-plists-split-p
+    '(:name    "Cooking"
+               :recipe  "whole wheat penne rigate in arrabbiata sauce"
+               :start   "2021-11-30T23:01:10+0530"
+               :stop    "2021-12-01T00:00:00+0530")
+    '(:name   "Cooking"
+              :recipe "whole wheat penne rigate in arrabbiata sauce"
+              :start  "2021-12-01T00:00:00+0530")))
+  ;; difference in time
+  (should
+   (not (chronometrist-plists-split-p
+         '(:name    "Cooking"
+                    :recipe  "whole wheat penne rigate in arrabbiata sauce"
+                    :start   "2021-11-30T23:01:10+0530"
+                    :stop    "2021-12-01T00:00:00+0530")
+         '(:name   "Cooking"
+                   :recipe "whole wheat penne rigate in arrabbiata sauce"
+                   :start  "2021-12-01T00:00:01+0530"
+                   :stop   "2021-12-01T00:06:22+0530"))))
+  ;; difference in key-values
+  (should
+   (not (chronometrist-plists-split-p
+         '(:name    "Cooking"
+                    :recipe  "whole wheat penne rigate in arrabbiata sauce"
+                    :start   "2021-11-30T23:01:10+0530"
+                    :stop    "2021-12-01T00:00:00+0530")
+         '(:name   "Cooking"
+                   :start  "2021-12-01T00:00:00+0530"
+                   :stop   "2021-12-01T00:06:22+0530")))))
+#+END_SRC
+
+** data structures
+*** list-tasks
+#+BEGIN_SRC emacs-lisp
+(chronometrist-ert-deftest list-tasks b
+  ;; (message "list-tasks test - hash-table-count %s" (hash-table-count (chronometrist-backend-hash-table b)))
+  (chronometrist-create-file b)
+  (let ((task-list (chronometrist-list-tasks b)))
+    (should (listp task-list))
+    (should (seq-every-p #'stringp task-list))))
+#+END_SRC
+
+** time functions
+*** format-duration-long                                             :pure:
+#+BEGIN_SRC emacs-lisp
+(ert-deftest chronometrist-format-duration-long ()
+  (should (equal (chronometrist-format-duration-long 5) ""))
+  (should (equal (chronometrist-format-duration-long 65) "1 minute"))
+  (should (equal (chronometrist-format-duration-long 125) "2 minutes"))
+
+  (should (equal (chronometrist-format-duration-long 3605) "1 hour"))
+  (should (equal (chronometrist-format-duration-long 3660) "1 hour, 1 minute"))
+  (should (equal (chronometrist-format-duration-long 3725) "1 hour, 2 minutes"))
+
+  (should (equal (chronometrist-format-duration-long 7200) "2 hours"))
+  (should (equal (chronometrist-format-duration-long 7260) "2 hours, 1 minute"))
+  (should (equal (chronometrist-format-duration-long 7320) "2 hours, 2 minutes")))
+#+END_SRC
+
+** plist pretty-printing
+[[file:../elisp/chronometrist.org::#program-pretty-printer][source]]
+
+*** plist-group-p
+#+BEGIN_SRC emacs-lisp
+(ert-deftest chronometrist-plist-group-p ()
+  (should (eq t (chronometrist-plist-group-p '(symbol   (:a 1 :b 2)))))
+  (should (eq t (chronometrist-plist-group-p '("string" (:a 1 :b 2)))))
+  (should (not (chronometrist-plist-group-p nil)))
+  (should (not (chronometrist-plist-group-p '("string")))))
+#+END_SRC
+
+*** plist-pp-to-string
+#+BEGIN_SRC emacs-lisp
+(ert-deftest chronometrist-pp-to-string ()
+  (should
+   (equal
+    (chronometrist-pp-to-string
+     '(:name "Task"
+       :tags (foo bar)
+       :comment ((70 . "baz")
+                 "zot"
+                 (16 . "frob")
+                 (20 20 "quux"))
+       :start "2020-06-25T19:27:57+0530"
+       :stop "2020-06-25T19:43:30+0530"))
+    (concat
+     "(:name    \"Task\"\n"
+     " :tags    (foo bar)\n"
+     " :comment ((70 . \"baz\")\n"
+     "           \"zot\"\n"
+     "           (16 . \"frob\")\n"
+     "           (20 20 \"quux\"))\n"
+     " :start   \"2020-06-25T19:27:57+0530\"\n"
+     " :stop    \"2020-06-25T19:43:30+0530\")")))
+  (should
+   (equal
+    (chronometrist-pp-to-string
+     '(:name  "Singing"
+       :tags  (classical solo)
+       :piece ((:composer "Gioachino Rossini"
+                :name     "Il barbiere di Siviglia"
+                :aria     ("All'idea di quel metallo" "Dunque io son"))
+               (:composer "Ralph Vaughan Williams"
+                :name     "Songs of Travel"
+                :movement ((4 . "Youth and Love")
+                           (5 . "In Dreams")
+                           (7 . "Wither Must I Wander?")))
+               (:composer "Ralph Vaughan Williams"
+                :name     "Merciless Beauty"
+                :movement 1)
+               (:composer "Franz Schubert"
+                :name     "Winterreise"
+                :movement ((1 . "Gute Nacht")
+                           (2 . "Die Wetterfahne")
+                           (4 . "Erstarrung"))))
+       :start "2020-11-01T12:01:20+0530"
+       :stop  "2020-11-01T13:08:32+0530"))
+    (concat
+     "(:name  \"Singing\"\n"
+     " :tags  (classical solo)\n"
+     " :piece ((:composer \"Gioachino Rossini\"\n"
+     "          :name     \"Il barbiere di Siviglia\"\n"
+     "          :aria     (\"All'idea di quel metallo\" \"Dunque io son\"))\n"
+     "         (:composer \"Ralph Vaughan Williams\"\n"
+     "          :name     \"Songs of Travel\"\n"
+     "          :movement ((4 . \"Youth and Love\")\n"
+     "                     (5 . \"In Dreams\")\n"
+     "                     (7 . \"Wither Must I Wander?\")))\n"
+     "         (:composer \"Ralph Vaughan Williams\"\n"
+     "          :name     \"Merciless Beauty\"\n"
+     "          :movement 1)\n"
+     "         (:composer \"Franz Schubert\"\n"
+     "          :name     \"Winterreise\"\n"
+     "          :movement ((1 . \"Gute Nacht\")\n"
+     "                     (2 . \"Die Wetterfahne\")\n"
+     "                     (4 . \"Erstarrung\"))))\n"
+     " :start \"2020-11-01T12:01:20+0530\"\n"
+     " :stop  \"2020-11-01T13:08:32+0530\")")))
+  (should (equal
+           (chronometrist-pp-to-string
+            '(:name "Cooking"
+              :tags (lunch)
+              :recipe (:name "moong-masoor ki dal"
+                       :url "https://www.mirchitales.com/moong-masoor-dal-red-and-yellow-lentil-curry/")
+              :start "2020-09-23T15:22:39+0530"
+              :stop "2020-09-23T16:29:49+0530"))
+           (concat
+            "(:name   \"Cooking\"\n"
+            " :tags   (lunch)\n"
+            " :recipe (:name \"moong-masoor ki dal\"\n"
+            "          :url  \"https://www.mirchitales.com/moong-masoor-dal-red-and-yellow-lentil-curry/\")\n"
+            " :start  \"2020-09-23T15:22:39+0530\"\n"
+            " :stop   \"2020-09-23T16:29:49+0530\")")))
+  (should (equal
+           (chronometrist-pp-to-string
+            '(:name    "Exercise"
+              :tags    (warm-up)
+              :start   "2018-11-21T15:35:04+0530"
+              :stop    "2018-11-21T15:38:41+0530"
+              :comment ("stretching" (25 10 "push-ups"))))
+           (concat
+            "(:name    \"Exercise\"\n"
+            " :tags    (warm-up)\n"
+            " :start   \"2018-11-21T15:35:04+0530\"\n"
+            " :stop    \"2018-11-21T15:38:41+0530\"\n"
+            " :comment (\"stretching\" (25 10 \"push-ups\")))")))
+  (should (equal
+           (chronometrist-pp-to-string
+            '(:name    "Guitar"
+              :tags    (classical)
+              :warm-up ((right-hand-patterns "pima" "piam" "pmia" "pmai" "pami" "paim"))
+              :start   "2021-09-28T17:49:18+0530"
+              :stop    "2021-09-28T17:53:49+0530"))
+           (concat
+            "(:name    \"Guitar\"\n"
+            " :tags    (classical)\n"
+            " :warm-up ((right-hand-patterns \"pima\" \"piam\" \"pmia\" \"pmai\" \"pami\" \"paim\"))\n"
+            " :start   \"2021-09-28T17:49:18+0530\"\n"
+            " :stop    \"2021-09-28T17:53:49+0530\")")))
+  (should (equal
+           (chronometrist-pp-to-string
+            '(:name   "Cooking"
+              :tags   (lunch)
+              :recipe ("urad dhuli"
+                       (:name     "brown rice"
+                        :brand    "Dawat quick-cooking"
+                        :quantity "40% of steel measuring glass"
+                        :water    "2× dry rice"))
+              :start  "2021-11-07T14:40:45+0530"
+              :stop   "2021-11-07T15:28:13+0530"))
+           (concat
+            "(:name   \"Cooking\"\n"
+            " :tags   (lunch)\n"
+            " :recipe (\"urad dhuli\"\n"
+            "          (:name \"brown rice\"\n"
+            "           :brand \"Dawat quick-cooking\"\n"
+            "           :quantity \"40% of steel measuring glass\"\n"
+            "           :water \"2× dry rice\"))\n"
+            " :start  \"2021-11-07T14:40:45+0530\"\n"
+            " :stop   \"2021-11-07T15:28:13+0530\")"))))
+#+END_SRC
+
+** backend
+Situations
+1. no file
+2. empty file
+3. non-empty file with no records
+4. single record
+   * active
+   * inactive
+   * active, day-crossing
+   * inactive, day-crossing
+5. multiple records
+6. +[plist-group] latest plist is split+ (covered in #4)
+
+Tests to be added -
+1. to-hash-table
+2. to-file
+
+The order of these tests is important - the last test for each case is one which moves into the next case.
+
+*** create-file
+:PROPERTIES:
+:CUSTOM_ID: tests-backend-create-file
+:END:
+#+BEGIN_SRC emacs-lisp
+(chronometrist-ert-deftest create-file b
+  ;; (message "create-file test - hash-table-count %s" (hash-table-count (chronometrist-backend-hash-table b)))
+  ;; * file does not exist *
+  (should (chronometrist-create-file b))
+  ;; * file exists but has no records *
+  (should (not (chronometrist-create-file b))))
+#+END_SRC
+
+*** latest-date-records
+#+BEGIN_SRC emacs-lisp
+(chronometrist-ert-deftest latest-date-records b
+  ;; (message "latest-date-records test - hash-table-count %s" (hash-table-count (chronometrist-backend-hash-table b)))
+  (let ((plist-1  (cl-first chronometrist-test-records))
+        (plist-2  (cl-second chronometrist-test-records))
+        (today-ts (chronometrist-date-ts)))
+    ;; * file does not exist *
+    (should-error (chronometrist-latest-date-records b))
+    (should (chronometrist-create-file b))
+    ;; (message "latest-date-records: %S" (chronometrist-latest-date-records b))
+    ;; * file exists but has no records *
+    (should (not (chronometrist-latest-date-records b)))
+    (should (chronometrist-insert b plist-1))
+    ;; * backend has a single active record *
+
+    ;; * backend has a single inactive record *
+    ;; * backend has a single active day-crossing record *
+    ;; * backend has a single inactive day-crossing record *
+
+    ;; * backend has two records and one is active *
+    ;; * backend has two records and both are inactive *
+    ;; * backend has two day-crossing records and one is active *
+    ;; * backend has two day-crossing records and both are inactive *
+    ))
+#+END_SRC
+
+*** insert
+#+BEGIN_SRC emacs-lisp
+(chronometrist-ert-deftest insert b
+  ;; (message "insert test - hash-table-count %s" (hash-table-count (chronometrist-backend-hash-table b)))
+  (let* ((plist1 (list :name "Test" :start (chronometrist-format-time-iso8601)))
+         (plist2 (append plist1 (list :stop (chronometrist-format-time-iso8601)))))
+    ;; * file does not exist *
+    (should-error (chronometrist-insert b plist1))
+    (should (chronometrist-create-file b))
+    ;; * file exists but has no records *
+    (should (chronometrist-insert b plist1))
+    (should (equal (progn (chronometrist-reset-backend b)
+                          (chronometrist-latest-date-records b))
+                   (list (chronometrist-date-iso) plist1)))
+    ;; * backend has a single active record *
+    (should (chronometrist-replace-last b plist2))
+    (should (equal (progn (chronometrist-reset-backend b)
+                          (chronometrist-latest-date-records b))
+                   (list (chronometrist-date-iso) plist2)))
+    ;; * backend has a single inactive record *
+    ;; * backend has a single active day-crossing record *
+    ;; * backend has a single inactive day-crossing record *
+
+    ;; * backend has two records and one is active *
+    ;; * backend has two records and both are inactive *
+    ;; * backend has two day-crossing records and one is active *
+    ;; * backend has two day-crossing records and both are inactive *
+    ))
+#+END_SRC
+
+* Local Variables
+# Local Variables:
+# delete-old-versions: t
+# End:

tests/test.sexp

@@ -1,57 +0,0 @@
-(:name "Programming"
- :start "2018-01-01T00:00:00+0530"
- :stop  "2018-01-01T01:00:00+0530")
-
-(:name "Swimming"
- :start "2018-01-01T02:00:00+0530"
- :stop  "2018-01-01T03:00:00+0530")
-
-(:name "Cooking"
- :start "2018-01-01T04:00:00+0530"
- :stop  "2018-01-01T05:00:00+0530")
-
-(:name "Guitar"
- :start "2018-01-01T06:00:00+0530"
- :stop  "2018-01-01T07:00:00+0530")
-
-(:name "Cycling"
- :start "2018-01-01T08:00:00+0530"
- :stop  "2018-01-01T09:00:00+0530")
-
-(:name "Programming"
- :start "2018-01-02T23:00:00+0530"
- :stop  "2018-01-03T01:00:00+0530")
-
-(:name "Cooking"
- :start "2018-01-03T23:00:00+0530"
- :stop  "2018-01-04T01:00:00+0530")
-
-(:name      "Programming"
- :tags      (bug-hunting)
- :project   "Chronometrist"
- :component "goals"
- :start     "2020-05-09T20:03:25+0530"
- :stop      "2020-05-09T20:05:55+0530")
-
-(:name     "Arrangement/new edition"
- :tags     (new edition)
- :song     "Songs of Travel"
- :composer "Vaughan Williams, Ralph"
- :start    "2020-05-10T00:04:14+0530"
- :stop     "2020-05-10T00:25:48+0530")
-
-(:name  "Guitar"
- :tags  (classical warm-up)
- :start "2020-05-10T15:41:14+0530"
- :stop  "2020-05-10T15:55:42+0530")
-
-(:name  "Guitar"
- :tags  (classical solo)
- :start "2020-05-10T16:00:00+0530"
- :stop  "2020-05-10T16:30:00+0530")
-
-(:name  "Programming"
- :tags  (reading)
- :book  "Smalltalk-80: The Language and Its Implementation"
- :start "2020-05-10T16:33:17+0530"
- :stop  "2020-05-10T17:10:48+0530")