This document provides a brief outline of the API provided by XRP, allowing
other addons to interact with RP profile data.

Looking up other characters
===========================

Character data for others is stored in four metatables, xrp.units, xrp.guids,
xrp.characters, and xrp.cache.

xrp.units:
	This metatable provides access to character profile data for a specified
	unit. For instance, xrp.units.target will contain information about the
	current target (or will be nil if the target is not a player). You may
	index this for any fields, and their contents will be returned (or nil if
	no contents).

xrp.guids:
	This metatable provides access to character profile data for a specified
	GUID. Note that GetPlayerInfoByGUID() must be able to succeed on the
	specified GUID (meaning the WoW client has seen it in this session, and
	you're not using a stored value from anothe session). As an example,
	xrp.guids[UnitGUID("player")] will contain information about the current
	player themselves (but, of course, this is better used with non-self
	targets, such as for GUIDs attached to CHAT_MSG_* events).

xrp.characters:
	This metatable provides access to character profile data for a specified
	character name. This name should be of the form Name-RealmName (though
	'-RealmName' *may* be ommitted for same-realm, but this is not
	recommended). For example, xrp.characters["Bor-WyrmrestAccord"] contains
	profile data for the character Bor on the Wyrmrest Accord realm.

The above three metatables automatically perform requests for updated versions
of fields as appropriate. In general, there is no purpose to running any
explicit request when interacting with XRP -- just access the information
through one of the above-three tables, and it will be updated shortly.

xrp.cache:
	This metatable provides the same access as the xrp.characters metatable,
	but it explicitly does not request new data. This should generally not be
	used, but is useful in cases where you explicitly want cached data, or are
	certain that a request for updated fields would fail.

All of the above tables can be indexed for MSP field names (such as NA for
roleplay name, GC for toon class, HI for character history, etc.), but pairs()
may not be used on them currently. If you absolutely require a full dump of
all available fields for a character, you may call the profile as a function,
but this is strongly discouraged. Supporting a specific set of fields and
indexing each of the individually is recommended.

Reacting to incoming profile data
=================================

Information on xrp:HookEvent() here.

Reading and writing profile data
================================

Character's own profile data info goes here.

Helper functions
================

Contained in xrp/core/helpers.lua are a number of useful functions that can be
used to manipulate data from XRP in helpful ways.

xrp:UnitNameWithRealm(unit):
	arguments: unit (unitID/string)
	returns: Unit name with attached realm name, including same-realm.

xrp:NameWithRealm(name, realm):
	arguments: name (string), realm (string, optional)
	returns: Returns input name if a realm name is already present, otherwise
		returns input name with specified realm name (or current realm name,
		if realm is nil or empty) attached.

xrp:NameWithoutRealm(name)
	arguments: name (string)
	returns: A name suitable for display, never having a realm name attached.
		In essence, this is similar to Ambiguate(), except it always strips
		realm names if present.

xrp:RealmNameWithSpacing(realm)
	arguments: realm (string)
	returns: Realm name with proper spacing. Currently only supports
		English-named realms.

xrp:StripEscapes(text)
	arguments: text (string)
	returns: Text with pipe escapes stripped or rendered non-functional.

xrp:StripPunctuation(text)
	arguments: text (string)
	returns: Text with most punctuation stripped from beginning and end of
		string. This is designed for in-line display of RP names, while
		removing attention-seeking formatting (i.e., ~~[[Name]]~~ becomes
		simply Name).

xrp:ConvertWeight(weight, units)
	arguments: weight (string), units (string)
	returns: Input weight converted, if possible, to specified units. Possible
		values for units are: "msp", "lb", and "kg". If units are not
		provided, the user-selected preferred units are used. If conversion is
		not possible, the input weight is returned untouched.

xrp:ConvertHeight(height, units)
	arguments: height (string), units (string)
	returns: Input height converted, if possible, to specified units. Possible
		values for units are: "msp", "cm", "m", and "ft". If units are not
		provided, the user-selected preferred units are used. If conversion is
		not possible, the input height is returned untouched.
