herolab.XPath

From RPTools Wiki
Revision as of 16:14, 15 March 2023 by Taustin (talk | contribs)
Jump to navigation Jump to search

herolab.XPath() Function

 Note: This function can only be used in a Trusted Macro

Introduced in version 1.5.0
Returns data results based on the passed in XPath expression from the XML statblock. This is a reliable and easier way to get stat data from a character than using regular expression parsing of Text stat blocks.

Usage

herolab.XPath(XPath)
herolab.XPath(XPath, id)

Options Coming in 1.8

herolab.XPath(XPath, id, delim)
herolab.XPath(XPath, id, "json")

Parameters

  • XPath - The XPath expression to evaluate against the XML statblock.
  • id - The id of the token. Defaults to the Current Token.
  • delim - Coming in 1.8. Custom delimiter for the returned results. Defaults to ", ". If equal to "json", a JSON Array will be returned instead of a String List.

Returns the requested data.

Example

Get various values from Hero Lab data (which is in XML).
[race = herolab.XPath('/document/public/character/race/@name')]
[alignment = herolab.XPath('/document/public/character/alignment/@name')]
[improvedInit = herolab.XPath('boolean(/document/public/character/feats/feat[starts-with(@name,"Improved Initiative")])')]

Returns:

Human Neutral Good 1
</sosyntaxhighlightrce>
==== Changes Coming in 1.8 ====
Sometimes the data desired from herolab contains commas or is otherwise incompatible with the [[String List]] format and default (comma) separator.  In the following example, the list of spells retrieved includes one called "Delay Poison, Communal" - as we see in the default output, this element would be incompatible with the standard String List format.
<syntaxhighlight lang="mtmacro" line>
[h: vXPath = "/document/public/character/spellsmemorized/spell[contains(@name,'De')]/@name"]
Default: [r: herolab.XPath(vXPath)]<br />
Custom Delim: [r: herolab.XPath(vXPath, token.name, "|")]<br />
JSON: <pre>[r: json.indent(herolab.XPath(vXPath, currentToken(), "json"))]</pre>

Returns:

Default: Delay Poison, Communal, Detect Magic, Detect Undead
Custom Delim: Delay Poison, Communal|Detect Magic|Detect Undead
JSON: 
[
  "Delay Poison, Communal",
  "Detect Magic",
  "Detect Undead"
]
When dealing with more complicated text elements with potential delimiter conflicts, it will usually be better to request the JSON output.

See Also

Version Changes

  • 1.8 - Added optional param for custom delimiter in returned results