Walk and deep copy in Lua filters

Walk and deep copy in Lua filters

[Bastien DUMONT]

Hi all,

I just discovered by chance that the method walk returns a deep copy of the passed object, leaving the original object untouched. See the following test case:

```deep-copy.lua
local orig = pandoc.Emph({ pandoc.Str('one'), pandoc.Space(), pandoc.Str('two') })
local copy = orig:walk({})
table.insert(copy.content, pandoc.Space())
table.insert(copy.content, pandoc.Str('three'))
assert(#orig.content == 3)
assert(#copy.content == 5)
```
`pandoc -L deep-copy.lua <<< ''` should return nothing (i.e. no error).

However, in the documentation, it is only stated that the “Result” is the “filtered block/inline element”: from this indication alone, it seems not obvious to me whether the passed object is changed (as it is customary with functions operating on Lua tables or userdata) or the method returns a new object.

To be clear, I am very happy with the current behaviour, for it gives a very simple means to get several deep copies of an objet and to manipulate them separately without having to regenerate the original object (e.g. via rather expensive calls to `pandoc.read()`). Nevertheless, since it is not really documented, can it be considered to be deliberate and stable? If this is the case, could it be possible to make explicit in the documentation, under the header “Result”, that the original block or inline element is left unchanged?

-- 
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/YqXK0Gyv%2B18RwQd1%40localhost.

Re: Walk and deep copy in Lua filters

[BPJ]

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

Why not use the clone method to get a copy? That said I like that walk
modifies a copy.

The only builtin Lua function which alters its argument in place I can
think of OTTOMH is table.sort, which is a gotcha because strings are
immutable so I always forget that table.sort modifies in place.

Den sön 12 juni 2022 13:18Bastien DUMONT <bastien.dumont-VwIFZPTo/vqsTnJN9+BGXg@public.gmane.org> skrev:

> Hi all,
>
> I just discovered by chance that the method walk returns a deep copy of
> the passed object, leaving the original object untouched. See the following
> test case:
>
> ```deep-copy.lua
> local orig = pandoc.Emph({ pandoc.Str('one'), pandoc.Space(),
> pandoc.Str('two') })
> local copy = orig:walk({})
> table.insert(copy.content, pandoc.Space())
> table.insert(copy.content, pandoc.Str('three'))
> assert(#orig.content == 3)
> assert(#copy.content == 5)
> ```
> `pandoc -L deep-copy.lua <<< ''` should return nothing (i.e. no error).
>
> However, in the documentation, it is only stated that the “Result” is the
> “filtered block/inline element”: from this indication alone, it seems not
> obvious to me whether the passed object is changed (as it is customary with
> functions operating on Lua tables or userdata) or the method returns a new
> object.
>
> To be clear, I am very happy with the current behaviour, for it gives a
> very simple means to get several deep copies of an objet and to manipulate
> them separately without having to regenerate the original object (e.g. via
> rather expensive calls to `pandoc.read()`). Nevertheless, since it is not
> really documented, can it be considered to be deliberate and stable? If
> this is the case, could it be possible to make explicit in the
> documentation, under the header “Result”, that the original block or inline
> element is left unchanged?
>
> --
> 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/YqXK0Gyv%2B18RwQd1%40localhost
> .
>

-- 
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/CADAJKhA9JY8Xm0X6SFe_2E8DBCwcdtSctuMgKWn2EoYC4gQyCQ%40mail.gmail.com.

[-- Attachment #2: Type: text/html, Size: 3580 bytes --]

Re: Walk and deep copy in Lua filters

[Albert Krewinkel]

Bastien DUMONT <bastien.dumont-VwIFZPTo/vqsTnJN9+BGXg@public.gmane.org> writes:

> I just discovered by chance that the method walk returns a deep copy
> of the passed object, leaving the original object untouched. [...]
>
> [...] Nevertheless, since it is not really documented, can it be
> considered to be deliberate and stable? If this is the case, could it
> be possible to make explicit in the documentation, under the header
> “Result”, that the original block or inline element is left unchanged?

Yes, this is deliberate and won't change. A PR to improve the docs would
be very welcome.


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

-- 
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/87tu8pyaur.fsf%40zeitkraut.de.

Re: Walk and deep copy in Lua filters

[Bastien DUMONT]

OK, thanks! I will submit a pull request tomorrow.

For BPJ: `clone()` returns a deep copy when called on objects, so it could be used in the example I provided. However, they return a shallow copy when called on Lists, which is my real use case. As you can see, the following chunk throws an error:

```
local orig = pandoc.Emph({ pandoc.Str('one'), pandoc.Space(), pandoc.Str('two') }).content
local copy = orig:clone()
copy[1].text = 'first'
assert(orig[1].text == 'one')
```

(In Lua, almost all methods in `table` modify their first argument and return a pointer to it.)

Le Sunday 12 June 2022 à 08:41:06PM, Albert Krewinkel a écrit :
> 
> Bastien DUMONT <bastien.dumont-VwIFZPTo/vqsTnJN9+BGXg@public.gmane.org> writes:
> 
> > I just discovered by chance that the method walk returns a deep copy
> > of the passed object, leaving the original object untouched. [...]
> >
> > [...] Nevertheless, since it is not really documented, can it be
> > considered to be deliberate and stable? If this is the case, could it
> > be possible to make explicit in the documentation, under the header
> > “Result”, that the original block or inline element is left unchanged?
> 
> Yes, this is deliberate and won't change. A PR to improve the docs would
> be very welcome.
> 
> 
> -- 
> Albert Krewinkel
> GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124
> 
> -- 
> 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/87tu8pyaur.fsf%40zeitkraut.de.

-- 
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/YqZPhvGeWIZaIPct%40localhost.