API types

From Wowpedia
(Redirected from API Types)
Jump to: navigation, search

The World of Warcraft API is constructed in lua, with an accompanying XML definition, in which everything is either a basic type, function or table. Tables are flexible objects that the API uses to define rather distinct WoW-specific "complex" types.

Basic Types

Lua

Lua variables are not formally assigned a type, but rather dynamically become a type when a value is assigned.[1] World of Warcraft uses seven basic types from Lua.

Type Description Implicit casting Explicit casting Special Functions
nil
absence of any value
boolean
true or false, historically represented as 1 or nil nil → false; any other value → true x = not not x
number
integer or floating-point "1" → 1; "1.23" → 1.23 returns a number or nil Math, Bitlib
string
array of UTF-8 characters 1.23 → "1.23"; true → "true" returns "nil", "function: x", etc. String
function
reference to executable code
table
reference to an association of key/value pairs Table
userdata
reference to an object implemented in C
The original WoW API was written in Lua v4 that had no boolean type; the formal definition being introduced in Lua 5.0
The Lua-based WoW API rides over a game engine written in C

XML

Although XML has 19 primitive data types,[2] FrameXML only uses five corresponding to Lua types:

Type Description Runtime (Lua)
xs:nil missing or empty attribute varies by the default value of each attribute
xs:boolean "true" or "false" usually becomes boolean
xs:int "1" usually becomes number
xs:float "1.23" usually becomes number
xs:string "abc" usually becomes a string or a reference (ie. _G["name"])

Complex World of Warcraft API Data Types

For the complete list of complex types, see Category:API types.

The API encodes several complex information using tables and strings. Although these objects are merely instances of the basic types, their utility comes from how the information is encoded. Wowpedia's API documentation treates these as complex types even though there is no such official term. These may be further categorized as below:

Category Basic Type Description
Numeric ID
number
Whole number enumerating each kind of something, usually ascending from 1 as each expansion adds to the list.
(Differs from the enumeration type which is a table with string/number pairs)
Example: [Northrend Dungeonmaster] has achievementID 1288
Encoded String
string
Colon-delimited description of an in-game object, usually beginning with its category and ID.
Example:  [Hearthstone] has itemString "item:6948::::::::80:105::::::"
Hyperlink
string
H and |h UI escape sequences, interpretted by chat windows as a clickable hyperlink.
Example: H [11] Arugal's Folly has questLink in |cff808080|Hquest:99:15|h[Arugal's Folly]|h|r
Globally Unique Identifier (GUID)
string
Hyphen-delimited string for every distinguishable object, possibly containing a numeric ID or encoded string in one of the fields.
Example: One single Kobold Vermin in Elwynn Forest might have GUID Creature-0-6-0-11-31146-000136DF91
Constant
varies
Global variable (commonly uppercase and underscores) intended to be written in code for legibility and compatibility.
The value is fixed (constant) during runtime but could differ between classic/retail or languages.
Translation Example: FrameXML/GlobalStrings.lua defines ABSORB = "Absorb" in enUS or ABSORB = "Поглот" in ruRU
Fixed-Value Example: FrameXML/Constants.lua defines LOOT_ROLL_TYPE_NEED = 1 and LOOT_ROLL_TYPE_GREED = 2
Enumeration
table
Keys are strings and values are integers used for quick identification. This approach has increasing usage to replace constants. They can be accessed with e.g. /dump Enum.ClubType
Example: Enum.ClubType has four keys "BattleNet", "Character", "Guild" and "Other" with values 0 to 3.
Struct
table
Return values as a consolidated table with several key/value pairs. This approach has increasing usage in the modern API.[3]
Example: returns a single table decribed by Struct Map.UiMapDetails
Mixin
table
FrameXML tables whose members are copied into another table using and often (not always) incorporated into XML virtual templates.
Example: SpellMixin provides standard methods on any Spell object inheriting from it.

References

 
  1. ^ R. Ierusalimschy, L. H. de Figueiredo, W. Celes. "2.2 – Values and Types", Lua 5.1 Reference Manual. ISBN 85-903798-3-3. 
  2. ^ XML Schema Working Group 2014-10-28. XML Schema Part 2: Datatypes Second Edition. World Wide Web Consortium.
  3. ^ For example, compare GetMapInfo() until Legion with after Patch 8.0.1