How to insert an org-deadline from lisp with a warning period?

Question

The org documentation tells us that we can use special syntax for a deadline to have a warning period:

You can specify a different lead time for warnings for a specific deadlines using the following syntax. Here is an example with a warning period of 5 days ‘DEADLINE: <2004-02-29 Sun -5d>’. This warning is deactivated if the task gets scheduled and you set org-agenda-skip-deadline-prewarning-if-scheduled to t.

This is also supported by Orgzly, where I want to use it.

I'd assume that I could call org-deadline with this syntax but it just throws out the warning period:

(org-deadline nil "<2021-07-20 Tue -1d>")
   ;; => DEADLINE: <2021-07-20 Tue>

The documentation of org-deadline says

With two universal prefix arguments, prompt for a warning delay.

But this doesn't help me since I don't want to call interactively.

Since my entries get automatically updated by calendar sync I also have the requirement that the previous DEADLINE: entry has to get removed in this case, which is automatically handled by org-deadline. I assume I could handle this with org-remove-timestamp-with-keyword but I'm not sure which function to use for timestamp insertion if org-deadline doesn't support the warning period syntax.

How do I insert a deadline from elisp with a warning period?

Answer 1

Per NickD's comment this may well be a bug. In the meantime, it looks like this does what you're aiming for (or at least points you in the right direction):

(defun dunne//add-deadline-warning (w)
  (save-excursion
    (org-back-to-heading t)
    (let* ((regexp org-deadline-time-regexp))
      (if (not (re-search-forward regexp (line-end-position 2) t))
      (user-error "No deadline information to update")
    (let* ((rpl0 (match-string 1))
           (rpl (replace-regexp-in-string " -[0-9]+[hdwmy]" "" rpl0)))
      (replace-match
       (concat org-deadline-string
           " <" rpl
           (format " -%dd" w)
           ">") t t))))))

(defun dunne//add-deadline-with-warning (w)
  (org-deadline nil)
  (dunne//add-deadline-warning w))

I mined the contents of dunne//add-deadline-warning from the two-prefix case in org--deadline-or-schedule and ripped out the logic to handle existing deadlines / allow selecting a warning date.