Bukkit

Turret Language

What is Turret Language (TurretLang)?

Turret Language is an alternative to YAML (YAML Ain't Markup Language or Yet Another Markup Language) with several differences that should help the plugin developers to create more user-friendly configuration files. Please note that TurretLang is not a plugin itself, but just a Bukkit-related API.

Comparation to YAML

TurretLang is designed to read plugin configuration files. Unlike YAML, it supports all Unicode chars (except those restricted (see "Restricted characters")) and holds all the data String-wise.

Currently the language supports String, byte, short, int, long, float, double, char, File, Object, String[] and Map<String, String> objects and use of special characters directly in the file (e.g. a variable can include a space char in its name). However, there is currently no support for configuration sections. As well there exists no way to change the configuration without modifying the sourcefile, but this possibility is in the todo list.

There are quick methods to reload the configuration, as a it is attached to its sourcefile.

Markup

All TurretLang files have a very simple structure:

• All lines beginning with an asterisk (*) and all empty lines are considered to be commentaries and ignored.
• All lines featuring a colon (:) are considered variable declarations and loaded into the configuration, so a line "This is a line:with a variable" will be considered a variable named "This is a line" with value "with a variable".
• All other lines are considered wrong variable declarations and not loaded; but each such line increases the amount of "failed" declarations that can be checked later.

Apart from all that, in variable declarations special syntax can be used to mark arrays (String[]), maps (Map<String, String>) and even Objects. In this language, any map is an array with specially encoded values.

• In an array, items should be separated using a semicolon (;). For exampe, a line "An example array:item0;item1;item2" will be considered an array {"item0", "item1", "item2"}. If no semicolon appears the "normal" value is considered to be the only element of an array.
• In a map, pairs of keys and values are separated by semicolons, just like arrays, while the key is separated from the value by the first occurance of at sign (@). If any pair does not contain an at sign, an error occures and an exception is thrown. So a line "Map:first key@a value;second key@a value with an @ sign;third key with an empty value@" will be considered the following map:

"first key" -> "a value"
"second key" -> "a value with an @ sign"
"third key with an empty value" -> ""

• In an Object, data is separated by asterisks (*). Any Object declaration begins with the complete name of the class that is followed by the arguments to pass while instantiating. When var.getValueAsObject() is used, a public constructor savedClass(String[] arguments) is called and the resulting Object is returned. Note that even if the Object does not require any arguments the rules above must be followed. So YourClass with several arguments may be stored as "com.yourPackage.YourClass*Argument 1*Argument 2" while AnotherClass that does not require any arguments is represented as "com.yourPackage.AnotherClass*" (unlike in arrays and maps, an asterisk is required even if there are no arguments to pass).

Restricted Characters

Note: these characters are not actually restricted but will cause an unexpected behavior when loaded.

• The asterisk (*) is not allowed as the first character of a varialbe's name as it will make the declaration be considered a commentary.
• The semicolon (;) is not allowed in arrays' and maps' values as it will separate one value into two (e.g. "wrong;syntax" will be red as {"wrong", "syntax"}). However, this does not influence String value as it is always provided as in declaration.
• The at sign (@) in keys' names, as then the key will be split into a new key and a part of a value (e.g. "wrong@key declaration@value" will be red as "wrong" -> "key declaration@value").
• The asterisk (*) is not allowed anywhere in Object declarations as it will split data.
• The new line character (\n) cannot be used anywhere as it will split declarations.

If the usage of any of these characters is unavoidable, plugins should use combinations manually: var.getValue().replaceAll("\\n", "\n") The option to replace combinations by restricted characters at low-level processing is in todo list.

Bugs

No bugs are currently discovered.

Please note that there has not been suffcient testing yet; if you find any glitch please me about it.

Todo list

• Add an option to translate combinations to restricted characters;
• Add a way to change the configuration values dynamically.

How to use?

Server owners

Are you running any plugin using TurretLang configurations? Here's a Newcomer's Guide to The Turret Language Configuration Files:

Q: How to change a setting?

1. Open the configuration file you wish to change (most probably it will be in \plugins\%pluginName%\config.tlc) with any text editor tool (like Notepad++ or Wordpad)
2. Actually change the value. To identify the variable's name take a look at the part just before the first colon (:). Be sure not to use any new line characters and, if it is supposed to be an array or a map, use the correct syntax (see "Markup").
3. Save the file! You're done!

Q: The plugin's complaining about the configuration! What's wrong?!

1. Check the basic TurretLang syntax according to "Markup" section.
2. Check the commentaries in the configuration as the problem may be not in the TurretLang syntax but in plugin's.
3. Report the error report and the configuration file to the complaining plugin's creator. It may be the author's fault.
4. If the creator blames the TurretLang, then report here. We'll find out the solution.

Q: This plugin crashes when the server launches!
The downloadable .jar file is not a Bukkit plugin; it is not supposed to be in \plugins\ folder.

Plugin developers

Willing to develop a plugin with TurretLang configurations? The downloadable jar contains all the necessary data including the source, the documentation and an example configuration with explanations. Include it in your build and it will work!

Q: What the hell is NullableBoolean?!
It is a "wrap" for the primitive boolean type. It is returned by var.getValueAsTrueBoolean() only and has three states: true, false and null. Null signifies that such value is not a boolean.

Q: How should I name the variables?
As TurretLang supports almost all the Unicode characters in the variables' names and is actually designed to make configuration as friendly as possible, it is preferred to write names as Normal sentances. E.g. "maxPlayers: 30" in YAML may be written as "The maximum amount of players:30" in TurretLang, so that it is as self-descriptive as possible.

Finally don't forget to tell me if you wish to use Turret Language in your plugin :)