Text Placeholder API Expressions

Adds math, conditional, and string manipulation expressions to Text Placeholder API.
This project uses Keval for parsing math expressions, and would have been exponentially more difficult without it. Show the author some love and star his repo!

Using Placeholders In Expressions

This extension uses the ${category:placeholder} syntax to allow supplying placeholders that resolve to numbers as components.
For example; to display a player's health as a percentage (such as within the tab list), you could use the following:
%expr:math ${player:health} * 100 / ${player:max_health}%%

Math Placeholder

The bulk of the additions (no pun intended) in this extension are accessed through the expr:math placeholder.

You can think of this placeholder as handling three distinct 'types':

• Components, such as numbers, functions, constants, and placeholders that resolve to numbers.
• Binary operators, such as addition or subtraction, which go between two components.
• Unary operators, such as negation and factorial, which apply to a single component.

Components and operators supplied by this extension

Binary operators are applied between two components.

Binary Operator	Function	Example	Result
+	Add	%expr:math 2 + 2%	4
-	Subtract	%expr:math 4 - 1%	3
*	Multiply	%expr:math 3 * 3%	9
/	Divide	%expr:math 9 / 4%	2.25
^	Exponent	%expr:math 3 ^ 3%	27

Unary operators are applied to a single component.

Unary Operator	Function	Example	Result
-	Negate	%expr:math 1 + -1%	0
+	Identity	%expr:math ??%	What does this even do
!	Factorial	%expr:math 5!%	120

Functions are components, taking expressions as arguments.

Function	Arguments	Description	Example	Result
mod	2	Modulo / remainder	%expr:math mod(7, 2)%	1
neg	1	Negate / invert (Like unary -)	%expr:math neg(10)%	-10
abs	1	Absolute value	%expr:math abs(-10)%	10
sqrt	1	Square root	%expr:math sqrt(34)%	5.8309
cbrt	1	Cube root	%expr:math cbrt(30)%	3.1072
exp	1	Exponential	%expr:math exp(4)%	54.5981
ln	1	Natural logarithm	%expr:math ln(4)%	1.3862
log10	1	Base 10 logarithm	%expr:math log10(4)%	0.6020
log2	1	Base 2 logarithm	%expr:math log2(4)%	2
rad	1	Degrees to radians	%expr:math rad(30)%	0.5235
sin	1	Sine	%expr:math sin(rad(30))%	0.4999
cos	1	Cosine	%expr:math cos(rad(30))%	0.8660
tan	1	Tangent	%expr:math tan(rad(30))%	0.5773
asin	1	Arcsine	%expr:math asin(rad(30))%	0.5510
acos	1	Arccosine	%expr:math acos(rad(30))%	1.0197
atan	1	Arctangent	%expr:math atan(rad(30))%	0.4823
ceil	1	Round up	%expr:math ceil(0.4)%	1
floor	1	Round down	%expr:math floor(0.6)%	0
round	1	Round	%expr:math round(0.5)%	1
min	2+	Smallest argument	%expr:math min(1, 0.3, 7)%	0.3
max	2+	Largest argument	%expr:math max(1, 0.3, 7)%	7
avg	2+	Average of arguments	%expr:math avg(1, 0.3, 7)%	2.7666

Constants are components which resolve to a constant value.

Constant	Description
PI	π
e	Euler's number

Conditional Placeholders

Arguments to these placeholders must be separated by semicolons (;) instead of spaces.

%expr:ifeq%

Test whether a and b are equal, and return c or d depending on the result.

%expr:ifeq aIsMath a bIsMath b cIsMath c dIsMath d%

Argument	Description
aIsMath	Whether to parse a as a math expression. Either true or false.
a	Math expression or text to compare against b. If treated as text, and spaces at the start or end of the string are removed.
bIsMath	Whether to parse b as a math expression. Either true or false.
b	Math expression or text to compare against a. If treated as text, and spaces at the start or end of the string are removed.
cIsMath	Whether to parse c as a math expression. Either true or false.
c	Math expression or text to use if a and b are equal.
dIsMath	Whether to parse d as a math expression. Either true or false.
d	Math expression or text to use if a and b are not equal.

Example

Player %expr:ifeq false; ${player:equipment_slot mainhand}; false; Diamond Sword; false; is; false; is not% holding a Diamond Sword.

Condition	Result
%player:equipment_slot mainhand% == "Diamond Sword"	Player is holding a Diamond Sword.
%player:equipment_slot mainhand% != "Diamond Sword"	Player is not holding a Diamond Sword.

%expr:iflt%

Test whether a is less than b, and return c or d depending on the result.

%expr:iflt a b cIsMath c dIsMath d%

Argument	Description
a	Math expression to compare against b.
b	Math expression to compare against a.
cIsMath	Whether to parse c as a math expression. Either true or false.
c	Math expression or text to use if a is less than b.
dIsMath	Whether to parse d as a math expression. Either true or false.
d	Math expression or text to use if a is not less than b.

Example

Player is in %expr:iflt ${player:health}; 14; false; poor; false; good% health

Condition	Result
%player:health% < 14	Player is in poor health
%player:health% >= 14	Player is in good health

%expr:ifgt%

Test whether a is greater than b, and return c or d depending on the result.

%expr:ifgt a b cIsMath c dIsMath d%

Argument	Description
a	Math expression to compare against b.
b	Math expression to compare against a.
cIsMath	Whether to parse c as a math expression. Either true or false.
c	Math expression or text to use if a is greater than b.
dIsMath	Whether to parse d as a math expression. Either true or false.
d	Math expression or text to use if a is not greater than b.

Example

Health: %expr:ifgt ${player:health}; 4; true; ${player:health} * 100 / ${player:max_health}%; false; Nearly dead!%

Condition	Result
%player:health% == 15	Health: 75
%player:health% == 14	Health: 70
%player:health% <= 4	Health: Nearly dead!

String Placeholders

Arguments to these placeholders must be separated by semicolons (;) instead of spaces.

%expr:pad%, %expr:padleft%, and %expr:padright%

Pad one or both sides of str with c until the string length reaches length.

%expr:pad length; str; c%
%expr:padleft length; str; c%
%expr:padright length; str; c%

Argument	Description
length	Math expression, target length of the padded string.
str	Source string to pad. Spaces at the start or end of the string are removed.
c	Character to use for padding.

Example

%expr:padleft 2 ${server:online} 0% / %server:max_players%

Condition	Result
%server:online% == 12	12 / 40
%server:online% == 4	04 / 40

%expr:padmatch%, %expr:padmatchleft%, and %expr:padmatchright%

Pad one or both sides of str with c until the string length matches the length of match.

%expr:padmatch match; str; c%
%expr:padmatchleft match; str; c%
%expr:padmatchright match; str; c%

Argument	Description
match	String to match the length of. Spaces at the start or end of the string are removed.
str	Source string to pad. Spaces at the start or end of the string are removed.
c	Character to use for padding.

Example

%expr:padmatchleft ${server:max_players} ${server:online} 0% / %server:max_players%

Condition	Result
%server:max_players% == 40, %server:online% == 4	04 / 40
%server:max_players% == 100, %server:online% == 4	004 / 100