add cli-tool `exist-exec`

[line-o]

exist-exec should execute queries in an existdb instance and the result should go to standard out

The query can be provided as a positional argument:

$ exist-exec '1 to 9'
1 2 3 4 5 6 7 8 9

The query can be in a file:

Contents of query.xq

1 to 9

$ exist-exec -f query.xq
1 2 3 4 5 6 7 8 9

[line-o]

Serialization and raw/ wrapped output may be useful options to provide.

[chakl]

I have 2 perfect use cases for exist-exec:

• quick ad-hoc commands like sm:passwd ("admin", "123")
• execution of a locally prepared XQuery stored in a file (eg to recursively adjust owner/permission on a DB subtree)

Being able to do this from the command line would be great. Without having to start GUI, browser and eXide first.

[line-o]

Yes @olaf your one-off example is better to showcase the value of exist-exec.

For your second example I am instantly thinking: "This should become exist-chmod and exist-chown"

[line-o]

But exist-exec will certainly be the one tool that does it all :)

[joewiz]

Should it be of any use, here are some approaches to executing XQuery on the command line:

• https://exist-db.org/exist/apps/doc/java-admin-client#execute
• https://docs.basex.org/wiki/Command-Line_Options#Standalone
• https://www.saxonica.com/documentation11/index.html#!using-xquery/commandline

[joewiz]

Examples:

% /Applications/eXist-db.app/Contents/Resources/bin/client.sh -x "current-dateTime()"
eXist version 6.0.1 (51506fc97a9e5bb55fdea71fc76def2c9d402886), Copyright (C) 2001-2022 The eXist-db Project
eXist-db comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions; for details read the license file.

Connecting to database...
Using config: /Applications/eXist-db.app/Contents/Resources/etc/conf.xml
Connected :-)
2022-02-11T16:29:16.935-05:00

% basex -q 'current-dateTime()'
2022-02-11T16:28:27.728-05:00

% java -cp $SAXON_CP net.sf.saxon.Query -qs:'current-dateTime()'
<?xml version="1.0" encoding="UTF-8"?>2022-02-11T16:28:56-05:00

[joewiz]

Also for reference, see xmlsh:

• https://github.com/xmlsh/xmlsh
• http://www.xmlsh.org/ModuleExist

[joewiz]

And for more inspiration, xidel:

• https://github.com/benibela/xidel
• https://www.videlibri.de/xidel.html#examples

[joewiz]

As long as we're at it, xqerl:

• https://github.com/zadean/xqerl
• https://zadean.github.io/xqerl/

[line-o]

@joewiz a great overview of CLIs 📖 From my first glance basex' looks very much like what we are after.

• -s with values "text", "adaptive", "json" for serialization (I believe we can and should drop the "method=")

• -b for binding variables used in conjunction with a query file

  -bv=example => declare variable $v external; $v

  we could do -b "v:map{ 'a': 'b' }"

  -b{URL}ln=value => declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln

  we might not need or be able to do that within exist

[line-o]

Some of the tools you mention are worth a look but designed for other use cases. xmlsh and xqerl provide REPLs and have therefore a very different design. xidel, while being a command line tool, is not interacting with a database but extracts data gathered from HTTP requests.

[joewiz]

I agree that BaseX's is a fitting model.

Re: serialization, method isn't the only option; there's also indentation, item-separator, omit-xml-declaration, html-version-number, etc. (See https://www.w3.org/TR/xslt-xquery-serialization-31/.)

Variable bindings are a great idea too. If util:eval is handling the requests on the eXist side, util:eval#3 takes an $external-variables parameter. A bit lower on the page, util:eval-and-serialize - which I believe is used in FusionDB Studio's server-side app fusion-studio-api for its XQuery evaluation - https://github.com/evolvedbinary/fusion-studio-api/blob/main/src/main/xar-resources/modules/query.xqm#L25-L57 - evaluates and serializes in one pass. But that variant lacks external variables. Indeed, fusion-studio-api would be a very nice candidate for any client-side utility looking to replace XML-RPC with REST.

[line-o]

Let's leave the XML-RPC replacement discussion out of this issue ;) Very valid points about serialization method just being one of the important parameters when it comes to serializing data from exist. We need to keep that in mind. As XML-RPC already provides variable bindings and at least is able to serialise to XML and JSON we should start with those already given options. The query itself can then leverage all serialization capabilities of exist.

[github-actions[bot]]

:tada: This issue has been resolved in version 4.8.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: