From 12f3fa5b6eaa2ee2801357550bc38828c209d523 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 6 Apr 2017 23:33:52 -0400 Subject: [PATCH] Add missing rater.xsd This is of limited use now with template support. But it is useful documentation nonetheless. --- src/current/rater.xsd | 1947 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1947 insertions(+) create mode 100644 src/current/rater.xsd diff --git a/src/current/rater.xsd b/src/current/rater.xsd new file mode 100644 index 00000000..d1bac472 --- /dev/null +++ b/src/current/rater.xsd @@ -0,0 +1,1947 @@ + + + + + + + + + + + + + + + + + + + Name of a package/rater. Must match the name of the XML file, sans the + extension. If the package is in a subdirectory, then the name should be + a relative path (e.g. "rates/company"). + + + + + + + + + + + + + + + Name of a constant. + + Underscore prefixes should be reserved for system constants. + + + + + + + + + + + + + + + Name of a type (as would be defined via typedef). + + + + + + + + + + + + + + + Name of a mathematical function. + + Since the name will appear in equations, it has a restricted character + set and length. + + + + + + + + + + + + + + + Name of a parameter (global or local) + + + + + + + + + + + + + + Represents a value yielded by a calculation (e.g. a premium). + + The camelCase requirement as opposed to the snake_case requirement used + for other variables, such as params, is intended to provide a + distinction. + + + + + + + + + + + + + + + Single-character index variable + + + + + + + + + + + + + Template name; underscore prefix and suffix is mandatory to help ensure + distinctive names between other identifiers. + + + + + + + + + + + + + Template parameter name + + Template parameters are delimited by '@'s; this restriction is in place + to permit substring replacements with clear delimiters. + + + + + + + + + + + + + Documentation for a specific element. + + The documentation must not be sparse; please provide something + descriptive that will be useful to someone completely new to the code. + + + + + + + + + + + + + + Symbol used to represent an entity when rendered. + + The string should consist of TeX/LaTeX commands and should produce a + single symbol. + + + + + + + + + + + Types of sets (vectors or matrices) + + + + + + + + + + + + + + + + Permits the static declaration of a matrix; a set represents a vector + and sibling sets can be combined to create a matrix + + + + + + + + + + + + Description explaining what the set represents + + + + + + + + + + + Value of the constant; must be compatible with the + enumeration's @type. + + + + + + + Description explaining what the value represents + + + + + + + + + + Defines a single constant. + + Constants differ from other variables (such as parameters) in that their + values cannot change; they exist as an alternative to hard-coding values + and as a means of re-use (magic values are not permitted). + + The value of the constant must be compatiable with its type. + + + + + + + + + + + + Name of the constant. The name must always be used in place of the + value when referencing the constant. + + + + + + + Value of the constant; must be within the domain of its type. + + + + + + + Constant data type + + + + + + + Useful description of the constant that explains what it is used for + and provides a context + + + + + + + Optional LaTeX symbol for typesetting + + + + + + + + (CORE ONLY) Denotes a constant whose value may be determined by runtime + + This should prevent any compiler from inlining the constant value. + + + + + + + + + + + + Path to a package without the extension. + + + + + + + + + + + + + + + Declares the package that this package is a sub-topic of. + + + + + + + Path to package, sans the ``.xml'' extension. + + + + + + + + Parent section name; defaults to root. + + + + + + + + + + Permits importing package or template contents for use in the parent document. + + The @package attribute may be used for explicitly loading a package. + + @templates specifies a path for template auto-loading, but does not load any + templates, allowing the system to use only the templates that are needed. + + + + + + + Path to package to import, sans the ``.xml'' extension. + + + + + + + + Export the symbols imported by this package + + By default, all imported symbols are local, meaning that importing a + package will not include the symbols that the package itself has + imported. This is generally desirable from a maintainance standpoint, + but certain meta-packages (packages that exist simply to include + packages) may wish to make use of this feature. + + Use sparingly. + + + + + + + + Short-hand for a separate topic-of node; parent + section. "true" is equivalent to "root". + + + + + + + + Allow importing symbol tables that are not explicitly defined as + includable packages. + + + + + + + + Strip @keep flag from all imported symbols. + + + + + + + + Do not import symbols flagged as external to the classifier. + + This is of limited use outside of specialized settings, such as the + UI classifier. + + + + + + + + Keep all classifications, even if @ignore-keep is set. + + + + + + + + + + + + Defines a type that may be used to represent a restricted set of values. + + + + + + + + + + + + + + + Name by which the type may be referenced + + + + + + + Description of what the type may be used for + + + + + + + Optional LaTeX symbol for typesetting + + + + + + + + + + Merges multiple typedefs of the same type into a single type. + + Useful for categorizing types and sub-types in a semantic manner. + + + + + + + + + + + + + Defines an enumerated set of values. + + The type may accept any @value in the set. When referenced, @name must + be used. The name must be styled as a constant (since it is not a + variable). + + + + + + + + + + Name of enumerated value. This defines a constant and so the + name should be styled as such. + + + + + + + Value of the constant; must be compatible with the + enumeration's @type. + + + + + + + Description explaining what the value represents + + + + + + + + + + + Type of all enumerated values in a particular list + + + + + + + + + + + + Represents a parameter accepted by the rater or a function. + + Parameters accepted by the rater itself will be declared globally, + whereas parameters defined within functions will be local to that + function. + + Regardless of scope, parameter names must never conflict. + + + + + + + Name by which parameter can be identified + + + + + + + Parameter data type + + + + + + + Description of parameter + + + + + + + Whether or not the parameter is a set of values of type @type (an + array) + + + + + + + Default value for parameter if none is provided; must be within the + domain of its @type + + + + + + + Optional LaTeX symbol for typesetting + + + + + + + + + + Defines a mathematical function --- a reusable equation that optionally + accepts arguments. + + Functions also have access to the global argument list and any other + values; not everything must be passed in. Functions may contain only + a single calculation node (which itself may contain other calculations). + + + + + + + + + + + + Name of the function. Since the function is intended to be a function + in the mathematical sense and may be output as part of an equation, + the name is restricted to lowercase alpha characters. + + + + + + + Description of function and its purpose + + + + + + + Optional symbol to use in place of function name when typesetting + + + + + + + + + + + + String of classifications, space-delimited. + + + + + + + + + + + + + + + + + + + + + + Name of parameter to replace in template + + + + + + + + String with which template parameter should be replaced + + All template parameters are replaced by the preprocessor before + the XML document reaches any other system; this means that all + parameter replacements are performed as strings, just as if you + copied and pasted the template XML into place and did a + search-and-replace/regex on the XML. + + Consequently, variable replacements are not permitted. You may + replace the parameter with text representing the name of a + global parameter, for example, but you cannot pass in the + current value of of that parameter. + + + + + + + + + + This node will be entirely removed and replaced with the child nodes + of the referenced template. + + + + + + + + + + + Name of template to include in its place. + + + + + + + + + + + + + This node will be replaced with the processed template. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Classifications, delimited by spaces, that must be satisfied in order + to perform the premium calculation. + + If no classification is given, then the rating will always be + performed. + + + + + + + Classifications, delimited by commas, that must be not be + satisfied in order to perform the premium calculation. + + + + + + + Optional LaTeX symbol used to identify this premium (display only) + + + + + + + Always enter this rate block, even if the classification does not + match. This is useful if you wish to use the _CMATCH_ results + even on a non-match. + + + + + + + + + + + + Class name to apply to block + + + + + + + + Whether or not the classification should be considered as if it were + part of a @no attribute + + + + + + + + + + Represents a premium calculation to be performed based on a prior + classification (sans @yields) + + + + + + + + + + + + + + Precision of result (empty will use system default) + + + + + + + + Compile the rate block even if it does not contribute to the + final premium (that is---is outside the dependency tree of + lv:yields) + + This is useful for calculating supplemental data that does not + directly contribute to the premium. + + + + + + + + Rate calculation should be compiled external to the classifier (that + is, the classification should only be performed on-demand for rating + purposes). + + This has the benefit of removing the classifier from the classify() + method, which may be important for, say, asserting on final premium + amount. + + + + + + + + + + + + Represents a premium calculation to be performed based on a prior + classification + + + + + + + + + Variable in which to store the result of the calculation (will + default to 0 if calculation is not performed). + + + + + + + + + + + + Identical to lv:rate, except that it requires and index with which it + will automatically loop through the magic _CMATCH_ set and multiply the + calculation by its value; this creates a conditional effect. + + + + + + + + + Set the index to use for summing over the _CMATCH_ set. + + + + + + + + Optional variable in which to store the result of the calculation (will + default to 0 if calculation is not performed). + + If not provided, will prefix the value of @generates. + + + + + + + + Produces a generating function as vector @generates + + + + + + + + Symbol to use for display of generator + + + + + + + + + + + + Generates lv:rate-each, applying the given template (simply removes + boilerplate template application at the root level) + + The template is expected to accept an @index@ parameter. + + + + + + + + + + + + + + + + + + Template to apply + + + + + + + + Variable in which to store the result of the calculation (will + default to 0 if calculation is not performed). + + + + + + + + Produces a generating function as vector @generates + + + + + + + + Symbol to use for display of generator + + + + + + + + Compile the rate block even if it does not contribute to the + final premium (that is---is outside the dependency tree of + lv:yields) + + This is useful for calculating supplemental data that does not + directly contribute to the premium. + + + + + + + + The symbol associated with the rate block should never be exported + (similar to a private member in Object-Oriented languages, or + static definitions in C) + + + + + + + + + + + + Permits default value generation. + + + + + + + + + + + + + + + + + + + + + + Converts the first character of the value to uppercase + + + + + + + + Converts the string to uppercase + + + + + + + + Converts the string to lowercase + + + + + + + + Converts '-' to '_' + + + + + + + + Converts '-' to '' + + + + + + + + Converts spaces to dashes + + + + + + + + Strip all characters that do not constitute a valid + object identifier (for use in genrating names) + + + + + + + + + + + + + + + + + + + + Value to add to param (assumed to be a numeric param) + + + + + + + + + + Converts a class name to its @yields variable + + + + + + + + + + + + + + + + + + + + + + + + + + + + Result of param copy should trigger template param expansion has if + the copied nodes were a part of the template itself. + + Without this option, param expansion is not performed on the copied + nodes for that pass, meaning that the copied nodes will be + unaffected by the template. + + + + + + + + + + + + + + + + + + + + + + + + Declares a parameter available for replacement within the template. + + Notice how, unlike parameters for raters and functions, this parameter + does not require a type; this is because all replacements are done by + the preprocessor and, as such, all replacements are done as strings. + + + + + + + + + + + Parameter name to be used for replacements + + + + + + + Parameter description + + + + + + + + + + Declares a template whose body may be referenced using lv:apply-template. + + Templates are a basic means of code reuse that act as macros: when + referenced by lv:apply-template, the body of the template will be put + in its place as if it were pasted by hand. Therefore, this achieves the + effect of copy-and-paste without the obvious downsides of actually + copying and pasting code. + + This permits the construction of lv:rate blocks in a more natural manner. Other + methods of re-use include referencing previously calculated premiums (by other + lv:rate blocks) and the use of functions; both have their downsides. Namely: + + - Premiums calculated by other lv:rate blocks yield a single float value, which + aggregates individual indexes that may have been used during rating. As such, + if you need those individual premiums per index, premiums from other lv:rate + blocks cannot be used. In such a case, functions may be used. + - Using a function requires verbose code for application and makes + the documentation and debugging more complicated. It does, however, + have the benefit of being able to accept arguments, which templates + cannot do (and as such should be used whenever variable reuse is + necessary outside the scope of the global parameter list). + - Templates were designed with the idea that a bunch of common calculations + could be defined that could then be applied to individual raters as a more + natural alternative to functions. That is---the developer is accustomed to + creating lv:rate blocks that contain calculations, not excessive function + calls joined together with other expressions. Templates eliminate the need + for boilerplate function application code and, because they are handled by + the preprocessor, also generate easy-to-understand documentation and make + debugging more natural for both developers and testers. + - While templates do not accept arguments, they *do* permit string-replacement + of parameters by the preprocessor. This has the benefit of being + able to replace text as if it were done in your editor. + Consequently, this means that the replacement can be anything that + is considered valid by the validator/compiler. + + + + + + + + + + + + Template name; will be used by lv:apply-template. + + + + + + + + Describe purpose of the template + + + + + + + + + + + + Classification identifier; will be used to refer to the classification. + + + + + + + + + + + + + + + Classifies data based on the provided argument list and other + classifications. Classifications are used during rating to determine + how premiums should be calculated in a declarative manner. + + If no classification criteria are provided, then the classification + will always take place (implying a direct "is a" relationship between + the rater and a particular classification). + + + + + + + + + + + Name of classification. Can be used to determine whether or not the + data has been classified as such. + + + + + + + Convert classification from a universal quantifier into an + existential + + + + + + + Description of classification + + + + + + + Optional variable in which to store a boolean set of matches (useful + if classifying against sets) + + As an example, consider classifying as vacant land by matching on a + set of class codes. The system will check each class code in the + provided set against valid class codes for vacant land. Should one + item in the set match any of the criteria, the + classification will succeed and its associated index in the @yields + identifier will be set to 1. Otherwise, the value will remain 0. + + This allows for performing conditional calculations by simply + multiplying by the boolean value. If the value is 0, that portion of + the equation will effectively have not happened, simulating a + conditional. + + + + + + + Always perform the classification, even if it is unused. + + Otherwise, the system may not compile unused classifications (and so + the classification would not occur). + + + + + + + Classification should result in termination (useful for eligibility + and error conditions) + + + + + + + Classification should be compiled external to the classifier (that + is, the classification should only be performed on-demand for rating + purposes). + + This has the benefit of removing the classifier from the classify() + method, which may be important for, say, asserting on final premium + amount. + + + + + + + + + + Criteria with which a classification may be matched. + + All criteria is driven off of the global argument list. + + + + + + + + + + + + + + + + + Succeeds if any of the child matches succeed (equivalent to an OR statement). + + + + + + + + + + + + + + + + + + + + + Succeeds if all of the child matches succeed (equivalent to an AND statement). + + This is implied by the root lv:classify node. + + + + + + + + + + + + + Perform a basic match against a given value or enumerated list. + + One of value or anyOf should be provided. If neither is provided, one + may provide any condition nodes accepted by c:when; multiple will be + combined with logical and. This provides additional flexibility + necessary for more complicated assertions that would otherwise rely on + convoluted regular expressions. + + + + + + + + + + + Name of global parameter to perform match on + + + + + + + Value to match against (must be within domain of parameter). Use only + one of this or @anyOf. + + + + + + + Value must match any value within an enumerated list. Enumeration to + match against must be within the domain of the parameter. USe only + one of this or @value. + + + + + + + JavaScript-compatible regular expression + + Forward slashes must be escaped with a backslash and opening/closing + delimiters should not be specified. + + + + + + + + + + Join matching classifiers into an lv:any block where they will be + matched on the value TRUE. + + Each matching classifier must have a @yields attribute. + + + + + + + Any classifier's @as attribute matching this prefix will be included + within an lv:any block. + + + + + + + + Univerisal quantifier (default is existential) + + + + + + + + + + + Yields a single value (premium) representing the entire result of the + rating process. + + + + + + + + + + + + + + Internal symbol types + + These are the strings used directly by the symbol map; it is + recommended that the user use some type of abstraction (e.g. a + template). + + + + + + + + + + + + + + + + + + + + Declares an external symbol + + This allows a symbol to be used in a package that does not either include + or define it. The symbol must be defined before linking. + + + + + + + Symbol name + + + + + + + + Symbol type + + + + + + + + Symbol data type + + + + + + + + Symbol dimensions (0 = scalar, 1 = vector, 2 = matrix, etc) + + + + + + + + Optional user-friendly message to output when extern is + missing (such as how to satisfy it). + + + + + + + + + + + Represents a single rater (calculator). This is a root node; there may be + only one rater per document. + + + + + + + + + + + + + + Denotes a group of common data. The section title will + become a heading in the documentation. + + + + + + + + + + + + + + + + + + + + Section title to appear in documentation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Base type that defines elements and attributes acceptable by any package + (note that a rater is considered to be a concrete package). + + + + + + + + + + + + + + + + + + + + + + + + + + + Entry point for a program package; yields final result. + + This will result in an error if the package is not a program. + + + + + + + + + UNIX-style package name that may be used to identify the package. Must + match the name of the file, sans the ``.xml'' extension. + + + + + + + + + + Represents a single rater (calculator). This is a root node; there may be + only one rater per document. All raters yield a final premium. + + + + + + + + + + + + + + + Represents a reusable package that may be included in raters or other + packages. This is a root node; there may be only one per document. + + + + + + + + + + + Package title. This is used as a user-friendly package + name, and as the heading for generated documentation. + + This replaces the previous @desc attribute, + which existed prior to the literate implementation. + + + + + + + + Deprecated; use @title. + + + + + + + + Package contains an entry point can may be linked into an + executable. + + + + + + + + + Used to indicate that the package is contained within the rating + framework itself. Do not use for your own + packages. + + + + + + + + Setting this to "true" will enable pretty sweet debugging features that + will make your life more tolerable (and perhaps even pleasant). + + + + + + + + When importing @keep symbols from packages, ignore those flagged + as @extclass + + + + + + + + Automatically treat all symbols as if they had @keep set. + + This ensures that all imported symbols will be present in + the compiled output. This is generally not desired, since + it will inflate the output by including unused symbols. + + N.B.: Currently only keeps classifications and their + generators! + + This is of limited use outside of specialized settings, such + as the UI classifier. + + + + + + + + + Mark generated eligibility classification with @keep. + + + + + + + + + + + + + Templates may exist as the root node in their own file for auto-loading. + + + + +