Updated Design: Using environment variables (markdown)

Design:-Using-environment-variables.md

@@ -4,10 +4,20 @@ There are a few other places where we want to enable more flexible configuration
 
 The basic usability of the `$(ENV_VAR)` approach has issues. It can only be used for node properties that are String types. For example, you can't use it within the Change or Switch node rules as the details of each rule are wrapped up into a single JavaScript Object. It's also not an obvious thing - you need to know about it in order to use it.
 
+ - [Update existing env var syntax](#0-update-existing-env-var-syntax)
  - [Add envvar as option to TypedInput](#1-add-envvar-as-option-to-typedinput)
  - [Project Settings](#2-project-settings)
  - [Subflow Instance Properties](#3-subflow-instance-properties)
  - [Compound Env Vars](#4-compound-env-vars)
+
+### 0. Update existing env var syntax
+
+The current syntax of `$(ENV_VAR)` was loosely inspired by the bash syntax for command substitution. However, JavaScript now supports [Template Literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) that use a subtly different syntax: `${ENV_VAR}`
+
+The difference between `$()` and `${}` is a potential source of confusion to new users.
+
+The proposal here is to deprecate (but still support where it's already used) the `$()` syntax in favour of `${}`.
+
 ### 1. Add envvar as option to TypedInput
 
 The first step here is to add Environment Variable as one of the pre-defined types in the TypedInput widget. That will make it a first-class configuration option and can be used with any node property. The `RED.utils.setMessageProperty` function can be updated to support env-var lookup - meaning Switch/Change node rules will be able to use them.
@@ -33,7 +43,7 @@ We've had an item on the backlog for a long time to allow subflow instances to b
 
 ### 4. Compound env-vars
 
-We currently only support using `$(ENV_VAR)` syntax if it is the complete node property - you cannot use `$()` within a longer string. But that would be quite useful to do.
+We currently only support using `$(ENV_VAR)` syntax (changing to also support `${ENV_VAR}`) if it is the complete node property - you cannot use `$()` within a longer string. But that would be quite useful to do.
 
 For example, an MQTT node that subscribes to `$(HOSTNAME)/events`. To achieve that today, env vars have to be created for each and every property that needs to be set. It's an okay workaround but can be cumbersome.
 
@@ -41,12 +51,12 @@ The question is whether we can support this sort of compound syntax within the e
 
 Within a normal `<input>`, it would just be case of looking for any and all `$(XYZ)` and substituting the corresponding value. The major issue with this approach is that longer properties, such as a Function or Template, are more likely to legitimately want to have `$(FOO)` appear in them without intending to be substituted. This is a real concern and prevents us from adding blanket support for it to all node properties.
 
-With the proposed TypedInput addition we can be more flexible. The question is how to do compound env-vars here - there's no markup to indicate name of env var versus text to concatenate it with. An option would be to require the use of `$(FOO)` if needed to delimit the env var.
+With the proposed TypedInput addition we can be more flexible. The question is how to do compound env-vars here - there's no markup to indicate name of env var versus text to concatenate it with. An option would be to require the use of `${FOO}` if needed to delimit the env var.
 
- - `FOO` - looks up `process.env.FOO` - as this is in context of a declared env-var type, the `$()` is superfluous, except...
- - `$(FOO)` - looks up `process.env.FOO`
- - `FOO$(BAR)` - looks up `process.env.BAR` and concatenates it to the literal `FOO`
+ - `FOO` - looks up `process.env.FOO` - as this is in context of a declared env-var type, the `${}` is superfluous, except...
+ - `${FOO}` - looks up `process.env.FOO`
+ - `FOO${BAR}` - looks up `process.env.BAR` and concatenates it to the literal `FOO`
 
 Both the Project Settings and Subflow Instance properties list would also support this format.
 
-This does mean compound env vars would only be possible using these new features - not in any arbitrary node property `<input>`. But a compound env var could be declared in Project Settings of Subflow Instance Properties which is then available as a simple `$(NEW_ENV_VAR)` to use anywhere in the flow.
+This does mean compound env vars would only be possible using these new features - not in any arbitrary node property `<input>`. But a compound env var could be declared in Project Settings of Subflow Instance Properties which is then available as a simple `${NEW_ENV_VAR}` to use anywhere in the flow.