Multiline Macros

Multiline Macros

[Thuna]

[-- Attachment #1: Type: text/plain, Size: 2720 bytes --]

Here's a package which allows defining multiline Org macros via
#+BEGIN_MACRO ... #+END_MACRO: https://git.sr.ht/~thuna/org-multiline-macro
(I've also attached the elisp file here.)

The README should explain it (hopefully) well enough, but I'll also try
explain it here:

- To define a multiline macro, do
  
  #+BEGIN_MACRO foo
  Some text which will be inserted,
  plus some more in a line.
  #+END_MACRO
  
  and {{{foo}}} will be replaced by that body, newlines included.

- Arguments can be used in the text much the same way:
  
  #+BEGIN_MACRO license
  Copyright (C) $1 {{{author}}} <{{{email}}}>
  #+END_MACRO

- You can create an eval macro by starting the macro contents with
  `(eval':
  
  #+BEGIN_MACRO add-one
  (eval (number-to-string
         (1+ (string-to-number $1))))
  #+END_MACRO
  
  and arguments work here as usual as well.

- You can bypass the need for the leading `(eval' by giving the block an
  `:eval yes' parameter,

  #+BEGIN_MACRO add-one :eval yes
  (number-to-string
   (1+ (string-to-number $1)))
  #+END_MACRO

  This also allows more than one form.  All the forms are evaluated in
  order, and the last one's result is the result of the macro.

  #+BEGIN_MACRO add-one-loudly :eval yes
  (setq $1 (string-to-number $1))
  (message "adding one to: %d" $1)
  (number-to-string (1+ $1))
  #+END_MACRO

This is basically all this package does.  There are a couple known
problems, which are listed in the README but which I will also repeat
here for completeness:

- #+BEGIN_MACRO is not a distinct element type but a special block which
   I am hacking org-macro.el to handle.  This comes with its fair share
   of problems, export being the most relevant one that I know of right
   now.

  The fix is to just make it a distinct element, but I want to tackle
  that only after I have figured out all the other kinks.

- Macro blocks are not editable.  This is doable however there is an
  additional challenge in that they should be editable as emacs lisp
  source blocks when they are eval macro blocks (maybe not if they are
  the implicit kind [aka without the :eval yes]), and I have no idea
  where to even start with this.  Some help from people familiar with
  the relevant code would be appreciated.

- :eval no should technically be forcing a macro block as non-eval, even
  if it starts with `(eval'.  This is currently not the case, because I
  didn't want to duplicate the code which makes it so.

- Some testing for SETUPFILE following would be appreciated.  I did a
  *very* light test, but I don't know if it actually works or not.  I
  just copied the code from a different function which handles it.

All thoughts, ideas, suggestions, and bug reports are welcome.


[-- Attachment #2: org-multiline-macro.el --]
[-- Type: application/x-emacs-lisp, Size: 6003 bytes --]

Re: Multiline Macros

[Ihor Radchenko]

Thuna <thuna.cing@gmail.com> writes:

> Here's a package which allows defining multiline Org macros via
> #+BEGIN_MACRO ... #+END_MACRO: https://git.sr.ht/~thuna/org-multiline-macro
> (I've also attached the elisp file here.)

Thanks for sharing!

> ...
> All thoughts, ideas, suggestions, and bug reports are welcome.

Your package sounds like something that might be incorporated into Org
mode itself - more advanced uses of Org macros often hit a barrier that
complex macros are hard to write.

On the other hand, making macros more sophisticated feels like
re-inventing the multiple other templating systems available for Elisp,
or even for Org mode itself (think about capture templates).

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>