INFO & INFOVARS 6.08

INFO & INFOVARS

RAW

I wanted to start a development discussion on how we process items for output since we seem to have different methods... like other things it would be nice to get one powerful, consistent method.

As always for architecture items on _dev: - Only high level syntax discussion (it's usually none, but this one really does have a syntax impact) - Read for intent, this is not the time to nitpick token names - There is no schedule, and no plan to define one - Be specific with examples of where this wouldn't meet needs - with specific examples of objects/rules... no chasing phantoms.

Assumptions: - For any given identification of output, we only need one thing - The output is unconditional

Clarification of assumptions: "One thing" is akin to TargetArea on a spell today, which is 1 thing (the token overwrites if provided again).  This is different than the current "DESC" or "Components" on a spell which are "append", and thus can be multiple things.  These multiple items use .CLEAR/.CLEARALL to clear the list.  If multiple outputs with the same identification are required, I'd like to see the rules structure/output structure that requires such behavior.

Unconditional is relative... since this should be assumed to arrive after the new variable system, if the data/OS wants to gate output on a FLAG in the new variable system, more power to them... so a trailing PRExxx is unnecessary to get full function.

I'll skip over the methods we have of doing substitution and get into my thought: What if we were to allow definition of a MessageFormat?

  INFO:InfoName|<message format>

Note that MessageFormat allows items that include | et al, so we can't tack on any extra items in that token.  No PRE, no variables, etc.

That would require:

  INFOVARS:InfoName|x|x

For the variables (x would be something valid in the new formula system)

InfoName doesn't need to be pre-defined, just needs to be recognized that it overwrites if it matches a previously defined item on that object.

Not 100% certain if we can catch if there is an INFO without the appropriate count of INFOVARS, though it looks like getFormats() can effectively help accomplish such a check at the end of LST load.

Seems this can replace OutputName, Desc, Aspect (for just about everything except 4E where PRExxx may be necessary? - not sure since I never played 4E), many of the spell tokens (e.g. TargetArea), and some others.

Sensible at all?

Any way to do it with another String formatting system that would allow it in one token like DESC is today? Is that tradeoff worth it vs being able to leverage java.text.MessageFormat (built into Java)

Note: One of my decision criteria here is avoiding indirection.  I've long held that data like this:

  NEWTOKEN:InfoName|message_ab_foo_1|x|y|z

...where message_ab_foo_1 has to be in a language file... is putting a huge burden on data because it forces indirection due to localization.  I neither want to develop nor debug data like that, so really have no interest in writing tokens that behave like that....

Having said that, this format does lend itself to localization, as the MessageFormat is effectively in the one token (INFO) and the specific information is named (The InfoName would be Description, OutputName, whatever).

You can therefore "address" that MessageFormat... so imagine a separate file doing:

  ABILITY:FEAT|Dodge|Description|<other language version of message format>

This allows the code to do the swap of the message format without making the original data indirect.

Thoughts?

TP.

This is a formalization of the proposal earlier put onto _dev to address a replacement for DESC.  The _dev discussion can be found here: https://groups.yahoo.com/neo/groups/pcgen_developers/conversations/topics/4412

Note that the dev discussion contains some examples I have not repeated here.

This is a proposed replacement for DESC, ASPECT, BENEFIT, and likely a number of other tokens.  Since those tokens will be replaced *over time* (this is not a deprecation of these older tokens), the full list is not currently defined (We will discover them as we go and I'm sure the data team will add to the list as they discover and use the flexibility provided here)

Specifically to these tokens, there are four main reasons to replace them:

First, they allow Prerequisites, which is a non-trivial endeavor in determining what to do in any given situation.  This can be confusing to a reader of the data (in trying to hold the PRExxx in their head) as well as uses CPU time for the code to determine at any given time what DESCs are "on"  or "off".

Second, they allow multiple tokens, so we have to keep track of a list, we have to allow clearing of that list, we have to do extra things because there can be more than one.   In the case of Aspect we actually have to do things that violate the isolation assumptions that support the use of an LST editor (so writing editor code for Aspect would be tough to get correct).  Reducing this to a one-to-one relationship helps simplify a number of things in the code (and I'd argue the data as well).

Third, it does not play well with any form of localization because the substitutions are hardcoded and the variables and strings are all mixed together.

Lastly, it is hardcoded to the existing formula system to do replacement.  Trying to mix the old and new formula systems is pretty much a disaster, so DESC (and other tokens that do similar replacement) need to be swapped out in the conversion  to the new formula system.

This is a proposal for a replacement for DESC and the other descriptive tokens.  There are two key Assumptions in this proposal: - For any given identification of output, we only need one thing - The output is unconditional

Clarification of assumptions:

"One thing" is akin to TargetArea on a spell today, which is 1 thing (the token overwrites if provided again).  This is different than the current "DESC" or "Components" on a spell which are "append", and thus can be multiple things.  These multiple items use .CLEAR/.CLEARALL to clear the list.  

If multiple outputs with the same identification are required, I'd like to see the rules structure/output structure that requires such behavior.  (This has been posted to _dev and bumped, and so far everything that has come back doesn't require multiple items, just a mental model change in how to make the data)

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)

   INFO:Description|"There {0,choice,0#are no files|1#is one file|1<are {0,number,integer} files}.
   INFOVARS:Description|NumFiles

Would output based upon the value of NumFiles (Assuming a Number of 0, 1, or 1+)

  0 = "There are no files"
  1 = "There is one file"
  1+ = "There are x files" with x being the value of NumFiles

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.

--- 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