From af49875cd3691427473e38b7ab60e48bb346ad39 Mon Sep 17 00:00:00 2001 From: Vlada Shubina Date: Fri, 7 Oct 2022 13:50:38 +0200 Subject: [PATCH] updated docs - added information about which fields are mandatory --- docs/Available-Symbols-Generators.md | 153 +++++++++++---------------- docs/Reference-for-template.json.md | 75 +++++++------ 2 files changed, 101 insertions(+), 127 deletions(-) diff --git a/docs/Available-Symbols-Generators.md b/docs/Available-Symbols-Generators.md index 71347385cfa..5d179daa77a 100644 --- a/docs/Available-Symbols-Generators.md +++ b/docs/Available-Symbols-Generators.md @@ -41,7 +41,6 @@ Available built-in generators for computing generated symbols values are: | [casing](#casing) | Enables changing the casing of a string. | | [coalesce](#coalesce) | Behaves like the C# `??` operator. | | [constant](#constant) | Constant value | -| [evaluate](#evaluate) | Evaluate a code expression (using C style syntax) | | [port](#port) | Generate a port number that can be used by web projects. | | [guid](#guid) | Create a new guid. | | [now](#now) | Get the current date/time. | @@ -55,10 +54,10 @@ Available built-in generators for computing generated symbols values are: Changes the case of the text of the source value to all upper-case or all lower-case. It does not affect spaces (i.e. does not do any sort of Camel Casing). #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|source|string|Source of the data| -|toLower|bool| applies lower case if true, uppercase otherwise| +| Name |Data Type| Description |Mandatory| +|----------|------|---------------|---| +|`source`|`string`| The name of symbol to use as the source of data.| yes | +|`toLower`|`bool`| applies lower case if `true`, upper case otherwise| no | ### Samples @@ -106,12 +105,16 @@ In this sample three symbols are defined: ## Coalesce Behaves like the C# `??` operator. +Note: as in C# `??` operator, empty string will be accepted as the valid value and returned. +The typical use of this generator is to check if the parameter was provided by user, otherwise set fallback generated value. + #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|sourceVariableName|string|source of the data| -|fallbackVariableName|string|alternate source of data| +|Name|Data Type|Description|Mandatory| +|---|---|---|---| +|`sourceVariableName`|`string`|the symbol name which is a primary source of data (left operand of `coalesce`)|yes| +|`fallbackVariableName`|`string`|the symbol name which is an alternate source of data(right operand of `coalesce`)|yes| +|`defaultValue`|`string`|default value to use, in case both values above are unavailable|no| ### Samples @@ -154,9 +157,9 @@ Uses constant value. #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|value|string|constant value| +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`value`|`string`|constant value|yes| ### Samples @@ -182,42 +185,17 @@ Uses constant value. [`Sample`](https://github.com/dotnet/dotnet-template-samples/tree/master/13-constant-value) -## Evaluate - -Defines expression that will be evaluated during the processing of the template based on parameters and other symbols. -The `computed` type symbols can be use for same purpose. - -#### Parameters - -| Name |Data Type| Description | -|----------|------|---------------| -|value|string|expression to be evaluated| - -### Samples - -In this sample `IndividualAuth` is `true` if the value of `auth`, another symbol defined in the template, is `IndividualB2C` -``` - "IndividualAuth": { - "type": "generated", - "generator": "evaluate", - "parameters": { - "action": "(auth == \"IndividualB2C\")" - }, - }, -``` -### Related -[`Implementation class`](https://github.com/dotnet/templating/blob/main/src/Microsoft.TemplateEngine.Orchestrator.RunnableProjects/Macros/EvaluateMacro.cs) - - ## Port Gets an available port number on the machine. During evaluation looks for a valid free port number trying to create a socket, and in case of problems, returns the value defined in the `fallback` parameter. #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|fallback|string|fallback value| +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`high`|`integer`|defined the high bound of range to select port from|no, default: `1024`| +|`low`|`integer`|defined the low bound of range to select port from|no, default: `65535`| +|`fallback`|`integer`|fallback value|no, default: `0`| ### Samples In this sample `KestrelPortGenerated` is a symbol that return the number of an available port or 5000. @@ -242,9 +220,9 @@ In this sample `KestrelPortGenerated` is a symbol that return the number of an a Creates a formatted guid for a replacement. To configure the output format of the macro you can use the **defaultFormat** parameter that accepts a single value from **{'n', 'd', 'b', 'p', 'x'}** for lowercase output or **{'N', 'D', 'B', 'P', 'X'}** for uppercase output. The formats are defined in [`Guid.ToString()` method documentation](https://msdn.microsoft.com/en-us/library/97af8hh4(v=vs.110).aspx) #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|defaultFormat|string|Format Descriptor| +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`defaultFormat`|`string`|format descriptor|no, default: `D`| ### Samples This sample creates different symbols showing the different formatting available for the generated guid. @@ -305,10 +283,10 @@ This sample creates different symbols showing the different formatting available Creates a symbol from the current date/time. #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|format|string|DateTime.ToString format| -|utc|bool|UTC time if true, local time otherwise| +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`format`|`string`|`DateTime.ToString()` format|no| +|`utc`|`bool`|UTC time if `true`, local time otherwise|no| ### Samples In this sample a symbol is created showing the current data, and replacing any instance of "01/01/1999" @@ -336,10 +314,10 @@ In this sample a symbol is created showing the current data, and replacing any i Creates a random integer value in a specified range. #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|low|integer|lower bound| -|high|integer|upper bound| +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`low`|`integer`|lower bound|yes| +|`high`|`integer`|upper bound|no, default:`int.MaxValue`| ### Samples This sample shows a symbol that generates a value from `0` to `10000` excluded, and replace any instance of `4321` @@ -367,17 +345,16 @@ This sample shows a symbol that generates a value from `0` to `10000` excluded, Defines a list of data manipulation steps based on regex expressions. #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|source|string|data source| -|steps|array|replacement steps| +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`source`|`string`|the symbol to transform|yes| +|`steps`|`array`|replacement steps|yes| -Replacement steps - -| Name |Data Type| Description | -|----------|------|---------------| -|regex|string|selection pattern| -|replacement|string|replacement formula| +`steps` element definition: +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`regex`|`string`, regex pattern|selection pattern|yes| +|`replacement`|`string`|the replacement value for matched pattern|yes| ### Samples @@ -410,13 +387,13 @@ Replacement steps [`RegEx.Replace Documentation`](https://msdn.microsoft.com/en-us/library/xwewhkd1(v=vs.110).aspx) ## RegexMatch -Tries to match regex pattern against value of source symbol and returns `True` if matched, otherwise `False`. +Tries to match regex pattern against value of source symbol and returns `true` if matched, otherwise `false`. #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|source|string|data source| -|pattern|string|match pattern| +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`source`|`string`|the symbol to attempt to match value|yes| +|`pattern`|`string`, regex pattern|the regex match pattern|yes| ### Samples @@ -444,17 +421,16 @@ Tries to match regex pattern against value of source symbol and returns `True` i Defines a set of conditions to be evaluated, and the value to return if the condition is met. The first condition to evaluate to true is used. To include a default case, add a condition that always evaluates to true as the last entry in `cases`. #### Parameters -| Name |Data Type| Description | -|----------|------|---------------| -|cases|array|choices to evaluate| -|evaluator|string|expression evaluation engine, if not C++| - -Cases definition +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`cases`|`array`|choices to evaluate|yes| +|`evaluator`|`enum`: `C++2`, `C++`, `MSBuild`, `VB`|expression evaluation engine|no, default: `C++2`| -| Name |Data Type| Description | -|----------|------|---------------| -|condition|string|condition to evaluate| -|value|string|value to return if match| +`cases` definition +|Name|Data Type|Description|Mandatory| +|----------|------|---------------|---| +|`condition`|`string`|the condition to evaluate, keep empty for default clause.|no| +|`value`|`string`|the value to return, if `condition` evaluates to `true`|yes| ### Samples @@ -497,18 +473,17 @@ In this case, if the user enters the value `123` as the value of the parameter ` Concatenates multiple symbols or constants with the defined separator into a new symbol. #### Parameters -| Name |Data Type| Optional | Description | +|Name|Data Type|Description|Mandatory| |----------|---------|----------|-----| -|symbols |array |no |all values to concatenate| -|separator |string |yes |the value used as the separator between the values to be concatenated, notice that you can use `/` as folder separator also on Windows since File API will convert it into `\` | -|removeEmptyValues |bool |yes |indicates whether empty values should be skiped or honored. By default this switch is off - leading to multiple consecutive separators in output string in case that same input values are null or empty| - -Symbols definition - -| Name |Data Type| Description | -|------|---------|---------------| -|type |string |`ref` to reference value from another symbol or `const` for string constant, defaults to `const`.| -|value |string |either name of another symbol or string constant| +|`symbols` |`array` |defines the values to concatenate|yes| +|`separator` |`string` |the value used as the separator between the values to be concatenated, notice that you can use `/` as folder separator also on Windows, since File API will convert it into `\` | yes | +|`removeEmptyValues` |`bool`|indicates whether the empty values should be skipped or honored. By default this switch is off - leading to multiple consecutive separators in output string in case that same input values are null or empty| no | + +`symbols` definition +|Name|Data Type|Description|Mandatory| +|------|---------|---------------|---| +|`type` |`enum`: `ref`, `const` |`ref` indicates that the value is referenced from another symbol
`const` - the value is a string constant|no, default: `const`| +|`value` |`string` |either a name of another symbol or string constant|yes, should be not empty or whitespace when `type` is `ref`| ### Samples diff --git a/docs/Reference-for-template.json.md b/docs/Reference-for-template.json.md index 270db681276..6076df9287e 100644 --- a/docs/Reference-for-template.json.md +++ b/docs/Reference-for-template.json.md @@ -131,22 +131,22 @@ There are 3 places from which a symbol can acquire its value: A symbol for which the config provides literal and/or default values. -|Name|Description| -|---|---| -|`type`|`parameter`| -|`dataType`| Supported values:
- `bool`: boolean type, possible values: `true`/`false`.
- `choice`: enumeration, possible values are defined in `choices` property.
- `float`: double-precision floating format number. Accepts any value that can be parsed by `double.TryParse()`.
- `int`/`integer`: 64-bit signed integer. Accepts any value that can be parsed by `long.TryParse()`.
- `hex`: hex number. Accepts any value that can be parsed by `long.TryParse(value.Substring(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out long convertedHex)`.
- `text`/`string`: string type.
- ``: treated as string. -|`defaultValue`|The value assigned to the symbol if no parameter is provided by the user or host. The default is *not applied* if [`isRequired`](#isRequired) configuration is set to `true` for a parameter (or is set to condition that evals to `true`), as that is an indication that user specified value is required. | -|`defaultIfOptionWithoutValue`|The value assigned to the symbol if explicit `null` parameter value is provided by the user or host.| -|`replaces`|The text to be replaced by the symbol value in the template files content| -|`fileRename`|The portion of template filenames to be replaced by the symbol value.| -|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.| -|`isRequired`|Optional. Indicates if the user supplied value is required or not. Might be a fixed boolean value or a condition string that evals based on passed parameters - more details in [Conditions documentation](Conditions.md#conditional-parameters).
If set to `true` (or condition that evals to `true`) and user has not specified the value on input, validation error occurs - even if [`defaultValue`](#defaultValue) is present.| -|`isEnabled`| Optional condition indicating whether parameter should be processed. Might be a fixed boolean value or a condition string that evals based on passed parameters - more details in [Conditions documentation](Conditions.md#conditional-parameters).| -|`choices`|Applicable only when `datatype=choice.`
List of available choices. Contains array of the elements:
- `choice`: possible value of the symbol.
- `description`: human readable text describing the meaning of the choice. This has no effect on template generation.
If not provided, there are no valid choices for the symbol, so it can never be assigned a value.| -|`allowMultipleValues`|Applicable only when `datatype=choice.`
. Enables ability to specify multiple values for single symbol.| -|`enableQuotelessLiterals`|Applicable only when `datatype=choice.`
. Enables ability to specify choice literals in conditions without quotation.| -|`onlyIf`| | -|`forms`|Defines the set of transforms that can be referenced by symbol definitions. Forms allow the specification of a "replaces"/"replacement" pair to also apply to other ways the "replaces" value may have been specified in the source by specifying a transform from the original value of "replaces" in configuration to the one that may be found in the source. [Details](https://github.com/dotnet/templating/wiki/Runnable-Project-Templates---Value-Forms)| +|Name|Description|Mandatory| +|---|---|---| +|`type`|`parameter`| yes | +|`dataType`| Supported values:
- `bool`: boolean type, possible values: `true`/`false`.
- `choice`: enumeration, possible values are defined in `choices` property.
- `float`: double-precision floating format number. Accepts any value that can be parsed by `double.TryParse()`.
- `int`/`integer`: 64-bit signed integer. Accepts any value that can be parsed by `long.TryParse()`.
- `hex`: hex number. Accepts any value that can be parsed by `long.TryParse(value.Substring(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out long convertedHex)`.
- `text`/`string`: string type.
- ``: treated as string.| no, default - `string` | +|`defaultValue`|The value assigned to the symbol if no parameter is provided by the user or host. The default is *not applied* if [`isRequired`](#isRequired) configuration is set to `true` for a parameter (or is set to condition that evals to `true`), as that is an indication that user specified value is required. | no | +|`defaultIfOptionWithoutValue`|The value assigned to the symbol if explicit `null` parameter value is provided by the user or host.|no | +|`replaces`|The text to be replaced by the symbol value in the template files content| no | +|`fileRename`|The portion of template filenames to be replaced by the symbol value.| no | +|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.| no | +|`isRequired`|Optional. Indicates if the user supplied value is required or not. Might be a fixed boolean value or a condition string that evals based on passed parameters - more details in [Conditions documentation](Conditions.md#conditional-parameters).
If set to `true` (or condition that evals to `true`) and user has not specified the value on input, validation error occurs - even if [`defaultValue`](#defaultValue) is present.| no | +|`isEnabled`| Optional condition indicating whether parameter should be processed. Might be a fixed boolean value or a condition string that evals based on passed parameters - more details in [Conditions documentation](Conditions.md#conditional-parameters).| no | +|`choices`|Applicable only when `datatype=choice.`
List of available choices. Contains array of the elements:
- `choice`: possible value of the symbol.
- `description`: human readable text describing the meaning of the choice. This has no effect on template generation.
If not provided, there are no valid choices for the symbol, so it can never be assigned a value.| yes, for `dataType` = `choice` | +|`allowMultipleValues`|Applicable only when `datatype=choice`.
Enables ability to specify multiple values for single symbol.| no | +|`enableQuotelessLiterals`|Applicable only when `datatype=choice`.
Enables ability to specify choice literals in conditions without quotation.|no | +|`onlyIf`| |no | +|`forms`|Defines the set of transforms that can be referenced by symbol definitions. Forms allow the specification of a "replaces"/"replacement" pair to also apply to other ways the "replaces" value may have been specified in the source by specifying a transform from the original value of "replaces" in configuration to the one that may be found in the source. [Details](https://github.com/dotnet/templating/wiki/Runnable-Project-Templates---Value-Forms)|no | ##### Examples Boolean optional parameter with default value `false`: @@ -262,14 +262,14 @@ There are some specifics in behavior of multichoice symbols that are worth notin A symbol that defines transformation of another symbol. The value of this symbol is derived from the value of another symbol by the application of form defined in `valueTransform`. -|Name|Description| -|---|---| -|`type`|`derived`| -|`valueSource`|The name of the other symbol whose value will be used to derive this value.| -|`valueTransform`|The name of the value form to apply to the source value.| -|`replaces`|The text to be replaced by the symbol value in the template files content| -|`fileRename`|The portion of template filenames to be replaced by the symbol value.| -|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.| +|Name|Description|Mandatory| +|---|---|---| +|`type`|`derived`| yes | +|`valueSource`|The name of the other symbol whose value will be used to derive this value.| yes | +|`valueTransform`|The name of the value form to apply to the source value.| yes | +|`replaces`|The text to be replaced by the symbol value in the template files content| no | +|`fileRename`|The portion of template filenames to be replaced by the symbol value.| no | +|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.| no | ##### Examples Renames `Application1` file to value of `name` symbol after last dot @@ -301,15 +301,14 @@ Renames `Application1` file to value of `name` symbol after last dot A symbol whose value gets computed by a built-in symbol value generator. [Details](https://github.com/dotnet/templating/wiki/Reference-for-available-macros) -|Name|Description| -|---|---| -|`type`|`generated`| -|`generator`|Generator to use:
- [casing](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#casing) - enables changing the casing of a string.
- [coalesce](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#coalesce) - behaves like the C# ?? operator.
- [constant](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#constant) - constant value.
- [evaluate](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#evaluate) - evaluates a code expression (using C style syntax).
- [port](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#port) - generates a port number that can be used by web projects.
- [guid](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#guid) creates a new guid.
- [now](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#now) - get the current date/time.
- [random](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#random) - generate random integer value.
- [regex](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#regex) - processes a regular expression.
- [switch](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#switch) - behaves like a C# switch statement.| -|`parameters`|The parameters for generator. See [description](https://github.com/dotnet/templating/wiki/Reference-for-available-macros) for each generator for details.| -|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.| -|`replaces`|The text to be replaced by the symbol value in the template files content| -|`fileRename`|(supported in 5.0.200 or higher) The portion of template filenames to be replaced by the symbol value.| -|`dataType`| Supported values:
- `bool`: boolean type, possible values: `true`/`false`.
- `float`: double-precision floating format number. Accepts any value that can be parsed by `double.TryParse()`.
- `int`/`integer`: 64-bit signed integer. Accepts any value that can be parsed by `long.TryParse()`.
- `hex`: hex number. Accepts any value that can be parsed by `long.TryParse(value.Substring(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out long convertedHex)`.
- `text`/`string`: string type.
- ``: treated as string. +|Name|Description|Mandatory| +|---|---|---| +|`type`|`generated`| yes | +|`generator`|Generator to use: See [this article](https://github.com/dotnet/templating/wiki/Reference-for-available-macros) for more details.| yes | +|`parameters`|The parameters for generator. See [description](https://github.com/dotnet/templating/wiki/Reference-for-available-macros) for each generator for details.| depends on generator | +|`replaces`|The text to be replaced by the symbol value in the template files content| no | +|`fileRename`|(supported in 5.0.200 or higher) The portion of template filenames to be replaced by the symbol value.| no | +|`dataType`| Supported values:
- `bool`: boolean type, possible values: `true`/`false`.
- `float`: double-precision floating format number. Accepts any value that can be parsed by `double.TryParse()`.
- `int`/`integer`: 64-bit signed integer. Accepts any value that can be parsed by `long.TryParse()`.
- `hex`: hex number. Accepts any value that can be parsed by `long.TryParse(value.Substring(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out long convertedHex)`.
- `text`/`string`: string type.
- ``: treated as string.| no, default: `string` | ##### Example @@ -365,11 +364,11 @@ A symbol whose value gets computed by a built-in symbol value generator. [Detail A symbol for which the config provides a Boolean predicate whose evaluation result is the computed symbol result. -|Name|Description| -|---|---| -|`type`|`computed`| -|`value`| Boolean expression to be computed.| -|`evaluator`|Language to be used for evaluation of expression:
- `C++2` - default
- `C++`
- `MSBUILD`
- `VB`| +|Name|Description|Mandatory| +|---|---|---| +|`type`|`computed`| yes | +|`value`| Boolean expression to be computed.| yes | +|`evaluator`|Language to be used for evaluation of expression:
- `C++2`
- `C++`
- `MSBUILD`
- `VB`| no, default: `C++2` | ##### Example