What is a use case for the pandoc.cli.parse_options Lua function?

[rnwst]

In the Lua filter documentation, I saw the function pandoc.cli.parse_options. Its behaviour is described as follows:

Parses command line arguments into pandoc options. Typically this function will be used in stand-alone pandoc Lua scripts, taking the list of arguments from the global arg.

What would be an example of a "standalone pandoc Lua script"? My current understanding is that the pandoc Lua modules are only available from within Lua filters or custom readers/writers, and cannot be required in standalone Lua scripts outside of pandoc. Therefore, I cannot think of a scenario where command line arguments could be provided to a script that utilises pandoc Lua modules.
(Perhaps @tarleb can answer this one - apologies for bothering you with this!)

[jgm]

Using pandoc-lua or pandoc lua you can run a standalone script in the pandoc environment.
Example test.lua:

local opts = pandoc.cli.parse_options(arg)

for k,v in pairs(opts) do
  print(k,v)
end

Now try

pandoc lua test.lua -f rst -t latex --trace

[rnwst]

That's amazing!! Is this capability documented anywhere? I can't find anything on that in the User's Guide or the Lua filters documentation (though it is entirely possible I overlooked it). If it isn't documented yet I'm happy to submit a PR.

I can see this being useful for all sorts of things, but one application I'm particularly excited about is running tests for Lua filters. Up to now I would've done this by wrapping all tests in a filter function inside of a Lua filter, which is not very elegant. Instead, the test script can be executed directly with pandoc lua with no need to wrap the tests in a filter function.

[rnwst]

My bad, I just found the relevant section in the manual: https://pandoc.org/MANUAL.html#running-pandoc-as-a-lua-interpreter
I think it might be useful to mention this in the Lua filters documentation as well, perhaps in the context of running tests. @jgm if you agree I'll prepare a corresponding PR.

[jgm]

sure, go ahead (if you can say how it's useful for testing filters -- I'm not sure about that)