PCGen Code Exploration Almanac

Introduction

This guide is a collection of strategies and ways to tackle tasks in the PCGen code. It doesn’t try to be an architectural guide, for that I would start with Explanation_of_the_Code_Base , which is a good document to be familiar with. There is also some good info at Architecture

Important Tools

There are a few commands I use all the time to explore/move around the PCGen code base.

• Open Type - Eclipse shift-ctrl-T - This allows you to search for a class by its name. Searches can be by the start of the name, use wildcards and even use camel case (NPE finds NullPointerException)
• Call Hierarchy - Eclipse ctrl-alt-H - This shows you where a method is called from. Its great way of tracing execution paths and seeing what the assumptions of callers are.

Lst Tokens as an Entry Point

Quite often you will know the data that is associated with a problem or request. An important tip to remember is that almost all LST tokens are processed by a class which starts with the same name. e.g. the kit EQUIPBUY token is processed by the class plugin.lsttokens.kit.startpack.EquipBuyToken

All token classes then have a parse and unparsed method (sometimes it is in a parent class). You can look at these to find out how the token is interpreted and where the value is stored. Generally the token value is stored in a map in the rules object with a specific constant as a key (e.g. Objectkey.EQUIP_BUY). You can use this key to trace where the token value is processed, thus quickly getting to the code you want to look at.

So, typically in Eclipse I will

1. Search for a class starting with the token name
2. Read through the parse method to see the key used to store the value (or relevant part of the value).
3. Open the Call hierarchy for the key to identify where the token’s value is processed.

Creating a New Lst Token

Adding a new LST token follows a fairly standard pattern:

1. Create a new token class
2. Add a unit test or two
3. Update the pluginbuild.xml
4. Test it out
5. Update the documentation

Also, if you hit any issues when you are creating a new tag post on the dev list for help and someone will be able to assist.

Create a new token class

Creating the new token class is the biggest step. First you need to decide where to create it. All new lst tokens should be under the plugin.lsttokens package. If it is restricted to a single object (Ability, Skill etc) then it should be created under the specific package e.g. plugin.lsttokens.ability. Once created, ensure you have added the LGPL license header and a basic description of the tag in the class java docs.

Now have a look at other tokens in the same package and pick one as an example, hopefully something that works in a similar way to the new tag you are adding. Have a look first at the class definition. Usually you will have something like

public class FooLst 
  extends AbstractNonEmptyToken<CDOMObject> 
  implements CDOMPrimaryToken<CDOMObject>

Here we are using the AbstractNonEmptyToken as the parent class, and thus getting all that classes functionality for free. We are also declaring this to be a CDOMPrimaryToken (i.e. a standalone Lst tag) which wil define what methods we need to implement for the new tag to work properly.

Every token will have a parse and an unparse method. What you will generally do is create a new StringKey, ObjectKey etc to record the new item against and then when you parse the tag you can record it against your key as follows:

context.getObjectContext().put(obj, StringKey.OUTPUT_NAME, value);

Then when you unparse it can read that key and write out the value:

String oname = context.getObjectContext().getString(obj,
	StringKey.OUTPUT_NAME);
if (oname == null)
{
	return null;
}
return new String[] { oname };

Unparsing is used by the LST converter (and the future LST editor) to write out the tag with the correct syntax.

Add a unit test or two

Tom has set up some great unit testing structures which will give your tag a full workout for little effort. Again, the best way is to copy and adjust the test for your example tag. You should be aiming to have a quick isolated test in the code/src/utest folder (e.g. OutputNameLstTest) and a parse/unparse test in the code/src/itest folder (e.g. OutputNameIntegrationTest). These will ensure that your new tags are working as you expect.

Update the pluginbuild.xml

The next step is updating the pluginbuild.xml file to add in your new tag. This creates a jar file for that tag which is then read by the PCGen plugin system on load. As a result PCGen will automatically know about your new tag with no further registration required. Again, use your example existing token as a guide. Once done, you should run the ant build and then run the PluginBuildTest unit test to check that the plguinbuild.xml file has been updated correctly - it will let you know if the name is incorrect etc.

Test it out

OK, now you have the tag added to PCGen. You can add it to some data, load the data and check that it is read in correctly.

Update the documentation

The last step is updating the documentation. When you advance your NEWTAG entry in jira to say the tag is implemented it goes to the docs team. Now they will add in the docs when they get time, but if you want to help out, you can base a new docs entry on the syntax description in your NEWTAG issue. The sample tag you used above can also be a good guide for how to enter it. Also don't forget to mark it as new for the version you added it in.