Lua: provide a function that describes an object

[tarleb]

The pandoc Lua interpreter already comes with most of the documentation that's available in doc/lua-filters. However, it cannot easily be accessed. It would be nice to have a function describe that can be called on any pandoc object and return useful information. For example, describe(pandoc.read) should print the documentation for that function.

Carried over from #6654.

[rnwst]

This is probably not feasible, but it would be really cool if lua-language-server could somehow be integrated into the REPL. This wouldn't just allow display of documentation similar to the proposed describe function, but also autocompletion and type checking (using pandoc-lua-types or similar). But probably much too difficult to implement - the REPL would effectively need to turn into a text editor with at least partial LSP support. But one can always dream!

luals.webm

[iandol]

@rnwst -- Lua remote debugging in VSCode should enable both the REPL alongside language server integration. What terminal editor and setup are you using? I think at least Neovim can support both debug adaptor protocol (DAP) for a lua remote debugger alongside their language server support?

[tarleb]

I guess what would already help to use pandoc with LSP would be the option to output type definitions for all functions, so that files like this can be auto-generated.

[rnwst]

@iandol -- That sounds very interesting. I am not a VSCode user, but I'd really like to give this a go. Could you provide more details about extensions that need to be installed etc. so I can replicate your setup? Currently, I'm using helix, and unfortunately there is no DAP support for Lua at the moment (but I'd be happy to give VSCode a go or go back to Neovim for debugging only).

@tarleb -- I've thought about that as well. Ideally, I'd like to be able to generate all of pandoc-lua-types from pandoc, rather than keeping it a separate project. It is the most complete implementation of pandoc Lua type definitions I could find, so could serve as a reference output if we decide to tackle this.

[iandol]

@rnwst -- I previously used zerobrane studio and mobdebug, instructions for that were formalised into this sample filter: https://github.com/pandoc/lua-filters/tree/master/lua-debug-example — but I did want to find a VSCode solution...

For VSCode, I had some problems with several lua debug filters. The most popular is actboy168 but no instructions for remote debugging and I never worked out what incantation was needed to get it to work. EmmyLua does have a remote debugger and (as it is a Chinese developer) I helped to translate English instructions - the extension debugger info is https://github.com/EmmyLua/VSCode-EmmyLua?tab=readme-ov-file#-debugging with the underlying debugger https://github.com/EmmyLua/EmmyLuaDebugger -- the debugger is bundled in EmmyLua and already precompiled for win/macos/linux; a command panel command injects code to modify the cpath to add the debug lib then the break. You run Pandoc and the lua code waits at the break and you attach with VSCode, you have full access to variables and REPL. EmmyLua has its own rust-based lua language server (it is in the credits section for lua-language-server, but not sure the relationship). If you could get pandoc-lua-types working with EmmyLua and remote debugging that would be wonderful.

Sorry to derail, hopefully the greater good of helping to write pandoc filters is shared with @tarleb's awesome describe suggestion...

[tarleb]

Ideally, I'd like to be able to generate all of pandoc-lua-types from pandoc, rather than keeping it a separate project.

@rnwst: If you're feeling adventurous and are ok with doing a bit of reverse engineering, then you could try do part of that with what we have now. All documentation is contained in the debug.getregistry()['HsLua docs'] table, so debug.getregestry()['HsLua docs'][pandoc.read] gets you the details of the pandoc.read function. There's no documentation yet for the structure that's returned, you'd have to infer it by inspecting the table, or by reading the file tools/update-lua-module-docs.lua.