Implement EXPath Binary Module 4.0

[joewiz]

Summary

• Implements 23 of 24 functions from the EXPath Binary Module 4.0 specification
• Only bin:infer-encoding is deferred (requires XQuery 4.0 record types)
• All functions adapted for XQuery 3.1 compatibility (enum → xs:string, union types → xs:base64Binary)

What Changed

New Files (8 source + 1 test)

• BinaryModule.java — Module registration (http://expath.org/ns/binary, prefix bin)
• BinaryModuleErrorCode.java — 8 spec-defined error codes
• BinaryModuleHelper.java — Shared utilities (binary data extraction, creation, endianness)
• BinaryConversionFunctions.java — bin:hex, bin:bin, bin:octal, bin:to-octets, bin:from-octets
• BinaryBasicFunctions.java — bin:length, bin:part, bin:join, bin:insert-before, bin:pad-left, bin:pad-right, bin:find
• BinaryTextFunctions.java — bin:decode-string, bin:encode-string
• BinaryPackingFunctions.java — bin:pack-double, bin:pack-float, bin:pack-integer, bin:unpack-double, bin:unpack-float, bin:unpack-integer, bin:unpack-unsigned-integer
• BinaryBitwiseFunctions.java — bin:or, bin:xor, bin:and, bin:not, bin:shift
• BinaryModuleTest.java — 74 JUnit tests

Modified Files

• exist-distribution/src/main/config/conf.xml — Register module
• extensions/expath/src/test/resources-filtered/conf.xml — Register module for tests

Spec Reference

• EXPath Binary Module 4.0

XQTS Results

All QT4 binary module test sets pass with zero failures:

Test Set	Tests	Failures	Errors
bin-and	11	0	0
bin-bin	19	0	0
bin-decode-string	79	0	0
bin-encode-string	15	0	0
bin-find	13	0	0
bin-from-octets	9	0	0
bin-hex	21	0	0
bin-infer-encoding	33	0	0
bin-insert-before	17	0	0
bin-join	8	0	0
bin-length	5	0	0
bin-not	5	0	0
bin-octal	18	0	0
bin-or	11	0	0
bin-pack-double	26	0	0
bin-pack-float	24	0	0
bin-pack-integer	56	0	0
bin-pad-left	13	0	0
bin-pad-right	13	0	0
bin-part	15	0	0
bin-shift	20	0	0
bin-to-octets	6	0	0
bin-unpack-double	27	0	0
bin-unpack-float	27	0	0
bin-unpack-integer	36	0	0
bin-unpack-unsigned-integer	35	0	0
bin-xor	12	0	0
Total	574	0	0

Note on XQTS Coverage

The XQTS results above were obtained using a development version of exist-xqts-runner with added support for XPath/XQuery 4.0 spec dependencies (XP40, XQ40). Running the XQTS binary module test sets requires eXist-db/exist-xqts-runner#45.

Test Plan

• 74 JUnit tests pass (unit tests)
• 574/574 XQTS QT4 binary module tests pass (27/27 test sets)
• Existing expath extension tests pass (no regressions)

Closes #6100

🤖 Generated with Claude Code

[joewiz]

Migration crosswalk: util: → bin: for binary operations

The new EXPath Binary Module (bin:) provides spec-compliant alternatives to several eXist-specific util: functions for binary processing. The following crosswalk table maps existing util: functions to their bin: equivalents (or composite expressions), to help users who might consider switching from eXist implementation-specific functions to the interoperable EXPath spec.

eXist util: function	EXPath bin: equivalent	Notes
util:binary-to-string($bin)	bin:decode-string($bin)	Both default to UTF-8
util:binary-to-string($bin, $enc)	bin:decode-string($bin, $enc)	Direct equivalent
util:string-to-binary($str)	bin:encode-string($str)	Both default to UTF-8
util:string-to-binary($str, $enc)	bin:encode-string($str, $enc)	Direct equivalent
util:base64-encode($str)	string(bin:encode-string($str))	util: operates on strings (text→base64 text); bin: returns xs:base64Binary, so cast/serialize to get the base64 string representation
util:base64-decode($str)	bin:decode-string(xs:base64Binary($str))	util: accepts a base64-encoded string; bin: accepts xs:base64Binary, so cast the string first
util:base64-encode-url-safe($str)	bin:encode-string($str) => string() => translate("+/=", "-_")	RFC 4648 §5 URL-safe encoding. See qt4cg/qtspecs#2381 for discussion of adding native support to a future spec.

Note: util:binary-doc, util:binary-doc-available, util:is-binary-doc, and util:binary-doc-content-digest are database-level resource accessors with no EXPath Binary Module counterpart.

🤖 Co-authored with Claude Code

[line-o]

I am thinking if this should not rather be a installable package.

[joewiz]

[This response was co-authored with Claude Code. -Joe]

@line-o Agreed — a standalone installable package is the right approach. We've already moved in this direction with five other EXPath/EXQuery modules:

• exist-crypto — EXPath Crypto (replaces the stale community XAR)
• exist-http-client — EXPath HTTP Client (native Java HttpClient)
• exist-request — EXQuery Request Module (28 functions)
• exist-zip — EXPath ZIP Module (native java.util.zip)
• exist-lsp — LSP for XQuery editors

All use a uniform convention: http://exist-db.org/pkg/* package names, exist-* abbrevs, 0.9.0-SNAPSHOT pre-release versions, installable on eXist 6.x+.

The EXPath Binary Module would follow the same pattern — extract from extensions/expath/ into a standalone exist-binary XAR. Same namespace (http://expath.org/ns/binary), same functions, zero external dependencies. The exist-lsp project is the template.

Happy to prepare this if you'd like.

[joewiz]

[This response was co-authored with Claude Code. -Joe]

Following the community's suggestion, this module has been extracted into a standalone EXPath package: https://github.com/joewiz/exist-binary

Same namespace (http://expath.org/ns/binary), same functions, zero external dependencies. Installable on eXist 6.x+ via xst package install. The standalone package follows the same convention as exist-crypto, exist-zip, exist-http-client, exist-request, and exist-lsp.

This PR can be closed in favor of the standalone package approach.

[joewiz]

Closing in favor of the standalone package approach at https://github.com/joewiz/exist-binary.