Org API

Begin an interactive 'drill session'. The user is asked to review a series of topics (headers). Each topic is initially presented as a 'question', often with part of the topic content hidden. The user attempts to recall the hidden information or answer the question, then presses a key to reveal the answer. The user then rates his or her recall or performance on that topic. This rating information is used to reschedule the topic for future review.

Org-drill proceeds by:

• Finding all topics (headings) in scope which have either been

used and rescheduled before, or which have a tag that matches
`org-drill-question-tag'.

• All matching topics which are either unscheduled, or are

scheduled for the current date or a date in the past, are
considered to be candidates for the drill session.

• If org-drill-maximum-items-per-session is set, a random

subset of these topics is presented. Otherwise, all of the
eligible topics will be presented.

scope determines the scope in which to search for questions. It accepts the same values as org-drill-scope, which see.

If resume-p is non-nil, resume a suspended drill session rather than starting a new one.

Run a new drill session, but try to use leftover due items that were not reviewed during the last session, rather than scanning for unreviewed items. If there are no leftover items in memory, a full scan will be performed.

Copy the subtree at point to the buffer dest. The copy will receive the tag 'imported'.

Run an interactive drill session in 'cram mode'. In cram mode, all drill items are considered to be due for review, unless they have been reviewed within the last org-drill-cram-hours hours.

Nil means a last review date has not yet been stored for the item. Zero means it was reviewed today. A positive number means it was reviewed that many days ago. A negative number means the date of last review is in the future -- this should never happen.

Run an interactive drill session using drill items from all org files in the same directory as the current file.

Arguments:

• optimal-factor: interval-factor if the item had been tested

exactly when it was supposed to be.

• optimal-interval: interval for next repetition (days) if the item had been

tested exactly when it was supposed to be.

• days-ahead: how many days ahead of time the item was reviewed.

Returns an adjusted optimal factor which should be used to calculate the next interval, instead of the optimal factor found in the matrix.

Returns nil, t, or a list of markers representing entries that were 'failed' and need to be presented again before the session ends.

resuming-p is true if we are resuming a suspended drill session.

Present the current topic for interactive review, as in org-drill. Review will occur regardless of whether the topic is due for review or whether it meets the definition of a 'review topic' used by org-drill.

Returns a quality rating from 0 to 5, or nil if the user quit, or the symbol EDIT if the user chose to exit the drill and edit the current item. Choosing the latter option leaves the drill session suspended; it can be resumed later using org-drill-resume.

See org-drill for more details.

Returns:

• NIL if the item is not to be regarded as scheduled for review at all.

This is the case if it is not a drill item, or if it is a leech item
that we wish to skip, or if we are in cram mode and have already reviewed
the item within the last few hours.

• 0 if the item is new, or if it scheduled for review today.
• A negative integer - item is scheduled that many days in the future.
• A positive integer - item is scheduled that many days in the past.

Is the current entry a 'leech item'?

Returns true if entry that is scheduled days-overdue dasy in the past, and whose last inter-repetition interval was last-interval, should be considered 'overdue'. If the arguments are not given they are extracted from the entry at point.

Is marker, or the point, in a 'drill item'? This will return nil if the point is inside a subheading of a drill item – to handle that situation use org-part-of-drill-entry-p.

Returns a list (STATUS DUE) where DUE is the number of days overdue, zero being due today, -1 being scheduled 1 day in the future. STATUS is one of the following values:

• nil, if the item is not a drill entry, or has an empty body
• :unscheduled
• :future
• :new
• :failed
• :overdue
• :young
• :old

markers is a list of markers, all of which will be freed (set to point nowhere). Alternatively, markers can be 't', in which case all the markers used by Org-Drill will be freed.

Returns a list of 6 items, containing all the stored recall

data for the item at point:

• LAST-INTERVAL is the interval in days that was used to schedule the item's

current review date.

• REPEATS is the number of items the item has been successfully recalled without

without any failures. It is reset to 0 upon failure to recall the item.

• FAILURES is the total number of times the user has failed to recall the item.
• TOTAL-REPEATS includes both successful and unsuccessful repetitions.
• AVERAGE-QUALITY is the mean quality of recall of the item over

all its repetitions, successful and unsuccessful.

• EASE is a number reflecting how easy the item is to learn. Higher is easier.

Auxiliary function used by org-drill-present-verb-conjugation and org-drill-show-answer-verb-conjugation.

Move the point to the heading which holds the :drill: tag for this drill entry.

Hide the current match with a 'cloze' visual overlay.

Hide the buffer region between beg and end with an 'invisible text' visual overlay, or with the string text if it is supplied.

test is a function taking no arguments. test will be called for each of the immediate subheadings of the current drill item, with the point on the relevant subheading. test should return nil if the subheading is to be revealed, non-nil if it is to be hidden. Returns a list containing the position of each immediate subheading of the current topic.

Like org-drill-days-since-last-review, but return value is in hours rather than days.

Returns an integer representing the number of days into the future that the current item would be scheduled, based on a recall quality of quality.

Returns true if the current drill session has continued past its maximum duration.

Returns true if the current drill session has reached the maximum number of items.

src and dest are two org mode buffers containing drill items. For each drill item in dest that shares an ID with an item in src, overwrite scheduling data in dest with data taken from the item in src. This is intended for use when two people are sharing a set of drill items, one person has made some updates to the item set, and the other person wants to migrate to the updated set without losing their scheduling data.

By default, any drill items in src which do not exist in dest are copied into dest. We attempt to place the copied item in the equivalent location in dest to its location in src, by matching the heading hierarchy. However if ignore-new-items-p is non-nil, we simply ignore any items that do not exist in dest, and do not copy them across.

TEXTS is a list of valid values for the 'display' text property. Present these overlays, in sequence, as the only visible content of the card.

Present the string question as the only visible content of the card.

Hides the first piece of text that is marked for cloze deletion.

Hides the last piece of text that is marked for cloze deletion.

Hides number-to-hide pieces of text that are marked for cloze deletion, chosen at random. If number-to-hide is negative, show only (ABS number-to-hide) pieces, hiding all the rest. If force-hide-first is non-nil, force the first piece of text to be one of the hidden items. If force-show-first is non-nil, never hide the first piece of text. If force-show-last is non-nil, never hide the last piece of text. If the number of text pieces in the item is less than number-to-hide, then all text pieces will be hidden (except the first or last items if force-show-first or force-show-last is non-nil).

Hide the to-hide'th piece of clozed text. 1 is the first piece. If to-hide is negative, count backwards, so -1 means the last item, -2 the second to last, etc.

Hides one of the pieces of text that are marked for cloze deletion, chosen at random.

Commonly, hides the FIRST piece of text that is marked for cloze deletion. Uncommonly, hide one of the other pieces of text, chosen at random.

The definitions of 'commonly' and 'uncommonly' are determined by the value of org-drill-cloze-text-weight.

Hides two of the pieces of text that are marked for cloze deletion, chosen at random.

Similar to org-drill-present-multicloze-hide1, but hides all the pieces of text that are marked for cloze deletion, except for one piece which is chosen at random.

Commonly, hides all pieces except one, where the shown piece is guaranteed NOT to be the first piece. Uncommonly, shows any random piece. The effect is similar to 'show1cloze' except that the first item is much less likely to be the item that is visible.

The definitions of 'commonly' and 'uncommonly' are determined by the value of org-drill-cloze-text-weight.

Commonly, hides all pieces except the last. Uncommonly, shows any random piece. The effect is similar to 'show1cloze' except that the last item is much less likely to be the item that is visible.

The definitions of 'commonly' and 'uncommonly' are determined by the value of org-drill-cloze-text-weight.

Similar to org-drill-present-multicloze-show1, but reveals two pieces rather than one.

Present a drill entry whose card type is 'conjugate'.

Returns a random number between 0.5 and 1.5.

Make an overlay that conceals the heading of the item. The overlay shows the string TEXT. Note: does not actually alter the item.

Make an overlay that conceals the entire text of the item, not including properties or the contents of subheadings. The overlay shows the string text. If multi-p is non-nil, text must be a list of values which are legal for the display text property. The text of the item will be temporarily replaced by all of these items, in the order in which they appear in the list. Note: does not actually alter the item.

Make overlays that conceal the entire text of the item, not including properties or the contents of subheadings. The overlay shows the string TEXT. Note: does not actually alter the item.

Returns quality rating (0-5), or nil if the user quit.

Resume a suspended drill session. Sessions are suspended by exiting them with the edit or quit options.

Show the answer for a drill item whose card type is 'conjugate'. reschedule-fn must be a function that calls org-drill-reschedule and returns its return value.

Arguments:

• failures: integer >= 0. The total number of times the item has

been forgotten, ever.

Returns the optimal FIRST interval for an item which has previously been forgotten on failures occasions.

Arguments:

• ease: floating point number >= 1.2. Corresponds to AF in SM8 algorithm.
• repetition: the number of times the item has been tested.

1 is the first repetition (ie the second trial). Returns: The factor by which the last interval should be multiplied to give the next interval. Corresponds to RF or OF.

Returns the ease (AF in the SM8 algorithm) which corresponds to a mean item quality of quality.

If days-ahead is supplied it must be a positive integer. The item will be scheduled exactly this many days into the future.

Stores the given data in the item at point.

Delete scheduling data from every drill entry in scope. This function may be useful if you want to give your collection of entries to someone else. Scope defaults to the current buffer, and is specified by the argument scope, which accepts the same values as org-drill-scope.

Run an interactive drill session using drill items within the subtree at point.