SkyrimForge.com Wiki

Repositories / Repository keyword substitutions

r7

When repositories are packaged, certain keyword substitutions take place on text files.

Note: Anything for XML also applies to .mod files (Warhammer Online's XML mod file).

Simple replacements

@file-revision@
Turns into the current revision of the file in integer form. e.g. 1234 Note: does not work for git
@project-revision@
Turns into the highest revision of the entire project in integer form. e.g. 1234 Note: does not work for git
@file-hash@
Turns into the hash of the file in hex form. e.g. 106c634df4b3dd4691bf24e148a23e9af35165ea Note: does not work for svn
@project-hash@
Turns into the hash of the entire project in hex form. e.g. 106c634df4b3dd4691bf24e148a23e9af35165ea Note: does not work for svn
@file-abbreviated-hash@
Turns into the abbreviated hash of the file in hex form. e.g. 106c63 Note: does not work for svn
@project-abbreviated-hash@
Turns into the abbreviated hash of the entire project in hex form. e.g. 106c63 Note: does not work for svn
@file-author@
Turns into the last author of the file. e.g. ckknight
@project-author@
Turns into the last author of the entire project. e.g. ckknight
@file-date-iso@
Turns into the last changed date (by UTC) of the file in ISO 8601. e.g. 2008-05-01T12:34:56Z
@project-date-iso@
Turns into the last changed date (by UTC) of the entire project in ISO 8601. e.g. 2008-05-01T12:34:56Z
@file-date-integer@
Turns into the last changed date (by UTC) of the file in a readable integer fashion. e.g. 20080501123456
@project-date-integer@
Turns into the last changed date (by UTC) of the entire project in a readable integer fashion. e.g. 2008050123456
@file-timestamp@
Turns into the last changed date (by UTC) of the file in POSIX timestamp. e.g. 1209663296
@project-timestamp@
Turns into the last changed date (by UTC) of the entire project in POSIX timestamp. e.g. 1209663296
@project-version@
Turns into an approximate version of the project. The tag name if on a tag, otherwise it's up to the repo. SVN returns something like "r1234", Git returns something like "v0.1-873fc1", Mercurial returns something like "r1234".

Debug replacements

These occur based on filetype, as they tend to tie into the comment system for the file.

The insides aren't removed so that line numbers stay the same, they just cause them to be commented out.

Lua

--@debug@ and --@end-debug@.
Turn into --[===[@debug and --@end-debug]===].
--[===[@non-debug@ and --@end-non-debug@]===].
Turn into --@non-debug@ and --@end-non-debug@.

XML

<!--@debug@--> and <!--@end-debug@-->.
Turn into <!--@debug and @end-debug@-->.
<!--@non-debug@ and @end-non-debug@-->.
Turn into <!--@non-debug@--> and <!--@end-non-debug@-->.

Alpha replacements

These occur based on filetype, as they tend to tie into the comment system for the file.

The insides aren't removed so that line numbers stay the same, they just cause them to be commented out.

These occur from packages created not from tags, i.e. alpha packages.

This is useful to put extra debugging information that you want your alpha testers to have, but don't want to appear in release versions.

Lua

--@alpha@ and --@end-alpha@.
Turn into --[===[@alpha@ and --@end-alpha@]===].
--[===[@non-alpha@ and --@end-non-alpha@]===].
Turn into --@non-alpha@ and --@end-non-alpha@.

Example:

--@alpha@
assert(everythingIsOkay())
--@end-alpha@

This would make it so the assert takes place in dev mode and alpha zips, but doesn't bother for release and beta.

XML

<!--@alpha@--> and <!--@end-alpha@-->.
Turn into <!--@alpha and @end-alpha@-->.
<!--@non-alpha@ and @end-non-alpha@-->.
Turn into <!--@non-alpha@--> and <!--@end-non-alpha@-->.

No-lib replacements

These occur based on filetype, as they tend to tie into the comment system for the file.

The insides aren't removed so that line numbers stay the same, they just cause them to be commented out.

These only occur on packages marked as -nolib.

TOC

#@no-lib-strip@ and #@end-no-lib-strip@.
Turn into # stripping libraries and # done stripping libraries, as well as adding a # to the beginning of each line in-between.

XML

<!--@no-lib-strip@--> and <!--@end-no-lib-strip@-->.
Turn into <!--@no-lib-strip and @end-no-lib-strip@-->.

Localization

If you've decided to use the localization app, you can inject the translations automatically with the following substitution:

@localization(locale="enUS", format="lua_table")@

or some derivation thereof.

The example turns into something that looks like { ["Some key"] = "Some value" }.

Arguments

Note: only locale and format are required.

locale
one of "enUS", "frFR", "deDE", etc. You'll see a full list of each possible locale on your project's localization page.
format
if "lua_table", then it will look like { ["Some key"] = "Some value" }
if "lua_additive_table", then it will look like L["Some key"] = "Some value"
handle-unlocalized - what to do when you have an unlocalized string.
if "english", then it will output the english value.
if "comment", then it will output the english value, but comment it out the line.
if "blank" (default), then it will output "", but comment out the line.
if "ignore", then no line will be printed out.
escape-non-ascii - whether to escape non-ASCII (unicode) strings as escape strings instead of raw UTF-8
if false (default), then you get a string like "Über"
if true, then you get a string like "\195\156ber"
prefix-values
This will prefix all value strings the given string. For WoW, the default is nothing. For WAR, since it is unicode-aware, its prefix is "L". e.g. "Hello" vs. L"Hello"
table-name - used in format="lua_additive_table" only.
This defines the name of the table to add to. For WoW, the default is "L". For WAR, the default is "T".

Example usage

Here's an example of AceLocale-3.0 usage with this new system:

enUS.lua


local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "enUS", true
--@debug@
, true
--@end-debug@
)

--@localization(locale="enUS", format="lua_additive_table")@

deDE.lua

local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "deDE")
if not L then return end

--@localization(locale="deDE", format="lua_additive_table")@

You're probably wondering about the @debug@ statement, but that's so that in development, you pass in an argument into :NewLocale that makes it so nonexistant translations don't error.

The resultant code will look like this:

enUS.lua

local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "enUS", true
--[===[@debug@
, true
]===]
)

L["Hello, World!"] = "Hello, World!"
L["How are you today?"] = "How are you today?"

deDE.lua local L = LibStub("AceLocale-3.0"):NewLocale("MyAddon", "deDE") if not L then return end

L["Hello, World!"] = "Hallo, Welt!" -- L["How are you today?"] = "" </code></pre>