Skip to content

Commit

Permalink
updated docs - added information about which fields are mandatory
Browse files Browse the repository at this point in the history
  • Loading branch information
@vlada-shubina
vlada-shubina committed Oct 7, 2022
1 parent 57c2ccc commit af49875
Show file tree
Hide file tree
Showing 2 changed files with 101 additions and 127 deletions.
153 changes: 64 additions & 89 deletions docs/Available-Symbols-Generators.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 </br> `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

Expand Down
Loading

0 comments on commit af49875

Please sign in to comment.