It is easy to figure out wich value a known constant has at runtime - you use it, you get the value.
However it is not easy to figure out wich value corresponds to wich Constant (Global Table Key)
This library deals with the plumbing: It goes over the entire global table and does string pattern matching. It then returns those Constant names and thier values in a easy to itterate over, int indexed table.
For added convinience it can also create you a value-indexed table from those results.

LibConstantMapper API
:getDataByMapping(map_name, rebuildCache)

Returns

If a map of this name exists it will do 1-2 things:
If no cache exists or rebuidChache is true, it will build the cache from scratch by itterating over the global table, sort the result by value first and then store it in the cache.
In any case it will return a deep copy of whatever the cache contains now.

Arguments

map_name
Name of the mapping. As defined durign registering and retrieved by listMaps
(optional)rebuildCache
If this parameter is true an existing cache for this mapping will be discarded and the data will be read in from the global table again.

Note: The prefered way of getting data since implemented in 0.2.


:getMappedData(pattern [, exclude])

Returns

A well formed array containing all the Keys and thier values that match pattern, but do not match exclude. Due to the nature of the source and extraction, no guarantees over the order of the key/value pairs or thier uniqueness of each value can be given (that is entirely up to the data, what order pairs uses today and the two patterns given).

Arguments

pattern
The string pattern that has to match for the key/value to land in the output
exclude
(Optional) another string pattern. If an global table entry matches the pattern and the exclude pattern, it is not included in the output (see the example case below)

:getValIndexedKeyList(input [, noDuplicateAssertion])

Returns

A table that uses the Values's as indexes and the keys as values. Thus allows quick value->key mapping. The input table is itterated via ipairs, so the result should be deterministic (if you should be using the noDuplicateAssertion override).
No guarantee that the keys are consecutive can be made (this depends entirly on the input).

Throws

An assertion error if the same a value has already been used as index. This error implies that something in the input is wrong - usually that the pattern/exclude combo is somehow not excluding everything it should. Thus resulting in the same value being more then once in the input table.

Arguments

input
The return values of a getDataByMapping() or getMappedData() should be given here.
But every table that can be itterated over with ipairs and contains nested tables with key&value indexes should be just as valid.

noDuplicateAssertion
Normally the function will throw an exception if it finds the same value a second time (and thus tries to write the same index again). If this is set to true, it will instead ignore the problem and overwrite the old value of the index.
Use at own risk: Duplicate values mean either you should not use this function on the data in the first place, or that something with the retrieval patterns is wrong. Supressing the assertion could lead to unforseen consequences down the road.

Maps
Having the right pattern/exclude pair to feed to getMappedData can be an issue. So I provided several pre-written patterns to feed it. Each of those is called a "map". The maps are provided as part of the addons main file.
Additional maps can be registered at runtime.

:listMaps()

Returns

The names of all the currently registered maps, wheter they are defined with the library or registered by other code.

:addMap(map, pattern [, exclude])

Arguments

map
A unique string that identifies this mapping. If a map with this value already exists, it is overwritten and it's cached values are discared.
pattern
The pattern associated with this map
exlcude
(Optional)The exclude pattern associated with this map

:getMap(map)

Returns

A table containing the pattern and exlucde entires under correspondingly named keys.

Arguments
map

The string that identifies the map, as given under addMap

Example Case (Chat Categories)
Unified Chat Tabs has been using the int ID of the categoreis during storage, but I realised this was flawed: If the order of categories changed after a update it would assign the wrong color data to the categories and enable/disable the wrong categories on each tab.
I needed to know wich Constant Name/Global Table Key related to wich Chat Category Number as I intended to use the Constants Name/Key during storage. And I needed that data at runtime, not compile time (after all I expected them to change with updates and the code had to react instantly).
The data looked like this at the time:
CHAT_CATEGORY_COMBAT_ALLIANCE_POINTS = 48
CHAT_CATEGORY_COMBAT_BATTLE_TOKENS = 46
CHAT_CATEGORY_COMBAT_BLOCK_ABSORBED_DEFEND = 58
CHAT_CATEGORY_COMBAT_DEATH = 61
CHAT_CATEGORY_COMBAT_DIRECT_DAMAGE = 51
CHAT_CATEGORY_COMBAT_DIRECT_HEAL = 53
...
CHAT_CATEGORY_HEADER_CHANNELS = 1
CHAT_CATEGORY_HEADER_COMBAT = 45
CHAT_CATEGORY_HEADER_GUILDS = 10
...
CHAT_CATEGORY_ZONE = 6
CHAT_CATEGORY_ZONE_ENGLISH = 20
CHAT_CATEGORY_ZONE_FRENCH = 21
CHAT_CATEGORY_ZONE_GERMAN = 22

Wich added the issue that it contained 3 entries I did not want - CHAT_CATEGORY_HEADER - because they were duplicate values and unrelated to my case.
Garkin pointed me out that if I find all that match "^CHAT_CATEGORY_" but exclude all that match "^CHAT_CATEGORY_HEADER" I would get exactly the data I wanted.

thus calling
:getMappedData("^CHAT_CATEGORY_", "^CHAT_CATEGORY_HEADER")
get's you an array looking like this (order is not guaranteed):
[1]

["key"] = "CHAT_CATEGORY_COMBAT_ALLIANCE_POINTS"
["value"] = 48

[2]

["key"] = "CHAT_CATEGORY_COMBAT_BATTLE_TOKENS"
["value"] = 46

[3]

["key"] = "CHAT_CATEGORY_COMBAT_BLOCK_ABSORBED_DEFEND"
["value"] = 58

[4]

["key"] = "CHAT_CATEGORY_COMBAT_DEATH"
["value"] = 61

[5]

["key"] = "CHAT_CATEGORY_COMBAT_DIRECT_DAMAGE"
["value"] = 51

[6]

["key"] = "CHAT_CATEGORY_COMBAT_DIRECT_HEAL"
["value"] = 53

...
[38]

["key"] = "CHAT_CATEGORY_ZONE"
["value"] = 6

[39]

["key"] = "CHAT_CATEGORY_ZONE_ENGLISH"
["value"] = 20

[40]

["key"] = "CHAT_CATEGORY_ZONE_FRENCH"
["value"] = 21

[41]

["key"] = "CHAT_CATEGORY_ZONE_GERMAN"
["value"] = 22

Feeding it to getMappedData would get you a table looking like this (keys will not be continous, as there are only 41 Constants/Keys that map to channel ID's. But there are 61 Channel ID's (so 20 remain unused)):
[1] = "CHAT_CATEGORY_SAY"
[2] = "CHAT_CATEGORY_YELL"
[3] = "CHAT_CATEGORY_WHISPER_INCOMING"
[4] = "CHAT_CATEGORY_WHISPER_OUTGOING"
...
[58] = "CHAT_CATEGORY_COMBAT_BLOCK_ABSORBED_DEFEND"
[59] = "CHAT_CATEGORY_COMBAT_RESIST"
[60] = "CHAT_CATEGORY_COMBAT_OTHER"
[61] = "CHAT_CATEGORY_COMBAT_DEATH"