Displaying deadline datestamp in todo agenda list?

[Karl Fogel <kfogel@red-bean.com>]

I'm using the DEADLINE keyword with TODO entries, and I'd like the DEADLINE date to be displayed as a datestamp next to each TODO item, when I list deadlined todo items.  In other words, I don't want to have to duplicate the DEADLINE timestamp as a timestamp on the TODO line itself in my Org Mode file -- since the timestamp is already present as the value of the DEADLINE keyword, can't Org Mode just use it?

Assume I have these Org Mode entries:

  * STARTED <2016-05-23> Org Mode scheduling test KIWI.
    DEADLINE: <2016-05-23>

  * TODO <2016-05-25> Org Mode scheduling test MELON.
    DEADLINE: <2016-05-25>

  * STARTED <2016-05-24> Org Mode scheduling test LIME.
    DEADLINE: <2016-05-24>

  * STARTED <2016-06-16> Org Mode scheduling test TARDIGRADE.
    SCHEDULED: <2016-05-23> DEADLINE: <2016-06-16>

And I have this custom code to bind "d" to show just the TODO items that have deadlines, in my `org-agenda' keymap:

  (defun ots-org-entry-skip-non-deadline ()
    "Return non-nil iff this org entry does not have the DEADLINE keyword."
    (if (not (org-entry-get (point) "DEADLINE"))
        (progn (outline-next-heading) (1- (point)))))
  
  (defvar ots-org-agenda-custom-commands-updated-p nil
    "If non-nil, we've already updated `org-agenda-custom-commands',
  so don't do it again.")
  
  ;; TBD: Oh, could use `org-add-agenda-custom-command' to do this.
  (unless ots-org-agenda-custom-commands-updated-p
    (unless (boundp 'org-agenda-custom-commands)
      (setq org-agenda-custom-commands ()))
    (setq org-agenda-custom-commands
          (cons '("d" "Deadlines and scheduled work" alltodo ""
                  ((org-agenda-skip-function 'ots-org-entry-skip-non-deadline)
                   ;; Add code here to control deadline date display?
                   (org-agenda-prefix-format '((agenda . " %i %-12:c%?-12t% s")
                                               (timeline . "  % s")
                                               (todo . " %i %-12:c %s")
                                               (tags . " %i %-12:c")
                                               (search . " %i %-12:c")))
                   (org-agenda-sorting-strategy '(deadline-up))))
                org-agenda-custom-commands))
    (setq ots-org-agenda-custom-commands-updated-p t))

Now if I do `M-x org-agenda' and then type `d', the four items are displayed like this:

  Global list of TODO items of type: ALL
  Available with ‘N r’: (0)[ALL] (1)TODO (2)STARTED (3)DONE
    OTS:           STARTED   Org Mode scheduling test KIWI.
    OTS:           STARTED   Org Mode scheduling test LIME.
    OTS:           TODO      Org Mode scheduling test MELON.
    OTS:           STARTED   Org Mode scheduling test TARDIGRADE.
  
But what I want is for each to show its corresponding DEADLINE datestamp, say like this:

  Global list of TODO items of type: ALL
  Available with ‘N r’: (0)[ALL] (1)TODO (2)STARTED (3)DONE
    OTS:         <2016-05-23>  STARTED   Org Mode scheduling test KIWI.
    OTS:         <2016-05-24>  STARTED   Org Mode scheduling test LIME.
    OTS:         <2016-05-25>  TODO      Org Mode scheduling test MELON.
    OTS:         <2016-06-16>  STARTED   Org Mode scheduling test TARDIGRADE.

I haven't found any way to make that happen.  After reading various Info pages, I started digging into the Org Mode code.  Now I'm looking at `org-agenda-get-todos' in org-agenda.el, which calls `org-agenda-format-item', passing "" as the first argument (EXTRA).  The doc string for `org-agenda-format-item' says:

  "EXTRA must be a string to replace the `%s' specifier in the prefix format."

I thought that maybe passing (org-agenda-get-deadlines) there instead of "" would supply `org-agenda-format-item' with the information it needs, but alas, that doesn't work and in fact the third call or so of `org-agenda-get-deadlines' raises an error.  (The doc strings for `org-agenda-get-todos and `org-agenda-get-deadlines' don't say all that much; it's quite possible I'm misunderstanding what the latter is for.)

However, if I pass a hardcoded non-empty value of EXTRA to the call to `org-agenda-format-item', it works.  That is, if I pass the hardcoded string "DEADLINE: <2016-05-24>" as the EXTRA argument in `org-agenda-get-todos', thus changing this line:

  txt (org-agenda-format-item "" txt level category tags t)

to this:

  txt (org-agenda-format-item "FISH" txt level category tags t)

...I get this result:

  Global list of TODO items of type: ALL
  Available with ‘N r’: (0)[ALL] (1)TODO (2)STARTED (3)DONE
    OTS:         FISH  STARTED   Org Mode scheduling test KIWI.
    OTS:         FISH  STARTED   Org Mode scheduling test LIME.
    OTS:         FISH  TODO      Org Mode scheduling test MELON.
    OTS:         FISH  STARTED   Org Mode scheduling test TARDIGRADE.

Okay, that's roughly what I expected, given that in my custom setting of `org-agenda-custom-commands', I set `org-agenda-prefix-format' so that the `todo' entry's value has "%s" at the end.

So this looks promising.  But now the question is, what is the Right Way to fetch the value of the DEADLINE keyword for the given TODO entry, at that point in the code, so I can pass that instead of "FISH"?  I had thought `org-agenda-get-deadlines' might do it, but that doesn't work.

Or am I going about this all wrong?  Hints welcome.  I hope it's clear what my goal is here, and I think it's a goal that others who use the DEADLINE keyword for TODO items might share.  This would be a great way to manage deadlines, if it worked :-).

Best regards,
-Karl