herolab.XPath: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
m (Conversion script moved page herolab.XPath to Herolab.XPath without leaving a redirect: Converting page title to first-letter uppercase)
No edit summary
 
(3 intermediate revisions by 2 users not shown)
Line 6: Line 6:
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.
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=
|usage=
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
herolab.XPath(XPath)
herolab.XPath(XPath)
herolab.XPath(XPath, id)
herolab.XPath(XPath, id)
</source>
</syntaxhighlight>
==== Options Coming in 1.8 ====
==== Options Coming in 1.8 ====
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
herolab.XPath(XPath, id, delim)
herolab.XPath(XPath, tokenRef, delim)
herolab.XPath(XPath, id, "json")
herolab.XPath(XPath, tokenRef, "json")
</source>
</syntaxhighlight>


'''Parameters'''
'''Parameters'''
{{param|XPath|The XPath expression to evaluate against the XML statblock.}}
{{param|XPath|The XPath expression to evaluate against the XML statblock.}}
{{param|id|The id of the token. Defaults to the Current Token.}}
{{param|tokenRef|Either the token [[getSelected|{{code|id}}]] or [[getTokenName|Token Name]] of the token. Defaults to the Current Token.}}
{{param|delim|'''Coming in 1.8'''.  Custom delimiter for the returned results.  Defaults to {{code|", "}}.  If equal to {{code|"json"}}, a [[JSON Array]] will be returned instead of a [[String List]].}}
{{param|delim|'''Coming in 1.8'''.  Custom delimiter for the returned results.  Defaults to {{code|", "}}.  If equal to {{code|"json"}}, a [[JSON Array]] will be returned instead of a [[String List]].}}
{{Note|Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.}}


Returns the requested data.
Returns the requested data.
Line 25: Line 26:
|example=
|example=
Get various values from Hero Lab data (which is in XML).
Get various values from Hero Lab data (which is in XML).
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[race = herolab.XPath('/document/public/character/race/@name')]
[race = herolab.XPath('/document/public/character/race/@name')]
[alignment = herolab.XPath('/document/public/character/alignment/@name')]
[alignment = herolab.XPath('/document/public/character/alignment/@name')]
[improvedInit = herolab.XPath('boolean(/document/public/character/feats/feat[starts-with(@name,"Improved Initiative")])')]
[improvedInit = herolab.XPath('boolean(/document/public/character/feats/feat[starts-with(@name,"Improved Initiative")])')]
</source>
</syntaxhighlight>
Returns:
Returns:
<source lang="mtmacro">
<syntaxhighlight lang="mtmacro">
Human Neutral Good 1
Human Neutral Good 1
</source>
</sosyntaxhighlightrce>
==== Changes Coming in 1.8 ====
==== 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.
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.
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: vXPath = "/document/public/character/spellsmemorized/spell[contains(@name,'De')]/@name"]
[h: vXPath = "/document/public/character/spellsmemorized/spell[contains(@name,'De')]/@name"]
Default: [r: herolab.XPath(vXPath)]<br />
Default: [r: herolab.XPath(vXPath)]<br />
Custom Delim: [r: herolab.XPath(vXPath, token.name, "|")]<br />
Custom Delim: [r: herolab.XPath(vXPath, token.name, "|")]<br />
JSON: <pre>[r: json.indent(herolab.XPath(vXPath, currentToken(), "json"))]</pre>
JSON: <pre>[r: json.indent(herolab.XPath(vXPath, currentToken(), "json"))]</pre>
</source>
</syntaxhighlight>
Returns:
Returns:
<source lang="mtmacro">
<syntaxhighlight lang="mtmacro">
Default: Delay Poison, Communal, Detect Magic, Detect Undead
Default: Delay Poison, Communal, Detect Magic, Detect Undead
Custom Delim: Delay Poison, Communal|Detect Magic|Detect Undead
Custom Delim: Delay Poison, Communal|Detect Magic|Detect Undead
Line 52: Line 53:
   "Detect Undead"
   "Detect Undead"
]
]
</source>
</syntaxhighlight>
When dealing with more complicated text elements with potential delimiter conflicts, it will usually be better to request the JSON output.
When dealing with more complicated text elements with potential delimiter conflicts, it will usually be better to request the JSON output.
|also=
|also=

Latest revision as of 23:59, 17 May 2024

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, tokenRef, delim)
herolab.XPath(XPath, tokenRef, "json")

Parameters

  • XPath - The XPath expression to evaluate against the XML statblock.
  • tokenRef - Either the token id or Token Name 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.
Token IDs are unique, but Token Names can be duplicated. Using Token Name when more than one token has the same name can produce unexpected results.


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

Hero Lab Integration

Version Changes

  • 1.8 - Added optional param for custom delimiter in returned results
Retrieved from "https://wiki.rptools.info/index.php?title=herolab.XPath&oldid=35128"