PCGen Wiki - User contributions [en]

Setting up the new Formula System

2018-03-09T16:24:58Z

Nuance: typo

{| align="right"
| __TOC__
|}

=The basics=

The new formula system is designed to do a few things relative to data:
* Validate formulas at LST load instead of runtime
* Dramatically increase flexibility
* It will replace many tokens, including all the BONUS tokens
* It allows a sensible location for global modifications (things generally related to rule book type modifications that impact all objects of a given type)

==Key concepts==

To use the new system a few key things need to be remembered:
* It is possible to have local variables
* All variables must be defined prior to use
* Variables are not only numbers, but can be Strings, Dice, etc.
** We call this the variable FORMAT

You will want to keep track of what these key terms mean as you learn the new formula system:
* FORMAT: The type of variable, e.g. NUMBER, BOOLEAN, ORDEREDPAIR.
* SCOPE: The part of the data in which a (local) variable is available
* MODIFIER: An argument to MODIFY* tokens, specifically the "command" of what the modification represents
* OPERATOR: A mathematical operator as you would see in a formula ("+", "-", etc.)
* GROUPING: A name for a set of objects in PCGen
* ASSOCIATION: An additional set of information attached to a MODIFY* token. This is a key-value pair of information, e.g. PRIORITY=100

=Creating and Using Variables=

==Required Setup==

Every format that needs to be used requires a default value. This value is shared throughout an entire system (it CANNOT be redefined to a different value). This is placed into a file referred to in a PCC file from the DATACONTROL: token.

===DATACONTROL (PCC File)===

DATACONTROL: is a new Campaign file token (for PCC files). It is treated "recursively" like other tokens, e.g. TEMPLATE.

DATACONTROL:x

* x is the file to be loaded as a DATACONTROL file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

===DEFAULTVARIABLEVALUE (DATACONTROL LST)===

The Format is:
DEFAULTVARIABLEVALUE:X|Y
* X is the format name
* Y is the default value

Example:
DEFAULTVARIABLEVALUE:NUMBER|0

It is a best practice to always define a DEFAULTVARIABLEVALUE for every FORMAT regardless of whether the data uses that FORMAT. The internal parts of PCGen may use it, so a default value may be required.

Note: it IS safe to "redefine" a DEFAULTVARIABLEVALUE to the same value. So if multiple datasets are loaded and they all had DATACONTROL: and all defined the default value for NUMBER to be 0, they will all happily load as the system is capable of recognizing the defaults are the same

==How to define a variable==

===VARIABLE (PCC File)===

To define a variable, you need to add an LST file that is referred to in a PCC file from the VARIABLE: token. It is treated "recursively" like other tokens, e.g. TEMPLATE.

VARIABLE:x

* x is the file to be loaded as a VARIABLE file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

There are 2 basic tokens for the VARIABLE file: GLOBAL and LOCAL.

===GLOBAL (VARIABLE File)===

* GLOBAL defines a global variable, usable from anywhere within the PlayerCharacter.

The format is:
GLOBAL:X=Y
* X is the format name
* Y is the variable name

Example:
GLOBAL:ORDEREDPAIR=Face

A GLOBAL token can take additional token on the line called EXPLANATION, which it is advisable to use to communicate to other data monkeys (and it is likely any future editor will also draw on this information).

===LOCAL (VARIABLE File)===

* LOCAL defines a local variable, usable only within the object on which the variable exists (or its children)
** The place where a local variable is usable is called the SCOPE. This could include a STAT (such as the stat's SCORE or STATMOD) or EQUIPMENT. The scopes possible in PCGen are hard-coded (see below for more info)

The format is:
LOCAL:W|X=Y
* W is the SCOPE of the variable
* X is the format name
* Y is the variable name

Example:
LOCAL:STAT|NUMBER=Score

A LOCAL token can take additional token on the line called EXPLANATION, which it is advisable to use to communicate to other data monkeys (and it is likely any future editor will also draw on this information).

===EXPLANATION (VARIABLE File)===

EXPLANATION: is a free-text token (no parsing is really done) that is designed to describe why a variable exists

Format:
EXPLANATION:x

* x is the text of the Explanation
* Limitations: By Design: Must not appear as the first token on a line
* Behavior: Overwrites (as if someone would use it twice??)

===Defaults in the VARIABLE file===

A few notes about the VARIABLE files:
If you see an item without a leading token, e.g.:
ORDEREDPAIR=Face
...then the system is using the default (GLOBAL). For now, the data standard is to avoid using this shortcut (as far as I know)

If you see an item without a leading format ("X" in both GLOBAL and LOCAL above), e.g.:
LOCAL:STAT|Score
...then the format is a NUMBER. For now, the data standard is to avoid using this shortcut (as far as I know)

Note both defaults can be combined, so a variable name with no other information on that line is a Global NUMBER

===No Overlapping===

In most programming languages, it is legal to have local variable share the same name as the global variable and thus "override" it in that context (although it is considered less than ideal, and in some languages it will now produce a warning). It is not legal in PCGen.

If a Global variable called "Hands" exists, then NO local variable IN ANY SCOPE can be "Hands".

Similar restrictions exist for scopes and SubScopes. If "CritMult" is an EQUIPMENT variable, then "CritMult" can't be an EQUIPMENT.PART variable.

Non-overlapping (when the Scopes do not interact) is legal. "Score" can be a local STAT variable and a local CHECK variable, for example.

For clarity:
* This occurs regardless of the FORMAT of the variables - tokens will infer the format from the variable name, so you can't have overlapping variables even of different FORMAT.
* Two variables of the same name but different FORMAT in the same SCOPE will cause an error as well, because that is effectively overlapping, and those variables can't be distinguished in most circumstances.

===Identical Duplication Legal===

It is legal for a load to include one or more PCC files that have one or more VARIABLE: files that redefine the same variables. As long as they are the same format and scope, they are not considered an error. If either the scope or format differs, then the "No Overlapping" rules above are applied.

A difference in the "Explanation" text is not considered a difference in the variables significant enough to trigger an error. (In fact, the last loaded Explanation will "win" -> it is overwritten each time it is encountered for redefined but identical variables)

==Setting and Modifying a variable==

===MODIFY (LST files)===

The MODIFY token is used to set a variable that is accessible in the current SCOPE. (Note: It could be local to the current scope or any ancestor of the current scope... so modifying a global variable always just requires MODIFY)

The format of the token is:
MODIFY:V|W|X|Y=Z|Y=Z
* V is the Variable name for which the value will be modified
** This variable MUST be visible in the current scope. Therefore, it must be either a global variable or a local variable on the current object or its parents.
* W is the MODIFIER to be taken on the variable (e.g. SET)
** There can be multiple actions (more below), but SET will ALWAYS be available for any format.
* X is the value related to the action. If the action is set, the variable will be set to the value in this part of the token.
** Note: The value CAN be a formula. It is possible, for example, to SET a variable to OtherVar+4 ... the system will solve that formula. For legal OPERATORS (e.g. "+") , see below.
* Y is the name of an (optional) ASSOCIATION. For now, PRIORITY (more below) is the only available association.
* Z is the value of the association.

Note: If a PRIORITY is not set it is assumed to be ZERO.

Example: Give a Player Character 2 hands:
MODIFY:Hands|SET|2

===MODIFYOTHER (LST files)===

The MODIFYOTHER token is used to set a variable that is not accessible in the current SCOPE. Beyond what is necessary in MODIFY, this token also requires the "address" of where to go before it runs the modification. Think of it as the ability to remotely place a MODIFY on another object (but revoke that MODIFY if the current object is no longer granted to the PC)

The format of the token is:
MODIFYOTHER:T|U|V|W|X|Y=Z|Y=Z
* T is the FORMAT of the object on which the resulting MODIFY (as defined by V-Z) should occur
* U is the object or GROUPING of objects on which the MODIFY (as defined by V-Z) should occur
** Note that this does not and will not support TYPE.
* V is the Variable name for which the value will be modified
** This variable MUST be visible in the scope of the addressed object. Therefore, it is likely to be a local variable on the remote object or its parents.
** In rare cases, a remote modification of a global variable is useful. It effectively adds to that global variable only if both objects are granted to the PC.
* W is the MODIFIER to be taken on the variable (e.g. SET)
** There can be multiple actions (more below), but SET will ALWAYS be available for any format.
* X is the value related to the action. If the action is set, the variable will be set to the value in this part of the token.
** Note: The value CAN be a formula. It is possible, for example, to SET a variable to OtherVar+4 ... the system will solve that formula. For legal OPERATORS (e.g. "+") , see below.
* Y is the name of an (optional) ASSOCIATION. For now, PRIORITY (more below) is the only available association.
* Z is the value of the association.

Note: If a PRIORITY is not set it is assumed to be ZERO.

Example: Reduce the HandsRequired on all Weapons by 1:
MODIFYOTHER:EQUIPMENT|GROUP=Weapon|HandsRequired|ADD|-1

Note this assumes GROUP:Weapon is in the LST line of every Weapon... PCGen can't guess or derive what a weapon is :)

==Formulas==

SET as a MODIFIER allows the use of a formula for the value. This follows many mathematical systems of using parenthesis - "(" and ")" to be precise - to group (and thus prioritize parts of the calculation).
There are a number of built in OPERATORs (see below). The system can also use functions, which use parenthesis to contain their arguments. For example:
* min(this,that)
Would return the minimum of the two variables "this" and "that".

===Built in Functions===

The system also has a series of built-in functions that work with the NUMBER format:
* abs: calculates the absolute value of the one argument.
* ceil: calculates the next integer that is >= the value of the one argument.
* floor: calculates the next lower integer that is <= the value of the one argument
* if: conditionally performs an operation. The first argument must resolve to a BOOLEAN. If true, the second argument is evaluated; if false, the third argument is evaluated.
* max: calculates the maximum of the provided two or more comma-separated arguments
* min: calculates the minimum of the provided two or more comma-separated arguments
* round: calculates the closest integer to the value of the one argument. Exactly 0.5 is rounded up.
* value: returns the value of the calculation before the current modification was started (no arguments)

Additional functions specifically related to PCGen are available:
* get: This function takes two arguments. The first is an Object type (like "SKILL"), the second is the key of a CDOMObject (like a Skill) (also in quotes)
**Example: get("SKILL","Hide")
* getFact: This function returns the value of a FACT. The first two arguments are much like the two arguments of "get", the third argument is the name of the FACT to be returned

=Legal Values=

==FORMATs==

Currently, the following are built-in formats:
* NUMBER: This is a mathematical value. Note that integer arithmetic is done if possible, so if you have an integer 6 and an integer 3, 6/3 will be an integer 2. If the 6 or 3 is a decimal value (double), then integer arithmetic was not possible and thus rounding may occur.
* STRING: A String
* BOOLEAN: A True/False value
* ORDEREDPAIR: An ordered pair of numbers. This could be an X,Y point (or in a game system more like a FACE)
* DICE: A value that takes the form AdB+C. A is the number of rolls of the die, B is the number of sides on the die, and C is the value to be added afterwords
* ALIGNMENT: An alignment object (None is default typically)

==OPERATORs==

For NUMBER, the following modifiers are available:
* +: performs addition
* -: performs subtraction (or is the unary minus operator to make a value negative)
* *: performs multiplication
* /: performs division
* %: performs a remainder function
* ^: performs an exponential calculation
* ==: Checks for equality (NOTE: Returns a BOOLEAN, not a NUMBER)
* !=: Checks for inequality (NOTE: Returns a BOOLEAN, not a NUMBER)
* >: Checks for greater than (NOTE: Returns a BOOLEAN, not a NUMBER)
* <: Checks for less than (NOTE: Returns a BOOLEAN, not a NUMBER)
* >=: Checks for greater than or equal to (NOTE: Returns a BOOLEAN, not a NUMBER)
* <=: Checks for less than or equal to (NOTE: Returns a BOOLEAN, not a NUMBER)

For BOOLEAN, the following modifiers are available:
* ==: Checks for equality
* !=: Checks for inequality
* &&: Performs a logical AND
* ||: Performs a logical OR
* !: Negates the value

For other formats, the following operators are always available:
* ==: Checks for equality (NOTE: Returns a BOOLEAN, not the compared format)
* !=: Checks for inequality (NOTE: Returns a BOOLEAN, not the compared format)

==MODIFIERs==

For NUMBER, the following modifiers are available:
* SET: This sets the variable to the value provided in the "X" parameter
* ADD: This adds the current value of the variable to the value provided in the "X" parameter
* MAX: This takes the maximum value of the current value of the variable and the value provided in the "X" parameter (i.e. min(current value, "X"))
* MIN: This takes the minimum value of the current value of the variable and the value provided in the "X" parameter (i.e. max(current value, "X"))
* MULTIPLY: This multiplies the current value of the variable and the value provided in the "X" parameter
* DIVIDE: This divides the current value of the variable by the value provided in the "X" parameter

For other Formats, the SET modifier will always be available

==GROUPINGs==

At present, the second argument of MODIFYOTHER supports 3 possible values:
* ALL
** This means the MODIFYOTHER will impact ALL objects of that type. This is useful for setting a general default for that value (e.g. you could default "HandsRequired" on weapons to 1)
* GROUP=X
** This is set by the GROUP token in LST data
* A specific object KEY

More will be added over time.

==SCOPEs==

The following are the legal scopes (not including GLOBAL):
* EQUIPMENT: This is a variable local to equipment
** EQUIPMENT.PART: This is a variable local to an equipment PART (or in older terms, an Equipment HEAD). Note that due to double sided weapons, Damage, CritMult and other items are generally on an equipment PART, not on the Equipment itself. Note also that this is a SUBSCOPE of the EQUIPMENT scope (so all variables in the EQUIPMENT scope can also be seen in the EQUIPMENT.PART scope)
* SAVE: This is a variable local to Save (or if you prefer, Check)
* SIZE: This is a variable local to the Size of a PC
* SKILL: This is a variable local to a Skill
* STAT: This is a variable local to a Stat

More will be added over time.

DYNAMIC can also be used to create a Scope and Object Type (see below)

=Examples=

==Understanding SubScope in practice==

To understand how local variables work in SubScopes, consider the following (note this is not all the variables we will use but a critical set to define the scope):
GLOBAL:NUMBER=Hands
LOCAL:EQUIPMENT|NUMBER=HandsRequired
LOCAL:EQUIPMENT|BOOLEAN=Penalized
LOCAL:EQUIPMENT.PART|NUMBER=CritMult

The Equipment part is what the traditional system called a "head" (so a double headed axe has two "parts" in the new system - this was done since in some game systems, an item could have more than 2)

To understand how variables are available and how they get modified consider this:

Inside of a piece of equipment it could do something like:
MODIFY:Penalized|SET|HandsRequired>Hands

This would be "true" if HandsRequired on the Equipment were more than the Hands on the PC. The "Hands" variable is Global, so it is available anywhere. A Template of "Extra Hands" could do something like:
MODIFY:Hands|ADD|2
... and that adds to the Global variable "Hands".

Now consider an Equipment Modifier that was something like "Lighter Than Normal". Assume the game benefit was one less hand is required. This would look like:
Lighter Than Normal MODIFY:HandsRequired|ADD|-1
(This ignores for the moment any situation like "can't be reduced to below one".)

Note that the EquipmentModifier falls into EQUIPMENT.PART, so that it has access to the HandsRequired variable from the EQUIPMENT scope and can modify it. Note that this change could then impact the result of the BOOLEAN variable Penalized, since HandsRequired changed. Note also that "HandsRequired", when evaluated anywhere in that Equipment is now 1 less. Even if another EquipmentModifier evaluates HandsRequired, it is analyzing the variable from its parent scope, so that value on a variable from EQUIPMENT is the same in every EquipmentModifier (in the EQUIPMENT.PART scope) of that piece of Equipment.

==Understanding SubScope on Equipment==

Since variables like CritMult and Damage would be on an Equipment "part" it is important to understand how to get access to that "part" from the LST code. If a single-headed weapon wanted a larger CritMult, it would be silly to have to add a Dummy EquipmentModifier just to modify the CritMult on the part. (Much of the point of the new system is to make things more direct)

There is a token for Equipment called PART. This effectively takes 2 arguments: A number (today 1 for the primary head, 2 for the secondary head) and a full token otherwise valid on a plain object. MODIFY and MODIFYOTHER will both work in that situation, so for a piece of Equipment to set its own CritMult to 3 on its primary (and perhaps only) head, it would do:
PART:1|MODIFY:CritMult|SET|3

Note since the MODIFY is a "real" token call it uses ":" after the MODIFY which makes PART look slightly different to most tokens which use | as an internal separator. Since PART is effectively calling a "real" token, we need to use the inner ":" in order to have it pass through the same code/parsing system.

==Understanding SubScopes in relation to MODIFYOTHER==

* Note Jan 29 2018: There is a possibility of a solution for this issue that would allow MODIFYOTHER to do direct addressing of sub-objects under certain conditions

Normally MODIFYOTHER allows you to "address" another scope. For example:
MODIFYOTHER:EQUIPMENT|Bastard Sword|HandsRequired|ADD|-1

However, since items like Damage and CritMult are actually on the EQUIPMENT.PART, that is different. If you consider how you would have to "address" the first head on "Bastard Sword", you would need something like:
SOMEWEIRDTOKEN:EQUIPMENT|Bastard Sword|PART|1|CritMult|ADD|1

Note that this requires both a primary and secondary address. No token like this exists (at the moment). To alter items in a SubScope, you need to pass them down to the SubScope. An attempt to modify it at the Equipment level, such as:
MyAbility MODIFYOTHER:EQUIPMENT|ALL|CritMult|ADD|1
... will fail (at LST load) because CritMult was on EQUIPMENT.PART, so it is not visible to the EQUIPMENT scope. Said another way, you can't universally modify all EQUIPMENT.PART variables by attempting to use that variable at a higher scope.

A more appropriate method (since this is relevant to a Feat that might alter CritMult) is to add another variable at the EQUIPMENT level:
LOCAL:EQUIPMENT|NUMBER=CritMultAdder
If all the heads then get
MODIFY:CritMult|ADD|CritMultAdder
... you can have the Feat do a MODIFYOTHER to alter CritMultAdder and the MODIFY will "pull" that into each PART:
SomeFeat MODIFYOTHER:EQUIPMENT|ALL|CritMultAdd|ADD|1
So the data can be set up to only require one modification from a Feat and each Equipment Part can pull that modification down into the part. (A tangential note for those objecting that the known modifiers of CritMult select a specific weapon type: Yep, got it. That's not possible yet, so not documented yet. Suspend disbelief on the examples - Imagine a more powerful Feat for now)

==Understanding PRIORITY and processing of MODIFY and MODIFYOTHER==

When a PlayerCharacter has multiple items that attempt to modify a variable, they are sorted by two systems:
* First, they are sorted by their user priority. This is provided in the PRIORITY=Z association. Lower PRIORITY will be processed first.
* Second, they are sorted by their inherent priority. This is a built-in system that approximates mathematical priority rules. It ensures, for example, that a SET will occur before ADD if they both have a matching user priority.

Example:
Assume we had the following items:
MODIFY:Hands|MULTIPLY|2|PRIORITY=100
MODIFY:Hands|SET|2|PRIORITY=50
MODIFY:Hands|ADD|1|PRIORITY=50

The first thing is that we can tell from the PRIORITY items that the SET and ADD will both occur BEFORE the multiply (because 50 < 100). For the SET and ADD, we would need to know the inherent priority (For what it's worth, SET is 0, ADD is 3, MULTIPLY and DIVIDE are 1 and 2 since they are higher priority than ADD in traditional math). This means the SET will happen first. So the result is Hands is SET to 2, then ADD 1 to get 3, then MULTIPLY by 2 to get 6.

By controlling the PRIORITY, the data team can reorder any calculation and perform much more complicated calculations than was possible with BONUS (where movement, for example, had multiple different BONUS tokens to try to do adding before and after a multiply). This is much the same as using parenthesis in a formula in normal math, but this allows you trigger any required ordering even if the MODIFY statements are in different objects.

==Using the previous value in a more complex calculation==

Take a modification that, for example, wishes to perform a calculation such as: "Reduce the value by 1, but to no less than 1". We could write this as two MODIFY statements, but that is probably undesirable for a few reasons:
* If the book states it as one sentence, it would be preferable to write it as one MODIFY
* It makes the calculation a bit harder to follow as to what is going on
* If the items are different PRIORITY, there is a risk of another dataset attempting to (or accidentally) putting something in between those two steps, resulting in an incorrect calculation.

Therefore, we need a method of drawing on the current value in a formula. To do that we use the value() function. The calculation above then becomes:
max(value()-1,1)
...and we can use it in a MODIFY as such:
MODIFY:HandsRequired|SET|max(value()-1,1)

Note that we are using SET here - if a formula is used, it is likely to be best done as a SET, since that will be much more clear than calculating a formula and then immediately applying another MODIFICATION. Note that some modifications may also prohibit a formula depending on their underlying behavior.

=Global Modifier File=

There is a new file type that is defined in the PCC files with GLOBALMODIFIER.

This file allows for a centralized (and clear to the data user) location for global modifications (don't hide things on stats or elsewhere anymore). This supports MODIFY for global variables (if you want to start all PCs with 2 hands for example) or MODIFYOTHER for local variables.

==GLOBALMODIFIER (PCC File)==

Format:
GLOBALMODIFIER:x
* x is the file to be loaded as a GLOBALMODIFIER file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

=Advanced Topics=

==Dynamic Objects and Scope==

This set of features allows the data to supplement the defined SCOPEs with new object types not originally comprehended in PCGen. Within a Dynamic Scope, the data can produce objects.

Warning: Attempts to define a SCOPE that overlaps with existing objects (e.g. LANGUAGE) will not produce a warning today but will get you in trouble long term. It won't work in the way you would like it to work (it won't attach a SCOPE to that object type), so just avoid those overlapping names. Basically if you can CHOOSE it, or use it with FACT, don't DYMAMICSCOPE it.

===DYNAMICSCOPE (DATACONTROL LST)===

The DYNAMICSCOPE token (used in files referred to by the DATACONTROL: token in PCC files) can define a Dynamic Scope.

DYNAMICSCOPE:x

*x is the new scope
**Any argument to DYNAMICSCOPE becomes a legal "scope" in LOCAL: in the variable definition file
**Limit of one new scope per line. (No delimiter on this token)
*Like other LST tokens, this is case insensitive, but usage in later tokens is always capitalized, so I suspect the data standard should be ALL CAPS

===DYNAMIC (PCC File)===

In order to create objects within the defined DYNAMICSCOPE, DYNAMIC: becomes a new token legal in PCC files. It's format is:

DYNAMIC:x

* x is the file just as in tokens like DEITY or DOMAIN
* INCLUDE/EXCLUDE on the line are are legal.

Within the Dynamic file, the Scope of the new objects being created MUST appear as a prefix token on the line. For example, if there was a DYNAMICSCOPE:VISION, then the following would be legal in a DYNAMIC file:
VISION:Darkvision
VISION:Low-Light Vision

* The "Token Name" (what appears before the ':') is the DYNAMICSCOPE name.
* These are created as basically hollow, simple objects.
* These objects CAN contain variables.
(It is the intent to allow these at some point to also have MODIFY* tokens, but that is not currently supported)

===GRANT (LST files)===

A Dynamic object MUST be granted in order to have its local variables modified or to have its modifiers have an impact (just like any other object)

GRANT:x|y

* x is a DYNAMICSCOPE
* y is the name of the dynamic object.

===Export===

Dynamic items can be exported in Freemarker using the

<#list pc.dynamic.x as y>

* x is the name of the DYNAMICSCOPE
* y is the local variable within the #list that the output team wants to use to access the dynamic object
* It is likely for ease of use by the output team, x and y will be identical

For a complete example using output, see below

===Example===

DATACONTROL: file:
DYNAMICSCOPE:VISION

DYNAMIC: file:
VISION:Normal
VISION:Darkvision
VISION:Low-Light Vision

VARIABLE: File:
LOCAL:VISION|NUMBER=Range

GLOBALMODIFIERFILE:
MODIFYOTHER:VISION|ALL|Range|Set|60

Sets a "default" range for any VISION, to avoid setting on each VISION object

RACE LST file:
Human <> GRANT:VISION|Normal

Export:

<#list pc.dynamic.vision as vision>
${vision.name} ${vision.val.range}
</#list>

(this ignores converting the range to local units and all that, but you get the idea)

==ARRAY Format==

In addition to the base formats, there is an ARRAY[x] format:
ARRAY[x]
* x is an existing valid Format
** x CANNOT be ARRAY (multi-dimensional arrays not supported
** Just to be precise, yes DYNAMIC formats are legal

(Note: This may get renamed - we need to decide on a few things for how this will work vs other types of collections)

===Modifiers===

There are two valid MODIFIERs for ARRAY:
* ADD: This adds a value to the ARRAY
** Mathematically, ARRAY acts as an ordered set of objects. Therefore, if you add an item to an array more than once it is ignored.
* SET: This sets the contents of the ARRAY

==Custom Functions==

Within certain game systems, there are calculations that are likely to be repeated. In order to simplify the calculation of these items, there is an ability to create custom functions.

A function can have zero or more arguments. The number is defined by what appears in the VALUE token (see below).

Note that the function actually has to be *used in the data* (not just defined) for most errors to be caught (since the system can't guess at overall context before a function is used and it would be possible to write a function that would work in more than one FORMAT).

===Function (DATACONTROL LST)===

FUNCTION:x
* This token must appear as the first token on a line in a DATACONTROL file.
* x is the name of the function. This name must starts with a letter, e.g. A-Z, additional legal characters are 0-9 and _ (none of those additional legal characters as the first character)
** x must not contain spaces, no other special characters.
** Function names are case insensitive (as many other things in LST files)

A Function MUST also contain a VALUE, which defines how the function is calculated.

If a FUNCTION appears more than once, the other characteristics (VALUE) must be identical.

===Value (DATACONTROL LST)===

VALUE:x
* Must appear as an additional token on the line of a FUNCTION: in the data control file
* x is a valid formula.
** This means it must have valid variable names, valid function names, matching parenthesis, etc.

In addition to all of the built-in functions (e.g. if, ceil, round), two additional items can be used:
* the arg(n) function (see below).
* Any previously defined FUNCTION. This MUST appear in the file before the current Function or in a file processed before the current file.

===arg (Function)===

The arg function is a "local" function to the VALUE: part of a FUNCTION (it can not generally be used in LST files). The arg function takes one argument. It MUST be a Integer >= 0.

arg(x)
* x is an integer number (zero-indexed)

When arg(x) is used in value, the function pulls from the arguments that were provided to the original function in the data.

===Using a Function===

When a function is used in LST data, it is called by the name provided in the FUNCTION token. It requires a certain number of arguments. This exactly matches the integer one greater than the highest number of the arg(n) function provided in the VALUE part of a FUNCTION (In computer science terms, the arg(n) function is zero-indexed). The provided arguments can be any legal formula, so:

d20Mod(INT)
d20Mod(INT+4)

...are both perfectly legal.

===Example===

The modification calculation in most d20 games is fairly easy to calculate, but is repeated very often. It basically takes (ability score - 10)/2.

Here is how we would define a new function d20Mod in the DATACONTROL file:
FUNCTION:d20Mod VALUE:floor((arg(0)-10)/2)

This would then be used in LST data as:

d20Mod(n)

The system will catch both of these as errors:

d20Mod()
d20Mod(14,5)

These have too few or too many arguments, respectively. It would also catch:

d20Mod("mystring")

...as an error (wrong format - requires a Number, found a String).

The n is substituted where "arg(0)" appears in the "VALUE"... so a statmod would be as easy as:

d20Mod(INT)

or some such... Direct values can also be used, e.g.:

d20Mod(10)

...would return 0.

==Performance Considerations==

It is possible to write two identical modifiers that perform the same net calculation on a PC. For example:
MODIFY:Age|ADD|2
MODIFY:Age|SET|value()+2

...perform the same calculation (adding 2 to Age).

Why have ADD at all? Answer: These are NOT AT ALL equivalent in memory use or speed/performance.

The ADD (Since it's adding an integer) occupies approximately 40 bytes of memory and is an extremely rapid calculation: If it took 200 nanoseconds I'd be surprised. This is because ADD is using a number. If it was a formula, even 1+2, it would load the formula parser. This special case on constants allows the modification system to modify a value without loading a much larger infrastructure, and this is valuable as a large majority of our calculations are simple modifications of values.

The SET shown above (since it has an operator) loads the formula system, and thus may occupy 500 (or more) bytes of memory (>10x), so it could take 100 times as long to process as the ADD (it also took longer during LST load).

Thus: When possible the data standards should be written to use numeric modifiers and no operator. (Think "static" modifiers ... that only use numbers) rather than a formula.

==Lookup and Tables==

For some situations, it makes more sense to have a lookup table rather than attempting to have a set of tokens or calculations perform processing. This also allows for much cleaner translation from books when the books are using tables to organize information.

The Table file format is designed to allow you to use a spreadsheet program to modify the tables and export the table in CSV format. While we don't strictly follow full CSV rules, as long as you avoid embedded quotes and embedded return carriage/line feed, it should be safe.

More than one table is allowed per file (to avoid sprawl and help simplify modification/management of tables).

===TABLE (PCC File)===

TABLE:x
* x is the file to be loaded as a TABLE file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

====Table LST file format====

File formatting considerations:
* Trailing commas will not impact any TABLE, and will be ignored
* Blank lines will be ignored. This includes lines with commas but without content. (allows tables to be separated by blank lines or lines of all commas)
* Attempts to use embedded line breaks or embedded quotes may or may not be supported by the parsing system, but certainly aren't supported for purposes of PCGen.
* Lines that have the first cell starting with "#" are considered comment lines and will be ignored. This will likely need to include if the first cell is escaped in quotes, just for protection from any tools that quote by default.
* Since the CSV format ignores leading/trailing spaces, one can easily have a spaced out version that is a table in a text editor if folks don't want to edit in a spreadsheet. (Having someone write a "PrettyTable" ... a trivial perl or python program to do that for the data team seems fairly easy)

A TABLE starts with STARTTABLE:
STARTTABLE:x
* x is the name of the Table. Most characters are allowed, avoiding quotes is advisable.
* Allowing Trailing commas allows the STARTTABLE lines to have blank cells where the rest are the table contents... we don't want to complain on minor things that may tools will do.

If a STARTTABLE is encountered when another Table is active, an LST load error will occur.

A TABLE ends with ENDTABLE:
ENDTABLE:x
* x is the name of the Table. Most characters are allowed, avoiding quotes is advisable.
* Allowing Trailing commas allows the ENDTABLE lines to have blank cells where the rest are the table contents... we don't want to complain on minor things that may tools will do.

If an ENDTABLE is encountered without a STARTTABLE, an LST load error will occur.

A Table must have a minimum of 3 rows, NOT counting the STARTTABLE and ENDTABLE tokens.

The First row:
x,x
* x is the column name. These are always the first line of the table after STARTTABLE:

Any column which has data MUST have a name.

The Second row:
y,y
* y is the format for the column. Any column that was named must have a FORMAT.

Additional rows:
z,z
* z represents contents of the table. These must be in the FORMAT provided for the appropriate column.

====Example====

STARTTABLE:Carrying Capacity,
Strength,Capacity
NUMBER,NUMBER
1,10
2,20
...
29,1400
ENDTABLE:Carrying Capacity,

===TABLE[x] Format===

When a TABLE is created, it implicitly picks up a FORMAT based on the FORMAT of the first column of the Table.
Unlike basic FORMATs shown above, TABLE has a SUBFORMAT (in brackets).

TABLE[x]
* x is the SUB-FORMAT of the TABLE (this is the format of the first column of the Table)
** x must be an otherwise valid FORMAT, and it is advised to avoid any FORMAT that has a SUB-FORMAT
*** This limitation may be inconsistently enforced. It certainly is prohibited to create a TABLE[TABLE[x]], but other situations the behavior may not be prohibited by the code (but the behavior is also not guaranteed)

===COLUMN[x] Format===

When a Column needs to be referred to in the data, it has a special format as well:

Unlike basic FORMATs shown above, COLUMN has a SUBFORMAT (in brackets).
COLUMN[x]
* x is the SUB-FORMAT of the COLUMN (this is the format of the data that appears in that column in a Table)
** x must be an otherwise valid FORMAT, and it is advised to avoid any FORMAT that has a SUB-FORMAT
*** This limitation may be inconsistently enforced. Such behavior may not be prohibited by the code (but avoiding bad behavior is also not guaranteed in a situation where embedded brackets occur)

===Using Tables===

With MODIFY, a TABLE[x] variable doesn't look any different. It's still:
MODIFY:TableNameVar|SET|"SomeTable"

"SomeTable" is still a string to a naive reader, but what the system will do at that point is make sure that SomeTable can actually be interpreted as a TABLE[x]... rather than just treating it as a String. Similar for column names when they are encountered (see below).

In that way, the sub variable will allow multiple tables to be swapped in, AS LONG AS they are the right format. If the format is not compatible, then all bets are off and you'll get an error.

===lookup() Function===

The major consideration is how to do the lookup in data. We can borrow some inspiration from things like Excel and Google Docs:

lookup(X,Y,Z)

* X is a table. This must resolve in the formula system to a valid table. For now, a get(...) function may be required.
* Y is the lookup value in the table. It must match the format of the first column in the table. At this time, it does an EXACT match.
* Z is the target column. This must resolve in the formula system to a valid table column. It must appear in the table named by the contents of the first argument of lookup.

Example: Max load calculation would be something like:
lookup("Carrying Capacity",floor(StrScore),"Capacity")*SizeMult
We have to do the floor due to the exact name of the lookup

Note: The format of both TABLE "Carrying Capacity" and COLUMN "Capacity" can be derived by PCGen internally and thus are no longer required to have a get (current as of Jan 30, 2018)

Note that this function allows some runtime errors, but catches a lot of possible issues. It is still possible to do a lookup on a Table that doesn't contain a specific column of the given name or format, simply because those items can be variables resolved at runtime. For example, if the third variable is COLUMN[NUMBER], we can check at load that the TABLEFORMAT has columns of FORMAT=NUMBER, but we can't guarantee the variable will resolve to a name actually in that table... that will have to wait for a runtime error. That's life, but it does allow us to know the formats at load time, so we do get a lot of error checking in the context of the usage, if not the exact table and column names.

Note you can do some really dynamic behaviors to have folks override game mode behaviors. For example, one neat item would be that we could alter a query for dice steps to extract the table name into the Global Modifier file:
MODIFY:DiceStepTable|SET|"Dice Step"
lookup(get("TABLE[NUMBER]",DiceStepTable),BaseDamage,get("COLUMN[NUMBER]",lookup("Step Column",CurrentSize-BaseSize,"Name")))

Note: In both cases here, the "get" is shown for completeness. In the case of DiceStepTable - it MAY be required or prohibited - it depends on what the Format is of the "DiceStepTable" variable. If it's TABLE, then the get is not necessary (and is actually prohibited). The example shown above assumes DiceStepTable is a String. The better design would be for it to be a TABLE (specifically TABLE[NUMBER]). For the "get" after the lookup, that is required - the lookup value will return a STRING, and as such, will needs to be converted to a COLUMN.

Now, if someone needs different dice steps for some reason... they can override the DiceStepTable variable and it will look up in a different table... so expansions could truly be expansions and not have to reach back into core PCC files in order to change key behaviors.

Consider also that spell tables can be shared across classes, or if a subclass alters the default, just create a new table rather than having to BONUS/MODIFY all the numbers in a table with adding and subtracting...

==To be completed==
* dropIntoContext
* Channels

=Material Changes=

==lookup function simplification==

Effective January 30, 2018, tables and columns can be referred to directly in lookup(). This is actually a "broad" change to how strings are interpreted. The system - when possible - fully asserts a FORMAT, and first attempts to convert the given String per the rules of that FORMAT. This also means an assignment of an ALIGNMENT, by key, will not require a "get":
MODIFY:Alignment|SET|"LE"
...will be fully legal. (This assumes Alignment is FORMAT: of ALIGNMENT)

Setting up the new Formula System

2018-03-09T16:10:11Z

Nuance: Correct typo/grammar error.

{| align="right"
| __TOC__
|}

=The basics=

The new formula system is designed to do a few things relative to data:
* Validate formulas at LST load instead of runtime
* Dramatically increase flexibility
* It will replace many tokens, including all the BONUS tokens
* It allows a sensible location for global modifications (things generally related to rule book type modifications that impact all objects of a given type)

==Key concepts==

To use the new system a few key things need to be remembered:
* It is possible to have local variables
* All variables must be defined prior to use
* Variables are not only numbers, but can be Strings, Dice, etc.
** We call this the variable FORMAT

You will want to keep track of what these key terms mean as you learn the new formula system:
* FORMAT: The type of variable, e.g. NUMBER, BOOLEAN, ORDEREDPAIR.
* SCOPE: The part of the data in which a (local) variable is available
* MODIFIER: An argument to MODIFY* tokens, specifically the "command" of what the modification represents
* OPERATOR: A mathematical operator as you would see in a formula ("+", "-", etc.)
* GROUPING: A name for a set of objects in PCGen
* ASSOCIATION: An additional set of information attached to a MODIFY* token. This is a key-value pair of information, e.g. PRIORITY=100

=Creating and Using Variables=

==Required Setup==

Every format that needs to be used requires a default value. This value is shared throughout an entire system (it CANNOT be redefined to a different value). This is placed into a file referred to in a PCC file from the DATACONTROL: token.

===DATACONTROL (PCC File)===

DATACONTROL: is a new Campaign file token (for PCC files). It is treated "recursively" like other tokens, e.g. TEMPLATE.

DATACONTROL:x

* x is the file to be loaded as a DATACONTROL file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

===DEFAULTVARIABLEVALUE (DATACONTROL LST)===

The Format is:
DEFAULTVARIABLEVALUE:X|Y
* X is the format name
* Y is the default value

Example:
DEFAULTVARIABLEVALUE:NUMBER|0

It is a best practice to always define a DEFAULTVARIABLEVALUE for every FORMAT regardless of whether the data uses that FORMAT. The internal parts of PCGen may use it, so a default value may be required.

Note: it IS safe to "redefine" a DEFAULTVARIABLEVALUE to the same value. So if multiple datasets are loaded and they all had DATACONTROL: and all defined the default value for NUMBER to be 0, they will all happily load as the system is capable of recognizing the defaults are the same

==How to define a variable==

===VARIABLE (PCC File)===

To define a variable, you need to add an LST file that is referred to in a PCC file from the VARIABLE: token. It is treated "recursively" like other tokens, e.g. TEMPLATE.

VARIABLE:x

* x is the file to be loaded as a VARIABLE file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

There are 2 basic tokens for the VARIABLE file: GLOBAL and LOCAL.

===GLOBAL (VARIABLE File)===

* GLOBAL defines a global variable, usable from anywhere within the PlayerCharacter.

The format is:
GLOBAL:X=Y
* X is the format name
* Y is the variable name

Example:
GLOBAL:ORDEREDPAIR=Face

A GLOBAL token can take additional token on the line called EXPLANATION, which it is advisable to use to communicate to other data monkeys (and it is likely any future editor will also draw on this information).

===LOCAL (VARIABLE File)===

* LOCAL defines a local variable, usable only within the object on which the variable exists (or its children)
** The place where a local variable is usable is called the SCOPE. This could include a STAT (such as the stat's SCORE or STATMOD) or EQUIPMENT. The scopes possible in PCGen are hard-coded (see below for more info)

The format is:
LOCAL:W|X=Y
* W is the SCOPE of the variable
* X is the format name
* Y is the variable name

Example:
LOCAL:STAT|NUMBER=Score

A LOCAL token can take additional token on the line called EXPLANATION, which it is advisable to use to communicate to other data monkeys (and it is likely any future editor will also draw on this information).

===EXPLANATION (VARIABLE File)===

EXPLANATION: is a free-text token (no parsing is really done) that is designed to describe why a variable exists

Format:
EXPLANATION:x

* x is the text of the Explanation
* Limitations: By Design: Must not appear as the first token on a line
* Behavior: Overwrites (as if someone would use it twice??)

===Defaults in the VARIABLE file===

A few notes about the VARIABLE files:
If you see an item without a leading token, e.g.:
ORDEREDPAIR=Face
...then the system is using the default (GLOBAL). For now, the data standard is to avoid using this shortcut (as far as I know)

If you see an item without a leading format ("X" in both GLOBAL and LOCAL above), e.g.:
LOCAL:STAT|Score
...then the format is a NUMBER. For now, the data standard is to avoid using this shortcut (as far as I know)

Note both defaults can be combined, so a variable name with no other information on that line is a Global NUMBER

===No Overlapping===

In most programming languages, it is legal to have local variable share the same name as the global variable and thus "override" it in that context (although it is considered less than ideal, and in some languages it will now produce a warning). It is not legal in PCGen.

If a Global variable called "Hands" exists, then NO local variable IN ANY SCOPE can be "Hands".

Similar restrictions exist for scopes and SubScopes. If "CritMult" is an EQUIPMENT variable, then "CritMult" can't be an EQUIPMENT.PART variable.

Non-overlapping (when the Scopes do not interact) is legal. "Score" can be a local STAT variable and a local CHECK variable, for example.

For clarity:
* This occurs regardless of the FORMAT of the variables - tokens will infer the format from the variable name, so you can't have overlapping variables even of different FORMAT.
* Two variables of the same name but different FORMAT in the same SCOPE will cause an error as well, because that is effectively overlapping, and those variables can't be distinguished in most circumstances.

===Identical Duplication Legal===

It is legal for a load to include one or more PCC files that have one or more VARIABLE: files that redefine the same variables. As long as they are the same format and scope, they are not considered an error. If either the scope or format differs, then the "No Overlapping" rules above are applied.

A difference in the "Explanation" text is not considered a difference in the variables significant enough to trigger an error. (In fact, the last loaded Explanation will "win" -> it is overwritten each time it is encountered for redefined but identical variables)

==Setting and Modifying a variable==

===MODIFY (LST files)===

The MODIFY token is used to set a variable that is accessible in the current SCOPE. (Note: It could be local to the current scope or any ancestor of the current scope... so modifying a global variable always just requires MODIFY)

The format of the token is:
MODIFY:V|W|X|Y=Z|Y=Z
* V is the Variable name for which the value will be modified
** This variable MUST be visible in the current scope. Therefore, it must be either a global variable or a local variable on the current object or its parents.
* W is the MODIFIER to be taken on the variable (e.g. SET)
** There can be multiple actions (more below), but SET will ALWAYS be available for any format.
* X is the value related to the action. If the action is set, the variable will be set to the value in this part of the token.
** Note: The value CAN be a formula. It is possible, for example, to SET a variable to OtherVar+4 ... the system will solve that formula. For legal OPERATORS (e.g. "+") , see below.
* Y is the name of an (optional) ASSOCIATION. For now, PRIORITY (more below) is the only available association.
* Z is the value of the association.

Note: If a PRIORITY is not set it is assumed to be ZERO.

Example: Give a Player Character 2 hands:
MODIFY:Hands|SET|2

===MODIFYOTHER (LST files)===

The MODIFYOTHER token is used to set a variable that is not accessible in the current SCOPE. Beyond what is necessary in MODIFY, this token also requires the "address" of where to go before it runs the modification. Think of it as the ability to remotely place a MODIFY on another object (but revoke that MODIFY if the current object is no longer granted to the PC)

The format of the token is:
MODIFYOTHER:T|U|V|W|X|Y=Z|Y=Z
* T is the FORMAT of the object on which the resulting MODIFY (as defined by V-Z) should occur
* U is the object or GROUPING of objects on which the MODIFY (as defined by V-Z) should occur
** Note that this does not and will not support TYPE.
* V is the Variable name for which the value will be modified
** This variable MUST be visible in the scope of the addressed object. Therefore, it is likely to be a local variable on the remote object or its parents.
** In rare cases, a remote modification of a global variable is useful. It effectively adds to that global variable only if both objects are granted to the PC.
* W is the MODIFIER to be taken on the variable (e.g. SET)
** There can be multiple actions (more below), but SET will ALWAYS be available for any format.
* X is the value related to the action. If the action is set, the variable will be set to the value in this part of the token.
** Note: The value CAN be a formula. It is possible, for example, to SET a variable to OtherVar+4 ... the system will solve that formula. For legal OPERATORS (e.g. "+") , see below.
* Y is the name of an (optional) ASSOCIATION. For now, PRIORITY (more below) is the only available association.
* Z is the value of the association.

Note: If a PRIORITY is not set it is assumed to be ZERO.

Example: Reduce the HandsRequired on all Weapons by 1:
MODIFYOTHER:EQUIPMENT|GROUP=Weapon|HandsRequired|ADD|-1

Note this assumes GROUP:Weapon is in the LST line of every Weapon... PCGen can't guess or derive what a weapon is :)

==Formulas==

SET as a MODIFIER allows the use of a formula for the value. This follows many mathematical systems of using parenthesis - "(" and ")" to be precise - to group (and thus prioritize parts of the calculation).
There are a number of built in OPERATORs (see below). The system can also use functions, which use parenthesis to contain their arguments. For example:
* min(this,that)
Would return the minimum of the two variables "this" and "that".

===Built in Functions===

The system also has a series of built-in functions that work with the NUMBER format:
* abs: calculates the absolute value of the one argument.
* ceil: calculates the next integer that is >= the value of the one argument.
* floor: calculates the next lower integer that is <= the value of the one argument
* if: conditionally performs an operation. The first argument must resolve to a BOOLEAN. If true, the second argument is evaluated; if false, the third argument is evaluated.
* max: calculates the maximum of the provided two or more comma-separated arguments
* min: calculates the minimum of the provided two or more comma-separated arguments
* round: calculates the closest integer to the value of the one argument. Exactly 0.5 is rounded up.
* value: returns the value of the calculation before the current modification was started (no arguments)

Additional functions specifically related to PCGen are available:
* get: This function takes two arguments. The first is a Object type (like "SKILL"), the second is the key of a CDOMObject (like a Skill) (also in quotes)
**Example: get("SKILL","Hide")
* getFact: This function returns the value of a FACT. The first two arguments are much like the two arguments of "get", the third argument is the name of the FACT to be returned

=Legal Values=

==FORMATs==

Currently, the following are built-in formats:
* NUMBER: This is a mathematical value. Note that integer arithmetic is done if possible, so if you have an integer 6 and an integer 3, 6/3 will be an integer 2. If the 6 or 3 is a decimal value (double), then integer arithmetic was not possible and thus rounding may occur.
* STRING: A String
* BOOLEAN: A True/False value
* ORDEREDPAIR: An ordered pair of numbers. This could be an X,Y point (or in a game system more like a FACE)
* DICE: A value that takes the form AdB+C. A is the number of rolls of the die, B is the number of sides on the die, and C is the value to be added afterwords
* ALIGNMENT: An alignment object (None is default typically)

==OPERATORs==

For NUMBER, the following modifiers are available:
* +: performs addition
* -: performs subtraction (or is the unary minus operator to make a value negative)
* *: performs multiplication
* /: performs division
* %: performs a remainder function
* ^: performs an exponential calculation
* ==: Checks for equality (NOTE: Returns a BOOLEAN, not a NUMBER)
* !=: Checks for inequality (NOTE: Returns a BOOLEAN, not a NUMBER)
* >: Checks for greater than (NOTE: Returns a BOOLEAN, not a NUMBER)
* <: Checks for less than (NOTE: Returns a BOOLEAN, not a NUMBER)
* >=: Checks for greater than or equal to (NOTE: Returns a BOOLEAN, not a NUMBER)
* <=: Checks for less than or equal to (NOTE: Returns a BOOLEAN, not a NUMBER)

For BOOLEAN, the following modifiers are available:
* ==: Checks for equality
* !=: Checks for inequality
* &&: Performs a logical AND
* ||: Performs a logical OR
* !: Negates the value

For other formats, the following operators are always available:
* ==: Checks for equality (NOTE: Returns a BOOLEAN, not the compared format)
* !=: Checks for inequality (NOTE: Returns a BOOLEAN, not the compared format)

==MODIFIERs==

For NUMBER, the following modifiers are available:
* SET: This sets the variable to the value provided in the "X" parameter
* ADD: This adds the current value of the variable to the value provided in the "X" parameter
* MAX: This takes the maximum value of the current value of the variable and the value provided in the "X" parameter (i.e. min(current value, "X"))
* MIN: This takes the minimum value of the current value of the variable and the value provided in the "X" parameter (i.e. max(current value, "X"))
* MULTIPLY: This multiplies the current value of the variable and the value provided in the "X" parameter
* DIVIDE: This divides the current value of the variable by the value provided in the "X" parameter

For other Formats, the SET modifier will always be available

==GROUPINGs==

At present, the second argument of MODIFYOTHER supports 3 possible values:
* ALL
** This means the MODIFYOTHER will impact ALL objects of that type. This is useful for setting a general default for that value (e.g. you could default "HandsRequired" on weapons to 1)
* GROUP=X
** This is set by the GROUP token in LST data
* A specific object KEY

More will be added over time.

==SCOPEs==

The following are the legal scopes (not including GLOBAL):
* EQUIPMENT: This is a variable local to equipment
** EQUIPMENT.PART: This is a variable local to an equipment PART (or in older terms, an Equipment HEAD). Note that due to double sided weapons, Damage, CritMult and other items are generally on an equipment PART, not on the Equipment itself. Note also that this is a SUBSCOPE of the EQUIPMENT scope (so all variables in the EQUIPMENT scope can also be seen in the EQUIPMENT.PART scope)
* SAVE: This is a variable local to Save (or if you prefer, Check)
* SIZE: This is a variable local to the Size of a PC
* SKILL: This is a variable local to a Skill
* STAT: This is a variable local to a Stat

More will be added over time.

DYNAMIC can also be used to create a Scope and Object Type (see below)

=Examples=

==Understanding SubScope in practice==

To understand how local variables work in SubScopes, consider the following (note this is not all the variables we will use but a critical set to define the scope):
GLOBAL:NUMBER=Hands
LOCAL:EQUIPMENT|NUMBER=HandsRequired
LOCAL:EQUIPMENT|BOOLEAN=Penalized
LOCAL:EQUIPMENT.PART|NUMBER=CritMult

The Equipment part is what the traditional system called a "head" (so a double headed axe has two "parts" in the new system - this was done since in some game systems, an item could have more than 2)

To understand how variables are available and how they get modified consider this:

Inside of a piece of equipment it could do something like:
MODIFY:Penalized|SET|HandsRequired>Hands

This would be "true" if HandsRequired on the Equipment were more than the Hands on the PC. The "Hands" variable is Global, so it is available anywhere. A Template of "Extra Hands" could do something like:
MODIFY:Hands|ADD|2
... and that adds to the Global variable "Hands".

Now consider an Equipment Modifier that was something like "Lighter Than Normal". Assume the game benefit was one less hand is required. This would look like:
Lighter Than Normal MODIFY:HandsRequired|ADD|-1
(This ignores for the moment any situation like "can't be reduced to below one".)

Note that the EquipmentModifier falls into EQUIPMENT.PART, so that it has access to the HandsRequired variable from the EQUIPMENT scope and can modify it. Note that this change could then impact the result of the BOOLEAN variable Penalized, since HandsRequired changed. Note also that "HandsRequired", when evaluated anywhere in that Equipment is now 1 less. Even if another EquipmentModifier evaluates HandsRequired, it is analyzing the variable from its parent scope, so that value on a variable from EQUIPMENT is the same in every EquipmentModifier (in the EQUIPMENT.PART scope) of that piece of Equipment.

==Understanding SubScope on Equipment==

Since variables like CritMult and Damage would be on an Equipment "part" it is important to understand how to get access to that "part" from the LST code. If a single-headed weapon wanted a larger CritMult, it would be silly to have to add a Dummy EquipmentModifier just to modify the CritMult on the part. (Much of the point of the new system is to make things more direct)

There is a token for Equipment called PART. This effectively takes 2 arguments: A number (today 1 for the primary head, 2 for the secondary head) and a full token otherwise valid on a plain object. MODIFY and MODIFYOTHER will both work in that situation, so for a piece of Equipment to set its own CritMult to 3 on its primary (and perhaps only) head, it would do:
PART:1|MODIFY:CritMult|SET|3

Note since the MODIFY is a "real" token call it uses ":" after the MODIFY which makes PART look slightly different to most tokens which use | as an internal separator. Since PART is effectively calling a "real" token, we need to use the inner ":" in order to have it pass through the same code/parsing system.

==Understanding SubScopes in relation to MODIFYOTHER==

* Note Jan 29 2018: There is a possibility of a solution for this issue that would allow MODIFYOTHER to do direct addressing of sub-objects under certain conditions

Normally MODIFYOTHER allows you to "address" another scope. For example:
MODIFYOTHER:EQUIPMENT|Bastard Sword|HandsRequired|ADD|-1

However, since items like Damage and CritMult are actually on the EQUIPMENT.PART, that is different. If you consider how you would have to "address" the first head on "Bastard Sword", you would need something like:
SOMEWEIRDTOKEN:EQUIPMENT|Bastard Sword|PART|1|CritMult|ADD|1

Note that this requires both a primary and secondary address. No token like this exists (at the moment). To alter items in a SubScope, you need to pass them down to the SubScope. An attempt to modify it at the Equipment level, such as:
MyAbility MODIFYOTHER:EQUIPMENT|ALL|CritMult|ADD|1
... will fail (at LST load) because CritMult was on EQUIPMENT.PART, so it is not visible to the EQUIPMENT scope. Said another way, you can't universally modify all EQUIPMENT.PART variables by attempting to use that variable at a higher scope.

A more appropriate method (since this is relevant to a Feat that might alter CritMult) is to add another variable at the EQUIPMENT level:
LOCAL:EQUIPMENT|NUMBER=CritMultAdder
If all the heads then get
MODIFY:CritMult|ADD|CritMultAdder
... you can have the Feat do a MODIFYOTHER to alter CritMultAdder and the MODIFY will "pull" that into each PART:
SomeFeat MODIFYOTHER:EQUIPMENT|ALL|CritMultAdd|ADD|1
So the data can be set up to only require one modification from a Feat and each Equipment Part can pull that modification down into the part. (A tangential note for those objecting that the known modifiers of CritMult select a specific weapon type: Yep, got it. That's not possible yet, so not documented yet. Suspend disbelief on the examples - Imagine a more powerful Feat for now)

==Understanding PRIORITY and processing of MODIFY and MODIFYOTHER==

When a PlayerCharacter has multiple items that attempt to modify a variable, they are sorted by two systems:
* First, they are sorted by their user priority. This is provided in the PRIORITY=Z association. Lower PRIORITY will be processed first.
* Second, they are sorted by their inherent priority. This is a built-in system that approximates mathematical priority rules. It ensures, for example, that a SET will occur before ADD if they both have a matching user priority.

Example:
Assume we had the following items:
MODIFY:Hands|MULTIPLY|2|PRIORITY=100
MODIFY:Hands|SET|2|PRIORITY=50
MODIFY:Hands|ADD|1|PRIORITY=50

The first thing is that we can tell from the PRIORITY items that the SET and ADD will both occur BEFORE the multiply (because 50 < 100). For the SET and ADD, we would need to know the inherent priority (For what it's worth, SET is 0, ADD is 3, MULTIPLY and DIVIDE are 1 and 2 since they are higher priority than ADD in traditional math). This means the SET will happen first. So the result is Hands is SET to 2, then ADD 1 to get 3, then MULTIPLY by 2 to get 6.

By controlling the PRIORITY, the data team can reorder any calculation and perform much more complicated calculations than was possible with BONUS (where movement, for example, had multiple different BONUS tokens to try to do adding before and after a multiply). This is much the same as using parenthesis in a formula in normal math, but this allows you trigger any required ordering even if the MODIFY statements are in different objects.

==Using the previous value in a more complex calculation==

Take a modification that, for example, wishes to perform a calculation such as: "Reduce the value by 1, but to no less than 1". We could write this as two MODIFY statements, but that is probably undesirable for a few reasons:
* If the book states it as one sentence, it would be preferable to write it as one MODIFY
* It makes the calculation a bit harder to follow as to what is going on
* If the items are different PRIORITY, there is a risk of another dataset attempting to (or accidentally) putting something in between those two steps, resulting in an incorrect calculation.

Therefore, we need a method of drawing on the current value in a formula. To do that we use the value() function. The calculation above then becomes:
max(value()-1,1)
...and we can use it in a MODIFY as such:
MODIFY:HandsRequired|SET|max(value()-1,1)

Note that we are using SET here - if a formula is used, it is likely to be best done as a SET, since that will be much more clear than calculating a formula and then immediately applying another MODIFICATION. Note that some modifications may also prohibit a formula depending on their underlying behavior.

=Global Modifier File=

There is a new file type that is defined in the PCC files with GLOBALMODIFIER.

This file allows for a centralized (and clear to the data user) location for global modifications (don't hide things on stats or elsewhere anymore). This supports MODIFY for global variables (if you want to start all PCs with 2 hands for example) or MODIFYOTHER for local variables.

==GLOBALMODIFIER (PCC File)==

Format:
GLOBALMODIFIER:x
* x is the file to be loaded as a GLOBALMODIFIER file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

=Advanced Topics=

==Dynamic Objects and Scope==

This set of features allows the data to supplement the defined SCOPEs with new object types not originally comprehended in PCGen. Within a Dynamic Scope, the data can produce objects.

Warning: Attempts to define a SCOPE that overlaps with existing objects (e.g. LANGUAGE) will not produce a warning today but will get you in trouble long term. It won't work in the way you would like it to work (it won't attach a SCOPE to that object type), so just avoid those overlapping names. Basically if you can CHOOSE it, or use it with FACT, don't DYMAMICSCOPE it.

===DYNAMICSCOPE (DATACONTROL LST)===

The DYNAMICSCOPE token (used in files referred to by the DATACONTROL: token in PCC files) can define a Dynamic Scope.

DYNAMICSCOPE:x

*x is the new scope
**Any argument to DYNAMICSCOPE becomes a legal "scope" in LOCAL: in the variable definition file
**Limit of one new scope per line. (No delimiter on this token)
*Like other LST tokens, this is case insensitive, but usage in later tokens is always capitalized, so I suspect the data standard should be ALL CAPS

===DYNAMIC (PCC File)===

In order to create objects within the defined DYNAMICSCOPE, DYNAMIC: becomes a new token legal in PCC files. It's format is:

DYNAMIC:x

* x is the file just as in tokens like DEITY or DOMAIN
* INCLUDE/EXCLUDE on the line are are legal.

Within the Dynamic file, the Scope of the new objects being created MUST appear as a prefix token on the line. For example, if there was a DYNAMICSCOPE:VISION, then the following would be legal in a DYNAMIC file:
VISION:Darkvision
VISION:Low-Light Vision

* The "Token Name" (what appears before the ':') is the DYNAMICSCOPE name.
* These are created as basically hollow, simple objects.
* These objects CAN contain variables.
(It is the intent to allow these at some point to also have MODIFY* tokens, but that is not currently supported)

===GRANT (LST files)===

A Dynamic object MUST be granted in order to have its local variables modified or to have its modifiers have an impact (just like any other object)

GRANT:x|y

* x is a DYNAMICSCOPE
* y is the name of the dynamic object.

===Export===

Dynamic items can be exported in Freemarker using the

<#list pc.dynamic.x as y>

* x is the name of the DYNAMICSCOPE
* y is the local variable within the #list that the output team wants to use to access the dynamic object
* It is likely for ease of use by the output team, x and y will be identical

For a complete example using output, see below

===Example===

DATACONTROL: file:
DYNAMICSCOPE:VISION

DYNAMIC: file:
VISION:Normal
VISION:Darkvision
VISION:Low-Light Vision

VARIABLE: File:
LOCAL:VISION|NUMBER=Range

GLOBALMODIFIERFILE:
MODIFYOTHER:VISION|ALL|Range|Set|60

Sets a "default" range for any VISION, to avoid setting on each VISION object

RACE LST file:
Human <> GRANT:VISION|Normal

Export:

<#list pc.dynamic.vision as vision>
${vision.name} ${vision.val.range}
</#list>

(this ignores converting the range to local units and all that, but you get the idea)

==ARRAY Format==

In addition to the base formats, there is an ARRAY[x] format:
ARRAY[x]
* x is an existing valid Format
** x CANNOT be ARRAY (multi-dimensional arrays not supported
** Just to be precise, yes DYNAMIC formats are legal

(Note: This may get renamed - we need to decide on a few things for how this will work vs other types of collections)

===Modifiers===

There are two valid MODIFIERs for ARRAY:
* ADD: This adds a value to the ARRAY
** Mathematically, ARRAY acts as an ordered set of objects. Therefore, if you add an item to an array more than once it is ignored.
* SET: This sets the contents of the ARRAY

==Custom Functions==

Within certain game systems, there are calculations that are likely to be repeated. In order to simplify the calculation of these items, there is an ability to create custom functions.

A function can have zero or more arguments. The number is defined by what appears in the VALUE token (see below).

Note that the function actually has to be *used in the data* (not just defined) for most errors to be caught (since the system can't guess at overall context before a function is used and it would be possible to write a function that would work in more than one FORMAT).

===Function (DATACONTROL LST)===

FUNCTION:x
* This token must appear as the first token on a line in a DATACONTROL file.
* x is the name of the function. This name must starts with a letter, e.g. A-Z, additional legal characters are 0-9 and _ (none of those additional legal characters as the first character)
** x must not contain spaces, no other special characters.
** Function names are case insensitive (as many other things in LST files)

A Function MUST also contain a VALUE, which defines how the function is calculated.

If a FUNCTION appears more than once, the other characteristics (VALUE) must be identical.

===Value (DATACONTROL LST)===

VALUE:x
* Must appear as an additional token on the line of a FUNCTION: in the data control file
* x is a valid formula.
** This means it must have valid variable names, valid function names, matching parenthesis, etc.

In addition to all of the built-in functions (e.g. if, ceil, round), two additional items can be used:
* the arg(n) function (see below).
* Any previously defined FUNCTION. This MUST appear in the file before the current Function or in a file processed before the current file.

===arg (Function)===

The arg function is a "local" function to the VALUE: part of a FUNCTION (it can not generally be used in LST files). The arg function takes one argument. It MUST be a Integer >= 0.

arg(x)
* x is an integer number (zero-indexed)

When arg(x) is used in value, the function pulls from the arguments that were provided to the original function in the data.

===Using a Function===

When a function is used in LST data, it is called by the name provided in the FUNCTION token. It requires a certain number of arguments. This exactly matches the integer one greater than the highest number of the arg(n) function provided in the VALUE part of a FUNCTION (In computer science terms, the arg(n) function is zero-indexed). The provided arguments can be any legal formula, so:

d20Mod(INT)
d20Mod(INT+4)

...are both perfectly legal.

===Example===

The modification calculation in most d20 games is fairly easy to calculate, but is repeated very often. It basically takes (ability score - 10)/2.

Here is how we would define a new function d20Mod in the DATACONTROL file:
FUNCTION:d20Mod VALUE:floor((arg(0)-10)/2)

This would then be used in LST data as:

d20Mod(n)

The system will catch both of these as errors:

d20Mod()
d20Mod(14,5)

These have too few or too many arguments, respectively. It would also catch:

d20Mod("mystring")

...as an error (wrong format - requires a Number, found a String).

The n is substituted where "arg(0)" appears in the "VALUE"... so a statmod would be as easy as:

d20Mod(INT)

or some such... Direct values can also be used, e.g.:

d20Mod(10)

...would return 0.

==Performance Considerations==

It is possible to write two identical modifiers that perform the same net calculation on a PC. For example:
MODIFY:Age|ADD|2
MODIFY:Age|SET|value()+2

...perform the same calculation (adding 2 to Age).

Why have ADD at all? Answer: These are NOT AT ALL equivalent in memory use or speed/performance.

The ADD (Since it's adding an integer) occupies approximately 40 bytes of memory and is an extremely rapid calculation: If it took 200 nanoseconds I'd be surprised. This is because ADD is using a number. If it was a formula, even 1+2, it would load the formula parser. This special case on constants allows the modification system to modify a value without loading a much larger infrastructure, and this is valuable as a large majority of our calculations are simple modifications of values.

The SET shown above (since it has an operator) loads the formula system, and thus may occupy 500 (or more) bytes of memory (>10x), so it could take 100 times as long to process as the ADD (it also took longer during LST load).

Thus: When possible the data standards should be written to use numeric modifiers and no operator. (Think "static" modifiers ... that only use numbers) rather than a formula.

==Lookup and Tables==

For some situations, it makes more sense to have a lookup table rather than attempting to have a set of tokens or calculations perform processing. This also allows for much cleaner translation from books when the books are using tables to organize information.

The Table file format is designed to allow you to use a spreadsheet program to modify the tables and export the table in CSV format. While we don't strictly follow full CSV rules, as long as you avoid embedded quotes and embedded return carriage/line feed, it should be safe.

More than one table is allowed per file (to avoid sprawl and help simplify modification/management of tables).

===TABLE (PCC File)===

TABLE:x
* x is the file to be loaded as a TABLE file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

====Table LST file format====

File formatting considerations:
* Trailing commas will not impact any TABLE, and will be ignored
* Blank lines will be ignored. This includes lines with commas but without content. (allows tables to be separated by blank lines or lines of all commas)
* Attempts to use embedded line breaks or embedded quotes may or may not be supported by the parsing system, but certainly aren't supported for purposes of PCGen.
* Lines that have the first cell starting with "#" are considered comment lines and will be ignored. This will likely need to include if the first cell is escaped in quotes, just for protection from any tools that quote by default.
* Since the CSV format ignores leading/trailing spaces, one can easily have a spaced out version that is a table in a text editor if folks don't want to edit in a spreadsheet. (Having someone write a "PrettyTable" ... a trivial perl or python program to do that for the data team seems fairly easy)

A TABLE starts with STARTTABLE:
STARTTABLE:x
* x is the name of the Table. Most characters are allowed, avoiding quotes is advisable.
* Allowing Trailing commas allows the STARTTABLE lines to have blank cells where the rest are the table contents... we don't want to complain on minor things that may tools will do.

If a STARTTABLE is encountered when another Table is active, an LST load error will occur.

A TABLE ends with ENDTABLE:
ENDTABLE:x
* x is the name of the Table. Most characters are allowed, avoiding quotes is advisable.
* Allowing Trailing commas allows the ENDTABLE lines to have blank cells where the rest are the table contents... we don't want to complain on minor things that may tools will do.

If an ENDTABLE is encountered without a STARTTABLE, an LST load error will occur.

A Table must have a minimum of 3 rows, NOT counting the STARTTABLE and ENDTABLE tokens.

The First row:
x,x
* x is the column name. These are always the first line of the table after STARTTABLE:

Any column which has data MUST have a name.

The Second row:
y,y
* y is the format for the column. Any column that was named must have a FORMAT.

Additional rows:
z,z
* z represents contents of the table. These must be in the FORMAT provided for the appropriate column.

====Example====

STARTTABLE:Carrying Capacity,
Strength,Capacity
NUMBER,NUMBER
1,10
2,20
...
29,1400
ENDTABLE:Carrying Capacity,

===TABLE[x] Format===

When a TABLE is created, it implicitly picks up a FORMAT based on the FORMAT of the first column of the Table.
Unlike basic FORMATs shown above, TABLE has a SUBFORMAT (in brackets).

TABLE[x]
* x is the SUB-FORMAT of the TABLE (this is the format of the first column of the Table)
** x must be an otherwise valid FORMAT, and it is advised to avoid any FORMAT that has a SUB-FORMAT
*** This limitation may be inconsistently enforced. It certainly is prohibited to create a TABLE[TABLE[x]], but other situations the behavior may not be prohibited by the code (but the behavior is also not guaranteed)

===COLUMN[x] Format===

When a Column needs to be referred to in the data, it has a special format as well:

Unlike basic FORMATs shown above, COLUMN has a SUBFORMAT (in brackets).
COLUMN[x]
* x is the SUB-FORMAT of the COLUMN (this is the format of the data that appears in that column in a Table)
** x must be an otherwise valid FORMAT, and it is advised to avoid any FORMAT that has a SUB-FORMAT
*** This limitation may be inconsistently enforced. Such behavior may not be prohibited by the code (but avoiding bad behavior is also not guaranteed in a situation where embedded brackets occur)

===Using Tables===

With MODIFY, a TABLE[x] variable doesn't look any different. It's still:
MODIFY:TableNameVar|SET|"SomeTable"

"SomeTable" is still a string to a naive reader, but what the system will do at that point is make sure that SomeTable can actually be interpreted as a TABLE[x]... rather than just treating it as a String. Similar for column names when they are encountered (see below).

In that way, the sub variable will allow multiple tables to be swapped in, AS LONG AS they are the right format. If the format is not compatible, then all bets are off and you'll get an error.

===lookup() Function===

The major consideration is how to do the lookup in data. We can borrow some inspiration from things like Excel and Google Docs:

lookup(X,Y,Z)

* X is a table. This must resolve in the formula system to a valid table. For now, a get(...) function may be required.
* Y is the lookup value in the table. It must match the format of the first column in the table. At this time, it does an EXACT match.
* Z is the target column. This must resolve in the formula system to a valid table column. It must appear in the table named by the contents of the first argument of lookup.

Example: Max load calculation would be something like:
lookup("Carrying Capacity",floor(StrScore),"Capacity")*SizeMult
We have to do the floor due to the exact name of the lookup

Note: The format of both TABLE "Carrying Capacity" and COLUMN "Capacity" can be derived by PCGen internally and thus are no longer required to have a get (current as of Jan 30, 2018)

Note that this function allows some runtime errors, but catches a lot of possible issues. It is still possible to do a lookup on a Table that doesn't contain a specific column of the given name or format, simply because those items can be variables resolved at runtime. For example, if the third variable is COLUMN[NUMBER], we can check at load that the TABLEFORMAT has columns of FORMAT=NUMBER, but we can't guarantee the variable will resolve to a name actually in that table... that will have to wait for a runtime error. That's life, but it does allow us to know the formats at load time, so we do get a lot of error checking in the context of the usage, if not the exact table and column names.

Note you can do some really dynamic behaviors to have folks override game mode behaviors. For example, one neat item would be that we could alter a query for dice steps to extract the table name into the Global Modifier file:
MODIFY:DiceStepTable|SET|"Dice Step"
lookup(get("TABLE[NUMBER]",DiceStepTable),BaseDamage,get("COLUMN[NUMBER]",lookup("Step Column",CurrentSize-BaseSize,"Name")))

Note: In both cases here, the "get" is shown for completeness. In the case of DiceStepTable - it MAY be required or prohibited - it depends on what the Format is of the "DiceStepTable" variable. If it's TABLE, then the get is not necessary (and is actually prohibited). The example shown above assumes DiceStepTable is a String. The better design would be for it to be a TABLE (specifically TABLE[NUMBER]). For the "get" after the lookup, that is required - the lookup value will return a STRING, and as such, will needs to be converted to a COLUMN.

Now, if someone needs different dice steps for some reason... they can override the DiceStepTable variable and it will look up in a different table... so expansions could truly be expansions and not have to reach back into core PCC files in order to change key behaviors.

Consider also that spell tables can be shared across classes, or if a subclass alters the default, just create a new table rather than having to BONUS/MODIFY all the numbers in a table with adding and subtracting...

==To be completed==
* dropIntoContext
* Channels

=Material Changes=

==lookup function simplification==

Effective January 30, 2018, tables and columns can be referred to directly in lookup(). This is actually a "broad" change to how strings are interpreted. The system - when possible - fully asserts a FORMAT, and first attempts to convert the given String per the rules of that FORMAT. This also means an assignment of an ALIGNMENT, by key, will not require a "get":
MODIFY:Alignment|SET|"LE"
...will be fully legal. (This assumes Alignment is FORMAT: of ALIGNMENT)

Setting up the new Formula System

2018-03-09T15:18:36Z

Nuance: Fix cut and paste error.

{| align="right"
| __TOC__
|}

=The basics=

The new formula system is designed to do a few things relative to data:
* Validate formulas at LST load instead of runtime
* Dramatically increase flexibility
* It will replace many tokens, including all the BONUS tokens
* It allows a sensible location for global modifications (things generally related to rule book type modifications that impact all objects of a given type)

==Key concepts==

To use the new system a few key things need to be remembered:
* It is possible to have local variables
* All variables must be defined prior to use
* Variables are not only numbers, but can be Strings, Dice, etc.
** We call this the variable FORMAT

You will want to keep track of what these key terms mean as you learn the new formula system:
* FORMAT: The type of variable, e.g. NUMBER, BOOLEAN, ORDEREDPAIR.
* SCOPE: The part of the data in which a (local) variable is available
* MODIFIER: An argument to MODIFY* tokens, specifically the "command" of what the modification represents
* OPERATOR: A mathematical operator as you would see in a formula ("+", "-", etc.)
* GROUPING: A name for a set of objects in PCGen
* ASSOCIATION: An additional set of information attached to a MODIFY* token. This is a key-value pair of information, e.g. PRIORITY=100

=Creating and Using Variables=

==Required Setup==

Every format that needs to be used requires a default value. This value is shared throughout an entire system (it CANNOT be redefined to a different value). This is placed into a file referred to in a PCC file from the DATACONTROL: token.

===DATACONTROL (PCC File)===

DATACONTROL: is a new Campaign file token (for PCC files). It is treated "recursively" like other tokens, e.g. TEMPLATE.

DATACONTROL:x

* x is the file to be loaded as a DATACONTROL file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

===DEFAULTVARIABLEVALUE (DATACONTROL LST)===

The Format is:
DEFAULTVARIABLEVALUE:X|Y
* X is the format name
* Y is the default value

Example:
DEFAULTVARIABLEVALUE:NUMBER|0

It is a best practice to always define a DEFAULTVARIABLEVALUE for every FORMAT regardless of whether the data uses that FORMAT. The internal parts of PCGen may use it, so a default value may be required.

Note: it IS safe to "redefine" a DEFAULTVARIABLEVALUE to the same value. So if multiple datasets are loaded and they all had DATACONTROL: and all defined the default value for NUMBER to be 0, they will all happily load as the system is capable of recognizing the defaults are the same

==How to define a variable==

===VARIABLE (PCC File)===

To define a variable, you need to add an LST file that is referred to in a PCC file from the VARIABLE: token. It is treated "recursively" like other tokens, e.g. TEMPLATE.

VARIABLE:x

* x is the file to be loaded as a VARIABLE file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

There are 2 basic tokens for the VARIABLE file: GLOBAL and LOCAL.

===GLOBAL (VARIABLE File)===

* GLOBAL defines a global variable, usable from anywhere within the PlayerCharacter.

The format is:
GLOBAL:X=Y
* X is the format name
* Y is the variable name

Example:
GLOBAL:ORDEREDPAIR=Face

A GLOBAL token can take additional token on the line called EXPLANATION, which it is advisable to use to communicate to other data monkeys (and it is likely any future editor will also draw on this information).

===LOCAL (VARIABLE File)===

* LOCAL defines a local variable, usable only within the object on which the variable exists (or its children)
** The place where a local variable is usable is called the SCOPE. This could include a STAT (such as the stat's SCORE or STATMOD) or EQUIPMENT. The scopes possible in PCGen are hard-coded (see below for more info)

The format is:
LOCAL:W|X=Y
* W is the SCOPE of the variable
* X is the format name
* Y is the variable name

Example:
LOCAL:STAT|NUMBER=Score

A LOCAL token can take additional token on the line called EXPLANATION, which it is advisable to use to communicate to other data monkeys (and it is likely any future editor will also draw on this information).

===EXPLANATION (VARIABLE File)===

EXPLANATION: is a free-text token (no parsing is really done) that is designed to describe why a variable exists

Format:
EXPLANATION:x

* x is the text of the Explanation
* Limitations: By Design: Must not appear as the first token on a line
* Behavior: Overwrites (as if someone would use it twice??)

===Defaults in the VARIABLE file===

A few notes about the VARIABLE files:
If you see an item without a leading token, e.g.:
ORDEREDPAIR=Face
...then the system is using the default (GLOBAL). For now, the data standard is to avoid using this shortcut (as far as I know)

If you see an item without a leading format ("X" in both GLOBAL and LOCAL above), e.g.:
LOCAL:STAT|Score
...then the format is a NUMBER. For now, the data standard is to avoid using this shortcut (as far as I know)

Note both defaults can be combined, so a variable name with no other information on that line is a Global NUMBER

===No Overlapping===

In most programming languages, it is legal to have local variable share the same name as the global variable and thus "override" it in that context (although it is considered less than ideal, and in some languages it will now produce a warning). It is not legal in PCGen.

If a Global variable called "Hands" exists, then NO local variable IN ANY SCOPE can be "Hands".

Similar restrictions exist for scopes and SubScopes. If "CritMult" is an EQUIPMENT variable, then "CritMult" can't be an EQUIPMENT.PART variable.

Non-overlapping (when the Scopes do not interact) is legal. "Score" can be a local STAT variable and a local CHECK variable, for example.

For clarity:
* This occurs regardless of the FORMAT of the variables - tokens will infer the format from the variable name, so you can't have overlapping variables even of different FORMAT.
* Two variables of the same name but different FORMAT in the same SCOPE will cause an error as well, because that is effectively overlapping, and those variables can't be distinguished in most circumstances.

===Identical Duplication Legal===

It is legal for a load to include one or more PCC files that have one or more VARIABLE: files that redefine the same variables. As long as they are the same format and scope, they are not considered an error. If either the scope or format differs, then the "No Overlapping" rules above are applied.

A difference in the "Explanation" text is not considered a difference in the variables significant enough to trigger an error. (In fact, the last loaded Explanation will "win" -> it is overwritten each time it is encountered for redefined but identical variables)

==Setting and Modifying a variable==

===MODIFY (LST files)===

The MODIFY token is used to set a variable that is accessible in the current SCOPE. (Note: It could be local to the current scope or any ancestor of the current scope... so modifying a global variable always just requires MODIFY)

The format of the token is:
MODIFY:V|W|X|Y=Z|Y=Z
* V is the Variable name for which the value will be modified
** This variable MUST be visible in the current scope. Therefore, it must be either a global variable or a local variable on the current object or its parents.
* W is the MODIFIER to be taken on the variable (e.g. SET)
** There can be multiple actions (more below), but SET will ALWAYS be available for any format.
* X is the value related to the action. If the action is set, the variable will be set to the value in this part of the token.
** Note: The value CAN be a formula. It is possible, for example, to SET a variable to OtherVar+4 ... the system will solve that formula. For legal OPERATORS (e.g. "+") , see below.
* Y is the name of an (optional) ASSOCIATION. For now, PRIORITY (more below) is the only available association.
* Z is the value of the association.

Note: If a PRIORITY is not set it is assumed to be ZERO.

Example: Give a Player Character 2 hands:
MODIFY:Hands|SET|2

===MODIFYOTHER (LST files)===

The MODIFYOTHER token is used to set a variable that is not accessible in the current SCOPE. Beyond what is necessary in MODIFY, this token also requires the "address" of where to go before it runs the modification. Think of it as the ability to remotely place a MODIFY on another object (but revoke that MODIFY if the current object is no longer granted to the PC)

The format of the token is:
MODIFYOTHER:T|U|V|W|X|Y=Z|Y=Z
* T is the FORMAT of the object on which the resulting MODIFY (as defined by V-Z) should occur
* U is the object or GROUPING of objects on which the MODIFY (as defined by V-Z) should occur
** Note that this does not and will not support TYPE.
* V is the Variable name for which the value will be modified
** This variable MUST be visible in the scope of the addressed object. Therefore, it is likely to be a local variable on the remote object or its parents.
** In rare cases, a remote modification of a global variable is useful. It effectively adds to that global variable only if both objects are granted to the PC.
* W is the MODIFIER to be taken on the variable (e.g. SET)
** There can be multiple actions (more below), but SET will ALWAYS be available for any format.
* X is the value related to the action. If the action is set, the variable will be set to the value in this part of the token.
** Note: The value CAN be a formula. It is possible, for example, to SET a variable to OtherVar+4 ... the system will solve that formula. For legal OPERATORS (e.g. "+") , see below.
* Y is the name of an (optional) ASSOCIATION. For now, PRIORITY (more below) is the only available association.
* Z is the value of the association.

Note: If a PRIORITY is not set it is assumed to be ZERO.

Example: Reduce the HandsRequired on all Weapons by 1:
MODIFYOTHER:EQUIPMENT|GROUP=Weapon|HandsRequired|ADD|-1

Note this assumes GROUP:Weapon is in the LST line of every Weapon... PCGen can't guess or derive what a weapon is :)

==Formulas==

SET as a MODIFIER allows the use of a formula for the value. This follows many mathematical systems of using parenthesis - "(" and ")" to be precise - to group (and thus prioritize parts of the calculation).
There are a number of build in OPERATORs (see below). The system can also use functions, which use parenthesis to contain their arguments. For example:
* min(this,that)
Would return the minimum of the two variables "this" and "that".

===Built in Functions===

The system also has a series of built-in functions that work with the NUMBER format:
* abs: calculates the absolute value of the one argument.
* ceil: calculates the next integer that is >= the value of the one argument.
* floor: calculates the next lower integer that is <= the value of the one argument
* if: conditionally performs an operation. The first argument must resolve to a BOOLEAN. If true, the second argument is evaluated; if false, the third argument is evaluated.
* max: calculates the maximum of the provided two or more comma-separated arguments
* min: calculates the minimum of the provided two or more comma-separated arguments
* round: calculates the closest integer to the value of the one argument. Exactly 0.5 is rounded up.
* value: returns the value of the calculation before the current modification was started (no arguments)

Additional functions specifically related to PCGen are available:
* get: This function takes two arguments. The first is a Object type (like "SKILL"), the second is the key of a CDOMObject (like a Skill) (also in quotes)
**Example: get("SKILL","Hide")
* getFact: This function returns the value of a FACT. The first two arguments are much like the two arguments of "get", the third argument is the name of the FACT to be returned

=Legal Values=

==FORMATs==

Currently, the following are built-in formats:
* NUMBER: This is a mathematical value. Note that integer arithmetic is done if possible, so if you have an integer 6 and an integer 3, 6/3 will be an integer 2. If the 6 or 3 is a decimal value (double), then integer arithmetic was not possible and thus rounding may occur.
* STRING: A String
* BOOLEAN: A True/False value
* ORDEREDPAIR: An ordered pair of numbers. This could be an X,Y point (or in a game system more like a FACE)
* DICE: A value that takes the form AdB+C. A is the number of rolls of the die, B is the number of sides on the die, and C is the value to be added afterwords
* ALIGNMENT: An alignment object (None is default typically)

==OPERATORs==

For NUMBER, the following modifiers are available:
* +: performs addition
* -: performs subtraction (or is the unary minus operator to make a value negative)
* *: performs multiplication
* /: performs division
* %: performs a remainder function
* ^: performs an exponential calculation
* ==: Checks for equality (NOTE: Returns a BOOLEAN, not a NUMBER)
* !=: Checks for inequality (NOTE: Returns a BOOLEAN, not a NUMBER)
* >: Checks for greater than (NOTE: Returns a BOOLEAN, not a NUMBER)
* <: Checks for less than (NOTE: Returns a BOOLEAN, not a NUMBER)
* >=: Checks for greater than or equal to (NOTE: Returns a BOOLEAN, not a NUMBER)
* <=: Checks for less than or equal to (NOTE: Returns a BOOLEAN, not a NUMBER)

For BOOLEAN, the following modifiers are available:
* ==: Checks for equality
* !=: Checks for inequality
* &&: Performs a logical AND
* ||: Performs a logical OR
* !: Negates the value

For other formats, the following operators are always available:
* ==: Checks for equality (NOTE: Returns a BOOLEAN, not the compared format)
* !=: Checks for inequality (NOTE: Returns a BOOLEAN, not the compared format)

==MODIFIERs==

For NUMBER, the following modifiers are available:
* SET: This sets the variable to the value provided in the "X" parameter
* ADD: This adds the current value of the variable to the value provided in the "X" parameter
* MAX: This takes the maximum value of the current value of the variable and the value provided in the "X" parameter (i.e. min(current value, "X"))
* MIN: This takes the minimum value of the current value of the variable and the value provided in the "X" parameter (i.e. max(current value, "X"))
* MULTIPLY: This multiplies the current value of the variable and the value provided in the "X" parameter
* DIVIDE: This divides the current value of the variable by the value provided in the "X" parameter

For other Formats, the SET modifier will always be available

==GROUPINGs==

At present, the second argument of MODIFYOTHER supports 3 possible values:
* ALL
** This means the MODIFYOTHER will impact ALL objects of that type. This is useful for setting a general default for that value (e.g. you could default "HandsRequired" on weapons to 1)
* GROUP=X
** This is set by the GROUP token in LST data
* A specific object KEY

More will be added over time.

==SCOPEs==

The following are the legal scopes (not including GLOBAL):
* EQUIPMENT: This is a variable local to equipment
** EQUIPMENT.PART: This is a variable local to an equipment PART (or in older terms, an Equipment HEAD). Note that due to double sided weapons, Damage, CritMult and other items are generally on an equipment PART, not on the Equipment itself. Note also that this is a SUBSCOPE of the EQUIPMENT scope (so all variables in the EQUIPMENT scope can also be seen in the EQUIPMENT.PART scope)
* SAVE: This is a variable local to Save (or if you prefer, Check)
* SIZE: This is a variable local to the Size of a PC
* SKILL: This is a variable local to a Skill
* STAT: This is a variable local to a Stat

More will be added over time.

DYNAMIC can also be used to create a Scope and Object Type (see below)

=Examples=

==Understanding SubScope in practice==

To understand how local variables work in SubScopes, consider the following (note this is not all the variables we will use but a critical set to define the scope):
GLOBAL:NUMBER=Hands
LOCAL:EQUIPMENT|NUMBER=HandsRequired
LOCAL:EQUIPMENT|BOOLEAN=Penalized
LOCAL:EQUIPMENT.PART|NUMBER=CritMult

The Equipment part is what the traditional system called a "head" (so a double headed axe has two "parts" in the new system - this was done since in some game systems, an item could have more than 2)

To understand how variables are available and how they get modified consider this:

Inside of a piece of equipment it could do something like:
MODIFY:Penalized|SET|HandsRequired>Hands

This would be "true" if HandsRequired on the Equipment were more than the Hands on the PC. The "Hands" variable is Global, so it is available anywhere. A Template of "Extra Hands" could do something like:
MODIFY:Hands|ADD|2
... and that adds to the Global variable "Hands".

Now consider an Equipment Modifier that was something like "Lighter Than Normal". Assume the game benefit was one less hand is required. This would look like:
Lighter Than Normal MODIFY:HandsRequired|ADD|-1
(This ignores for the moment any situation like "can't be reduced to below one".)

Note that the EquipmentModifier falls into EQUIPMENT.PART, so that it has access to the HandsRequired variable from the EQUIPMENT scope and can modify it. Note that this change could then impact the result of the BOOLEAN variable Penalized, since HandsRequired changed. Note also that "HandsRequired", when evaluated anywhere in that Equipment is now 1 less. Even if another EquipmentModifier evaluates HandsRequired, it is analyzing the variable from its parent scope, so that value on a variable from EQUIPMENT is the same in every EquipmentModifier (in the EQUIPMENT.PART scope) of that piece of Equipment.

==Understanding SubScope on Equipment==

Since variables like CritMult and Damage would be on an Equipment "part" it is important to understand how to get access to that "part" from the LST code. If a single-headed weapon wanted a larger CritMult, it would be silly to have to add a Dummy EquipmentModifier just to modify the CritMult on the part. (Much of the point of the new system is to make things more direct)

There is a token for Equipment called PART. This effectively takes 2 arguments: A number (today 1 for the primary head, 2 for the secondary head) and a full token otherwise valid on a plain object. MODIFY and MODIFYOTHER will both work in that situation, so for a piece of Equipment to set its own CritMult to 3 on its primary (and perhaps only) head, it would do:
PART:1|MODIFY:CritMult|SET|3

Note since the MODIFY is a "real" token call it uses ":" after the MODIFY which makes PART look slightly different to most tokens which use | as an internal separator. Since PART is effectively calling a "real" token, we need to use the inner ":" in order to have it pass through the same code/parsing system.

==Understanding SubScopes in relation to MODIFYOTHER==

* Note Jan 29 2018: There is a possibility of a solution for this issue that would allow MODIFYOTHER to do direct addressing of sub-objects under certain conditions

Normally MODIFYOTHER allows you to "address" another scope. For example:
MODIFYOTHER:EQUIPMENT|Bastard Sword|HandsRequired|ADD|-1

However, since items like Damage and CritMult are actually on the EQUIPMENT.PART, that is different. If you consider how you would have to "address" the first head on "Bastard Sword", you would need something like:
SOMEWEIRDTOKEN:EQUIPMENT|Bastard Sword|PART|1|CritMult|ADD|1

Note that this requires both a primary and secondary address. No token like this exists (at the moment). To alter items in a SubScope, you need to pass them down to the SubScope. An attempt to modify it at the Equipment level, such as:
MyAbility MODIFYOTHER:EQUIPMENT|ALL|CritMult|ADD|1
... will fail (at LST load) because CritMult was on EQUIPMENT.PART, so it is not visible to the EQUIPMENT scope. Said another way, you can't universally modify all EQUIPMENT.PART variables by attempting to use that variable at a higher scope.

A more appropriate method (since this is relevant to a Feat that might alter CritMult) is to add another variable at the EQUIPMENT level:
LOCAL:EQUIPMENT|NUMBER=CritMultAdder
If all the heads then get
MODIFY:CritMult|ADD|CritMultAdder
... you can have the Feat do a MODIFYOTHER to alter CritMultAdder and the MODIFY will "pull" that into each PART:
SomeFeat MODIFYOTHER:EQUIPMENT|ALL|CritMultAdd|ADD|1
So the data can be set up to only require one modification from a Feat and each Equipment Part can pull that modification down into the part. (A tangential note for those objecting that the known modifiers of CritMult select a specific weapon type: Yep, got it. That's not possible yet, so not documented yet. Suspend disbelief on the examples - Imagine a more powerful Feat for now)

==Understanding PRIORITY and processing of MODIFY and MODIFYOTHER==

When a PlayerCharacter has multiple items that attempt to modify a variable, they are sorted by two systems:
* First, they are sorted by their user priority. This is provided in the PRIORITY=Z association. Lower PRIORITY will be processed first.
* Second, they are sorted by their inherent priority. This is a built-in system that approximates mathematical priority rules. It ensures, for example, that a SET will occur before ADD if they both have a matching user priority.

Example:
Assume we had the following items:
MODIFY:Hands|MULTIPLY|2|PRIORITY=100
MODIFY:Hands|SET|2|PRIORITY=50
MODIFY:Hands|ADD|1|PRIORITY=50

The first thing is that we can tell from the PRIORITY items that the SET and ADD will both occur BEFORE the multiply (because 50 < 100). For the SET and ADD, we would need to know the inherent priority (For what it's worth, SET is 0, ADD is 3, MULTIPLY and DIVIDE are 1 and 2 since they are higher priority than ADD in traditional math). This means the SET will happen first. So the result is Hands is SET to 2, then ADD 1 to get 3, then MULTIPLY by 2 to get 6.

By controlling the PRIORITY, the data team can reorder any calculation and perform much more complicated calculations than was possible with BONUS (where movement, for example, had multiple different BONUS tokens to try to do adding before and after a multiply). This is much the same as using parenthesis in a formula in normal math, but this allows you trigger any required ordering even if the MODIFY statements are in different objects.

==Using the previous value in a more complex calculation==

Take a modification that, for example, wishes to perform a calculation such as: "Reduce the value by 1, but to no less than 1". We could write this as two MODIFY statements, but that is probably undesirable for a few reasons:
* If the book states it as one sentence, it would be preferable to write it as one MODIFY
* It makes the calculation a bit harder to follow as to what is going on
* If the items are different PRIORITY, there is a risk of another dataset attempting to (or accidentally) putting something in between those two steps, resulting in an incorrect calculation.

Therefore, we need a method of drawing on the current value in a formula. To do that we use the value() function. The calculation above then becomes:
max(value()-1,1)
...and we can use it in a MODIFY as such:
MODIFY:HandsRequired|SET|max(value()-1,1)

Note that we are using SET here - if a formula is used, it is likely to be best done as a SET, since that will be much more clear than calculating a formula and then immediately applying another MODIFICATION. Note that some modifications may also prohibit a formula depending on their underlying behavior.

=Global Modifier File=

There is a new file type that is defined in the PCC files with GLOBALMODIFIER.

This file allows for a centralized (and clear to the data user) location for global modifications (don't hide things on stats or elsewhere anymore). This supports MODIFY for global variables (if you want to start all PCs with 2 hands for example) or MODIFYOTHER for local variables.

==GLOBALMODIFIER (PCC File)==

Format:
GLOBALMODIFIER:x
* x is the file to be loaded as a GLOBALMODIFIER file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

=Advanced Topics=

==Dynamic Objects and Scope==

This set of features allows the data to supplement the defined SCOPEs with new object types not originally comprehended in PCGen. Within a Dynamic Scope, the data can produce objects.

Warning: Attempts to define a SCOPE that overlaps with existing objects (e.g. LANGUAGE) will not produce a warning today but will get you in trouble long term. It won't work in the way you would like it to work (it won't attach a SCOPE to that object type), so just avoid those overlapping names. Basically if you can CHOOSE it, or use it with FACT, don't DYMAMICSCOPE it.

===DYNAMICSCOPE (DATACONTROL LST)===

The DYNAMICSCOPE token (used in files referred to by the DATACONTROL: token in PCC files) can define a Dynamic Scope.

DYNAMICSCOPE:x

*x is the new scope
**Any argument to DYNAMICSCOPE becomes a legal "scope" in LOCAL: in the variable definition file
**Limit of one new scope per line. (No delimiter on this token)
*Like other LST tokens, this is case insensitive, but usage in later tokens is always capitalized, so I suspect the data standard should be ALL CAPS

===DYNAMIC (PCC File)===

In order to create objects within the defined DYNAMICSCOPE, DYNAMIC: becomes a new token legal in PCC files. It's format is:

DYNAMIC:x

* x is the file just as in tokens like DEITY or DOMAIN
* INCLUDE/EXCLUDE on the line are are legal.

Within the Dynamic file, the Scope of the new objects being created MUST appear as a prefix token on the line. For example, if there was a DYNAMICSCOPE:VISION, then the following would be legal in a DYNAMIC file:
VISION:Darkvision
VISION:Low-Light Vision

* The "Token Name" (what appears before the ':') is the DYNAMICSCOPE name.
* These are created as basically hollow, simple objects.
* These objects CAN contain variables.
(It is the intent to allow these at some point to also have MODIFY* tokens, but that is not currently supported)

===GRANT (LST files)===

A Dynamic object MUST be granted in order to have its local variables modified or to have its modifiers have an impact (just like any other object)

GRANT:x|y

* x is a DYNAMICSCOPE
* y is the name of the dynamic object.

===Export===

Dynamic items can be exported in Freemarker using the

<#list pc.dynamic.x as y>

* x is the name of the DYNAMICSCOPE
* y is the local variable within the #list that the output team wants to use to access the dynamic object
* It is likely for ease of use by the output team, x and y will be identical

For a complete example using output, see below

===Example===

DATACONTROL: file:
DYNAMICSCOPE:VISION

DYNAMIC: file:
VISION:Normal
VISION:Darkvision
VISION:Low-Light Vision

VARIABLE: File:
LOCAL:VISION|NUMBER=Range

GLOBALMODIFIERFILE:
MODIFYOTHER:VISION|ALL|Range|Set|60

Sets a "default" range for any VISION, to avoid setting on each VISION object

RACE LST file:
Human <> GRANT:VISION|Normal

Export:

<#list pc.dynamic.vision as vision>
${vision.name} ${vision.val.range}
</#list>

(this ignores converting the range to local units and all that, but you get the idea)

==ARRAY Format==

In addition to the base formats, there is an ARRAY[x] format:
ARRAY[x]
* x is an existing valid Format
** x CANNOT be ARRAY (multi-dimensional arrays not supported
** Just to be precise, yes DYNAMIC formats are legal

(Note: This may get renamed - we need to decide on a few things for how this will work vs other types of collections)

===Modifiers===

There are two valid MODIFIERs for ARRAY:
* ADD: This adds a value to the ARRAY
** Mathematically, ARRAY acts as an ordered set of objects. Therefore, if you add an item to an array more than once it is ignored.
* SET: This sets the contents of the ARRAY

==Custom Functions==

Within certain game systems, there are calculations that are likely to be repeated. In order to simplify the calculation of these items, there is an ability to create custom functions.

A function can have zero or more arguments. The number is defined by what appears in the VALUE token (see below).

Note that the function actually has to be *used in the data* (not just defined) for most errors to be caught (since the system can't guess at overall context before a function is used and it would be possible to write a function that would work in more than one FORMAT).

===Function (DATACONTROL LST)===

FUNCTION:x
* This token must appear as the first token on a line in a DATACONTROL file.
* x is the name of the function. This name must starts with a letter, e.g. A-Z, additional legal characters are 0-9 and _ (none of those additional legal characters as the first character)
** x must not contain spaces, no other special characters.
** Function names are case insensitive (as many other things in LST files)

A Function MUST also contain a VALUE, which defines how the function is calculated.

If a FUNCTION appears more than once, the other characteristics (VALUE) must be identical.

===Value (DATACONTROL LST)===

VALUE:x
* Must appear as an additional token on the line of a FUNCTION: in the data control file
* x is a valid formula.
** This means it must have valid variable names, valid function names, matching parenthesis, etc.

In addition to all of the build-in functions (e.g. if, ceil, round), two additional items can be used:
* the arg(n) function (see below).
* Any previously defined FUNCTION. This MUST appear in the file before the current Function or in a file processed before the current file.

===arg (Function)===

The arg function is a "local" function to the VALUE: part of a FUNCTION (it can not generally be used in LST files). The arg function takes one argument. It MUST be a Integer >= 0.

arg(x)
* x is an integer number (zero-indexed)

When arg(x) is used in value, the function pulls from the arguments that were provided to the original function in the data.

===Using a Function===

When a function is used in LST data, it is called by the name provided in the FUNCTION token. It requires a certain number of arguments. This exactly matches the integer one greater than the highest number of the arg(n) function provided in the VALUE part of a FUNCTION (In computer science terms, the arg(n) function is zero-indexed). The provided arguments can be any legal formula, so:

d20Mod(INT)
d20Mod(INT+4)

...are both perfectly legal.

===Example===

The modification calculation in most d20 games is fairly easy to calculate, but is repeated very often. It basically takes (ability score - 10)/2.

Here is how we would define a new function d20Mod in the DATACONTROL file:
FUNCTION:d20Mod VALUE:floor((arg(0)-10)/2)

This would then be used in LST data as:

d20Mod(n)

The system will catch both of these as errors:

d20Mod()
d20Mod(14,5)

These have too few or too many arguments, respectively. It would also catch:

d20Mod("mystring")

...as an error (wrong format - requires a Number, found a String).

The n is substituted where "arg(0)" appears in the "VALUE"... so a statmod would be as easy as:

d20Mod(INT)

or some such... Direct values can also be used, e.g.:

d20Mod(10)

...would return 0.

==Performance Considerations==

It is possible to write two identical modifiers that perform the same net calculation on a PC. For example:
MODIFY:Age|ADD|2
MODIFY:Age|SET|value()+2

...perform the same calculation (adding 2 to Age).

Why have ADD at all? Answer: These are NOT AT ALL equivalent in memory use or speed/performance.

The ADD (Since it's adding an integer) occupies approximately 40 bytes of memory and is an extremely rapid calculation: If it took 200 nanoseconds I'd be surprised. This is because ADD is using a number. If it was a formula, even 1+2, it would load the formula parser. This special case on constants allows the modification system to modify a value without loading a much larger infrastructure, and this is valuable as a large majority of our calculations are simple modifications of values.

The SET shown above (since it has an operator) loads the formula system, and thus may occupy 500 (or more) bytes of memory (>10x), so it could take 100 times as long to process as the ADD (it also took longer during LST load).

Thus: When possible the data standards should be written to use numeric modifiers and no operator. (Think "static" modifiers ... that only use numbers) rather than a formula.

==Lookup and Tables==

For some situations, it makes more sense to have a lookup table rather than attempting to have a set of tokens or calculations perform processing. This also allows for much cleaner translation from books when the books are using tables to organize information.

The Table file format is designed to allow you to use a spreadsheet program to modify the tables and export the table in CSV format. While we don't strictly follow full CSV rules, as long as you avoid embedded quotes and embedded return carriage/line feed, it should be safe.

More than one table is allowed per file (to avoid sprawl and help simplify modification/management of tables).

===TABLE (PCC File)===

TABLE:x
* x is the file to be loaded as a TABLE file
* Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.

====Table LST file format====

File formatting considerations:
* Trailing commas will not impact any TABLE, and will be ignored
* Blank lines will be ignored. This includes lines with commas but without content. (allows tables to be separated by blank lines or lines of all commas)
* Attempts to use embedded line breaks or embedded quotes may or may not be supported by the parsing system, but certainly aren't supported for purposes of PCGen.
* Lines that have the first cell starting with "#" are considered comment lines and will be ignored. This will likely need to include if the first cell is escaped in quotes, just for protection from any tools that quote by default.
* Since the CSV format ignores leading/trailing spaces, one can easily have a spaced out version that is a table in a text editor if folks don't want to edit in a spreadsheet. (Having someone write a "PrettyTable" ... a trivial perl or python program to do that for the data team seems fairly easy)

A TABLE starts with STARTTABLE:
STARTTABLE:x
* x is the name of the Table. Most characters are allowed, avoiding quotes is advisable.
* Allowing Trailing commas allows the STARTTABLE lines to have blank cells where the rest are the table contents... we don't want to complain on minor things that may tools will do.

If a STARTTABLE is encountered when another Table is active, an LST load error will occur.

A TABLE ends with ENDTABLE:
ENDTABLE:x
* x is the name of the Table. Most characters are allowed, avoiding quotes is advisable.
* Allowing Trailing commas allows the ENDTABLE lines to have blank cells where the rest are the table contents... we don't want to complain on minor things that may tools will do.

If an ENDTABLE is encountered without a STARTTABLE, an LST load error will occur.

A Table must have a minimum of 3 rows, NOT counting the STARTTABLE and ENDTABLE tokens.

The First row:
x,x
* x is the column name. These are always the first line of the table after STARTTABLE:

Any column which has data MUST have a name.

The Second row:
y,y
* y is the format for the column. Any column that was named must have a FORMAT.

Additional rows:
z,z
* z represents contents of the table. These must be in the FORMAT provided for the appropriate column.

====Example====

STARTTABLE:Carrying Capacity,
Strength,Capacity
NUMBER,NUMBER
1,10
2,20
...
29,1400
ENDTABLE:Carrying Capacity,

===TABLE[x] Format===

When a TABLE is created, it implicitly picks up a FORMAT based on the FORMAT of the first column of the Table.
Unlike basic FORMATs shown above, TABLE has a SUBFORMAT (in brackets).

TABLE[x]
* x is the SUB-FORMAT of the TABLE (this is the format of the first column of the Table)
** x must be an otherwise valid FORMAT, and it is advised to avoid any FORMAT that has a SUB-FORMAT
*** This limitation may be inconsistently enforced. It certainly is prohibited to create a TABLE[TABLE[x]], but other situations the behavior may not be prohibited by the code (but the behavior is also not guaranteed)

===COLUMN[x] Format===

When a Column needs to be referred to in the data, it has a special format as well:

Unlike basic FORMATs shown above, COLUMN has a SUBFORMAT (in brackets).
COLUMN[x]
* x is the SUB-FORMAT of the COLUMN (this is the format of the data that appears in that column in a Table)
** x must be an otherwise valid FORMAT, and it is advised to avoid any FORMAT that has a SUB-FORMAT
*** This limitation may be inconsistently enforced. Such behavior may not be prohibited by the code (but avoiding bad behavior is also not guaranteed in a situation where embedded brackets occur)

===Using Tables===

With MODIFY, a TABLE[x] variable doesn't look any different. It's still:
MODIFY:TableNameVar|SET|"SomeTable"

"SomeTable" is still a string to a naive reader, but what the system will do at that point is make sure that SomeTable can actually be interpreted as a TABLE[x]... rather than just treating it as a String. Similar for column names when they are encountered (see below).

In that way, the sub variable will allow multiple tables to be swapped in, AS LONG AS they are the right format. If the format is not compatible, then all bets are off and you'll get an error.

===lookup() Function===

The major consideration is how to do the lookup in data. We can borrow some inspiration from things like Excel and Google Docs:

lookup(X,Y,Z)

* X is a table. This must resolve in the formula system to a valid table. For now, a get(...) function may be required.
* Y is the lookup value in the table. It must match the format of the first column in the table. At this time, it does an EXACT match.
* Z is the target column. This must resolve in the formula system to a valid table column. It must appear in the table named by the contents of the first argument of lookup.

Example: Max load calculation would be something like:
lookup("Carrying Capacity",floor(StrScore),"Capacity")*SizeMult
We have to do the floor due to the exact name of the lookup

Note: The format of both TABLE "Carrying Capacity" and COLUMN "Capacity" can be derived by PCGen internally and thus are no longer required to have a get (current as of Jan 30, 2018)

Note that this function allows some runtime errors, but catches a lot of possible issues. It is still possible to do a lookup on a Table that doesn't contain a specific column of the given name or format, simply because those items can be variables resolved at runtime. For example, if the third variable is COLUMN[NUMBER], we can check at load that the TABLEFORMAT has columns of FORMAT=NUMBER, but we can't guarantee the variable will resolve to a name actually in that table... that will have to wait for a runtime error. That's life, but it does allow us to know the formats at load time, so we do get a lot of error checking in the context of the usage, if not the exact table and column names.

Note you can do some really dynamic behaviors to have folks override game mode behaviors. For example, one neat item would be that we could alter a query for dice steps to extract the table name into the Global Modifier file:
MODIFY:DiceStepTable|SET|"Dice Step"
lookup(get("TABLE[NUMBER]",DiceStepTable),BaseDamage,get("COLUMN[NUMBER]",lookup("Step Column",CurrentSize-BaseSize,"Name")))

Note: In both cases here, the "get" is shown for completeness. In the case of DiceStepTable - it MAY be required or prohibited - it depends on what the Format is of the "DiceStepTable" variable. If it's TABLE, then the get is not necessary (and is actually prohibited). The example shown above assumes DiceStepTable is a String. The better design would be for it to be a TABLE (specifically TABLE[NUMBER]). For the "get" after the lookup, that is required - the lookup value will return a STRING, and as such, will needs to be converted to a COLUMN.

Now, if someone needs different dice steps for some reason... they can override the DiceStepTable variable and it will look up in a different table... so expansions could truly be expansions and not have to reach back into core PCC files in order to change key behaviors.

Consider also that spell tables can be shared across classes, or if a subclass alters the default, just create a new table rather than having to BONUS/MODIFY all the numbers in a table with adding and subtracting...

==To be completed==
* dropIntoContext
* Channels

=Material Changes=

==lookup function simplification==

Effective January 30, 2018, tables and columns can be referred to directly in lookup(). This is actually a "broad" change to how strings are interpreted. The system - when possible - fully asserts a FORMAT, and first attempts to convert the given String per the rules of that FORMAT. This also means an assignment of an ALIGNMENT, by key, will not require a "get":
MODIFY:Alignment|SET|"LE"
...will be fully legal. (This assumes Alignment is FORMAT: of ALIGNMENT)

INFO and INFOVARS

2017-01-05T13:01:06Z

Nuance: Wrapped the overly long line (it was off the page on my 4k monitor).

The proposal involves two LST tokens:

INFO:x|y
* x is an "info name". This is data defined
* y is the message format. It matches the format required by java.text.MessageFormat, which can be found, among many other places, here: http://docs.oracle.com/javase/7/docs/api/java/text/MessageFormat.html#getFormatsByArgumentIndex%28%29
* This token overwrites (if the "info name" matches)

INFOVARS:x|y=z|y=z
* x is an "info name". This is data defined
* y is a scope from the new Formula System (e.g. AREA). The y= is optional if y is "VAR" (the default numeric variable scope)
* z is a variable from the new Formula System (e.g. Face)
* This token overwrites (if the "info name" matches)

Some notes:

The "info name" is dynamic. It is NOT under the control of something like the data control file (it is NOT like FACT names or Variables). It is more similar to today's Aspect names.
There are rules for the "info name" regarding use in INFO and INFOVARS. Specifically:
If an info name is used in INFOVARS but never in INFO on that object, it is an LST load error
If an info name is used in INFO and the Message Format requires variables and no INFOVARS is provided, it is an LST load error
If an info name is used in INFO and the Message Format requires N variables and the number provided to INFOVARS does not match N, then it is an LST load error.

Note: The "info name" is only so flexible, but the code will not restrict it at this time. I would advise the data standard be all letters
and numbers (no spaces, no special characters), and if we can get to a standard the data team wants strongly enforced, that can be done.

Output in the new Freemarker system is implied. Any INFO token will be available under *.info . For example:
* Race LST file
* Monkey <> INFO:Wildness|Monkeys are usually found in the wild
* can be accessed under the following:
* pc.race.info.wildness

* https://groups.yahoo.com/neo/groups/pcgen_experimental/conversations/messages/19346

User:Nuance

2016-03-06T18:53:30Z

Nuance:

This is a page about [[User:Nuance|andrew]] also [[Andrew Wilson]]. There are many like it, but this one is mine.

I'm the data Gibbon; code Tamarin version of andrew. Not to be confused with Messrs [[User:LegacyKing|Maitlaind]] or [[User:Tir_Gwaith|McDougal]].

Andrew Wilson

2016-03-06T18:52:13Z

Nuance: /* Introduction */

{| align="right"
| __TOC__
|}

=Introduction=
I'm a software developer based in the UK; my GitHub id is ampersandrew.

In March 2016, I moved to a java coding role. My previous day job was safety critical software, mostly in Ada. Before that, I worked on a website in Linux, Apache, MySQL & Perl.

I joined the PCGen code team on the 19th April 2001, which seems like a very long time ago now. These days I mostly do data work for the project.

I became a data Tamarin in December 2011, and a data Gibbon in November 2012.

=Teams I belong to=
{| border=1
|-
! Team !! Rank
|-
| [[Data|Content - Data]] || [[Explanation_of_Teams#Gibbon|Gibbon]]
|-
| [[Code]] || [[Explanation_of_Teams#Tamarin|Tamarin]]
|}

=Contact Details=
{| border=1
|-
| Timezone || GMT
|-
| e-mail || ampersandrewATliveDOTcom
|}

Andrew Wilson

2016-03-06T18:42:46Z

Nuance: /* Contact Details */

{| align="right"
| __TOC__
|}

=Introduction=
I'm based in the UK, my sourceforge id is nuance. Day job is safety critical software, mostly ada these days. I Joined the PCGen team on the 19th April 2001, which seems like a very long time ago now.

=Teams I belong to=
{| border=1
|-
! Team !! Rank
|-
| [[Data|Content - Data]] || [[Explanation_of_Teams#Gibbon|Gibbon]]
|-
| [[Code]] || [[Explanation_of_Teams#Tamarin|Tamarin]]
|}

=Contact Details=
{| border=1
|-
| Timezone || GMT
|-
| e-mail || ampersandrewATliveDOTcom
|}

Andrew Wilson

2016-03-06T18:42:00Z

Nuance: /* Teams I belong to */

Data

2016-03-06T18:41:09Z

Nuance: /* Gibbon */

{| align="right"
| __TOC__
|}
=Introduction=

Welcome to the Wiki section of the Data team! The data team is a sub team under the umbrella of the [[Content]] team.

=Mission Statement=
To create data (books) for PCGen that encompasses all aspects of character creation, is true to the publisher's intent and results in output that is correct and complete for the end-user.

=Data Meetings=
* [[Data Meeting Availability]]
* [[Data Meeting Logs]]

=Books Requested by Users=
* [[Content Requests]]

=Conversion Logs for 6.0=
* [[GameMode35e]]
* [[GameMode_3e]]
* [[GameMode_Pathfinder]]
* [[GameMode_deadlands]]

=Active Proposals=
* [[Redesigning COMPANIONLIST and Companion Leveladjustment]]
* [[COMPANIONTYPE| COMPANIONTYPE a new token to make grouping companions together]]
* [[Dragons redesigned]]
* [[NATURALATTACK the new system]]

* [[Formula Parser Conversion - Data]]
* [[Magic Item Cost issue]]

=Resources=
* [[Joining the Data Team]]

* [[Video Lessons]]

* [[Data Team Tools]]
* [[Dataset Creation/Maintenance]]
* [[Dataset Testing]]
* [[PCGen Data Team Processes (JIRA)]]
* [[PCGen Data Team FAQ]]
* [[PCGen Data Team Useful Links]]

* [[Lst File How To]]

* [[Data Team Resource Page]]

* [[Quality Assurance Team]]

* [[Challenging Data Issues and Proposed Solutions]]

=Active Team Members=
Members of this team (and areas of specialty/responsibility) are:

===[[Explanation of Teams#Silverback|Silverback]]===
* [[LegacyKing|Andrew Maitland]]

===[[Explanation of Teams#Second|2nd]]===
* [[Distant_Scholar|Doug Limmer]]

===[[Explanation of Teams#Chimp|Chimp]]===
* [[Chris Chandler|Barak]] - Tag design, consulting (CMP datasets)
* [[User:Nylanfs|Paul Grosse]]
* [[LegacyKing|Andrew Maitland]]
* [[Stefan Radermacher]]
* [[Eric C Smith|Maredudd]]

===[[Explanation of Teams#Gibbon|Gibbon]]===
* [[David R. Bender]]
* [[Distant_Scholar|Doug Limmer]]
* [[Andrew Wilson]]

===[[Explanation of Teams#Tamarin|Tamarin]]===
* [[Paul Shipley (elro the onk)]]

===[[Explanation of Teams#Lemur|Lemur]]===
* Henk Slaaf - Q&A, Patches
* Anestis Kozakis
* Swiftbrook - Pathfinder

===Special Titles===
{| border=1
|-

|}

=Inactive Team Members=

===[[Explanation of Teams#Silverback|Silverback]]===
* [[Eddy Anthony]]
* [[Frank Kliewe]]

===[[Explanation of Teams#Chimp|Chimp]]===
* [[Tir Gwaith]] - 3e, 3.5e, Races, Classes, Prettylst
* Michael Gray (taluroniscandar) - 3e and 3.5e Psionics
* Aaron Divinsky, Default Monster Kits, [[Internationalization]]
* [[Eddy Anthony]]

===[[Explanation of Teams#Gibbon|Gibbon]]===
* [[Paul W. King|Paul King]]
* Phantom of Krankor - Need real name

===[[Explanation of Teams#Tamarin|Tamarin]]===
* Ratheof Blithwyn
* [[Shelley Stephen]]

===[[Explanation of Teams#Lemur|Lemur]]===
* [[Andargor]]
* David Saulnier
* Dennis Baker
* Eric Jarman
* [[Jason Horner]]
* Phillip Ryan - PrettyLst
* Fluxxdog
* [[Martijn Verburg]]
* Ainvar Garrettson
* John Bauldree
* Monty, aka Fabio Montanari - 3.5e
* Jonathan A. Arnold - Homebrew Help
* Peter Yovich
* [[Terry FitzSimons]]
* Arjan van Ginneken
* Thomas Cooper
* [[Tod Milam]]
* Harvey Howell
* Terry Milnes
* [[Allen Cohn]]

===Special Titles===
{| border=1
|-
| [[Andargor]] || Amoeba
|-
| [[Shelley Stephen]] || 1st flunky in charge of finding weird bugs
|-
| [[Tir Gwaith]] || [[Strange Monkey]]
|}

Meeting 2013 01 04

2013-01-05T00:06:38Z

Nuance: /* Log */

{| align="right"
| __TOC__
|}

[[http://wiki.pcgen.org/Meeting_Logs PCGen BoD Meeting Minutes Home]]

=Attendance=
* Chair - David (Adv 2nd)
* Admin - Anestis (Website 2nd)
* Architecture - Tom (Arch SB)
* Code - James (Code SB)
* Content - Eric (Docs 2nd)
* Pub. Relations - David (Adv 2nd)

=Summary=

=Log=
<PapaDRB[Ad_2nd]> According to Kar, the agenda is: 
<PapaDRB[Ad_2nd]> Agenda: * 6.0.1 release * 6.0.x data upgrade path progress * 6.1.0 progress/blockers * Finances 
<PapaDRB[Ad_2nd]> Tom, James. Will one of you comment on 6.0.1 (or is it 6.1.0). 
<[Arch_SB]thpr> 6.0.1 would be James to comment on that 
<James[Code_SB]> ok 
<James[Code_SB]> Right so lets gets some confusion sorted out first :) 
<PapaDRB[Ad_2nd]> LOL 
<James[Code_SB]> 6.0.1 is a patch for production 
<James[Code_SB]> 6.1.1 is the first alpha for the next dev cycle 
<PapaDRB[Ad_2nd]> Gotcha. 
<James[Code_SB]> So the current plan is to hold off on 6.0.1 until we have socialised the bug data changes in the alpha release 
<James[Code_SB]> From the code side we have 15 fixes in for 6.0.1 with abotu 6 more to come that Tom wants to put across 
<[Arch_SB]thpr> I'm trying to get to those this evening 
<James[Code_SB]> Cool 
<James[Code_SB]> I'll push the source selection improvements into 6.0.1 as well, but would appreciate feedback if anyone wants to kick the tyres 
<James[Code_SB]> Andrew's plan for data is to bulk copy all of the data changes in trunk back t the 6.0 branch once they have beenput put out in the 6.1.1 alpha release 
<James[Code_SB]> That'll be a big change but includes a lot of small fixes and some tidy up/standardisation 
<James[Code_SB]> So overall I wouldn't expect 6.0.1 RC1 to come out until late Jan. 
<PapaDRB[Ad_2nd]> Ok. Are the source selection improvements in the nightly autobuilds yet? 
<James[Code_SB]> yep they are there 
<James[Code_SB]> However now is a good time to sing out if anyone has anything they weant included in the production patch 
<James[Code_SB]> That's probably it for the 6.0.1 prod fix progress - any questions or comments? 
<[Arch_SB]thpr> not here 
<PapaDRB[Ad_2nd]> not here, either. 
<[Arch_SB]thpr> afk for 3 min 
<James[Code_SB]> Can anyone else add any further detail on the "6.0.x data upgrade path progress" item? 
<PapaDRB[Ad_2nd]> Sorry, no. That really is Andrew's baby with some help from others. 
<James[Code_SB]> He did ask me to hold off on the 6.1.1 alpha to allow a few more issues to be addressed - that's the last I have heard 
<[Arch_SB]thpr> back 
<James[Code_SB]> So we might move on to the 6.1.1 alpha progress then 
<PapaDRB[Ad_2nd]> Ok, go for it. 
<James[Code_SB]> On the code side we have around 35 items included already 
<James[Code_SB]> I am continuing the expuingin of the old UI code and have converted all choosers to the new chooser disalog apart from sub-class/specialty and aubstitution class selection 
<James[Code_SB]> My plan for those is to go back to a single column with the name in available but provide a full info panel at the bottom of the dialog allowing rich info for the currently highlighed choice, much like any other avaiolable/selected pair in the system 
<James[Code_SB]> I've also addressed the feedback on source selection that RobertD provided 
<James[Code_SB]> So that will be in the alpha 
<James[Code_SB]> Tom, how about you? 
<[Arch_SB]thpr> Have worked a few different things. 
<[Arch_SB]thpr> Driving toward more facets, and have done most of the work to get rid of associations created in Playercharacter 
<[Arch_SB]thpr> By having those in facets, we can directly trigger behaviors from one location and know it will add/remove safely 
<[Arch_SB]thpr> there are 2 major things left, one of which is the CHOOSE system 
<[Arch_SB]thpr> that is tied into other work I'm doing 
<[Arch_SB]thpr> Which is on abilities and making it so we no longer clone abilities 
<[Arch_SB]thpr> Making all selections type safe (And some additional checking we get from that) is also tied into the same project 
<[Arch_SB]thpr> investigation has shown that I think I'll need to go off to a branch 
<[Arch_SB]thpr> We have like 4 methods of getting Abilities into a Character and each has quirks where I'm not sure I can write unit tests against them like I want. 
<[Arch_SB]thpr> I want to ensure we can test both add/remove and persistence to PCG, and all of them have something that is .... challenging 
<[Arch_SB]thpr> (or in some cases downright bugs) 
<[Arch_SB]thpr> So I'll push as far as I can in trunk and then go off to a branch for a bit on that one 
<[Arch_SB]thpr> that way I can break things temporarily, knowing I also have unit tests that will show when they are fixed, and when it's all happy , can bring it all back to trunk 
*** jujutsunerd has quit IRC: Read error: Connection reset by peer 
<James[Code_SB]> Sounds like a good plan 
<PapaDRB[Ad_2nd]> Yup. 
<[Arch_SB]thpr> Overall, good progress recently toward getting things into facets 
<James[Code_SB]> Did you want CI activated on the branch? We could make the emails not go to the dev list 
<[Arch_SB]thpr> Next up will probably be Spells, as that right now is very passive 
*** Maredudd has joined #pcgen 
<[Arch_SB]thpr> CI would be awesome on the branch 
<James[Code_SB]> k, I'll configure it once you make the branch 
<James[Code_SB]> Hi Eric 
*** Maredudd is now known as [DOC]Maredudd 
<[Arch_SB]thpr> cool, thanks 
<[DOC]Maredudd> Hi James 
<James[Code_SB]> @Eric, we are just discussing the upcoming 6.1.1 alpha release - anything to add there? 
<[DOC]Maredudd> 6.1.1? 
<[DOC]Maredudd> Nothing for either 6.1.0 or 6.0.1 . . . 
<James[Code_SB]> Yeah renaming the first alpha to try and reduce confusion 
<[DOC]Maredudd> Ah! Makes sense! :-) 
<[DOC]Maredudd> I have nothing for the alpha. I am interested to see how the data changes work out so we can determine what gets ported to 6.0.1. 
<James[Code_SB]> Likewise 
<[DOC]Maredudd> What is the tie frame for 6.1.1? 
<[DOC]Maredudd> time frame . . . 
<James[Code_SB]> Code is ready (Tom - you happy wiht that) so just waiting on the word from Andrew 
<James[Code_SB]> I am guessing next weekend (12/13) 
<[DOC]Maredudd> Next weekend is good for me. I'll be nusy on the 12th, but the 14th I'll be available to do the Mac file. 
<[DOC]Maredudd> 13th . . . :-) 
<James[Code_SB]> Excellent 
<PapaDRB[Ad_2nd]> Ok. Anything else for 6.0.1 or 6.1.1 ? 
<[DOC]Maredudd> How long after 6.1.1 before we do 6.0.1? 
<James[Code_SB]> I reckon late Jan for 6.0.1 RC1 
<[DOC]Maredudd> Cool. 
<[Arch_SB]thpr> code ready whenever 
<James[Code_SB]> Excellent 
<[Arch_SB]thpr> I guess technically that's arch ready whenever ;) 
<James[Code_SB]> :) A healthy mix 
<PapaDRB[Ad_2nd]> Ok. Anestis, anything for web or your projects? 
<[Web_2nd]Anestis> Jami has done a great job with the Wordpress site. Just a few tweaks I think, and our FB/Twitter integration. 
<[Web_2nd]Anestis> I want to have the ability to comment on the Donate page removed. 
<[Web_2nd]Anestis> Has everyone seen the site yet? 
<[Arch_SB]thpr> I'm not sure I have 
<[DOC]Maredudd> I haven't. Can you send me a link? 
<PapaDRB[Ad_2nd]> Same for me. Send a link please 
<[Web_2nd]Anestis> http://pcgen.org/wordpress 
<James[Code_SB]> If it is close we should set a schedule for release 
<[Web_2nd]Anestis> It's fairly close, yeah 
<[Web_2nd]Anestis> Probably equivalent to beta 
<[Web_2nd]Anestis> Kar, Drew and Eric are actually setup as Editors so that they can post articles/updates 
<James[Code_SB]> Could you propose a schedule at the next BoD meeting please? 
<[Web_2nd]Anestis> I guess. Depends if I can make the next meeting, as well as as if I can get Jami to do the required changes 
<James[Code_SB]> Well, it is not so much needing to get changes done, but to set a target 
<James[Code_SB]> Even if that is a few months away 
<[Web_2nd]Anestis> OK 
<[Web_2nd]Anestis> Not so much as a web issue, and maybe not a discussion for now, but as I mentioned on the mailing list, maybe look at setting up a Google+ community. 
<PapaDRB[Ad_2nd]> What is a google+ community? Is it like yahoo groups? or something else entirely 
<[Web_2nd]Anestis> It's more like a Facebook group 
<[Web_2nd]Anestis> but on google+ 
<[Web_2nd]Anestis> The link I posted on the BOD Mailing list has information on it 
<PapaDRB[Ad_2nd]> Ok, what is a facebook group? 
<PapaDRB[Ad_2nd]> Oh, ok. I'll chedk that out 
<PapaDRB[Ad_2nd]> anyone else have anything? 
<[Arch_SB]thpr> nope 
<[Web_2nd]Anestis> That's really all from me 
<PapaDRB[Ad_2nd]> Eric, James ? 
<James[Code_SB]> All good here 
<PapaDRB[Ad_2nd]> Ok, *bangs* gavel down. Meeting adjourned. I'll post it on the web site. Thank you all for coming. 
<[DOC]Maredudd> I have nothing for now.

User:Nuance

2012-11-09T21:52:27Z

Nuance:

This is a page about [[User:Nuance|andrew]] also [[Andrew Wilson]]. There are many like it, but this one is mine.

I'm the code Tamarin version of andrew. Not to be confused with Messrs [[User:LegacyKing|Maitlaind]] or [[User:Tir_Gwaith|McDougal]].

Andrew Wilson

2012-11-09T21:50:15Z

Nuance: /* Teams I belong to */

{| align="right"
| __TOC__
|}

=Introduction=
I'm based in the UK, my sourceforge id is nuance. Day job is safety critical software, mostly ada these days. I Joined the PCGen team on the 19th April 2001, which seems like a very long time ago now.

=Teams I belong to=
{| border=1
|-
! Team !! Rank
|-
| [[Data|Content - Data]] || [[Explanation_of_Teams#Tamarin|Tamarin]]
|-
| [[Code]] || [[Explanation_of_Teams#Tamarin|Tamarin]]
|}

=Contact Details=
{| border=1
|-
| Timezone || GMT
|-
| e-mail || andrewATrivendaleDOTnet
|}

Code

2012-11-09T21:49:00Z

Nuance: /* Tamarin */

{| align="right"
| __TOC__
|}

=Introduction=
Welcome to the Wiki section for the Code Monkey team!

=Mission Statement=
'''TBA'''

=Resources=
* [[Developers Meeting]]
* [[Dev Meeting Log 20120309]]
* [[Dev Meeting Log 20120429]]
* [[Dev Meeting Log 20121103]]

==For New Starters==
* [[Joining the Code Team]] General steps to take to prepare yourself
* [[Code Monkey Introduction]]

==Developer Environment==
* [[Basic Developer Setup]]
* [[Subversion Setup]]
* [[Merging]] with SVN
* [[Building PCGen]], also see [[ANT]] and [[MAVEN]]
* [[Continuous Integration]]

==Coding==
* [[Coding Standards]]
* [[Deprecating a Token]]
* [[Explanation of the Code Base]]
* [[Graph Theory]]
* [[Logging in the Code Base]]
* [[Unit Testing]]
* [[Removing Libraries]]
* [[Unnecessary Code Detector]]

=Completed Sub Projects=
* [[Ability Object TODO List]]
* [[LST_Editor_Verification]]

=Open Sub Projects=
* [[Internationalization]]
* [[CDOM]]
* [[UI Overhaul]]
* [[LST_Editor]]
* [[Major Code Projects]]
* [[Template Engine]]

=Active Team Members=

===[[Explanation of Teams#Silverback|Silverback]]===
* [[James Dempsey]]

===[[Explanation of Teams#Second|2nd]]===
* TBA

===[[Explanation of Teams#Chimp|Chimp]]===
* [[Tom Parker]]

===[[Explanation of Teams#Gibbon|Gibbon]]===
* Jayme Cox
* [[Stefan Radermacher]]

===[[Explanation of Teams#Tamarin|Tamarin]]===
* [[Andrew Wilson]]
* [[Martijn Verburg]]
* [[Connor Petty]]

===[[Explanation of Teams#Lemur|Lemur]]===
* [[Eddy Anthony]]
* Per Christian Henden
* Thomas Cooper
* [[Tod Milam]] - Mac Developer

===[[X-Terminator Mark II]]===
* [[Greg Bingleman]] - [http://www.codemonkeypublishing.com Code Monkey Publishing]

===Other===
* Brad Stiles, SVN advice
* Jason Buchanan, Advice on old code
* [[Jonas Karlson]], Advice on old code

=Passive Team Members=

* B. K. Oxley (Provides IntelliJ licenses)

=Inactive Team Members=

===[[Explanation_of_Teams#2nd|2nd]]===
* Devon Jones

===[[Explanation_of_Teams#Chimp|Chimp]]===
* Aaron Divinsky

===[[Explanation_of_Teams#Tamarin|Tamarin]]===
* Andriy Sen
* [[Kevin Fernandes]]
* [[Koen Van Daele]]
* [[Joe Frazier, Jr.]]
* Per Christian Henden

===[[Explanation_of_Teams#Lemur|Lemur]]===
* Bill Neumann
* Dan Parks
* [[Eduard Martinescu]]
* Eric Jarman
* Jasper Spaans
* Julio Esslinger Viegas
* Peter Barker
* [[Rick Ryker]]
* Thomas Clegg
* Tony Lavalle
* Hades Lucifer [7/20/10]
* Josh Johnston [7/20/10]
* MotorViper [7/20/10]
* [[Steven West]] [7/20/10]
* [[Alec Ross]] [7/20/10]
* [[Tir Gwaith]] [7/20/10]

===Other===
* [[Andargor]], Suggestions
* [[Bryan McRoberts]], Advice on old code
* Kurt Wimmer, Suggestions
* Walter Duncan, Held the old pcgen_autobuild user

Coding Standards

2011-05-07T13:29:43Z

Nuance: /* General Coding guidelines */

{| align="right"
| __TOC__
|}

=Introduction=

Releases typically happen every second Sunday Canberra, Australia (UTC+11) time. There may be code freezes on release days, but these will be announced in advance on the developers and experimental lists. There are 2 taboos:

# Checking in code that breaks the build.
# Checking in code that obviously wasn't tested.

We have a couple of code monkeys who make sweeps through the code to make sure it's all in the proper format, and we have others who go through looking to optimize code. Everyone has their role and things have gone very smoothly. If you are not certain about something, ask! Nobody is here to bite your head off (unless they are role-playing a troll). Try the developer's mailing list or any of the Yahoo! Groups or the Silverbacks.

=Code Style=

Coding styles can be assisted by your IDE, see the standards folder in the SVN repository.

* For Eclipse you can use [http://pcgen.svn.sourceforge.net/viewvc/*checkout*/pcgen/Trunk/pcgen/code/standards/eclipse32_pcgen.xml 3.2 Formatter Rules]

Voting for the code conventions is currently restricted to active code monkeys (have checked in in the last 6 months), the current votes (and therefore standard) is below.

{| border=1
|-
! Rule !! For !! Against
|-
| Use Tabs || 4 || 4
|-
| Use Spaces || 4 || 4
|-
| Have braces around 1 line control statements || 8 || 0
|-
| Open and close braces on their own line || 5 || 3
|-
| 1 space padding inside parenthesis when calling a method || 0 || 8
|-
| 1 space padding inside parenthesis when declaring a method || 0 || 8
|-
| Space after a comma || 8 || 0
|}

'''Who Has Voted''' (simply link in your name when you have done so)
# [[Martijn Verburg]]
# Aaron Divinsky
# [[Andrew Wilson]]
# Brian (telechus)
# [[Devon Jones]]
# [[Greg Bingleman]]
# [[James Dempsey]]
# [[Jonas Karlson]]
# Stefan Radermacher
# [[Tir Gwaith]]
# [[Tod Milam]]

=Code Warnings and Errors=

Code Warnings and Errors may vary by tool.

'''Please note that IDEA 9.01 can utilise Eclipse formatting rule exports, so we no longer need to cover that case'''

{| border=1
|-
! Rule !! Eclipse 3.5.1 !! IDEA 9.01 !! NetBeans !! Description
|-
| Non-static Access to a static member || Y || ? || Y || -
|-
| Indirect access to a static member || Y || ? || Y || -
|-
| Unqualified access to an instance field || Y || ? || Probably Y || Referencing instance fields with ''this'' keyword
|-
| Undocumented Empty block || Y || ? || Y || -
|-
| Access to a non-accessible member of an enclosing type || Y || ? || Probably Y || -
|-
| Method with a constructor name || Y || ? || Y || -
|-
| Parameter Assignment || Y || ? || Y || -
|-
| Non-externalized Strings (missing/unused $NON-NLS$tag) || Y || ? || N || -
|-
| Serializable class without serialVersionUID || Y || ? || Y || -
|-
| Assignment has no effect (''x = x;'') || Y || ? || Y || -
|-
| Possible accidental boolean assignment ''if (a = b)'' || Y || ? || N || -
|-
| ''finally'' does not complete normally || Y || ? || ? || -
|-
| Empty Statement || Y || ? || Y || -
|-
| Using a char array in String concatenation || Y || ? || ? || -
|-
| Hidden catch block || Y || ? || ? || -
|-
| Inexact type match for vararg arguments || Y || ? || ? || -
|-
| Boxing and unboxing conversions || Y || ? || ? || Basically wants you to explicitly box and unbox basic types
|-
| Enum type constant not covered in switch statement || Y || ? || N || -
|-
| switch case falls through || Y || ? || N || -
|-
| Null pointer access || Y || ? || Y || -
|-
| Potential null pointer access || Y || ? || Y || -
|-
| Comparing identical values ('x' == 'x') || Y || ? || N || -
|-
| Missing synchronized modifier on inherited method || Y || ? || Y || -
|-
| Class overrides equals() but not hashCode() || Y || ? || Y || -
|-
| Dead code (e.g. 'if (false)') || Y || ? || Y* || Netbeans is covered by 'Unreachable Statement' option
|-
| Field declaration hides another field or variable || Y || ? || Y || -
|-
| Local declaration hides another field or variable (General) || Y || ? || Y || -
|-
| Local declaration hides another field or variable (Constructors and Gettors/Setters) || Y || ? || Y || -
|-
| Type parameter hides another type || Y || ? || Probably Y || -
|-
| Method does not override package visible method || Y || ? || Probably Y || -
|-
| Interface method conflicts with protected method in Object || Y || ? || N || -
|-
| Deprecated API || Y || ? || Y || -
|-
| Deprecated API (signal use of deprecated api inside deprecated code) || Y || ? || Y || -
|-
| Deprecated API (signal overriding or implementing method) || Y || ? || Y || -
|-
| Forbidden Reference (access rules) || Y || ? || Y || -
|-
| Discouraged Reference (access rules) || Y || ? || Y || -
|-
| Local variable is never read || Y || ? || Y || -
|-
| Parameter is never read (non overriding methods) || Y || ? || Y || -
|-
| Parameter is never read (overriding methods) || Y || ? || Y || -
|-
| Parameter is never read (even if documented with @param tag) || Y || ? || Y || -
|-
| Unused import || Y || ? || Y || -
|-
| Unused local or private member || Y || ? || Y || Includes unused private methods
|-
| Unused method || Y* || ? || Y || Eclipse is covered by 'Unused local or private member' option
|-
| Unreachable statement || Y* || ? || Y || Eclipse is covered by 'Dead code' option
|-
| .equals on Array || N || ? || Y || -
|-
| .equals on Incompatible Types || N || ? || Y || -
|-
| Comparing Strings using == or != || N || ? || Y || -
|-
| Synchronization on non-final field || N || ? || Y || -
|-
| Redundant null check || Y || ? || N || -
|-
| Unnecessary else || Y || ? || N || -
|-
| Unnecessary cast or instanceof || Y || ? || Y || -
|-
| Unnecessary declaration of thrown checked exception (non overriding methods) || Y || ? || Y || -
|-
| Unnecessary declaration of thrown checked exception (overriding methods) || Y || ? || Y || -
|-
| Unnecessary declaration of thrown checked exception (ignore exceptions declared with @throws or @exception) || Y || ? || ? || -
|-
| Unnecessary declaration of thrown checked exception (ignore Exception and Throwable) || Y || ? || ? || -
|-
| Unused break/continue label || Y || ? || N || -
|-
| Redundant super interface || Y || ? || ? || -
|-
| Unchecked generic type operation (JDK1.5) || Y || ? || Y || -
|-
| Usage of a raw type (JDK1.5) || Y || ? || Y || i.e. Using List instead of List<String>
|-
| Generic type parameter declared with a final type bound (JDK1.5) || Y || ? || ? || -
|-
| Missing Override annotation || Y || ? || Y || -
|-
| Missing Deprecated annotation || Y || ? || Y || -
|-
| Annotation is used as a super interface || Y || ? || Y || -
|-
| Unhandled token in SupressWarnings token || Y || ? || N || -
|-
| Unused SupressWarnings token || Y || ? || N || -
|-
| Enable SupressWarnings annotations || Y || ? || Y || -
|}

==Standard 2004-Present==
Coding warnings and errors can be highlighted for correction by your IDE, see the standards folder in the SVN repository.

Voting for the code warnings is currently restricted to active code monkeys (have checked in in the last 6 months), the current votes (and therefore standard) is below.

{| border=1
|-
! Rule !! For !! Against !! Description
|-
| Non-static Access to a static member || 3 || 0 || -
|-
| Indirect access to a static member || 3 || 0 || -
|-
| Unqualified access to an instance field || 0 || 3 || Referencing instance fields with ''this'' keyword
|-
| Undocumented Empty block || 2 || 1 || -
|-
| Access to a non-accessible member of an enclosing type || 2 || 1 || -
|-
| Method with a constructor name || 3 || 0 || -
|-
| Parameter Assignment || 3 || 0 || -
|-
| Non-externalized Strings (missing/unused $NON-NLS$tag) || 2 || 1 || Basically [[Internationalization]] will need this
|-
| Serializable class without serialVersionUID || 0 || 3 || -
|-
| Assignment has no effect (''x = x;'') || 2 || 1 || -
|-
| Possible accidental boolean assignment ''if (a = b)'' || 3 || 0 || -
|-
| ''finally'' does not complete normally || 3 || 0 || -
|-
| Empty Statement || 3 || 0 || -
|-
| Using a char array in String concatenation || 3 || 0 || -
|-
| Hidden catch block || 2 || 1 || -
|-
| Boxing and unboxing conversions || 0 || 3 || Basically wants you to explicitly box and unbox basic types
|-
| Inexact type match for vararg arguments || 3 || 0 || -
|-
| Enum type constant not covered in switch statement || 3 || 0 || -
|-
| switch case falls through || 1 || 2 || -
|-
| Null reference || 3 || 0 || -
|-
| Field declaration hides another field or variable || 3 || 0 || -
|-
| Local declaration hides another field or variable (General) || 3 || 0 || -
|-
| Local declaration hides another field or variable (Constructors and Gettors/Setters) || 1 || 2 || -
|-
| Type parameter hides another type || 3 || 0 || -
|-
| Method overridden but not package visible || 3 || 0 || -
|-
| Interface method conflicts with protected method in Object || 3 || 0 || -
|-
| Deprecated API || 3 || 0 || -
|-
| Forbidden Reference (access rules) || 3 || 0 || -
|-
| Discouraged Reference (access rules) || 3 || 0 || -
|-
| Local variable is never read || 3 || 0 || -
|-
| Parameter is never read (non overriding methods) || 3 || 0 || -
|-
| Parameter is never read (overriding methods) || 0 || 3 || -
|-
| Unused import || 3 || 0 || -
|-
| Unused local or private member || 3 || 0 || -
|-
| Unnecessary cast or instanceof || 3 || 0 || -
|-
| Unnecessary else || 2 || 1 || -
|-
| Unnecessary declaration of thrown checked exception (non overriding methods) || 3 || 0 || -
|-
| Unnecessary declaration of thrown checked exception (overriding methods) || 2 || 1 || -
|-
| Unused break/continue label || 3 || 0 || -
|-
| Unchecked generic type operation (JDK1.5) || 3 || 0 || -
|-
| Usage of a raw type (JDK1.5) || 3 || 0 || i.e. Using List instead of List<String>
|-
| Generic type parameter declared with a final type bound (JDK1.5) || 0 || 3 || -
|-
| Missing Override annotation || 2 || 1 || -
|-
| Missing Deprecated annotation || 2 || 1 || -
|-
| Annotation is used as a super interface || 2 || 1 || -
|-
| Unhandled token in SupressWarnings token || 3 || 0 || -
|}

'''Who Has Voted''' (simply link in your name when you have done so)
# [[Martijn Verburg]]
# Aaron Divinsky
# [[Andrew Wilson]]
# Brian (telechus)
# Devon Jones
# Greg Bingleman
# [[James Dempsey]]
# Jonas Karlson
# Stefan Radermacher
# Tir Gwaith
# Tod Milam

=General Coding guidelines=

# Arguments should have meaningful names, even if that makes them really long. variables that are temporary and throwaway you can name something inane - I like to name temporary strings aString for lack of any additional creative effort on my part :) (But for some of us, plain old s is just fine.) You will see aPC almost everywhere for PlayerCharacter instances, regardless of other conventions.
# Name arguments to methods something reasonable so IDE's that display the argument names can give a guide as to what is expected. If the method is something like setVision(String arg) it's pretty clear what's expected, but for methods which take multiple arguments it's especially important to name the arguments well.
# Always keep optimization in mind. Avoid creating unnecessary variables. But don't go out of your of your way to optimize if it clouds the meaning of the code or makes it harder to maintain. When in doubt, correctness trumps performance.
# Keep scope in mind — if a variable or method can be made private, protected or final, do so. If you're not sure what the difference is in these, don't be afraid to ask. This gets into the minutest of Java and we're glad to educate you so we can all make the best code possible.
# Write unit tests for new code, see [[Unit Testing]].
# Add comments and Javadoc.
# If you change the syntax of a lst tag or output sheet token or modify the GUI or anything else that needs to be reflected in the Documentation, post a note here with Doc Monkeys! in the title so it gets their attention. If you can type up your notes so it fits with the format used in the actual documentation, the Doc Monkeys will love you. If you're not able to do that, give them at least something to work with and they'll make the rest up. :)
# Be friendly and courteous. If someone checks in code that annoys you — e-mail them. If you can't reach them or get no response, e-mail me. Slamming here shouldn't be necessary.
# Don't break the build. I've broken the build myself, so I don't hold it against anyone if they break it (though I don't expect anyone to make a habit of it!). Running ''ant complete'' pretty much saves you from this embarrassment.
# Make sure the JUnit tests pass before checking in your code. Running ''ant test'' is the answer here. (The "complete" target for ant includes "test", by the way.) Keep an eye on the autobuilds. If the software is presently failing for the auto-builds, it might be a good time to focus on build-fixing changes.

Remember we're all doing this for fun and because we want to produce something that can support character creation/maintenance for all our favorite books (and our own creations!).

If anyone wants to tackle a bug or feature but doesn't know where the code they should focus on is located, feel free to ask. I'm more than happy to point out where I think the related code would be located if that means its another bug or feature I don't have to worry about! PCGen has a fairly large code base so new developers will need some time to get used to how everything is organized. I don't mind helping to speed that process along, and I'm sure others would be willing to answer questions if they're posted here as well.

Andrew Wilson

2011-05-07T13:24:57Z

Nuance: Created page with "{| align="right" | __TOC__ |} =Introduction= I'm based in the UK, my sourceforge id is nuance. Day job is safety critical software, mostly ada these days. I Joined the PCGe..."

{| align="right"
| __TOC__
|}

=Introduction=
I'm based in the UK, my sourceforge id is nuance. Day job is safety critical software, mostly ada these days. I Joined the PCGen team on the 19th April 2001, which seems like a very long time ago now.

=Teams I belong to=
{| border=1
|-
! Team !! Rank
|-
| [[Code]] || [[Can't remember (don't pay much attention to it)]]
|}

=Contact Details=
{| border=1
|-
| Timezone || GMT
|-
| e-mail || andrewATrivendaleDOTnet
|}

User:Nuance

2009-04-08T22:42:10Z

Nuance:

This is a page about [[User:Nuance|andrew]]. There are many like it, but this one is mine.

I'm the code Lemur version of andrew. Not to be confused with Messrs [[User:LegacyKing|Maitlaind]] or [[User:Tir_Gwaith|McDougal]].

Separator Characters

2009-04-08T21:55:53Z

Nuance:

{| align="right"
| __TOC__
|}

==Background==

There is an issue as far as long-term consistency for the use of characters to represent logical "AND" and "OR"

This document uses CHOOSE:TEMPLATE (since it doesn't exist) as an example. For additional CHOOSE tokens and proposals, you can see [[Architecture Changes 5.17]]

To readers: Please add additional options if you have additional ideas. You may find the [[Data LST Standards]] useful to look at reserved characters.

==Option #1, Using Pipe as an OR separator, Using Comma as an AND separator==

===Using Primitives===

CHOOSE:TEMPLATE|Template1|Template2

...allows a choice of Template1 or Template2

CHOOSE:TEMPLATE|TYPE=Foo|!TYPE=Bar

...allows a choice of any Template that is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|TYPE=Foo,!TYPE=Bar

...allows a choice of any Template that is both TYPE=Foo and not TYPE=Bar

===Using Single a Qualifier===

CHOOSE:TEMPLATE|PC[TYPE=Foo|!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo,!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo,!TYPE=Bar|TYPE=Goo]

...allows a choice of any Template that the character already has, where the Template is (a) both TYPE=Foo and not TYPE=Bar OR (b) TYPE=Goo

===Using Multiple Qualifiers===

CHOOSE:TEMPLATE|PC[TYPE=Foo|!TYPE=Bar]|QUALIFIED[TYPE=Goo]

...allows a choice of
(a) Any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar
OR
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo,!TYPE=Bar],QUALIFIED[TYPE=Goo]

...allows a choice of:
(a) Any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar
AND
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo,!TYPE=Bar|TYPE=Goo]|QUALIFIED,!PC

...allows a choice of:
(a) Any Template that the character already has, where the Template is (a1) both TYPE=Foo and not TYPE=Bar OR (a2) TYPE=Goo
OR
(b) Any Template that the PC is qualified to take, but has not yet taken.

===Discussion===

* Note that this is the existing syntax used in the CHOOSE proposals as they are shown on the Wiki. [TRP]
* Showing this syntax to a few non coders it definitely wasn't instinctively clear that ',' was an AND symbol. However, '|' was instinctively picked up as an OR symbol [[User:Karianna|karianna]] 18:59, 1 April 2009 (CEST)
* Part of that is that the pipe '|' just seems to break that attention naturally, which is why it works so well as a subtoken separator. But I think we should move away from giving two jobs to the same thing.--[[User:Michael W. Fender|Fluxxdog]] 01:12, 2 April 2009 (CEST)
Insert comments on option #1 here.

==Option #2, Using Comma as an OR separator, Using Ampersand as an AND separator==

===Using Primitives===

CHOOSE:TEMPLATE|Template1,Template2

...allows a choice of Template1 or Template2

CHOOSE:TEMPLATE|TYPE=Foo,!TYPE=Bar

...allows a choice of any Template that is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|TYPE=Foo&!TYPE=Bar

...allows a choice of any Template that is both TYPE=Foo and not TYPE=Bar

===Using Single a Qualifier===

CHOOSE:TEMPLATE|PC[TYPE=Foo,!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo&!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo&!TYPE=Bar,TYPE=Goo]

...allows a choice of any Template that the character already has, where the Template is (a) both TYPE=Foo and not TYPE=Bar OR (b) TYPE=Goo

===Using Multiple Qualifiers===

CHOOSE:TEMPLATE|PC[TYPE=Foo,!TYPE=Bar],QUALIFIED[TYPE=Goo]

...allows a choice of
(a) Any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar
OR
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo&!TYPE=Bar]&QUALIFIED[TYPE=Goo]

...allows a choice of:
(a) Any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar
AND
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo&!TYPE=Bar,TYPE=Goo],QUALIFIED&!PC

...allows a choice of:
(a) Any Template that the character already has, where the Template is (a1) both TYPE=Foo and not TYPE=Bar OR (a2) TYPE=Goo
OR
(b) Any Template that the PC is qualified to take, but has not yet taken.

===Discussion===

*I think this is a problem, as ampersand is not a reserved character in PCGen. This is used in actual data that we ship, and thus we would expect homebrews to feel this character is also legal. Therefore, in order to implement this properly, we end up having to have a Data Converter, as this will break existing PCs. (which is the open FREQ, not the item completed for 5.16). While I think this is a nice idea, I think the hurdle is too large to do this quickly. [TRP]

Insert other comments on option #2 here.

==Option #3, Using <OR> as an OR separator, Using <AND> as an AND separator==

===Using Primitives===

CHOOSE:TEMPLATE|Template1<OR>Template2

...allows a choice of Template1 or Template2

CHOOSE:TEMPLATE|TYPE=Foo<OR>!TYPE=Bar

...allows a choice of any Template that is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|TYPE=Foo<AND>!TYPE=Bar

...allows a choice of any Template that is both TYPE=Foo and not TYPE=Bar

===Using Single a Qualifier===

CHOOSE:TEMPLATE|PC[TYPE=Foo<OR>!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo<AND>!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo<AND>!TYPE=Bar<OR>TYPE=Goo]

...allows a choice of any Template that the character already has, where the Template is (a) both TYPE=Foo and not TYPE=Bar OR (b) TYPE=Goo

===Using Multiple Qualifiers===

CHOOSE:TEMPLATE|PC[TYPE=Foo<OR>!TYPE=Bar]<OR>QUALIFIED[TYPE=Goo]

...allows a choice of
(a) Any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar
OR
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo<AND>!TYPE=Bar]<AND>QUALIFIED[TYPE=Goo]

...allows a choice of:
(a) Any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar
AND
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo<AND>!TYPE=Bar<OR>TYPE=Goo]<OR>QUALIFIED<AND>!PC

...allows a choice of:
(a) Any Template that the character already has, where the Template is (a1) both TYPE=Foo and not TYPE=Bar OR (a2) TYPE=Goo
OR
(b) Any Template that the PC is qualified to take, but has not yet taken.

===Discussion===

* Note that the unicode discussion here was broken out into option #4. - thpr Apr 4

*I Have a similar concern here to option #2, as we have not reserved < or > as restricted characters. < and > are used in actual data that we ship, and thus we would expect homebrews to feel this character is also legal. There is less risk of using (literally) <OR> or <AND>, which makes this somewhat safer than option #2. However, this does introduce restrictions on data naming. In order to implement this without risk, we end up having to have a Data Converter, as this will break existing PCs. (which is the open FREQ, not the item completed for 5.16). I think the hurdle is too large to do the FREQ converter quickly. [TRP]

*Do the characters '<' and '>' matter? Are there other characters that can't be used in a key name that can be used for identifying a logical operator? What about '$'? Are there any characters that we cannot use whatsoever for this? --[[User:Michael W. Fender|Fluxxdog]] 04:03, 1 April 2009 (CEST)

:* You may find the [[Data LST Standards]] useful to find reserved characters.
::*Not as helpful as you think. This just lists what should and shouldn't be used in our releases, not what actually can and can't be used.
::::*Not True: Characters which should never be used in object names are Commas (,), Pipes (|), Backslashes (\), Colons (:), Semicolons (;), Periods (.), Brackets ([]), Percent (%), Asterisk (*) and Equals (=). Perhaps we should change the language to "must not be used" to be more RFC 2119-like and avoid confusion. [TRP]
:::For example, we shouldn't use a backslash '\' but we can.
::::*I'm not convinced. Legality isn't defined by what parses cleanly. There are specific reasons each of those characters is prohibited. Try using backslash in a name inside a count() inside a Formula and see if it works. If that does work, I'd have to go code hunting to figure out what the case is that prohibits backslash, but it's on that list for a reason. [TRP]
:::::*...You don't know why? OK< just to test your challenge, I tried making a feat and having something else count() that number of times I took that feat. Problem is, it won't even let me take the feat. Possible safeguard? - Fluxxdog
:::DEFINE:Spaced\Variable|0 BONUS:VAR|Spaced\Variable|3 DESC:Here's the value: %1|Spaced\Variable
:::...still spits out "''Here's the value: 3''"--[[User:Michael W. Fender|Fluxxdog]] 23:35, 4 April 2009 (CEST)
:::I'll double back a bit. If we go the route of using our "shouldn't use" characters, what options do we have?
::::(snip - please read [[Data LST Standards]])
::::* The issue here is that the items prohibited from names are the ONLY characters we can use without writing a converter. [TRP]
:::None of these should be used as they already have other functions already.
::::*This is where the problem lies.
:::::* Depends on your definition of problem, but the point I have is that we either make sacrifices from the ideal, or we delay the conversion to these tokens until we can reach the ideal, which may be years away. I'd rather make sacrifices, which means using the characters on the prohibited list or getting REALLY wide agreement and community input that we can break datasets. [TRP]
::::::*That's my point. Who uses a backslash in their data sets? And the backslash isn't used anywhere else in LST files already. I'd say it's the ideal nominee for such an operation. - Fluxxdog
:::*Backslashes (\)
:::Curious thought, does anything actually use this? I don't think I've seen anything other than file names, which aren't used in LST files.
::::CHOOSE:TEMPLATE|Extra Weaponry\OR\Extra Appendage\OR\Extra Flavor\OR\Candle Power\OR\Super Eyesight
:::Unless a backslash is already being used, that doesn't look too bad itself. And it's highly unlikely, even more so than < and >, that it's used in LST files for even homebrews. It certainly isn't in our LST files now.--[[User:Michael W. Fender|Fluxxdog]] 02:32, 5 April 2009 (CEST)

* [nuance] I think the lower case version stands out better.

:* I'll definitely agree with nuance on using lowercase for 'and' and 'or'. Makes it so much more obvious.--[[User:Michael W. Fender|Fluxxdog]] 01:08, 2 April 2009 (CEST)

::* I happen to prefer the uppercase versions. - thpr 
:::One needs to consider also that these will often be used with Primitive objects, e.g.: 
:::CHOOSE:TEMPLATE|Extra Weaponry<or>Extra Appendage<or>Extra Flavor<or>Candle Power<or>Super Eyesight 
:::CHOOSE:TEMPLATE|Extra Weaponry<OR>Extra Appendage<OR>Extra Flavor<OR>Candle Power<OR>Super Eyesight 
:::... so I feel that the upper case keyword is far more consistent with our tokens (where the keywords like TEMPLATE, TYPE, etc. are all upper case) and also stand out more.
:::*How dare you use logic! ^^ But yeah, when you put it that way, we should stick to the standard of using CAPS for hardcoded words.--[[User:Michael W. Fender|Fluxxdog]] 23:35, 4 April 2009 (CEST)

*Just a tad bit of a summation here: If we use a character to denote the logical operators, the backslash '\' would seem the ideal choice as it's already restricted from being used in key names, so \AND\ and \OR\? Unless I'm misunderstanding you, Tom, out of the "don't use" list, this is the only one that's both
::A) not in use for some other purpose
::B) not in use for data sets
:If I'm wrong, please say so.--[[User:Michael W. Fender|Fluxxdog]] 16:26, 5 April 2009 (CEST)
::* If the path is to follow the spelled-out separators, then of the reserved characters (,|\:.[]%*=), .[]%= are already in the syntax and can't be used due to parsing problems. : is our main token/value separator, and I'd really like to avoid that (though we can use it if necessary). That leaves ,|\* of which only | is used elsewhere in the token (as a separator). ,*\ all remain unused in the context of CHOOSE. , is used elsewhere, but if we convert the other tokens, it would otherwise be unused. [TRP]
:::*Here's what I'm getting at: Backslash is not used anywhere else. I've searched all the LST files in the data sets we publish (and just to be sure, I checked the alpha sets too) and nothing uses it. I don't even recall coming across a token that does use it. I'd rather leave the comma free, just in case and to avoid any confusion, and using a mathematical operator '*' just seems to ask for trouble somewhere.
:::If we go this route, is there any reason not to use the backslash for this? I.E. \AND\ \OR\ --[[User:Michael W. Fender|Fluxxdog]] 01:14, 6 April 2009 (CEST)
::::* From a programming perspective, \AND\ is just as easy as a comma. However, just to be clear, this process is to gather opinions, and we are missing some key players so far. If the backslash is considered unclear, then that will be a major reason for it not to be used, and it will not be used. You seem to have a strong opinion about this, but you need to give other people a chance to express their opinion as well. Just because it is not used elsewhere, doesn't mean it is inevitable under this option. [TRP]
:::::*Heh, not trying to dominate here, but yeah, I think this is the better way. I dislike option 1 and 2 as symbolism in a LST file is pretty aggravating on its own. (I'm pretty familiar with wild cards, so using '%' wasn't a big leap for me.) Using the words AND and OR would make it so much clearer. I dislike option 4 because it would require us to train people how to use such non-standard characters. Option 3 seems to be dependent on which character(s) we use to mark the logical operators, so I'd like to narrow it down to a best choice to get behind.
::::::In the end, I won't be the one to make the final call. But when that call is made, I'll have contributed something to the process, which is why I've joined with the team in the first place.
::::::And the rest of you just watching form the side lines, chime in! Tom's right, 3 people can't haggle about this by themselves! :p --[[User:Michael W. Fender|Fluxxdog]] 02:26, 6 April 2009 (CEST)

* [[User:Nuance|nuance]] Backslashes—I hate this option. It's hard to say how much I hate it.

* [[User:Nuance|nuance]] Can I point out I'm also convinced we shouldn't use / or - in things like class names. is CL=Funky-Gibbon asking for how many levels in class "Funky-Gibbon" or is it asking for how many levels in class "Funky" less the variable "Gibbon". If I defined the variable Gibbon would it change the answer, what if I has class Funky and Variable Gibbon already defined and then defined class Funky-Gibbon? Same argument with / what does CL=Funky/Gibbon mean?

Insert comments on option #3 here.

==Option #4, Leverage Unicode to use other separators, e.g. «OR» as an OR separator, Using «AND» as an AND separator==

Examples use lowercase

===Using Primitives===

CHOOSE:TEMPLATE|Template1«or»Template2

...allows a choice of Template1 or Template2

CHOOSE:TEMPLATE|TYPE=Foo«or»!TYPE=Bar

...allows a choice of any Template that is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|TYPE=Foo«and»!TYPE=Bar

...allows a choice of any Template that is both TYPE=Foo and not TYPE=Bar

===Using Single a Qualifier===

CHOOSE:TEMPLATE|PC[TYPE=Foo«or»!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo«and»!TYPE=Bar]

...allows a choice of any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar

CHOOSE:TEMPLATE|PC[TYPE=Foo«and»!TYPE=Bar«or»TYPE=Goo]

...allows a choice of any Template that the character already has, where the Template is (a) both TYPE=Foo and not TYPE=Bar OR (b) TYPE=Goo

===Using Multiple Qualifiers===

CHOOSE:TEMPLATE|PC[TYPE=Foo«or»!TYPE=Bar]«or»QUALIFIED[TYPE=Goo]

...allows a choice of
(a) Any Template that the character already has, where the Template is either TYPE=Foo or not TYPE=Bar
OR
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo«and»!TYPE=Bar]«and»QUALIFIED[TYPE=Goo]

...allows a choice of:
(a) Any Template that the character already has, where the Template is both TYPE=Foo and not TYPE=Bar
AND
(b) Any Template the PC is qualified to take that is TYPE=Goo

CHOOSE:TEMPLATE|PC[TYPE=Foo«and»!TYPE=Bar«or»TYPE=Goo]«or»QUALIFIED«and»!PC

...allows a choice of:
(a) Any Template that the character already has, where the Template is (a1) both TYPE=Foo and not TYPE=Bar OR (a2) TYPE=Goo
OR
(b) Any Template that the PC is qualified to take, but has not yet taken.

===Discussion===

* [nuance] LST files are UTF8, so theoretically we can use any unicode character. The problem with that is editor support—which it has to be said is getting better all the time. Since full unicde may be a bit of a shock , iso-8859-1 (latin 1) has « and » (alt0171 and alt0187 respectively). It also has ¿ (alt0191) which ties up nicely with ? if was want to wrap words.

:Of course, fully in the realm of unicode madness, we could always use ∧ for and, and ∨ for or, but the data folk might shoot us :-). Actually we could consider ^ to mean and, paired with |

::CHOOSE:TEMPLATE|PC[TYPE=Foo^!TYPE=Bar|TYPE=Goo]|QUALIFIED^!PC

::...allows a choice of:
::(a) Any Template that the character already has, where the Template is (a1) both TYPE=Foo and not TYPE=Bar OR (a2) TYPE=Goo
::OR
::(b) Any Template that the PC is qualified to take, but has not yet taken.

:I think I prefer the last one, but I don't like the way | looks against ]. On this wiki ! is hard to distinguish from |, ¬ (shift ` on my keyboard) actually means not. I think using « and » in place of [ and ], and ¬ for not

::CHOOSE:TEMPLATE|PC«TYPE=Foo^¬TYPE=Bar|TYPE=Goo»|QUALIFIED^¬PC

:is easier to read but that might be a bit radical. Perhaps it's time we has that full reserved characters discussion.
:*Very true since we don't seem to have a full list (see above in option 3 about standards vs. actually allowed)--[[User:Michael W. Fender|Fluxxdog]] 23:58, 4 April 2009 (CEST)

*I'd like to move away from symbolism for words and actually use the words themselves. It makes it a lot easier for new people to read.--[[User:Michael W. Fender|Fluxxdog]] 01:08, 2 April 2009 (CEST)

*Using '«' and '»' is a good idea, but how exactly do you type that in? I think we should stick closer to what's available on the common keyboards without having to dig through a font list. Although, that gives me an idea... What about a character combinations?

:* [[User:Nuance|nuance]] Sorry if it was a bit opaque, but I gave instructions for how to type it (on a windows machine at least). Press and hold the "alt" key to the left of your space bar. Now, using the numeric keypad, type the numbers 0171, realease the "alt" key. Et viola «. » is similarly produced with the numbers 0187. Once you have one of them cut and paste is also an option. Since we aren't fully in the unicode realm here, most OSes have some way to type characters in the ios-8859-1 range.
::*I'm not saying it's a bad idea, I'm saying it's not a good idea. People will have to look into some kind of "tips and tricks" for their keyboard AND OS AND language AND font, since not every combination will work like that. Heck, tested it on 3 different programs on my system and it doesn't work at all. I think this is definitely a case of "the simpler the better".--[[User:Michael W. Fender|Fluxxdog]] 23:58, 4 April 2009 (CEST)

::: [http://en.wikipedia.org/wiki/Guillemets#Typing_.22.C2.AB.22_and_.22.C2.BB.22_on_computers| Typing the Guilemets « »]
:::*We'd have to include that link everytime «AND» or «OR» is included or put the information in the docs just to ensure everyone has that info when coding LST files. I'd say, at the very least, let's stick with characters that can't or shouldn't be used in Key names.--[[User:Michael W. Fender|Fluxxdog]] 02:19, 5 April 2009 (CEST)

::::[[User:Nuance|nuance]] I disagree, we would need to include the info in our Docs, but that's it. People already need to read the docs to code in LST. We have mailing lists where people can ask questions. I think « and » are infinitely better than \ in this context. \and\ is horrendously ugly and IMO hard to read. Point is « and » are easy to type on the vast majority of keyboards/OSes. Most poeple who can't figure out how to do something in lst ask or look at the distributed sets. If they're looking at distributed data then—at the very least—they can cut and paste «AND» and «OR» into their own code.

:Hey coders! Could we do something along the lines of <<and>>? Using 2 '<' to signify a logical operator? Surely that must make things easier. -[[User:Michael W. Fender|Fluxxdog]] 01:08, 2 April 2009 (CEST)

:* Really doesn't make a huge difference. The < and > still aren't identified as reserved characters. It reduces the risk slightly, but it's probably small with <AND> and <OR> anyway. - thpr

Insert comments on option #4 here.

Separator Characters

2009-04-04T23:58:32Z

Nuance:

Separator Characters

2009-04-04T21:36:56Z

Nuance:

Separator Characters

2009-04-01T18:18:39Z

Nuance:

CDOM References Concept Document

2009-04-01T17:16:26Z

Nuance:

{| align="right"
| __TOC__
|}

==Overview==

CDOM References are effectively pointers to CDOM Objects. A Single reference directly refers to a single object (something like referring to the Feat Dodge), and it follows very closely the pointer analogy. Group references, which can be refer to multiple objects (something like TYPE=Foo) effectively serve as a pointer to a group of one or more objects.

CDOM References are created and are aware of their underlying contents during the load of PCC/LST files, and with some minor exceptions, are not dynamic (meaning they do not change at runtime).

CDOM Reference objects can be found in the pcgen.cdom.reference package.

==Types of References==

===Simple References===

Simple References are references that refer to non-categorized objects. This includes most CDOM Objects within PCGen; the major exception is Ability objects, which are Categorized. A Simple Reference cannot refer to a Categorized CDOM Object.

===Categorized References===

Categorized References are references that refer to categorized objects. This includes Ability objects. A Categorized CDOM Object cannot refer to a Simple CDOM Object.

===Single References===

Simple references refer to a single object. These can be resolved during runtime to return the underlying CDOM Object.

===Group References===

Group referenfes refer to one or more objects. These can share various characteristics, such as a TYPE, or be universal for a given type of object by using the ANY reference. In limited cases, pattern matching references are also available.

===Transparent References===

Game Mode and PCC files are loaded when PCGen is launched. When these files refer to objects that would be loaded with future data, a Transparent Reference is created. These are special references that can be loaded multiple times (vs. other References that cannot be loaded more than once).

===Direct References===

References are used in multiple ways:

# A Reference can be used directly: References can be stored in ListKey or ObjectKey locations within a CDOM Object.
# A Reference can be used as an index: i.e. referring to a list of objects, such as the reference constructed from the CLASSES token in the Spell LST file referring to ClassSpellLists.

However, there is one infrastructure to support lists, and those lists may be either static or unconstructed at LST load. The static references are known lists, yet in order to share infrastructure with unknown lists, even the known lists have to be wrapped in a CDOM Reference. For this reason, there is the ability to create Direct References. These CDOM References do not require resolution, as they are passed the single CDOM Object they will contain at the time the Direct Reference is constructed.

==Lifecycle of a Reference==

# Transparent Reference Creation: Game Mode and PCC files are loaded when PCGen is launched. When these files refer to objects that would be loaded with future data, a Transparent Reference is created. References are constructed by a Game Mode-based LoadContext, so that multiple references to an object of the same Class and Key will use the same Reference.
# Reference Creation: When LST files are loaded, and CDOM Objects are referred to in the data, a CDOM Reference is created. References are constructed by the LoadContext, so that multiple references to an object of the same Class and Key will use the same Reference.
# Disposal on FORGET: LST files allow certain objects to be "forgotten", meaning they are disposed of from the loaded data, and cannot be used at runtime. However, given that the LST load process is single-pass, the FORGET is encountered well after References have been created for objects that were referred to by the forgotten object. Since the object is not loaded, it is appropriate to ignore any of those references, so the Token/Loader system includes a mechanism to dispose of those CDOM References when a FORGET is encountered.
# Loading of References (Runtime): If the LST load occurred in support of runtime processing of characters, loading is performed. This is not done if the LST load was performed in support of the editor system (not yet performed in PCGen 5.16). Once load of the data is complete, References are resolved. For Single References, this involves loading the Reference with the object it refers to. For deterministic Group References, this also involves loading with References. Some Group References are processed dynamically, meaning their contents are determined at runtime.
# Resolution (Runtime): If the LST load occurred in support of runtime processing of characters, loading is performed. This is not done if the LST load was performed in support of the editor system (not yet performed in PCGen 5.16). When a PlayerCharacter is being processed, the various CDOM References are resolved to determine the objects underlying the CDOM Reference.
# Write: Objects may be written back to an LST file from a CDOM References, and each CDOMReference has a getLSTformat() method that provides the unique method of identifying the reference that can be stored in a persistent state (in an LST file).

==The Origin of References==

===Background Concepts===

Keys: Objects (such as Races, Languages, etc.) which are loaded from LST files need to have a unique identifier so that relationships between objects can be created without ambiguity.

Category: In addition to a Key, Ability objects also have another part of their unique identifier, called a Category. This is usage #1 of Ability Categories, see the [[Ability Category]] explanation.

===The Challenge===

When data is loaded from PCC/LST files, there is an order of operations challenge. (For any developers, this is similar to challenges that a compiler faces when compiling source code).

Specifically:

# Objects can reference each other (e.g. a Race settings available starting Languages). This is a challenge because circular references are likely (such as a restriction on the language to limit it to the particular Race that allows it as a starting Language)
# Objects can use KEY and CATEGORY anywhere on a given line. This creates an (intra-line) indexing challenge that exacerbates the circular reference problem and increases the difficulty of resolving that issue.

Additionally, since the purpose with the transition to the CDOM design is to support an integrated LST Editor that shares a load framework with the runtime environment

# CDOM References must support a round-robin to LST files. This means that group references (e.g. TYPE=Foo) must know the reference name and not universally expand to their contained components (yet must be able to return the contained components at runtime).
# Sorting of CDOMReferences must be deterministic (PCGen 5.16 solves this by alphabetizing the lists of CDOMReferences in the tokens)

===The Solution in PCGen 5.16===

In order to keep the data structured in a way that keeps information stored in a location close to where it is addressed in the rules, addressing the order of operations challenges is a code issue, not a data structure issue.

In PCGen 5.14 and earlier, this problem was solved by storing information within PCGen as Strings, and then resolving those Strings against unique identifiers for each object (generally the Key). This led to a number of issues, including performance issues due to String parsing, as well as failure to catch some errors until runtime.

There are various potential solutions to such problems, and some of these are covered in [[Rebuild of the Token/Loader System]]. These were addressed in PCGen with the integration of a new Token/Loader system during the PCGen 5.16 cycle. While there are solutions that would drive a two-pass parse of the data, the solution implemented in PCGen 5.16 limits the load of data to a single pass on the LST files. Thus PCGen uses a series of references to allow the data at LST load to refer to objects which have not been encountered within the data. After the load is complete, the references are resolved to their underlying objects.

===Benefits of the defined solution===

# Duplicate keys are detected at load, regardless of their source file, thus no references should be ambiguous
# Empty Group references can flag a warning if they do not contain any contents. This serves as LST error checking to catch accidental typos in a group identifier
# Since References can be constructed well before they are resolved, references allow Game Mode information to be loaded once, thus preventing re-parsing of those files when a different set of sources is loaded.

===Characteristics/Weaknesses of the defined solution===

This section refers to PCGen 5.16

# Currently, the LoadContext system uses WeakReferences to control the Disposal of CDOM Reference objects when FORGET is encountered. In theory this does not guarantee that irrelevant CDOM Reference objects do not produce load errors due to missing information. In practice, this error is unlikely to be encountered. However, an ideal structure would design around this problem. This issue is partially a function of the method of storage used in PCGen 5.16 (the Graph structure envisioned for CDOM is not in place), and partially a function of using a one-pass load. There are multiple solutions to this problem, but since it's mostly a theoretical issue, it is not being addressed as a critical issue.
# Currently, BONUS, CHOOSE, and the PRExxx tokens have not been converted to the new Token/Loader system and do not yet provide all of the benefits outlined above. A CHOOSE rebuild has been proposed as part of the PCGen 5.17 cycle (which leads to the next stable release, either 5.18 or 6.0).
# Currently CDOM References are classes and are not provided into CDOM Objects as an Interface. In order to reduce potential for corruption of CDOMReferences, the single references are controlled to allow them to only be resolved once. This is done without providing a method for resetting a CDOM Reference. This is done to provide a strict mechanism to prevent errors and abuse of the CDOM Reference objects during runtime (this can be thought of as a short-term overly strict system to train developers and force separation between load and runtime). Once we have a more stable and modular core in place, this strict mechanism may be relaxed and/or exchanged for interfaces. Currently, this strict mechanism makes Game Mode references slightly more complex than other references.
# Some References are resolved at runtime. Theoretically, this is a performance issue, but practically, the dynamic references are rare enough that this is not an issue. The core of PCGen has much larger performance issues that should be addressed first before this is addressed as a performance issue. It may turn out to be unnecessary optimization, so addressing this weakness is currently not scheduled for any release.
# Resolution may be an issue. This is mostly a theoretical issue at this point, but the dereferencing driven by the use of CDOM Reference objects is slightly slower than direct objects. This is considered a minor performance issue, and unless demonstrated as a performance issue, will not be addressed. There are some concerns about references in relation to lists (such as adding Spells to a ClassSpellList) and the complexity required to access the underlying information. While this is a recognized issue, this pain point will be addressed in a near-future release as the PlayerCharacter data structure is changed to a Graph-based structure.

CDOM References Concept Document

2009-04-01T17:12:03Z

Nuance:

{| align="right"
| __TOC__
|}

==Overview==

CDOM References are effectively pointers to CDOM Objects. A Single reference directly refers to a single object (something like referring to the Feat Dodge), and it follows very closely the pointer analogy. Group references, which can be refer to multiple objects (something like TYPE=Foo) effectively serve as a pointer to a group of one or more objects.

CDOM References are created and are aware of their underlying contents during the load of PCC/LST files, and with some minor exceptions, are not dynamic (meaning they do not change at runtime).

CDOM Reference objects can be found in the pcgen.cdom.reference package.

==Types of References==

===Simple References===

Simple References are references that refer to non-categorized objects. This includes most CDOM Objects within PCGen; the major exception is Ability objects, which are Categorized. A Simple Reference cannot refer to a Categorized CDOM Object.

===Categorized References===

Categorized References are references that refer to categorized objects. This includes Ability objects. A Categorized CDOM Object cannot refer to a Simple CDOM Object.

===Single References===

Simple references refer to a single object. These can be resolved during runtime to return the underlying CDOM Object.

===Group References===

Group referenfes refer to one or more objects. These can share various characteristics, such as a TYPE, or be universal for a given type of object by using the ANY reference. In limited cases, pattern matching references are also available.

===Transparent References===

Game Mode and PCC files are loaded when PCGen is launched. When these files refer to objects that would be loaded with future data, a Transparent Reference is created. These are special references that can be loaded multiple times (vs. other References that cannot be loaded more than once).

===Direct References===

References are used in multiple ways:

# A Reference can be used directly: References can be stored in ListKey or ObjectKey locations within a CDOM Object.
# A Reference can be used as an index: i.e. referring to a list of objects, such as the reference constructed from the CLASSES token in the Spell LST file referring to ClassSpellLists.

However, there is one infrastructure to support lists, and those lists may be either static or unconstructed at LST load. The static references are known lists, yet in order to share infrastructure with unknown lists, even the known lists have to be wrapped in a CDOM Reference. For this reason, there is the ability to create Direct References. These CDOM References do not require resolution, as they are passed the single CDOM Object they will contain at the time the Direct Reference is constructed.

==Lifecycle of a Reference==

# Transparent Reference Creation: Game Mode and PCC files are loaded when PCGen is launched. When these files refer to objects that would be loaded with future data, a Transparent Reference is created. References are constructed by a Game Mode-based LoadContext, so that multiple references to an object of the same Class and Key will use the same Reference.
# Reference Creation: When LST files are loaded, and CDOM Objects are referred to in the data, a CDOM Reference is created. References are constructed by the LoadContext, so that multiple references to an object of the same Class and Key will use the same Reference.
# Disposal on FORGET: LST files allow certain objects to be "forgotten", meaning they are disposed of from the loaded data, and cannot be used at runtime. However, given that the LST load process is single-pass, the FORGET is encountered well after References have been created for objects that were referred to by the forgotten object. Since the object is not loaded, it is appropriate to ignore any of those references, so the Token/Loader system includes a mechanism to dispose of those CDOM References when a FORGET is encountered.
# Loading of References (Runtime): If the LST load occurred in support of runtime processing of characters, loading is performed. This is not done if the LST load was performed in support of the editor system (not yet performed in PCGen 5.16). Once load of the data is complete, References are resolved. For Single References, this involves loading the Reference with the object it refers to. For deterministic Group References, this also involves loading with References. Some Group References are processed dynamically, meaning their contents are determined at runtime.
# Resolution (Runtime): If the LST load occurred in support of runtime processing of characters, loading is performed. This is not done if the LST load was performed in support of the editor system (not yet performed in PCGen 5.16). When a PlayerCharacter is being processed, the various CDOM References are resolved to determine the objects underlying the CDOM Reference.
# Write: Objects may be written back to an LST file from a CDOM References, and each CDOMReference has a getLSTformat() method that provides the unique method of identifying the reference that can be stored in a persistent state (in an LST file).

==The Origin of References==

===Background Concepts===

Keys: Objects (such as Races, Languages, etc.) which are loaded from LST files need to have a unique identifier so that relationships between objects can be created without ambiguity.

Category: In addition to a Key, Ability objects also have another part of their unique identifier, called a Category. This is usage #1 of Ability Categories, see the [[Ability Category]] explanation.

===The Challenge===

When data is loaded from PCC/LST files, there is an order of operations challenge. (For any developers, this is similar to challenges that a compiler faces when compiling source code).

Specifically:

# Objects can reference each other (e.g. a Race settings available starting Languages). This is a challenge because circular references are likely (such as a restriction on the language to limit it to the particular Race that allows it as a starting Language)
# Objects can use KEY and CATEGORY anywhere on a given line. This creates an (intra-line) indexing challenge that exacerbates the circular reference problem and increases the difficulty of resolving that issue.

Additionally, since the purpose with the transition to the CDOM design is to support an integrated LST Editor that shares a load framework with the runtime environment

# CDOM References must support a round-robin to LST files. This means that group references (e.g. TYPE=Foo) must know the reference name and not universally expand to their contained components (yet must be able to return the contained components at runtime).
# Sorting of CDOMReferences must be deterministic (PCGen 5.16 solves this by alphabetizing the lists of CDOMReferences in the tokens)

===The Solution in PCGen 5.16===

In order to keep the data structured in a way that keeps information stored in a location close to where it is addressed in the rules, addressing the order of operations challenges is a code issue, not a data structure issue.

In PCGen 5.14 and earlier, this problem was solved by storing information within PCGen as Strings, and then resolving those Strings against unique identifiers for each object (generally the Key). This led to a number of issues, including performance issues due to String parsing, as well as failure to catch some errors until runtime.

There are various potential solutions to such problems, and some of these are covered in [[Rebuild of the Token/Loader System]]. These were addressed in PCGen with the integration of a new Token/Loader system during the PCGen 5.16 cycle. While there are solutions that would drive a two-pass parse of the data, the solution implemented in PCGen 5.16 limits the load of data to a single pass on the LST files. Thus PCGen uses a series of references to allow the data at LST load to refer to objects which have not been encountered within the data. After the load is complete, the references are resolved to their underlying objects.

===Benefits of the defined solution===

# Duplicate keys are detected at load, regardless of their source file, thus no references should be ambiguous
# Empty Group references can flag a warning if they do not contain any contents. This serves as LST error checking to catch accidental typos in a group identifier
# Since References can be constructed well before they are resolved, references allow Game Mode information to be loaded once, thus preventing re-parsing of those files when a different set of sources is loaded.

===Characteristics/Weaknesses of the defined solution===

This section refers to PCGen 5.16

# Currently, the LoadContext system uses WeakReferences to control the Disposal of CDOM Reference objects when FORGET is encountered. In theory this does not guarantee that irrelevant CDOM Reference objects do not produce load errors due to missing information. In practice, this error is unlikely to be encountered. However, an ideal structure would design around this problem. This issue is partially a function of the method of storage used in PCGen 5.16 (the Graph structure envisioned for CDOM is not in place), and partially a function of using a one-pass load. There are multiple solutions to this problem, but since it's mostly a theoretical issue, it is not being addressed as a critical issue.
# Currently, BONUS, CHOOSE, and the PRExxx tokens have not been converted to the new Token/Loader system and do not yet provide all of the benefits outlined above. A CHOOSE rebuild has been proposed as part of the PCGen 5.17 cycle (which leads to the next stable release, either 5.18 or 6.0).
# Currently CDOM References are classes and are not provided into CDOM Objects as an Interface. In order to reduce potential for corruption of CDOMReferences, the single references are controlled to allow them to only be resolved once. This is done without providing a method for resetting a CDOM Reference. This is done to provide a strict mechanism to prevent errors and abuse of the CDOM Reference objects during runtime (this can be thought of as a short-term overly strict system to train developers and force separation between load and runtime). Once we have a more stable and modular core in place, this strict mechanism may be relaxed and/or exchanged for interfaces. Currently, this strict mechanism makes Game Mode references slightly more complex than other references.
# Some References are resolved at runtime. Theoretically, this is a performance issue, but practically, the dynamic references are rare enough that this is not an issue. The core of PCGen has much larger performance issues that should be addressed first before this is addressed as a performance issue. It may turn out to be unnecessary optimization, so addressing this weakness is currently not scheduled for any release.
# Resolution may be an issue. This mostly a theoretical issue at this point, but the dereferencing driven by the use of CDOM Reference objects is slightly slower than direct objects. This is considered a minor performance issue, and unless demonstrated as a performance issue, will not be addressed. There are some concerns about references in relation to lists (such as adding Spells to a ClassSpellList) and the complexity required to access the underlying information. While this is a recognized issue, this pain point will be addressed in a near-future release as the PlayerCharacter data structure is changed to a Graph-based structure.

CDOM References Concept Document

2009-04-01T16:38:11Z

Nuance:

{| align="right"
| __TOC__
|}

==Overview==

CDOM References are effectively pointers to CDOM Objects. A Single reference directly refers to a single object (something like referring to the Feat Dodge), and it follows very closely the pointer analogy. Group references, which can be refer to multiple objects (something like TYPE=Foo) effectively serve as a pointer to a group of one or more objects.

CDOM References are created and are aware of their underlying contents during the load of PCC/LST files, and with some minor exceptions, are not dynamic (meaning they do not change at runtime).

CDOM Reference objects can be found in the pcgen.cdom.reference package.

==Types of References==

===Simple References===

Simple References are references that refer to non-categorized objects. This includes most CDOM Objects within PCGen; the major exception is Ability objects, which are Categorized. A Simple Reference cannot refer to a Categorized CDOM Object.

===Categorized References===

Categorized References are references that refer to categorized objects. This includes Ability objects. A Categorized CDOM Object cannot refer to a Simple CDOM Object.

===Single References===

Simple references refer to a single object. These can be resolved during runtime to return the underlying CDOM Object.

===Group References===

Group referenfes refer to one or more objects. These can share various characteristics, such as a TYPE, or be universal for a given type of object by using the ANY reference. In limited cases, pattern matching references are also available.

===Transparent References===

Game Mode and PCC files are loaded when PCGen is launched. When these files refer to objects that would be loaded with future data, a Transparent Reference is created. These are special references that can be loaded multiple times (vs. other References that cannot be loaded more than once).

===Direct References===

References are used in multiple ways:

# Reference can be directly used: References can be stored in ListKey or ObjectKey locations within a CDOM Object.
# References are used as an index: This is referring to a list of objects, such as the CLASSES token in the Spell LST file referring to ClassSpellLists.

However, there is one infrastructure to support lists, and those lists may be either static or unconstructed at LST load. The static references are known lists, yet in order to share infrastructure with unknown lists, even the known lists have to be wrapped in a CDOM Reference. For this reason, there is the ability to create Direct References. These CDOM References do not require resolution, as they are passed the single CDOM Object they will contain at the time the Direct Reference is constructed.

==Lifecycle of a Reference==

# Transparent Reference Creation: Game Mode and PCC files are loaded when PCGen is launched. When these files refer to objects that would be loaded with future data, a Transparent Reference is created. References are constructed by a Game Mode-based LoadContext, so that multiple references to an object of the same Class and Key will use the same Reference.
# Reference Creation: When LST files are loaded, and CDOM Objects are referred to in the data, a CDOM Reference is created. References are constructed by the LoadContext, so that multiple references to an object of the same Class and Key will use the same Reference.
# Disposal on FORGET: LST files allow certain objects to be "forgotten", meaning they are disposed of from the loaded data, and cannot be used at runtime. However, given that the LST load process is single-pass, the FORGET is encountered well after References have been created for objects that were referred to by the forgotten object. Since the object is not loaded, it is appropriate to ignore any of those references, so the Token/Loader system includes a mechanism to dispose of those CDOM References when a FORGET is encountered.
# Loading of References (Runtime): If the LST load occurred in support of runtime processing of characters, loading is performed. This is not done if the LST load was performed in support of the editor system (not yet performed in PCGen 5.16). Once load of the data is complete, References are resolved. For Single References, this involves loading the Reference with the object it refers to. For deterministic Group References, this also involves loading with References. Some Group References are processed dynamically, meaning their contents are determined at runtime.
# Resolution (Runtime): If the LST load occurred in support of runtime processing of characters, loading is performed. This is not done if the LST load was performed in support of the editor system (not yet performed in PCGen 5.16). When a PlayerCharacter is being processed, the various CDOM References are resolved to determine the objects underlying the CDOM Reference.
# Write: Objects may be written back to an LST file from a CDOM References, and each CDOMReference has a getLSTformat() method that provides the unique method of identifying the reference that can be stored in a persistent state (in an LST file).

==The Origin of References==

===Background Concepts===

Keys: Objects (such as Races, Languages, etc.) which are loaded from LST files need to have a unique identifier so that relationships between objects can be created without ambiguity.

Category: In addition to a Key, Ability objects also have another part of their unique identifier, called a Category. This is usage #1 of Ability Categories, see the [[Ability Category]] explanation.

===The Challenge===

When data is loaded from PCC/LST files, there is an order of operations challenge. (For any developers, this is similar to challenges that a compiler faces when compiling source code).

Specifically:

# Objects can reference each other (e.g. a Race settings available starting Languages). This is a challenge because circular references are likely (such as a restriction on the language to limit it to the particular Race that allows it as a starting Language)
# Objects can use KEY and CATEGORY anywhere on a given line. This creates an (intra-line) indexing challenge that exacerbates the circular reference problem and increases the difficulty of resolving that issue.

Additionally, since the purpose with the transition to the CDOM design is to support an integrated LST Editor that shares a load framework with the runtime environment

# CDOM References must support a round-robin to LST files. This means that group references (e.g. TYPE=Foo) must know the reference name and not universally expand to their contained components (yet must be able to return the contained components at runtime).
# Sorting of CDOMReferences must be deterministic (PCGen 5.16 solves this by alphabetizing the lists of CDOMReferences in the tokens)

===The Solution in PCGen 5.16===

In order to keep the data structured in a way that keeps information stored in a location close to where it is addressed in the rules, addressing the order of operations challenges is a code issue, not a data structure issue.

In PCGen 5.14 and earlier, this problem was solved by storing information within PCGen as Strings, and then resolving those Strings against unique identifiers for each object (generally the Key). This led to a number of issues, including performance issues due to String parsing, as well as failure to catch some errors until runtime.

There are various potential solutions to such problems, and some of these are covered in [[Rebuild of the Token/Loader System]]. These were addressed in PCGen with the integration of a new Token/Loader system during the PCGen 5.16 cycle. While there are solutions that would drive a two-pass parse of the data, the solution implemented in PCGen 5.16 limits the load of data to a single pass on the LST files. Thus PCGen uses a series of references to allow the data at LST load to refer to objects which have not been encountered within the data. After the load is complete, the references are resolved to their underlying objects.

===Benefits of the defined solution===

# Duplicate keys are detected at load, regardless of their source file, thus no references should be ambiguous
# Empty Group references can flag a warning if they do not contain any contents. This serves as LST error checking to catch accidental typos in a group identifier
# Since References can be constructed well before they are resolved, references allow Game Mode information to be loaded once, thus preventing re-parsing of those files when a different set of sources is loaded.

===Characteristics/Weaknesses of the defined solution===

This section refers to PCGen 5.16

# Currently, the LoadContext system uses WeakReferences to control the Disposal of CDOM Reference objects when FORGET is encountered. In theory this does not guarantee that irrelevant CDOM Reference objects do not produce load errors due to missing information. In practice, this error is unlikely to be encountered. However, an ideal structure would design around this problem. This issue is partially a function of the method of storage used in PCGen 5.16 (the Graph structure envisioned for CDOM is not in place), and partially a function of using a one-pass load. There are multiple solutions to this problem, but since it's mostly a theoretical issue, it is not being addressed as a critical issue.
# Currently, BONUS, CHOOSE, and the PRExxx tokens have not been converted to the new Token/Loader system and do not yet provide all of the benefits outlined above. A CHOOSE rebuild has been proposed as part of the PCGen 5.17 cycle (which leads to the next stable release, either 5.18 or 6.0).
# Currently CDOM References are classes and are not provided into CDOM Objects as an Interface. In order to reduce potential for corruption of CDOMReferences, the single references are controlled to allow them to only be resolved once. This is done without providing a method for resetting a CDOM Reference. This is done to provide a strict mechanism to prevent errors and abuse of the CDOM Reference objects during runtime (this can be thought of as a short-term overly strict system to train developers and force separation between load and runtime). Once we have a more stable and modular core in place, this strict mechanism may be relaxed and/or exchanged for interfaces. Currently, this strict mechanism makes Game Mode references slightly more complex than other references.
# Some References are resolved at runtime. Theoretically, this is a performance issue, but practically, the dynamic references are rare enough that this is not an issue. The core of PCGen has much larger performance issues that should be addressed first before this is addressed as a performance issue. It may turn out to be unnecessary optimization, so addressing this weakness is currently not scheduled for any release.
# Resolution may be an issue. This mostly a theoretical issue at this point, but the dereferencing driven by the use of CDOM Reference objects is slightly slower than direct objects. This is considered a minor performance issue, and unless demonstrated as a performance issue, will not be addressed. There are some concerns about references in relation to lists (such as adding Spells to a ClassSpellList) and the complexity required to access the underlying information. While this is a recognized issue, this pain point will be addressed in a near-future release as the PlayerCharacter data structure is changed to a Graph-based structure.

Developers Meeting

2008-10-22T13:23:22Z

Nuance: /* Availability */

It would be good to get a meeting of the Code Monkeys going. Please fill in your available times below:

=Timezones=

{| border="1"
! Name !! Current Timezone !! Offset from GMT/UTC
|-
| [[Tom Parker]] || EDT || -4
|-
| [[James Dempsey]] || AEDT || +11
|-
| [[nuance]] || GMT (currently BST) || +0 (currentlt +1)
|}

=Availability=
{| border="1"
! Name !! Mon !! Tue !! Wed !! Thu !! Fri !! Sat !! Sun
|-
| [[James Dempsey]] || 6pm-11pm AEDT || 6pm-11pm AEDT|| 6pm-11pm AEDT|| 6pm-11pm AEDT||6pm-11pm AEDT || 7am-11pm AEDT|| 7am-4pm AEDT
|-
| [[James Dempsey]] || 12am-5am UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC 8pm-12am UTC || 12am-12pm UTC 8pm-12am UTC
|-
| [[Tom Parker]] || 12am-3am UTC 10pm-12am UTC || 12am-3am UTC ''10pm-12am UTC'' || ''12am-3am UTC'' || none || 1am-3am UTC 10pm-12am UTC || 12am-1am UTC ''1am-3am UTC'' 11am-2pm UTC ''2pm-9pm UTC'' 9pm-12am UTC || 12am-3am UTC 11am-3pm UTC ''3pm-7pm UTC'' 7pm-12am UTC
|-
| [[Andrew Wilson]] (nuance) || none || ''8pm–1am'' || none || none || 7pm-12am UTC || 12am-3am UTC 9am-12am UTC || 12am-3am UTC 1pm-12am UTC
|-
| Common Time (James + Tom) || 12am-3am UTC || none || none || none || none || 11am-12pm UTC ''8pm-9pm UTC'' 9pm-12am UTC || 12am-3am UTC 11am-12pm UTC 8pm-12am UTC
|}

PST is GMT -8 
MST is GMT -7 
EST is GMT -5

''italicized items'' are limited availability: means availability needs to be negotiated based on other periodic activities

[http://www.timeanddate.com/worldclock/meetingtime.html?year=2008&month=10&day=25&p1=57&p2=179&p3=37&p4=-1 Time comparison]

Developers Meeting

2008-10-22T12:56:32Z

Nuance: /* Availability */

It would be good to get a meeting of the Code Monkeys going. Please fill in your available times below:

=Timezones=

{| border="1"
! Name !! Current Timezone !! Offset from GMT/UTC
|-
| [[Tom Parker]] || EDT || -4
|-
| [[James Dempsey]] || AEDT || +11
|-
| [[nuance]] || GMT (currently BST) || +0 (currentlt +1)
|}

=Availability=
{| border="1"
! Name !! Mon !! Tue !! Wed !! Thu !! Fri !! Sat !! Sun
|-
| [[James Dempsey]] || 6pm-11pm AEDT || 6pm-11pm AEDT|| 6pm-11pm AEDT|| 6pm-11pm AEDT||6pm-11pm AEDT || 7am-11pm AEDT|| 7am-4pm AEDT
|-
| [[James Dempsey]] || 12am-5am UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC 8pm-12am UTC || 12am-12pm UTC 8pm-12am UTC
|-
| [[Tom Parker]] || 12am-3am UTC 10pm-12am UTC || 12am-3am UTC ''10pm-12am UTC'' || ''12am-3am UTC'' || none || 1am-3am UTC 10pm-12am UTC || 12am-1am UTC ''1am-3am UTC'' 11am-2pm UTC ''2pm-9pm UTC'' 9pm-12am UTC || 12am-3am UTC 11am-3pm UTC ''3pm-7pm UTC'' 7pm-12am UTC
|-
| [[nuance]] || none || ''8pm–1am'' || none || none || 7pm-12am UTC || 12am-3am UTC 9am-12am UTC || 12am-3am UTC 1pm-12am UTC
|-
| Common Time (James + Tom) || 12am-3am UTC || none || none || none || none || 11am-12pm UTC ''8pm-9pm UTC'' 9pm-12am UTC || 12am-3am UTC 11am-12pm UTC 8pm-12am UTC
|}

PST is GMT -8 
MST is GMT -7 
EST is GMT -5

''italicized items'' are limited availability: means availability needs to be negotiated based on other periodic activities

[http://www.timeanddate.com/worldclock/meetingtime.html?year=2008&month=10&day=25&p1=57&p2=179&p3=37&p4=-1 Time comparison]

Developers Meeting

2008-10-22T12:49:09Z

Nuance: /* Timezones */

It would be good to get a meeting of the Code Monkeys going. Please fill in your available times below:

=Timezones=

{| border="1"
! Name !! Current Timezone !! Offset from GMT/UTC
|-
| [[Tom Parker]] || EDT || -4
|-
| [[James Dempsey]] || AEDT || +11
|-
| [[nuance]] || GMT (currently BST) || +0 (currentlt +1)
|}

=Availability=
{| border="1"
! Name !! Mon !! Tue !! Wed !! Thu !! Fri !! Sat !! Sun
|-
| [[James Dempsey]] || 6pm-11pm AEDT || 6pm-11pm AEDT|| 6pm-11pm AEDT|| 6pm-11pm AEDT||6pm-11pm AEDT || 7am-11pm AEDT|| 7am-4pm AEDT
|-
| [[James Dempsey]] || 12am-5am UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC || 7am-12pm UTC 8pm-12am UTC || 12am-12pm UTC 8pm-12am UTC
|-
| [[Tom Parker]] || 12am-3am UTC 10pm-12am UTC || 12am-3am UTC ''10pm-12am UTC'' || ''12am-3am UTC'' || none || 1am-3am UTC 10pm-12am UTC || 12am-1am UTC ''1am-3am UTC'' 11am-2pm UTC ''2pm-9pm UTC'' 9pm-12am UTC || 12am-3am UTC 11am-3pm UTC ''3pm-7pm UTC'' 7pm-12am UTC
|-
| Common Time (James + Tom) || 12am-3am UTC || none || none || none || none || 11am-12pm UTC ''8pm-9pm UTC'' 9pm-12am UTC || 12am-3am UTC 11am-12pm UTC 8pm-12am UTC
|}

PST is GMT -8 
MST is GMT -7 
EST is GMT -5

''italicized items'' are limited availability: means availability needs to be negotiated based on other periodic activities

[http://www.timeanddate.com/worldclock/meetingtime.html?year=2008&month=10&day=25&p1=57&p2=179&p3=37&p4=-1 Time comparison]

Building PCGen

2008-08-10T01:33:18Z

Nuance: /* Building PCGen from the command line */

{| align="right"
| __TOC__
|}
=Building PCGen from the command line=

This process uses the [[ANT]] tool, you need the following software packages:

* Java Development Kit (aka Java SDK or JDK). You should use the latest version (update) of the JDK 5.0 available for download from [http://java.sun.com/javase/downloads/index_jdk5.jsp here]. At the time of writing this was JDK 5.0 Update 15. Java 1.6 will also work, but no 1.6 specific features should be used in the code. Other JDKs might work, but no one has tried.
* Ant 1.7.0 (or later) from [http://jakarta.apache.org/ant/ here]. Ant is an all-Java replacement for make, and is fully cross-platform. Note: You will also need to download the jakarta-ant optional.jar file if using certain versions of Ant. See [[ANT]] section for further details
* If you wish to run the test suite you will need JUnit 3.6 from [http://www.junit.org/ here].
* You will also need the latest version of the PCGen source code available from SVN. See [[Subversion Setup]] for details.

Open a command window and change to the root directory/folder where you installed the PCGen source code. There should be a file called build.xml there.

Type ant clean at the command prompt. This will make sure you have a clean start. Then run ant. This will build the pcgen.jar file. The jar file will be in ./bin. You can run pcgendev.bat or pcgendev.sh to run it or manually copy the jar file to the PCGen root directory.

**NOTE**
* If you get a "Could not create task of type: javacc" you need to ensure you have the jakarta-ant optional.jar file in the $ANT_HOME/lib directory. (You only need this for older versions of Ant).
* If you get a "Could not create task of type: junit" you need to copy the junit.jar file from the pcgen/libs directory to the $ANT_HOME/lib directory. (You only need this for older versions of Ant).

To generate the JavaDocs use ant docs, and for deployments you can use ant deploy, and finally ant all does all of the above (clean, build, docs, deploy), and ant complete does everything including a full testing cycle (which can take a while).

Typing the command <pre>ant</pre> will build the code and run a small selection of tests.

Typing the command <pre>ant dotest</pre> will build the code and run the full test suite.

Typing the command <pre>ant reporttest</pre> after running the tests will generate a test report. The xml result files are generated while running the tests, they can be found in ./code/build/test-results/xml/ after making the reporttest target, a browsable set of html reports can be found in ./code/build/rpt/test-results/

=Using Eclipse to build PCGen=

You can build PCGen from within Eclipse. You will need to do a little bit of setup first though:
# Go to Window > Preferences, then Ant > Runtime then select Ant Home Entries under the Classpath tab.
# Click Add Jars. Select the junit.jar under pcgen/lib/test.
Now you should be able to select the build.xml, right click and hit Run > Ant Build and it should work.

==Running and debugging==

# Open the PCGen project.
# Open the Run dialog by right-clicking on the PCGen project and selecting Run > Run....
# Select the Java Application nide.
# Press the New button for a new configuration. Edit by field, thus:
Name -> PCGen

Main class -> pcgen.gui.pcGenGUI
# Press Apply to save the configuration.
# Press Run to start PCGen.

You can also run a single test by right clicking on the test and selecting Debug > JUnit Test. This is a great way to track through a bug too.

=Using IDEA to build PCGen=

You can build PCGen from within IDEA. You will need to do a little bit of setup first though:
# Go to the Window > Tool Windows > Ant Build. Press the [+] button to add a build file.
# Navigate to and select the build.xml Ant script in the root of the PCGen project tree. Press Ok.

You can now select any Ant target you wish. Particularly helpful are the build and fetch-data targets.

==Running and debugging==

NB - IDEA will build the software sufficient for running and debugging within the IDE automatically just by following these step. This is not the same as the build from the Building section, above, which builds the software suitable for command-line use.

# Open the PCGen.ipr project file.
# Get the Run/Debug Configurations dialog with Run > Edit Configurations from the menu bar.
# Select the Application tab.
# Press the [+] button for a new configuration. Edit by field, thus:
Name -> PCGen

Main class -> pcgen.gui.pcGenGUI
# Uncheck Display settings before running/debugging.
# Press Ok.

You can now run PCGen with the green right-pointing triangle on the toolbar and debug with the green right-facing beetle on a blue diamond. Or just use the Run menu.

=Using Maven to build PCGen=

See [[MAVEN]]