Org Edna

Requirements

There are two ways to install Edna: From GNU ELPA, or from source.

From ELPA:

M-x package-install org-edna

From Source:

bzr branch https://bzr.savannah.gnu.org/r/org-edna-el/ org-edna

After that, add the following to your init file (typically .emacs):

;; Only necessary if installing from source
(add-to-list 'load-path "/full/path/to/org-edna/")
(require 'org-edna)

;; Always necessary
(org-edna-mode)

If you ever want to disable Edna, run (org-edna-mode) again.

To determine if Edna is active, check the org-edna-mode variable.

Let’s start with an example: Say you want to do laundry, but once you’ve put your clothes in the washer, you forget about it. Even with a tool like org-notify or appt, Org won’t know when to remind you. If you’ve got them scheduled for an hour after the other, maybe you forgot one time, or ran a little late. Now Org will remind you too early.

Edna can handle this for you like so:

* TODO Put clothes in washer
  SCHEDULED: <2017-04-08 Sat 09:00>
  :PROPERTIES:
  :TRIGGER: next-sibling scheduled!("++1h")
  :END:
* TODO Put clothes in dryer
  :PROPERTIES:
  :TRIGGER: next-sibling scheduled!("++1h")
  :BLOCKER:  previous-sibling
  :END:
* TODO Fold laundry
  :PROPERTIES:
  :TRIGGER: next-sibling scheduled!("++1h")
  :BLOCKER:  previous-sibling
  :END:
* TODO Put clothes away
  :PROPERTIES:
  :TRIGGER: next-sibling scheduled!("++1h")
  :BLOCKER:  previous-sibling
  :END:

After you’ve put your clothes in the washer and mark the task DONE, Edna will schedule the following task for one hour after you set the first heading as done.

Another example might be a checklist that you’ve done so many times that you do part of it on autopilot:

* TODO Address all TODOs in code
* TODO Commit Code to Repository

The last thing anyone wants is to find out that some part of the code on which they’ve been working for days has a surprise waiting for them. Once again, Edna can help:

* TODO Address all TODOs in code
  :PROPERTIES:
  :BLOCKER: file("main.cpp") file("code.cpp") re-search?("TODO")
  :END:
* TODO Commit Code to Repository

A blocker indicates conditions which must be met in order for a heading to be marked as DONE. Typically, this will be a list of headings that must be marked as DONE.

A trigger is an action to take when a heading is set to done. For example, scheduling another task, marking another task as TODO, or renaming a file.

Edna has its own language for commands, the basic form of which is KEYWORD(ARG1 ARG2 ...)

KEYWORD can be any valid lisp symbol, such as key-word, KEY_WORD!, or keyword?.

Each argument can be one of the following:

• A symbol, such as arg or org-mode
• A quoted string, such as “hello” or “My name is Edna”
• A number, such as 0.5, +1e3, or -5
• A UUID, such as c5e30c76-879a-494d-9281-3a4b559c1a3c

Each argument takes specific datatypes as input, so be sure to read the entry before using it.

The parentheses can be omitted for commands with no arguments.

A finder specifies locations from which to test conditions or perform actions. These locations are referred to as “targets”. The current heading, i.e. the one that is being blocked or triggered, is referred to as the “source” heading.

More than one finder may be used. In this case, the targets are merged together, removing any duplicates.

Many finders take additional options, marked “OPTIONS”. See relatives for information on these options.

Once Edna has collected its targets for a trigger, it will perform actions on them.

Actions must always end with ’!’.

Edna provides help for any keyword with M-x org-edna-describe-keyword. When invoked, a list of keywords (finders, actions, etc.) known to Edna will be provided. Select any one to get its description.

This description includes the syntax and an explanation of what the keyword does. Some descriptions also contain examples.

Some finders, match in particular, can take a long time to run. Oftentimes, this can make it unappealing to use Edna at all, especially with long checklists.

The finder cache is one solution to this. To enable it, set org-edna-finder-use-cache to non-nil. This can be done through the customization interface, or manually with setq.

When enabled, the cache will store the results of every finder form for a configurable amount of time. This timeout is controlled by org-edna-finder-cache-timeout. The cache is also invalidated if any of the results are invalid, which can happen if their target files have been closed.

For example, if there are several entries in a checklist that all use the form match("daily") as part of their trigger, the results of that form will be cached. When the next item is marked as DONE, the results will be searched for in cache, not recomputed.

When reverting Org mode files, the cache will often be invalidated. This isn’t the case for every Org mode file, so we can’t just tell Emacs to automatically reset the cache when reverting a file. Instead, we provide the command org-edna-reset-cache to reset the finder cache. If you notice headings that should be blocking but aren’t while cache is enabled, reset the cache and check again.

Edna gives you he option to specify blocking conditions. Each condition is checked for each of the specified targets; if one of the conditions returns true for that target, then the source heading is blocked.

If no condition is specified, !done? is used by default, which means block if any target heading isn’t done.

“Consideration” and “consider” are special keywords that are only valid for blockers.

A blocker says “If ANY heading in TARGETS meets CONDITION, block this task”.

In order to modify the ANY part of that statement, the consider keyword may be used:

1. consider(any)
2. consider(all)
3. consider(FRACTION)
4. consider(NUMBER)

(1) blocks the current task if any target meets the blocking condition. This is the default case.

(2) blocks the current task only if all targets meet the blocking condition.

* Shovel Snow
** TODO Shovel on Monday
** TODO Shovel on Tuesday
** TODO Shovel on Wednesday
** TODO Put shovel away
   :PROPERTIES:
   :BLOCKER: consider(all) rest-of-siblings-wrap
   :END:

The above example blocks “Put shovel away” so long as all of the siblings are still marked TODO.

(3) blocks the current task if at least FRACTION of the targets meet the blocking condition.

* Work
** TODO Shovel Snow
** TODO Clean room
** TODO Vacuum
** TODO Eat lunch
** TODO Work on Edna
   :PROPERTIES:
   :BLOCKER: consider(0.5) rest-of-siblings-wrap
   :END:

The above example blocks “Work on Edna” so long as at least half of the siblings are marked TODO. This means that three of them must be completed before development can begin on Edna.

(4) blocks the current task if at least NUMBER of the targets meet the blocking condition.

* Work
** TODO Shovel Snow
** TODO Clean room
** TODO Vacuum
** TODO Eat lunch
** TODO Work on Edna
   :PROPERTIES:
   :BLOCKER: consider(2) rest-of-siblings-wrap
   :END:

The above example blocks “Work on Edna” so long as two of the siblings are marked TODO. This means that NUMBER=1 is the same as specifying any.

A consideration must be specified before the conditions to which it applies.

Both “consider” and “consideration” are valid keywords; they both mean the same thing.

Let’s say you’ve got the following checklist:

* TODO Nightly
  DEADLINE: <2017-12-22 Fri 22:00 +1d>
  :PROPERTIES:
  :ID:       12345
  :BLOCKER:  match("nightly")
  :TRIGGER:  match("nightly") todo!(TODO)
  :END:
* TODO Prepare Tomorrow's Lunch                                     :nightly:
* TODO Lock Back Door                                               :nightly:
* TODO Feed Dog                                                     :nightly:

You don’t know in what order you want to perform each task, nor should it matter. However, you also want the parent heading, “Nightly”, to be marked as DONE when you’re finished with the last task.

There are two solutions to this: 1. Have each task attempt to mark “Nightly” as DONE, which will spam blocking messages after each task.

The second is to use conditional forms. Conditional forms are simple; it’s just if/then/else/endif:

if CONDITION then THEN else ELSE endif

Here’s how that reads:

“If CONDITION would not block, execute THEN. Otherwise, execute ELSE.”

For our nightly entries, this looks as follows:

* TODO Prepare Tomorrow's Lunch                                     :nightly:
  :PROPERTIES:
  :TRIGGER:  if match("nightly") then ids(12345) todo!(DONE) endif
  :END:

Thus, we replicate our original blocking condition on all of them, so it won’t trigger the original until the last one is marked DONE.

Occasionally, you may find that you’d rather execute a form if the condition would block. There are two options.

The first is to use consider(all). This will tell Edna to block only if all of the targets meets the condition, and thus not block if at least one of them does not meet the condition. This is the opposite of Edna’s standard operation, which only allows passage if all targets meet the condition.

* TODO Prepare Tomorrow's Lunch                                     :nightly:
  :PROPERTIES:
  :TRIGGER:  if consider(all) match("nightly") then ids(12345) todo!(DONE) endif
  :END:

The second is to switch the then and else clauses:

* TODO Prepare Tomorrow's Lunch                                     :nightly:
  :PROPERTIES:
  :TRIGGER:  if match("nightly") then else ids(12345) todo!(DONE) endif
  :END:

The conditional block tells it to evaluate that section. Thus, you can conditionally add targets, or conditionally check conditions.

Another common use case is to check for a property:

* TODO My Task
  :PROPERTIES:
  :TRIGGER: if self has-property?("REPEAT" "2") then self set-property!("REPEAT" inc) todo!("TODO") endif
  :REPEAT: 0
  :END:

When “My Task” is set to DONE, REPEAT will be incremented, then the task will be set back to TODO. This happens until REPEAT is 2. Once that happens, the task will be left alone, staying in the DONE state.

Be warned that trying the above example with a repeater will not work. In order for that to work, Edna must take over the repeater:

* TODO My Task
  SCHEDULED: <2020-09-02 Wed>
  :PROPERTIES:
  :TRIGGER: if self has-property?("REPEAT" "2") then self set-property!("REPEAT" inc) scheduled!("+1d") todo!("TODO") endif
  :REPEAT: 0
  :END:

This example will increment the SCHEDULED time by one day every time the task is marked DONE.

Sometimes, you have a heading like this:

* My Task
  :PROPERTIES:
  :TRIGGER:  self set-property!("TEST" inc)
  :END:

You want to mark it as DONE because that’s how you do things. Will Edna run when you do that?

The answer is it can. There is user variable called org-edna-from-todo-states that controls the categories of TODO states from which changing a heading will cause Edna to run. This has two possible values:

todo

Edna will only run if the old TODO state is in org-not-done-keywords. This is the default.

not-done

Edna will run if the old TODO state is not in org-done-keywords. This includes no state at all.

Further, using conditional forms, it is possible to take different actions depending on the new TODO state. For example:

* My Task
  :PROPERTIES:
  :TRIGGER:  if self todo-state?("COMPLETE") then self set-property!("TEST" inc) endif
  :TEST:     0
  :END:

This will only increment the TEST property if the new TODO state is not “COMPLETE”. Currently, there is no way to take different actions depending on the old TODO state.

There are two ways to set the BLOCKER and TRIGGER properties: by hand, or the easy way. You can probably guess which way we prefer.

With point within the heading you want to edit, type M-x org-edna-edit. You end up in a buffer that looks like this:

Edit blockers and triggers in this buffer under their respective sections below.
All lines under a given section will be merged into one when saving back to
the source buffer.  Finish with `C-c C-c' or abort with `C-c C-k'.

BLOCKER
BLOCKER STUFF HERE

TRIGGER
TIRGGER STUFF HERE

In here, you can edit the blocker and trigger properties for the original heading in a cleaner environment. More importantly, you can complete the names of any valid keyword within the BLOCKER or TRIGGER sections using completion-at-point.

When finished, type C-c C-c to apply the changes, or C-c C-k to throw out your changes.

In order to distinguish between actions, finders, and conditions, we add ’?’ to conditions and ’!’ to actions. This is taken from the practice in Guile and Scheme to suffix destructive functions with ’!’ and predicates with ’?’.

Thus, one can have an action that files a target, and a finder that finds a file.

We recommend that you don’t name a finder with a special character at the end of its name. As we devise new ideas, we consider using special characters for additional categories of keywords. Thus, to avoid complications in the future, it’s best if everyone avoids using characters that may become reserved in the future.

Finders have the form org-edna-finder/KEYWORD, like so:

(defun org-edna-finder/test-finder ()
  (list (point-marker)))

All finders must return a list of markers, one for each target found, or nil if no targets were found.

Actions have the form org-edna-action/KEYWORD!:

(defun org-edna-action/test-action! (last-entry arg1 arg2)
  )

Each action has at least one argument: last-entry. This is a marker for the current entry (not to be confused with the current target).

The rest of the arguments are the arguments specified in the form.

(defun org-edna-condition/test-cond? (neg))

All conditions have at least one argument, “NEG”. If NEG is non-nil, the condition should be negated.

Most conditions have the following form:

(defun org-edna-condition/test-condition? (neg)
  (let ((condition (my-test-for-condition)))
    (when (org-xor condition neg)
      (string-for-blocking-entry-here))))

For conditions, we return true if condition is true and neg is false, or if condition is false and neg is true:

This is an XOR table, so we pass CONDITION and NEG into org-xor to get our result.

A condition must return a string if the current entry should be blocked.

There are two ways to submit bug reports:

1. Using the bug tracker at Savannah
2. Sending an email using org-edna-submit-bug-report

When submitting a bug report, be sure to include the Edna form that caused the bug, with as much context as possible.

Our build system uses EDE. EDE can be a little finicky at times, but we feel the benefits, namely package dependency handling and Makefile generation, outweigh the costs.

One of the issues that many will likely encounter is the error “Corrupt file on disk”. This is most often due to EDE not loading all its subprojects as needed. If you find yourself dealing with this error often, place the following in your .emacs file:

;; Target types needed for working with edna
(require 'ede/proj-elisp)
(require 'ede/proj-aux)
(require 'ede/proj-misc)

These are the three target types that edna uses: elisp for compilation and autoloads; aux for auxiliary files such as documentation; and misc for tests.

When creating a new file, EDE will ask if you want to add it to a target. Consult with one of the edna devs for guidance, but usually selecting “none” and letting one of us handle it is a good way to go.

To compile Edna, you’ve got to have EDE create the Makefile first. Run the following in your Emacs instance to generate the Makefile:

M-x ede-proj-regenerate

This will create the Makefile and point it to the correct version of Org. The targets are as follows:

compile

Compiles the code. This should be done to verify that everything will compile, as ELPA requires this.

autoloads

Creates the autoloads file. This should also run without problems, so it’s a good idea to check this one as well.

check

Runs the tests in org-edna-tests.el.

To run any target, call make:

make compile autoloads

The above command compiles Edna and generates the autoloads file.

There are two ways to test Edna: the command-line and through Emacs.

The command-line version is simple, and we ask that you do any final testing using this method. This is how we periodically check to verify that new versions of Org mode haven’t broken Edna. It uses the Makefile, which is generated with EDE. See Compiling Edna for how to do that. Once you have, run make check on the command line.

Edna tests are written using ERT, the Emacs Regression Testing framework. In order to use it interactively in Emacs, the following must be done:

1. Load org-edna-tests.el
2. Run M-x ert-run-tests-interactively
3. Select which tests to run, or just the letter “t” to run all of them.

Results are printed in their own buffer. See the ERT documentation for more details.

There are a few rules to follow:

• Verify that any new Edna keywords follow the appropriate naming conventions
• Any new keywords should be documented
• We operate on headings, not headlines
  • Use one word in documentation to avoid confusion
• Make sure your changes compile
• Run ’make check’ to verify that your mods don’t break anything
• Avoid additional or altered dependencies if at all possible
  • Exception: New versions of Org mode are allowed

If you’re new to bazaar, we recommend using Emacs’s built-in VC package. It eases the overhead of dealing with a brand new VCS with a few standard commands. For more information, see the info page on it (In Emacs, this is C-h r m Introduction to VC RET).

To contribute with bazaar, you can do the following:

# Hack away and make your changes
$ bzr commit -m "Changes I've made"
$ bzr send -o file-name.txt

Then, use org-edna-submit-bug-report and attach “file-name.txt”. We can then merge that into the main development branch.

Documentation is always helpful to us. Please be sure to do the following after making any changes:

1. Update the info page in the repository with C-c C-e i i
2. If you’re updating the HTML documentation, switch to a theme that can easily be read on a white background; we recommend the “adwaita” theme

• Allow id: syntax in ids finder
• Added setting org-edna-from-todo-states
  • See What Constitutes “Not Done” for more

• Marked org-edna-load and org-edna-unload as deprecated
• Renamed to org-edna--load and org-edna--unload to reflect internal use only intention

• Added org-edna-mode as a minor mode, as opposed to org-edna-load and org-edna-unload

• Added org-edna-reset-cache to allow a user to reset the finder cache
• Fixed timestamp format bug with scheduled! and deadline!
  • See Timestamp Format for more

• Fixed bug in multiple blocking conditions

• Various bugs fixes
  • Fixed parsing of consideration
  • Limited cache to just the finders that don’t depend on current position
• Added “buffer” option for match finder
• Added timestamp sorting to relatives finder
• Inverted meaning of consideration to avoid confusion
• Added has-tags? and matches? conditions

Quick fix for beta7.

Biggest change here is the cache.

• Added cache to the finders to improve performance
• Updated documentation to include EDE
• Added testing and compiling documentation

Lots of parsing fixes.

• Fixed error reporting
• Fixed parsing of negations in conditions
• Fixed parsing of multiple forms inside if/then/else blocks

Some new forms and a new build system.

• Added new forms to set-property!
  • Now allows ’inc, ’dec, ’previous, and ’next as values
• Changed build system to EDE to properly handle dependencies
• Fixed compatibility with new Org effort functions

Just some bug fixes from the new form parsing.

• Fixed multiple forms getting incorrect targets
• Fixed multiple forms not evaluating

HUGE addition here

• Conditional Forms
  • See Conditional Forms for more information
• Overhauled Internal Parsing
• Fixed consideration keywords
• Both consider and consideration are accepted now
• Added ’any consideration
  • Allows passage if just one target is fulfilled

Big release here, with three new features.

• Added interactive keyword editor with completion
  • See Setting the Properties for how to do that
• New uses of schedule! and deadline!
  • New “float” form that mimics diary-float
  • New “landing” addition to “+1d” and friends to force planning changes to land on a certain day or type of day (weekend/weekday)
  • See Scheduled/Deadline for details
• New “relatives” finder
  • Renamed from chain-find with tons of new keywords
  • Modified all other relative finders (previous-sibling, first-child, etc.) to use the same keywords
  • See relatives for details
• New finders
  • previous-sibling-wrap
  • rest-of-siblings-wrap