Script:APILogic
From Roll20 Wiki
 | Page Updated: 2021-10-19 |
APILogic
APILogic introduces logical structures (things like IF, ELSEIF, and ELSE) as well as real-time inline math operations, and variable muling to Roll20 command lines. It can test sets of conditions and, depending on the result, include or exclude parts of the command line that actually reaches the chat processor.
For example, given the statement:
!somescript {& if a = a} true stuff {& else} default stuff {& end}
…results in the following reaching the chat:
!somescript true stuff
- Discussion: APILogic thread(Forum)
- File Location: APILogic.js (submitted to the one-click, but until then, find it in my personal repo)
- Script Dependency: libInline.js (also submitted to the one-click)
- Documentation for APILogic 1.2.1(and before)
APILogic exploits a peculiarity of the way many of the scripts reach the chat interface (a peculiarity first discovered by – who else? – The Aaron) to give it the ability to intercept the chat message before it reaches other scripts, no matter if it is installed before or after them in the script library. It also uses a separate bit of script magic to let it retain ownership of the message even when otherwise asynchronous chat calls would be going.
Caveat: The method APILogic utilizes has been tested and shown to work with a large number of scripts. If you find that it doesn’t, you should be reminded that the most foolproof way to ensure proper timing of script execution is to load APILogic in your script library before the other script. But hopefully you’ll find that you don’t need to do that!)
Also, although it requires the API, it is not only for API messages. You can use these logic structures with basic chat messages, too. This document will show you how.
Credits: Created by timmaugh. Many thanks to The Aaron for lending his expertise on questions I had, and to the other members of the House of Mod for sounding out and working through ideas.
Contents |
Triggering and Usage
You won’t invoke APILogic directly by using a particular handle and a line dedicated for the APILogic to detect. Instead, any API call (beginning with an exclamation point: ‘!’) that also includes any IF, DEFINE, MULE, EVAL, EVAL-, or MATH tag somewhere in the line will trigger APILogic to examine and parse the message before handing it off to other scripts.
As mentioned, you are not limited to using APILogic only for calls that are intended for other scripts. There are mechanisms built into the logic that let you output a simple chat message (no API) once you’ve processed all of the logic structures. That means you can use the logic structures in a simple message that was never intended to be picked up by a script, and also in a message that, depending on the conditions provided, might need to be picked up by another script, or alternatively flattened to a simple message to hit the chat log.
The Basic Structures: IF, ELSEIF, ELSE, and END
An IF begins a logical test, providing conditions that are evaluated. It can be followed by any number of ELSEIF tags, followed by zero or 1 ELSE tag. Finally, an IF block must be terminated with an END tag. Each of these are identified by the {& type ... } formation. For instance:
{& if … }
{& elseif …}
{& else}
{& end}
A properly structured IF block might look like this:
{& if (conditions) } true text {& elseif (conditions) } alt text {& else } default text {& end}
Each IF and ELSEIF tag include conditions to be evaluated (discussed in a moment). If an IF’s conditions evaluate as true, the subsequent text is included in the command line. While nested IF blocks embedded within that included text are detected and evaluated, no further sibling tags to the initial IF tag are evaluated until the associated END tag. On the other hand, if an IF evaluates to false, evaluation moves to the next logical structure (ELSEIF, ELSE, or END). ELSEIFs are evaluated just as IFs are, with processing passing forward if we find a false set of conditions. If we ever reach an ELSE, that text is included.
Nesting IF Blocks
You can nest IF blocks in other portions of the line to prompt a new set of evaluation for the enclosed text. They can occur in another IF, in an ELSEIF, or in an ELSE. If the outer logic structure passes validation so that the contents are evaluated, the nested IF block will be evaluated. Each IF must have an END, therefore the first END to follow the last IF belongs to that IF. Similarly, all ELSEIF and ELSE tags that follow an IF (until an END is detected) belong to that IF.
{& if } ... {& elseif } ... {& if } ... {& elseif } ... {& end } ... {& else } ... {& end}
In the example, an IF-ELSEIF-END block exists in the first ELSEIF of the outer IF block. it will only be evaluated (and can only be included) if the outer IF block fails validation and the ELSEIF passes.
Conditions
Each IF and ELSEIF must have at least one condition to evaluate. A condition can be either binary (i.e., a = b), or unary (i.e., c), and each element of a condition (the a, b, or c) can be a sheet item, text, inline roll, or a previously evaluated condition set (more on this in a moment).
Logical Comparisons
The following logical comparisons are allowed for comparing two items (binary operations):
a = b // equals a != b // does not equal a > b // is greater than a >= b // is greater than or equal a < b // is less than a <= b // is less than or equal a ~ b // includes a !~ b // does not include
Sheet Items
The specific ability to retrieve sheet items was removed from APILogic and rolled into the Fetch script (also part of the Meta-Toolbox). Use a Fetch construction to retrieve the sheet item data before APILogic evaluates it as part of condition.
Text as Condition
If you need to include space in a bit of text to include as one side of a comparison operation, you should enclose the entire text string in either single quotes, double quotes, or tick marks. With three options available, you should have an option available even if the text you need to include might, itself have an instance of one of those characters. For instance, the following would not evaluate properly, because of the presence of the apostrophe in the word “don’t”:
@(Bob the Slayer.slogan) ~ 'don't go'
Instead, wrap it in another option for denoting the text:
@(Bob the Slayer.slogan) ~ "don't go"
This is good to remember if you intend to use Roll20 parsing to retrieve something. For instance, if you want to use the name of the character associated with the Selected token as a condition, you should wrap that in some form of quotes if there is a chance that name will include a space.
"@{selected|token_name}" ~ Slayer
// will reach the API after Roll20 parsing as...
"Bob the Slayer" ~ Slayer
Chaining Conditions (AND/OR) and Grouping
Multiple conditions can be used for each IF or ELSEIF tag. Use && to denote and AND case, and use || to denote an OR case.
{& if a = b && c = d }
Conditions are evaluated left to right by default. Use parentheses to enclose groups to force those conditions to evaluate as a group before being compared to sibling conditions:
{& if a = b && ( c = d || e != f) }
Multiple levels of grouping can be used, provided each sibling element (whether group or condition) is connected with && or ||:
{& if ( a = b && ( c = d || e != f ) ) || ( d > b && g ) }
Naming and Reusing Groups
The reasoning behind why you would want to include a part of your command line might be needed at several times in your command line. In that case, you should name your condition group so that you can simply refer to that name later. Name a group by including a bracketed word (no space) after the opening parentheses, before any non-whitespace character:
{& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) }
The above would store the result of the condition (whether Bob the Slayer’s sanity was over 10) as sanitycheck, available to be used later in the command line, including in future, deferred processing (disucssed later).
{& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) } conditionally included text {& end} always included text {& if sanitycheck } conditionally included text {& end}
BE AWARE that conditions are ONLY evaluated for IF and ELSEIF tags which reach the parser. If your group is defined in a portion of the command line that is not evaluated because the IF or ELSEIF was never reached, the group will never be evaluated and the test will never be stored.
{& if a = !a } true case text {& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) } true case for nested if {& end } {& end } always included text {& if sanitycheck} ...{& end}
In that case, the first condition a = !a does not pass validation, so the subsequent text is never evaluated (including the IF tag where the sanitycheck is defined).
If you find yourself in this position, you can either investigate a definition (see Using DEFINE Tag, below), or using a root-level IF tag with a single space of dependent text (that is, providing little alteration to your command line, regardless of if it passes).
!somescript {& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) } {& end} ...
Because the END tag follows nearly immediately on the IF tag, no important text is included or excluded from the command line, no matter the result of the test. The IF tag is there simply to force the group to be evaluated and the result stored. This would be a better solution than using a definition if the group was particularly complex since the definition is a simple text replacement operation. Using a named group ensures that the group is only being retrieved and evaluated once (read more in Using DEFINE Tag).
Negation
Negation can be applied to any element of a condition or to any group by use of the ! character. This can be handy to test for the non-existence of a sheet item:
!@|Bob the Slayer|weaponsmith
…or to reverse the evaluation of a group:
!( @|Bob the Slayer|weaponsmith > 4 && @|Bob the Slayer|impromptu_poetry > 2 )
…or to get the opposite result from a named group:
{& if !sanitycheck }
Note that if you use negation at the same time you are naming a group, the group will evaluate and the result will be stored as with the name. Negation will then return the opposite of the stored value:
! ( [sanitycheck] a = a )
…will store true as the value of the sanitycheck group, but return false because of the negation. Referring to the sanitycheck group later will retrieve the initial true value.
Using DEFINE Tag
A DEFINE tag is a way to provide definitions for terms that you will then use in text replacements throughout your command line. A DEFINE tag can come anywhere in your command line, and is parsed out before any processing of logical constructs occurs. A DEFINE tag is structured like this:
{& define ([term1] definition1) ([term2] definition2) ... }
The term refers to what you will use, elsewhere in the command line, to represent the definition. Since the definition is terminated by a parentheses, you do NOT need to enclose it in some form of quotation marks UNLESS you need to include leading or trailing spaces.
Since DEFINE replacements are simple text replacement operations, these can be a way to save typing (providing a short term to represent a long definition that will need to be utilized a number of times in a command line). It also provides a way of minimizing work should a definition need to change – giving you only one place to change it instead of many. This means you could define a ([speaker] Bob the Slayer) term, and use speaker anywhere you would refer to the character; then, if you passed that macro language to a fellow player, they would only have to replace the name with their character in one place.
Difference Between Definition and Named Group
As mentioned in the section on using named groups, although the syntax for defining a term is very similar to naming a group, the two structures are different. If you placed the entirety of a group as a definition, you would be replicating that text anywhere you referenced the associated term, but each time that text was encountered, the group would be evaluated anew. Declaring the name for the group in an IF tag, where that name represents a set of conditions, ensures that those conditions are only evaluated once.
Change Log
- Version 2.0.0 - Initial Re-release as part of the ZeroFrameMeta Toolbox
- Version 1.2.1 - Script:APILogic/v1.2.1 (and before) - info on older version
Related Pages
- API:Script Index Curated list of Roll20 APIs
- Meta-Toolbox - collection of powerful APIs
- libInline(Forum) - provides an easy interface for inline rolls
- InsertArg(Forum) -- script preamp, siege engine, menu maker, command line constructor
- SelectManager(Forum) -- Utility to Preserve the Selected Tokens For API-Generated Calls
- Complete Guide to Rolls & Macros
