Home

General Information:

Circe is a simple extension scripting language which assists with data conversion by providing easy access to certain common methods other programming languages provide for data conversion. For instance, a string means a string of characters. Circe provides some methods for checking if the string matches a certain phrase, getting the length of a string, cutting the string into pieces, replacing bits of the string, and more.

If you're looking for an expansion which lets you write in a proper programming language, with functions and such, I highly recommend using the JavaScript expansion.

Feedback:

If you think this sort of expansion is what you need, but it doesn't offer features you need, please feel welcome to suggest them or if you're familiar with Java, open a Pull Request. If this guide isn't sufficient, feel welcome to ask questions as well.

Placeholder:

Bracket placeholders are processed at the very start before further processing is done, and at the end before the placeholder result is returned.
The identifier for this expansion is %circe_<expression>%. The parameter <expression> accepts an Expression type input.
You can also write your Expression in a file under path ../plugins/PlaceholderAPI/circe ending with the .circe file type, and refer to the file with this placeholder: %circe_file:<fileName>. Lines starting with the character ˘#˘ will be ignored and can be used for comments.

Debugging:

If either the first method or the file starts with the line debug;, then the placeholder will send you error messages in case the language failed to interpret what you wanted to do. If you don't add it, it'll return an empty line - to hide the exception message from your players.

As the base placeholder:

%circe_debug; <expression>%

In the file:

debug;
<expression>

Here's a list of common error messages and what they might mean:

"Unknown token: <x>" - The character or word used is not part of the language.
"Invalid variable reference/declaration." - Somewhere you used the character $, but didn't follow up with a variable name. Variable names can't start with numbers, which might be the reason for this error.
"Invalid variable reference: $<name>" - The variable does not exist.
"Invalid variable declaration: <name>" - After the variable symbol, name, equals sign, then expression, the following symbol should be a common-comma (;).

Expression:

An expression can be any of the sub-types described below. Note that when describing Function types, we'll follow this description format: function(<parameterType1>, <parameterType2>, ...): <returnType> (example: size(<string>): <number>). Also note, that anything in <arrow> brackets refers to an expression, without the arrow brackets included. Example of the size function call: size("test").

Expressions are always returned to their caller. If a Variable is attempting to store an expression, then the variable is the caller, and the value will be passed to it. Function arguments after being resolved are passed to the function, then the function return value will be returned to whatever executed the function. If nothing else is attempting to process the expression, the expression is returned as the placeholder value. For example:

Here the Number expression 5 is returned as the value of the placeholder.

%circe_5%

And here the String argument is passed to the function, and then the value of the function will be the final placeholder value.

%circe_size("test")%

Number:

The number type accepts whole or decimal numbers. You can add the prefix - for negative numbers, but you can't use +. Math is also not supported in expressions, but you can use the calc function for math, like calc("1 + 1"). Variables can also be referenced in the calc function but without their $ prefix.

Some utility functions for this type are:

toNumber(<string>)
round(<number>): <number>

But don't worry about them for now. They'll be documented below, in the Function section.

String:

A string is a list of characters, encased by double quotation marks. "Here's an example of a string." You can include quotations inside your string by escaping the inner quotations. "Here's an example of a \"string\" type." The final placeholder value, if it's of string type, will be returned quotation-less - the outer quotations will be removed.

Function:

When describing the function expression type, we'll follow this descriptive format:

function(<parameterType1>, <parameterType2>, ...): <returnType>

Here the function refers to a function name, the parentheses () list arguments are separated by a comma, and the return type will be the expression type returned to the caller.

If the size function description is size(<string or array>): <number>, then when we call size("test") we know to expect the result 4.

Click here to view the list of available functions.

Special:

These are mostly meant for utility, like converting one type to another so that it can be used in other functions and such.

Function	Description
`calc(<string>): <number>`	Expressions in this expansion don't support math, but you can write a math expression in the string parameter of this function, and it will be resolved into a number. The evaluator for this is exp4j. Variables can be referenced in this but without the use of the `$` prefix (`$index = 1; calc("index + 1")`).
`round(<number>): <number>`	Rounds any number to a round number.
`toArray(<expression>): <array>`	This returns a singleton array of the passed argument. This means the array returned will contain that single passed element. This is intended for util.
`toNumber(<string>): <number>`	This will attempt to convert a string to a number.
`toString(<number>, <number>): <string>`	This will convert a number to a string. The second number is the radix. Set to 10 for the decimal system.

Merged:

Merged functions are functions which accept both array or string-type expressions.

Function	Description
`contains(<string or array>, <string or number>): <string>`	Checks if the string or array contains the second passed argument. The return is either the string `true` or `false`.
`equals(<string or array>, <string or array>): <string>`	Returns either the string `true` or `false`. It'll return `false` if types are mismatched.
`indexOf(<string or array>, <string or number>): <number>`	Returns the position (index) of the first instance of the element passed in the second argument, or `-1` if not found. Note that the first position is 0. When checking for the position of a sub-string in a string, the position returned will refer to the position of the very start of that sub-string in the passed string.
`lastIndexOf(<string or array>m <string or number>): <number>`	Same as above, but the search will start from the end.
`isEmpty(<string or array>): <string>`	Returns either the string `true` or `false`.
`size(<string or array>): <number>`	Returns length of the passed expression.

String:

Function	Description
`charAt(<string>, <number>): <string>`	Returns the single character at position. Index starts from 0.
`charCodeAt(<string>, <number>): <string>`	Returns the UTF-16 code unit at the given index.
`endsWith(<string>, <string>): <string>`	Check if the string ends with the second passed argument. The returned string value is either `true` or `false`.
`lowercase(<string>): <string>`	Transforms the whole string to lowercase.
`match(<string>, <string>): <array>`	The second passed argument can follow the RegExp format.
`padStart(<string>, <minLength: number>, <pad: string>): <string>`	Takes text in the first argument, and as long as it is shorter than the min length in the second argument, it adds text from the third argument to the start.
`padEnd(<string>, <minLength: number>, <pad: string>): <string>`	Takes text in the first argument, and as long as it is shorter than the min length in the second argument, it adds text from the third argument to the end.
`repeat(<string>, <number>): <string>`	The returned value is the string repeated as many times as the second argument denotes, without spacers.
`replaceAll(<string>, <string>, <string>): <string>`	The second passed argument can follow the RegExp format. The third argument is the string the match is replaced with.
`replaceFirst(<string>, <string>, <string>): <>`	The second passed argument can follow the RegExp format. The third argument is the string the match is replaced with.
`reverseString(<string>): <string>`	Reverses the order of characters.
`split(<string>, <string>, <limit>): <array>`	Returns an array of strings which are bits of the first argument split by the second, which supports the RegExp format. An empty string will result in the string being split at the position of every character. The third argument defines the limit for the number of splits done - set to 0 not to limit.
`startsWith(<string>, <string>): <string>`	Check if the string starts with the second passed argument. The returned string value is either `true` or `false`.
`substring(<string>, <number>, <number>): <string>`	Cuts the string by the start and end indexes, and returns the cut string.
`trim(<string>): <string>`	Removes whitespace (spaces) from the start and end of the string.
`unicode(<number>): <string>`	Returns the character the passed UTF-16 code unit argument represents.
`uppercase(<string>): <string>`	Transforms the whole string to lowercase.

Array:

Function	Description
`elementAt(<array>, <index>): <expression>`	Returns the element found by the index. Remember that they start from 0.
`join(<array>, <string>): <string>`	Returns a string constructed by joining the array with the passed second argument as the joiner.
`pop(<array>): <expression>`	Returns the last element of the array.
`push(<array>, <string or number>): <array>`	Pushes the second argument to the array end, and returns the array.
`reverseArray(<array>): <array>`	Reverses the elements in the array.
`shift(<array>): <expression>`	Returns the first element from the array.
`slice(<array>, <number>, <number>): <array>`	Returns the array of elements located from the second (start) argument index to the third (end).
`splice(<array>, <number>, <number>, <array>): <array>`	Replaces the elements located from the second argument (start) to the third argument (end) with the elements of the array passed in fourth argument, then returns the modified array.
`subtract(<array>, <array>): <array>`	Returns the difference between the two passed arrays.
`unshift(<array>, <string or array>): <array>`	Pushes the second argument to the start of the array, and returns the array.

Array:

The array represents a list of expressions. You can define it as: ˙[<expression_0>, <expression_1>, ...]˙ (example: [0, 2,"3", size("etc.")]).

Variable:

A variable can either be defined to be set to a value, or to reference a value at the position of an expected <expression>. They're not required for a working Circe script but help with readability, especially if you're defining the Circe placeholder in a .circle file, which supports multiple lines, unlike the base placeholder.

To set a variable to a value, follow this syntax:

$name = <expression>;

To reference a variable, you can reference it wherever an Expression is expected. The variable must match the expected Expression type. Reference it with $name. You can also reference it in the calc function string parameter but don't use the $ character at the start.

A variable can be stored before any Expression is expected. You can chain variable declarations leading up to a final expression which will be returned as the placeholder value.

$a = "x";
$b = $a;
$b

Since function parameters are expressions, you can also define variables inside functions before the argument which will be passed is defined. The same can be done before every element of an array. This is quite unconventional in other programming languages, but it happens to be an artefact of how the parser was built. It happens to help with readability when you're using the base placeholder format instead of the file, especially when you're using functions which are very long because otherwise, you might lose track that the function belongs to that function and that argument.

Here's an example which extracts the "there" word in the string "Hello there world!":

Without variables, in basically both file and base placeholder form:

%circe_substring("Hello there world!", indexOf("Hello there world!", " "), lastIndexOf("Hello there world!", " "))%

In file form:

$string = "Hello there world!";
$start = indexOf($string, " ");
$end = lastIndexOf($string, " ");
$there = substring($string, $start, $end);
$there;

In base placeholder form:

%circe_elementAt(substring($string = "Hello there world!"; $string, indexOf($string, " "), lastIndexOf($string, " "))%

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Home

Contents:

General Information:

Feedback:

Placeholder:

Debugging:

Expression:

Number:

String:

Function:

Special:

Merged:

String:

Array:

Array:

Variable:

Clone this wiki locally