Expose the Aegisub version to Lua as aegisub.version

[CoffeeFlux]

Scripts can currently only check aegisub.lua_automation_version, which has been 4 for years, so there's no way for them to tell whether newer API additions exist. DependencyControl in particular needs to guard on the upcoming CLI mode API (#670).

This adds aegisub.version, a table with:

Field	Value
string	The version string, e.g. "3.5.0" for a release or "9900-master-4e440a614" for a development build
release	Whether this was built from a release tag
build	The build number, which increases with each commit on master (0 when built from a shallow clone)
major, minor, patch	The version numbers, for X.Y.Z release tags only

Development builds have no semantic version, so they only get string and build. Prereleases such as 3.5.0-beta deliberately get no version numbers either, so that a check like major > 3 or (major == 3 and minor >= 5) doesn't pass for prereleases of that version.

For new APIs, checking for the function itself (if aegisub.foo then) is still the most robust guard; this is for cases where that isn't possible.

Tested on macOS with an autoload script that dumps the table:

Build	Result
Development build	string=9902-…-edabbb808 release=false build=9902, no numbers
Local v3.6.0 tag	string=3.6.0 release=true build=9902 major=3 minor=6 patch=0
Local v3.6.0-beta tag	string=3.6.0-beta release=true build=9902, no numbers

The automation API docs will need a matching entry.

🤖 Generated with Claude Code

[CoffeeFlux]

I need to fix up the actual values returned here, but we definitely need a richer way to fetch the version than just the automation API counter, unless we want to start bumping that any time we change anything. The motivation here in particular is wanting to add an API for DepCtrl to use, but needing a way to gate on it. I'm inclined to start by exposing less and seeing what's useful, so maybe the build number is the right place to start, along with the semver version set in meson?

[petzku]

While this does seem logical, is there a reason against scripts just checking for the specific features they expect to be present? e.g. petzku.Phantom checks if aegisub.gui exists before registering a macro that depends on it; Encode Clip similarly guards just the aegisub.gui.is_modified call.

EDIT: i somehow entirely glossed over this being mentioned in OP already, sorry. still, though: it's not clear to me what those cases are where you couldn't check for function existence (unless you're planning on significant backwards-compat breaks, i guess?)

[arch1t3cht]

I guess one case I can think of is where an API function that used to take three arguments is extended to take an optional fourth argument in a newer version, or if aegisub.dialog.display is extended to allow more fields in the dialog control table. Unless script authors explicitly relied on a fourth argument being a no-op before, this would be a backwards-compatible extension that's hard to detect without calling API functions.

Either way, exposing the version explicitly is just more idiomatic.

As for the specific API, the conclusion is that it looks good to me, but for future reference here's why I discarded some alternatives:

• Considering Aegisub's history with having multiple active forks, I thought about adding some extra free-form field where non-official versions of Aegisub could identify themselves, but the string already pretty much allows that, and any additional logic would just complicate things further. If it really becomes necessary, forks can always add extra keys to the table themselves. And the hope is to go back to a single upstream anyway.
• In the past I thought about adding some sort of subversioning to the lua API specifically (as opposed to the version of Aegisub as a whole). But exposing Aegisub's main version is probably a good idea anyway, at which point the Lua API version would not really bring too many additional benefits.

Regarding the code:

• The version string parsing should probably go into a version.h utility function? (Returning something like an std::optional<std::tuple<int, int, int>>)
• Most (I haven't checked in detail which) Lua API functions have documentation in automation/v4-docs. But there's also the Lua Reference on the website, and the two seem to diverge in some places. One day, those two sets of documentation should probably be compared and consolidated into one single source of truth, but that's a bigger project. But until then, it's probably best to at least add documentation for aegisub.version to the v4-docs.