Formula Parser Equip Vars Proposal - Revision history

Tom Parker at 03:46, 16 August 2015

2015-08-16T03:46:11Z

Tom Parker at 21:26, 9 August 2015

2015-08-09T21:26:44Z

Show changes

Tom Parker at 00:42, 2 July 2014

2014-07-02T00:42:08Z

Show changes

Tom Parker at 19:10, 31 May 2014

2014-05-31T19:10:01Z

Tom Parker: /* Major Components */

2014-05-31T18:51:10Z

‎Major Components

Tom Parker: /* Other Functional Requirements */

2014-05-31T18:40:03Z

‎Other Functional Requirements

Tom Parker: /* FormulaValidity */

2014-05-31T18:37:43Z

‎FormulaValidity

Tom Parker: /* Capping a value */

2014-05-31T18:36:12Z

‎Capping a value

Tom Parker: /* A Note on Possible usage */

2014-05-31T18:33:14Z

‎A Note on Possible usage

Tom Parker: /* A Note on Possible usage */

2014-05-31T18:32:57Z

‎A Note on Possible usage

@@ Line 364: / Line 364: @@
 Future:
   DEFAULTVARIABLEVALUE:NUMBER|0 (in Game Mode Misc Info)
-  VARTYPEDEF:NUMBER|VAR (in Data Control file)
+  NAMESPACEDEF:NUMBER|VAR (in Data Control file)
   GLOBAL:VAR|InspireDurationBase (in Variable Def file)
   GLOBAL:VAR|InspireHeroicsDuration (in Variable Def file)
@@ Line 566: / Line 566: @@
 It's probably appropriate to walk through the various items and their names:
-  DEFAULTVARIABLEVALUE:NUMBER|0 (in Game Mode Misc Info)
+  DEFAULTVARIABLEVALUE:NUMBER|0 (in Data Control File)
-This sets the default value for a "Variable Format".  Variable Formats will likely be implemented as plugins (and it will translate "NUMBER" as representing a variable of Number.class).  This is required in order to use that "Variable Format" in the first argument to VARTYPEDEF:
+This sets the default value for a "Variable Format".  Variable Formats will likely be implemented as plugins (and it will translate "NUMBER" as representing a variable of Number.class).  This is required in order to use that "Variable Format" in the first argument to NAMESPACEDEF:
-  VARTYPEDEF:NUMBER|VAR (in Data Control File)
+  NAMESPACEDEF:NUMBER|VAR (in Data Control File)
 This Defines a Namespace / "Variable Type" called "VAR".  Variable Type "VAR" is a "NUMBER".  "NUMBER" is a Variable Format and therefore any "VAR" will default to the value provided in the Game Mode Misc Info file for "NUMBER"

@@ Line 770: / Line 770: @@
   Toes is set to 10.  The set at Priority 1000 "resets" the value vs. the 0+10 that was originally calculated for Toes (effectively done at priority = 0).
   No other updates because the value for Toes did not change.
 =Key Items for the Data Team to consider=

@@ Line 547: / Line 547: @@
 ==Variable Scope==
-To be stored in pcgen.base.formula.scope
+Also stored in pcgen.base.formula.variable due to the relationship between variables and the Scope in which they are used.
 Principles of Design:
 * Support local variables (e.g. a variable solely calculated within a piece of equipment)
 * Detect when a variable is properly used in scope (see use cases)
-* A Variable name can only be defined in one scope.  If "Foo" is used as an Equipment variable, it CANNOT be used as a Spell variable (for example) [this assumes we support multiple scopes of local variables at some point] (see use cases).  Enforcement of this is done by "VariableIDFactory".
+* A Variable name may be defined in more than one scope AS LONG AS the scopes are disjoint.  If "Foo" is used as an Equipment variable, it CAN be used as a Spell variable (for example) but NOT as a Global Variable (because use of "Foo" inside of Equipment would then be ambiguous as to whether it was referring to the Global Variable or the Local one).  [This assumes we support multiple scopes of local variables at some point] (see use cases).  Enforcement of this is done by "ScopeLibrary".
 * Each variable scope needs to understand / contain its parent scope so that the scope tree can be "walked" during variable resolution
-* Scope should not be null (there should be a "global scope" object) [This is mainly for "laziness" of not wanting to have null checks all over the place - just enforce up front the != null characteristic]
+* Scope should not be null (there should be a "global scope" object) [This is mainly for "laziness" of not wanting to have null checks all over the place - just enforce up front the != null characteristic].  This is enforced by "ScopeLibrary".
 ===Discussion===
@@ Line 569: / Line 569: @@
 ====VariableScopeDefinition design reasoning====
-One possibility would have been to force the VariableScopeDefinition to be a hard class, such as Equipment.class and have that implicitly compared within the VariableIDFactory.  This was seen as too restrictive, given that there may be situations where - for example - subclasses may be legal.  If local variables are allowed on classes, then we need to allow those to work on a SubClass line as well.  So a strict compare does not work, and if the rule is not that obvious, then it's better to externalize the check.
+One possibility would have been to force the VariableScopeDefinition to be a hard class, such as Equipment.class and have that implicitly compared within the ScopeLibrary.  This makes a pretty broad set of assumptions in how a VariableScopeDefintion is related to another VariableScopeDefintion (is it just the class hierarchy, should interfaces be ignored, etc.)  It also makes an awkward situation for interim classes where the scope may not be sensible in a given use.  There is also the problem that we know we have situations where the scope of a sub-class should match that of the class (think SubClass.class).  Thus, coding this as a Class was seen as too restrictive.  If local variables are allowed on classes, then we need to allow those to work on a SubClass line as well.  So a strict compare does not work, and if the rule is not that obvious, then it's better to externalize the check.
-Therefore, we have a VariableScopeDefinition object that has an isCompatible(x) method.  This allows us to subclass items yet still have them in a specific scope, since a given implementation of VariableScopeDefinition can understand what is legal.  (SubClass, SubstitutionClass, etc.).  In general, we avoid having the VariableIDFactory make an assumption about what is or is not legal for a given scope...
+Therefore, we have a VariableScopeDefinition object.  Since scope definitions are defined by their parent scope, this allows us to subclass items yet still have them in a specific scope, since a given implementation of VariableScopeDefinition can understand precisely what the parent scope is.  All of the construction and enforcement is done by "ScopeLibrary".
-Why is VariableIDFactory necessary? - Why a factory?
+====ScopeLibrary design reasoning====
-Specifically, we want to control where VariableIDs are manufactured to ensure we are always manufacturing variableIDs that are compatible with the given scope for a variable.
+Why is ScopeLibrary necessary? - Why a factory?
 Since that needs to be enforced against where a variable is legal, we need the VariableID construction to be closely associated with the VariableScopeDefinition object, so we contain construction inside the factory and the factory also holds the VariableScopeDefinition objects, so a VariableID cannot be constructed if it does not meet the VariableScopeDefinition.
@@ Line 600: / Line 601: @@
 * Want to be able to tell if a formula is valid at LST load (find invalid variables/functions, find incorrect or invalid function arguments)
 * Want to be able to get a list of variables from a formula so we can establish dependencies
 ** Ensure proper validation of local/global variables and catching scope problems at LST load (see use cases)
 ** Help avoid recalculations of unnecessary things (if desired)
@@ Line 669: / Line 671: @@
 This has to do with how the FormulaManager works.
-Adding a Variable means teaching the VariableIDFactory that a new local variable is allowed.  Allowing a "super local" variable (a.k.a. "temporary" variable) would mean allowing it in an arbitrary scope.  So we immediately take on the burden of allowing a variable in more than one scope.  (Alternately we would enable it in one scope, use it, and then delete that availability - that level of churn seems unnecessary).  Even with it enabled in more than one scope, we have to teach the "variable cache" the value, and then immediately clear the value so it is not accidentally used elsewhere.  We also have to build a new FormulaManager (since the FormulaManager passes itself to any functions and we have to have it pass the "correct" one - so a decorator on the FormulaManager will not work).  The result of using a variable is a lot of load, use, destroy behavior (and in ways that is _definitely_ not thread safe because the "variable cache" is shared and polluted with the "local" value).
+Adding a Variable means teaching the ScopeFactory that a new local variable is allowed.  Allowing a "super local" variable (a.k.a. "temporary" variable) would mean allowing it in an arbitrary scope.  So we immediately take on the burden of allowing a variable in more than one scope.  (Alternately we would enable it in one scope, use it, and then delete that availability - that level of churn seems unnecessary).  Even with it enabled in more than one scope, we have to teach the "variable cache" the value, and then immediately clear the value so it is not accidentally used elsewhere.  We also have to build a new FormulaManager (since the FormulaManager passes itself to any functions and we have to have it pass the "correct" one - so a decorator on the FormulaManager will not work).  The result of using a variable is a lot of load, use, destroy behavior (and in ways that is _definitely_ not thread safe because the "variable cache" is shared and polluted with the "local" value).
-Using a function allows us to create a derivative FormulaManager that does not alter the variable storage.  So the VariableIDFactory, VariableScope, and VariableStore all remain unchanged.  We simply decorate the existing function library with a new function library that recognizes "value()" as a function, and pass that new FormulaManager into the Formula to be resolved.  It still results in a few "temporary" objects (a FormulaManager, the decorator on the FunctionLibrary, and an EvaluateVisitor), but since it does not alter shared resources (e.g. the VariableCache), it is thread safe in addition to being significantly less effort to implement.
+Using a function allows us to create a derivative FormulaManager that does not alter the variable storage.  So the ScopeFactory, VariableScope, and VariableStore all remain unchanged.  We simply decorate the existing function library with a new function library that recognizes "value()" as a function, and pass that new FormulaManager into the Formula to be resolved.  It still results in a few "temporary" objects (a FormulaManager, the decorator on the FunctionLibrary, and an EvaluateVisitor), but since it does not alter shared resources (e.g. the VariableCache), it is thread safe in addition to being significantly less effort to implement.

@@ Line 241: / Line 241: @@
 * The entire concept of a PJEP pool goes away (in exchange we effectively have a context, but those are reusable so we don't ever have the lock/free necessity of PJEP)
 * We actually prohibit any funky hoop-jumping.  By only providing the context in the sense of a variable library, we can accurately handle things like spell-localized items (e.g. today's CASTERLEVEL term) without having a temporarily set global item (which - by the way - isn't thread safe)
 ==Interaction with existing (JEP) Formula System==

@@ Line 514: / Line 514: @@
 Visitor pattern already well recognized, so we can just have visitors that perform different functions and that should be reasonable for a developer to follow.
-==FormulaValidity==
+==FormulaSemantics==
-Principles of design:
+Performs Two Functions:
 * Let parse errors do their thing (We'll have to consider what we do as far as bad parser diagnostics)
-* A formula should be able to return a FormulaValidity object to identify (with specificity) any issues with the formula
+* A formula should be able to return a FormulaSemanticsobject to identify (with specificity) any issues with the formula
 * If there is more than one issue, only one issue needs to be returned (fast fail is acceptable)
 * Want to be able to be clear to a user why something is not a valid formula (e.g. a variable that is never defined)
 * Things to detect: Bad structure (internal errors), invalid # of formula arguments, function not found, variable not found
 ==Variables==

@@ Line 488: / Line 488: @@
 or preferably:
-  MODIFY:CappedAtTwenty|MIN|20|PRIORITY=1000000
+  MODIFY:CappedAtTwenty|MAX|20|PRIORITY=1000000
 This way, the data sets a "soft limit" at 20, that the data can override if it REALLY needs to by setting a priority over 1000000

@@ Line 47: / Line 47: @@
 * Equipment: since EqMods can be attached
 * Spells: Since they could be enhanced by things like MetaMagic Feats by the time they become castable spells (eventually forming what the code team calls a CharacterSpell)
-* Classes: Since there are ClassLevels that can be "attached" (Note that this has an inherent "problem" with variables that are based on class level; thus it is unlikely that local variables will make their way to classes in any tactical timeframe.
+* Classes: Since there are ClassLevels that can be "attached" (Note that this has an inherent "problem" with variables that are based on class level; thus it is unlikely that local variables will make their way to classes in any tactical timeframe.)
 ==Paren Function==

@@ Line 44: / Line 44: @@
 ====A Note on Possible usage====
-While this proposal is specific to Equipment for completeness of thought and assistance in understanding possible future uses, the only places where local variables make sense is:
+While this proposal is specific to Equipment for completeness of thought and assistance in understanding possible future uses, the most obvious places where local variables make sense is:
 * Equipment: since EqMods can be attached
 * Spells: Since they could be enhanced by things like MetaMagic Feats by the time they become castable spells (eventually forming what the code team calls a CharacterSpell)
 ==Paren Function==