Bukkit

This plugin has neither a config or any commands; it is a developer library.

GTNLib

GTNLib is a Java library for reading Grouped Tag Notation (GTN) files - a form of information notation designed for Bukkit Plugins.

Introduction to Grouped Tag Notation

Grouped Tag Notation is a text file format designed to store information for bukkit plugins. It was originally intended to be used as a way of storing Inventories but has since been expanded to store any information. Let's have a look at a basic GTN File. First thing – all lines of GTN have a semi-colon at the end - using a semi-colon anywhere else WILL break the code.

/This is a comment, it requires a semi-colon;
/Below is a line of GTN that represents an item;
/The item is 1 stone sword in first hotbar slot with Sharpness 3;

{b:0}{t:STONE_SWORD}{s:1}{e:DAMAGE_ALL-3};

/Every GTN line that isn’t a comment is called an item;
/An item is formed of one or more tags with a key and a value;
/The key and value are seperated with a colon;
/A tag is enclosed in curly braces as you can see above;

/Groups of items can be named like these integers;

@magicnumbers;
{t:INT}{v:42};
{t:INT}{v:404};

/Un-named items are referred to in the code as having the name ‘base’;
/This includes the sword above;
/Therefore naming a set of items ‘base’ with the @ syntax will not work;

That is how a basic GTN file looks. There is nothing else to it, but it is very versatile and can represent many things.

Reading a GTN in your plugin

Before you start, you must of course add the GTNLib jar to your build path. This is done in the same way as you add the bukkit jar when you start making your plugin. GTN files are read with a Reader. Readers all implement the class GTNReader and therefore have the same methods. However, before you use a reader you have to build a GroupedTagList object from a file. This is done with the following code:

GroupedTagList list = null;
try{
    list = GTNLib.buildGTL(new File(“./plugins/MyPlugin/thingy.gtn”));
}
catch (InvalidFileException e){
    e.printWarning();
}

Now you have done that, you need to do something with the read file. This depends on what you want to do, but if I want to get a minecraft location from it, I might use the inbuilt LocationReader. Readers have two methods, one is multipleAccumulator and one is singleAccumulator. One gets just one item, the other gets all of them. If I am only looking for one location here is the code to get the item under the name ‘spawn’.

LocationReader l = new LocationReader();
Location loc = l.singleAccumulator(list, “spawn”);

That is it! A full list of Readers available in GTNLib is as follows:

General Reader - Numeric

• DoubleParser
• IntegerParser

General Reader – Text

• StringReader
• CharReader

MC Reader – Inventory

• InventoryReader

MC Reader – Location

• LocationReader

Some readers have extra methods to help you use them better. Take InventoryReader as an example.

InventoryReader i = new InventoryReader();
i.setInventory(list, Bukkit.getPlayer(“Notch”), “kit”);

setInventory is basically a multipleAccumulator, but that also sets the players inventory to the result of the multiple accumulator. These are called Helper or Add-on methods.

Creating your own Reader

To create your own reader, first create a class. The convention is for it to follow the scheme ‘ThingReader’ where Thing is replaced with what it reads. Make the class implement GTNReader. You need to provide parameters for two types. The first one is a single item, so in the case of LocationParser it is the Bukkit Location class, and the next is several items. This will usually be a Set of the single item type, but this is not always the case. For example’s sake I will create a class that has a single item parameter ‘ExampleThing’ and a multiple item parameter ‘Set<ExampleThing>’. I will now implement the methods required, which will create this:

public class ExampleReader implements GTNReader<ExampleThing, Set<ExampleThing>>{

	@Override
	public ExampleThing singleAccumulator(GroupedTagList list, String name) {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public Set<ExampleThing> multipleAccumulator(GroupedTagList list,
			String name) {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public ExampleThing reader(GroupedTagItem i) throws InvalidFileException {
		// TODO Auto-generated method stub
		return null;
	}
	
}

Now you need to fill out the methods. I will do this and then talk you through the code.

public class ExampleReader implements GTNReader<ExampleThing, Set<ExampleThing>>{

	@Override
	public ExampleThing singleAccumulator(GroupedTagList list, String name) {
		Set<GroupedTagItem> iset = list.getItems(name);
		GroupedTagItem item = iset.iterator().next();
		try{
		    return reader(item);
		}
		catch(InvalidFileException e){
			e.printWarning();
		}
		return null;
	}

	@Override
	public Set<ExampleThing> multipleAccumulator(GroupedTagList list, String name) {
		Set<GroupedTagItem> iset = list.getItems(name);
		Set<ExampleThing> thingset = new HashSet<>();
		for(GroupedTagItem item : iset){
			try{
			    thingset.add(reader(item));
			}
			catch(InvalidFileException e){
				e.printWarning();
			}
		}
		return thingset;
	}

	@Override
	public ExampleThing reader(GroupedTagItem i) throws InvalidFileException {
		if(i.hasTag("x")){
			String xval = i.getTag("x");
			return new ExampleThing(xval);
		}
		else{
			throw new InvalidFileException(2);
		}
	}
	
}

The reader method is the core of the Reader class. It takes a single GroupedTagItem and turns it into a single resulting item. The other two methods take the list and either iterate through it (in the case of multipleAccumulator) to get the results or just pass a single GroupedTagItem to the reader method (singleAccumulator). Note that the reader can throw an InvalidFileException – these are the different error codes InvalidFileException can hold.

Codes

• 0 - File is not .gtn
• 1 - Invalid File Syntax
• 2 - Missing compulsary tag
• 3 - Invalid tag value
• 4 - Missing Namespace
• 5 - Tag not applicable

Github

https://github.com/fourohfour/GTNLib - Feel free to clone it and play around, any bug fixes/enhancements welcome