Lua filters: diff between block:walk and pandoc.walk_block?

Lua filters: diff between block:walk and pandoc.walk_block?

[Jim Pryor]

[-- Attachment #1.1: Type: text/plain, Size: 1760 bytes --]

In the Lua filter API, many (all?) Block elements have a method `walk`. 
There's also a function `pandoc.walk_block`. (Similarly for Inline elements 
and the function `pandoc.walk_inline`.)

I'm having a devil of a time figuring out the difference between these 
pairs of functions. Searching the docs and this list hasn't helped.

This git commit does purport to explain the difference:

> commit fa643ba6d78fd97f0a779840dca32bfea3b296f8
> Author: Albert Krewinkel <albert@...de>
> Date:   Mon Dec 6 16:55:19 2021 +0100
> ...
> - `*walk*` methods are added to `Block` and `Inline` values; the methods
> are similar to `pandoc.utils.*walk*_block` and `pandoc.utils.*walk*_inline`, 
but 
> apply to filter also to the element itself, and therefore return a list 
of element 
> instead of a single element.

However, from my testing (with pandoc v2.19, custom cabal build using 
-flua53, so with hslua 2.1.0), what's suggested in that commit message 
doesn't seem (anymore?) to be true. If I have a `function Block(elem) ...`, 
neither `elem:walk(filter)` nor `pandoc.walk_block(elem, filter)` seem to 
apply the filter to elem itself. And neither seems to return a List; they 
just return a single Block element.

Do these functions behave exactly the same? Or are there situations where 
you'd want to/have to use one of them rather than the other?

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/55582578-0af3-4e8f-b79a-fcd612f3cf20n%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 2299 bytes --]

Re: Lua filters: diff between block:walk and pandoc.walk_block?

[Albert Krewinkel]

Hi Jim,

Jim Pryor <jim.pryor.nyu-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:

> In the Lua filter API, many (all?) Block elements have a method `walk`.
> There's also a function `pandoc.walk_block`. (Similarly for Inline
> elements and the function `pandoc.walk_inline`.)
>
> I'm having a devil of a time figuring out the difference between these
> pairs of functions. Searching the docs and this list hasn't helped.
>
> This git commit does purport to explain the difference:
>
> [...]
>
> > - `walk` methods are added to `Block` and `Inline` values; the methods
> > are similar to `pandoc.utils.walk_block` and
> > `pandoc.utils.walk_inline`, but
> > apply to filter also to the element itself, and therefore return a
> > list of element instead of a single element.
>
> However, from my testing (with pandoc v2.19, custom cabal build using
> -flua53, so with hslua 2.1.0), what's suggested in that commit message
> doesn't seem (anymore?) to be true.

You are right, this commit message is outdated. We decided to return a
single element instead.

> If I have a `function Block(elem) ...`, neither `elem:walk(filter)`
> nor `pandoc.walk_block(elem, filter)` seem to apply the filter to elem
> itself. [...]

The reason for that is that, if we apply the a function to the `elem`,
the result may be a list of elements. That's often not what we want
though, and most people won't expect. Of course, the current behavior is
a bit confusing as well -- it's just in the nature of `walk`. You can
get the list value with `pandoc.Blocks{elem}:walk(filter)`.

> Do these functions behave exactly the same? Or are there situations
> where you'd want to/have to use one of them rather than the other?

They are *almost* the same, with two differences:

1. `walk_block` will convert its argument to a Block element if it isn't
   a Block; we could pass in a string or an Inline element, and it would
   still work.

2. `elem:walk()` supports filters with topdown traversal order,
   `walk_block` doesn't.

The `walk_block` and `walk_inline` functions exist for historical
reasons -- we will probably deprecate and remove them in the future.


-- 
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124