Applescript Support in TaskPaper 3


Hi Jesse

I’m trying to find an overview of Applescript support in TP 3. The posts I’ve come across are all referring to the state of scripting in FoldingText and what will also be present in TP 3. I haven’t used FT but have invested quite a lot of time in scripting TaskPaper 2 (including such offbeat use cases as using TP for rough drafts of Keynote presentations - . Could you clarify what the Applescript dictionary for TP 3 is going to look like? Can we expect that all of the elements of TP 2 Applescript will remain? If not, what’s likely to be cut?



TP3 has very rich scripting support. Not yet documented, but the intrepid can begin some preliminary explorations though ⇧ ⌘ W > resources > birch.js, and I’m sure that full documentation will follow, at some stage.

The core of the application is written in JavaScript, and the natural choice for its programming interface is therefore JavaScript rather than AppleScript. (You should still be able to find the FT discussion thread where the problem of maintaining two parallel APIs for these applications was discussed - the mood was that it would be sensible to just maintain a JS interface, with a bridge from AppleScript for calling the JS code for those who prefer to do it that way.

Your existing AS scripts will continue to run from copies of TP2, and learning a little JavaScript will enable you to write faster scripts, with even more reach, in TP3.

( I do remember pausing for breath before jumping into JavaScript from AS, so I sympathise, and I can assure you that having made the leap, JS turns out to be much easier and more pleasant that AS in several respects (easier records, richer libraries etc). It’s also more omnipresent - more useful not just on the web, but on iOS too (Drafts, TextExpander, and various other apps).

(I now do all of my OS X scripting in JavaScript for Applications, incidentally, after years of investing quite heavily in AS )


Can you give us an example of a script and how to run that script in the current TaskPaper? It can get many pointing into the right direction.


Of course – I will sit down at some point tonight and translate @derickfay’s TP2 → Keynote script into a TP3 version.

In the meanwhile, if you are running Yosemite onwards you can:

  1. Open OS X Script Editor,
  2. change the drop-down control at top left from AppleScript to "JavaScript*
  3. copy and paste the code from Script: move a @now or @next tag on to the next item
  4. (with a TP3 document open) click the Run button in Script Editor.


While it may seem daunting at first, I’m firmly in the camp that believes the move to javascript is a valid and worthwhile one. I’m still learning and looking at scripts made by @complexpoint and others helps. The weird part is how you get javascript code to be pared within TaskPaper. However, once you get over that hurdle, the rest is plain old javascript and to learn that, there is a wealth of information.


Thanks for the replies, from which it sounds like there isn’t a plan for Applescript support.

I get that JavaScript is probably the future automation on the Mac and in the long term probably worth investing some time in, esp. as I last worked in the language in 2002. At the moment though I don’t have the time to refresh and update my knowledge then poke through 52000+ lines of code in birch.js , and was hoping for a pathway whereby I wouldn’t need to rewrite all my existing scripts.

At this point I’ve already rewritten (or found equivalents for) many of them in Python for use with Editorial on iOS. So I’m thinking it will be more productive to work in Python and manipulate TaskPaper files directly. Unlike TP 2, TP 3 seems to immediately refresh when a file has changed externally, which would eliminate a significant obstacle to this approach.


poke through 52000+ lines of code in birch.js

Absolutely – I take your point, and I should have mentioned that all of the scripting interface is attached to the editor object of TP3.

If anyone did want to get a sense of what is there, before the documentation is released, the thing to search for would be OutlineEditor.prototype.

The interface may not be fully finalised yet, but it you look at the methods of OutlineEditor – things like:

    etc. etc.

(ignoring anything that starts with an underscore (it will be for internal use) you may get some idea of the richness and depth of the scripting interface.

I’m thinking it will be more productive to work in Python and manipulate TaskPaper files directly

Well, that’s possible – everyone’s mileage varies. I think, however, that when the documentation comes out, you may find that it automatically lifts a lot of weight which you would have to shift manually in Python.

(Amongst other things, it immediately gives you a particular array of lines (and all their properties) in exchange for any TP3 search path, including all the axes like descendant, following-sibling etc and all the filtering by tags and their values, and by line type).

And, of course, because of web browser competition, JavaScript is very highly optimised. It runs a lot faster than Python and Applescript : - )


Here is a quick TP3 translation of @derickfay’s Keynote script for TP2.

(Tested on Keynote 6.6.1 - Keynote’s applescript has changed, so Derick’s original script would need tweaking for TP2 too at this stage)

A few points:

  1. It assumes that a TP3 document, and an empty KeyNote presentation are both already open
  2. Copy paste the code into Script Editor (checking that it says AppleScript in the top left drop down, and click run.
  3. Here, I am calling the TP JS script from Applescript. It’s usually simpler really to do it from JavaScript for Applications, so that you don’t have a single page containing two languages. (Embedding JS in AS requires, for example, adding an escaping backslash before things like \n and \t for newline and tab).

Essentially, TP evaluates the JS script in the context of the front document, and returns a value.


-- This part of the code is a literal JavaScript string
-- Below, in AppleScript,
-- you will see a line in which this script is evaluated
-- in the context of the front TP3 document

set strTPCode to "
  function TP3Code(editor, options) {

    var oOutline = editor.itemBuffer.outline,
      lstProjects = oOutline.evaluateItemPath('//@type=project');

      function (oProj) {
        var lstTasks = oProj.evaluateItemPath('descendant::@type=task'),
          lstNotes = oProj.evaluateItemPath('descendant::@type=note');

        return {
          title: oProj.body.string.split(':')[0],

            function (oTask) {
              return oTask.body.string.slice(2).split('@')[0];

            function (oNote) {
              return oNote.body.string;

tell application "TaskPaper"
  tell front document
    set lstProjects to evaluate script strTPCode
  end tell
end tell

tell application "Keynote"
  tell document 1
    repeat with theProject in lstProjects
      tell (make new slide)
        set object text of text item 1 to title of theProject
        set object text of text item 2 to tasks of theProject
        set strNotes to notes of theProject
        if strNotes is not "" then set presenter notes to strNotes
      end tell
    end repeat
  end tell
end tell


You may already have seen this:


Thanks very much for these resources - I hadn’t seen that link.


Here, for comparison, is a translation of the TP to KeyNote script for use in Script Editor from JavaScript for Applications, rather than from AppleScript.

(Change the language selector at the top left of Script Editor to JavaScript)

A couple of notes on the code:

  1. The whole thing is optionally wrapped in an unnamed and immediately executed function. This makes all the variables local, rather than mixed in with all of JavaScript’s global library variables. One big advantage of doing this is that if we use the Safari JavaScript debugger in El Capitan, we will immediately see all our variables grouped together in the Local panel, rather than having to hunt for them among the globals.

  2. We’ve used the optional use strict line. It just checks that we have explicitly declared all our variables (a helpful habit) and gives us a few more useful error messages.

CODE for running from JavaScript for Applications (Yosemite onwards).

(function () {
  'use strict';

  function TaskPaperContextScript(editor, options) {

    var oOutline = editor.itemBuffer.outline;

    return oOutline.evaluateItemPath(
    ).map(function (oProj) {
      return {
        title: oProj.bodyString.split(':')[0],

        tasks: oProj.evaluateItemPath(
        ).map(function (oTask) {
          return oTask.bodyString.slice(2).split('@')[0];

        notes: oProj.evaluateItemPath(
        ).map(function (oNote) {
          return oNote.bodyString;

  var TaskPaper = Application("TaskPaper"),
    lstProjects = TaskPaper.documents[0].evaluate({
      script: TaskPaperContextScript.toString()

  var KeyNote = Application("Keynote"),
    kdoc = KeyNote.documents[0],

    oBulletSlide = kdoc.masterSlides['Bullets'],
    slides = kdoc.slides;

  // To experiment with Safari's JavaScript Debugger in El Capitan,
  // 1. uncomment the following line:

  // debugger;

  // 2. follow the instructions in the
  // OSX 10.11 JavaScript for Automation Release Notes


    function (dctProj) {

      var oSlide = KeyNote.Slide();

      if (!dctProj.title) oSlide.baseSlide = oBulletSlide;

      oSlide.defaultTitleItem.objectText = dctProj.title;

      oSlide.defaultBodyItem.objectText = dctProj.tasks;

      oSlide.presenterNotes = dctProj.notes;


(we can step through the execution of the code line by line, watching the value of variables change. We can also explore application objects, and see their methods and properties)


I suspect the new version will be more like FoldingText in its scripting support, but I’m one of those who is hoping the same level of Applescript support makes it into the new version eventually. Over the years that I’ve had TaskPaper 2, I’ve put together a lot of scripts that I trigger using Alfred, and it’s going to be a good deal of work to learn Javascript and recreate those for version 3. Applescript is challenging, but Javascript is much more opaque to look at for me as a nonprogrammer. Learning it and rewriting the scripts that I barely got working in v2’s Applescript is going to be a pain.

Assuming the scripting support is going to change – which it sounds like is happening – what would make the situation a lot better would be the ability to run TaskPaper 2 scripts at the same time TaskPaper 3 is open. That way I could use my existing scripts to add tasks from Alfred and change due dates without manually shutting down the new version first.


I think this should be possible right now. You can tell a specific version of an app with applescript like this:



Well…the upshot of this was that I’ve ended up moving all my serious task & project management to OmniFocus. I’d given it a try a few times before and kept coming back to TP, but it stuck this time – I realized that 90% of what I was doing with scripts in TP (around scheduling, deferring, customizing views, quick entry, etc.) was already baked into OF, or trivially easy with Applescript. (And for other reasons – notably the realization that TP may be too intrinsically unstructured (however agile it may be) for my work processes). So rather than rewrite a whole bunch of scripts for a new language on the same platform, I’ve ended up switching platforms…I’ll still definitely buy TP 3 but am probably not going to make the investment in scripting that I had anticipated.