Placeholder type handlers

[Maximvdw]

Problem statement
Many code duplication and inconsistencies occur with various generic placeholders. A common example is a Bukkit location that returns an X,Y,Z,Pitch,Yaw,Roll value. Currently, expansions have to create a placeholder for every _x, _y, _z variant of the placeholder. Similar issues can appear with other default Bukkit types such as Players, etc...

Goal
The goal is to create type handlers that convert a one placeholder type to many (string) placeholders. This will enforce consistency throughout expansions and limit code duplication.

Requirements

• Type handlers should accept any Object that is not a String
• Type handlers could be registered globally and locally per expansions, local type handlers should have a higher priority. I envision that every expansion can register a type handler (e.g. a LocationExpansion offers all placeholders associated to a Location)
• Type handlers should be able to create multiple placeholders, either by cancelling the creation of the non-string placeholder and using the PAPI API to register placeholders, or some other interface to facilitate this
• Placeholder information should be forwarded to type handlers, such as the placeholder name and arguments
• String types should not support type handlers - they should remain unmodified. However, there might be use cases where a user is interested in a %player_name_uppercase% or similar 'text' action. Maybe a 'Text' object can be added to PAPI to indicate a string that can support text manipulation like uppercase, lowercase, substring, ....

Use cases

• Many decimal numbers accept arguments to round the value. A type handler could facilitate this to create consistency for these arguments when returning a double or float.
• Similar to the above use case, the same thing can be done for a java.util.Date object, using consistent arguments to determine the formatting
• Many placeholders return the 'player' (e.g. player of a town, player nearby, top player, ...) a player on itself might have more information, the Player Expansion could register a 'Player type handler' that returns all placeholders currently available for every single player placeholder. Example: townyadvanced_town_owner (fictional placeholder) returns a Player instance. The Player Expansion registers a player handler that offers placeholders such as townyadvanced_town_owner_uuid, townyadvanced_town_owner_is_flying,.. without code repetition

[Andre601]

The placeholders themself that are suggested come from the eCloud to my knowledge.

The expansion itself receives a method call (i.e. onRequest(OfflinePlayer, String)) with a String representing anything after the first _
PAPI itself doesn't really care about how many arguments/variables there are. It only checks if the first part is a valid key and forwards everything else to the expansion in question to handle.

It's the expansion's job to validate the full placeholder pattern, which it does by returning a non-null String.

I hope I understood your message correctly.
We could perhaps have a `getPlayer and getWorld method that takes a String, checks it for valid values and if everything is fine, return the corresponding value.

[PiggyPiglet]

The placeholders themself that are suggested come from the eCloud to my knowledge.

The expansion itself receives a method call (i.e. onRequest(OfflinePlayer, String)) with a String representing anything after the first _
PAPI itself doesn't really care about how many arguments/variables there are. It only checks if the first part is a valid key and forwards everything else to the expansion in question to handle.

It's the expansion's job to validate the full placeholder pattern, which it does by returning a non-null String.

I hope I understood your message correctly.
We could perhaps have a `getPlayer and getWorld method that takes a String, checks it for valid values and if everything is fine, return the corresponding value.

Not sure you quite understood the issue, this is a proposal for an API addition - I really like it. Might have a go at implementing it next week when I get some free time

[Maximvdw]

The placeholders themself that are suggested come from the eCloud to my knowledge.

The expansion itself receives a method call (i.e. onRequest(OfflinePlayer, String)) with a String representing anything after the first _
PAPI itself doesn't really care about how many arguments/variables there are. It only checks if the first part is a valid key and forwards everything else to the expansion in question to handle.

It's the expansion's job to validate the full placeholder pattern, which it does by returning a non-null String.

I hope I understood your message correctly.
We could perhaps have a `getPlayer and getWorld method that takes a String, checks it for valid values and if everything is fine, return the corresponding value.

The idea is indeed to have it as an API addition for the returned data. Currently placeholders are expected to handle all arguments and return a string that will be used to replace the placeholder. My suggestion is to also support returning other Objects other than strings. These non-string objects can then be handled by an expansion that converts it to multiple string placeholders.

For example, instead of implementing a placeholder for the X, Y and Z coordinate in a placeholder that should return a location - you simple create a new placeholder "location" (fictional expansion identifier 'myplugin') and return a Location.

A location type handler can then create string placeholders for all information in this location:
'myplugin_location_x', 'myplugin_location_world', ... . That way, you do not need code repetition for these things over multiple expansions + you add consistency to users because they can expect that every placeholder that returns "a location" will also have a way to get the world of that location ,etc..

I think I might have confused you with the argument example(s). What I meant with that was to also add a bit of dynamic type handling. Lets say you have a "tps" placeholder that returns a double. Instead of handling the arguments to determine the rounding ,etc... your type handler could do this for you - again limiting code repetition when another expansion also returns a double that should support rounding, etc..

I would not create built-in handlers. While I indeed suspect that it will be most useful in commonly used Java data types or Bukkit data types - it should not be assumed to only be used for that.