diff --git a/conformance-tests/2023-09/base/jobs/7.5--numeric-string-zeros-in-range-elements.test.yaml b/conformance-tests/2023-09/base/jobs/7.5--numeric-string-zeros-in-range-elements.test.yaml new file mode 100644 index 00000000..9f591ccd --- /dev/null +++ b/conformance-tests/2023-09/base/jobs/7.5--numeric-string-zeros-in-range-elements.test.yaml @@ -0,0 +1,67 @@ +# Template Schemas §7.5: a numeric string loses notation redundant to its value (leading zeros, a +# leading '+') and keeps notation it was written in (decimal places, an exponent). +# +# Both halves over FLOAT and INT range elements. '0.50' is here because its leading zero is the +# whole integer part. The exponent elements carry a dot ('2.50E+2', not '1E+2') because the runner +# re-dumps the template through PyYAML, which leaves a dotless exponent unquoted, and a YAML 1.2 +# parser then reads it as a literal that makes no request at all. Assertions bracket the +# value because the runner substring-matches, so a bare 'W:2.5' is satisfied by 'W:2.50'. +# +# A normalizing implementation misses W[2.50] and W[2.50E+2]; one forwarding text misses F[2]. +template: + specificationVersion: jobtemplate-2023-09 + name: TestJob + steps: + - name: FloatRange + parameterSpace: + taskParameterDefinitions: + - name: Weight + type: FLOAT + range: ['2.50', '03.500', '0.50', '1.5', '2.50E+2', '1.0e-3', '+4.25'] + script: + actions: + onRun: + command: python + args: + - -c + - print(r'W[{{Task.Param.Weight}}]') + - name: IntRange + parameterSpace: + taskParameterDefinitions: + - name: Frame + type: INT + range: ['1', '02', '003', '+7'] + script: + actions: + onRun: + command: python + args: + - -c + - print(r'F[{{Task.Param.Frame}}]') +expected: + output: + - 'W[2.50]' + - 'W[3.500]' + - 'W[0.50]' + - 'W[1.5]' + - 'W[2.50E+2]' + - 'W[1.0e-3]' + - 'W[4.25]' + - 'F[1]' + - 'F[2]' + - 'F[3]' + - 'F[7]' + forbidden: + # Normalizing to the number the element denotes. + - 'W[2.5]' + - 'W[3.5]' + - 'W[0.5]' + - 'W[250]' + - 'W[250.0]' + - 'W[0.001]' + # Forwarding the source text unchanged. + - 'W[03.500]' + - 'W[+4.25]' + - 'F[02]' + - 'F[003]' + - 'F[+7]' diff --git a/wiki/2023-09-Template-Schemas.md b/wiki/2023-09-Template-Schemas.md index 2cd3441d..97c0a573 100644 --- a/wiki/2023-09-Template-Schemas.md +++ b/wiki/2023-09-Template-Schemas.md @@ -315,7 +315,8 @@ userInterface: # @optional ``` -Where `` is a string whose value is the string representation of an integer value in base-10, and: +Where `` is a string whose value is the string representation of an integer value in base-10 +(see [Numeric strings](#75-numeric-strings) for how such a value is rendered), and: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. @@ -373,7 +374,8 @@ userInterface: # @optional ``` Where `` is a string whose value is the string representation of a floating point or integer value in -base-10, and: +base-10 (see [Numeric strings](#75-numeric-strings) for how such a value is rendered, including the decimal places it +was written with), and: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. @@ -1112,7 +1114,8 @@ With: Where `` is a string whose value is the string representation of an integer value in base-10, `` (See [<TaskParameterStringValue>](#342-taskparameterstringvalue)) must resolve to the -string representation of an integer value in base-10, and: +string representation of an integer value in base-10, both are rendered as described in +[Numeric strings](#75-numeric-strings), and: 1. *name* — The name of the parameter. 2. *type* — The literal "INT", defining this parameter as integer valued. @@ -1186,7 +1189,9 @@ With: Where `` is a string whose value is the string representation of a floating point value in base-10, `` (See [<TaskParameterStringValue>](#342-taskparameterstringvalue)) must resolve to the -string representation of a floating point value in base-10, and: +string representation of a floating point value in base-10, both are rendered as described in +[Numeric strings](#75-numeric-strings) — which preserves the decimal places the element was written with, so a range +element of `'2.50'` gives a Task the value `2.50` — and: 1. *name* — The name of the parameter. 2. *type* — The literal "FLOAT", defining this parameter as floating point valued. @@ -2026,6 +2031,32 @@ With the `EXPR` extension enabled, expressions that reference values not yet kno stage are type-checked using the declared types of those values, catching type errors as early as possible. See the [Expression Language](2026-02-Expression-Language) specification for details. +### 7.5. Numeric strings + +``, ``, and `` are the string forms of a number. A field +that accepts one of them accepts the number written as text wherever it would otherwise accept an +``, ``, or `` literal. + +Such a value is rendered back into text — into a format string result, and from there onto a Task's +command line — so how it was written is part of what the Template asked for. Two rules govern that: + +1. **Notation redundant to the value is removed.** Redundant leading zeros and a leading `+` both + are: an `` of `'007'` renders `7`, and a `` of `'+2.50'` renders `2.50`. + A leading zero that is not redundant is kept, so `'0.50'` renders `0.50` and `'02.50'` renders + `2.50`. + +2. **Notation the value was written in is preserved.** Decimal places and an exponent both are: + `'2.50'` renders `2.50` and not `2.5`, and `'1E+2'` renders `1E+2` and not `100`. An exponent + keeps the case of its marker and the sign inside it. Writing the value as a string is the only + way a Template can ask for a fixed number of decimal places, which renderers commonly require; + a `` literal cannot, because `2.50` and `2.5` are the same literal after parsing. + +An `` and a `` have no decimal places and no exponent, so rule 1 is the +whole of their behaviour: each renders as the integer it denotes. + +The sign of a zero is left unspecified in this revision: a `` of `'-0.00'` may render +`-0.00` or `0.00`. + ## 8. `` This object is only available in the extension `FEATURE_BUNDLE_1`