Function expandToNode

A tag function that attaches the template's content to a CompositeGeneratorNode.

This is done segment by segment, and static template portions as well as substitutions are added individually to the returned CompositeGeneratorNode. At that common leading indentation of all the template's static parts is trimmed, whereas additional indentations of particular lines within that static parts as well as any line breaks and indentation within the substitutions are kept.

For the sake of good readability and good composability of results of this function like in the following example, the subsequent rule is applied.

 expandToNode`
  This is the beginning of something

  ${foo.bar ? expandToNode`
    bla bla bla ${foo.bar}

  `: undefined
  }
  end of template
 `
Copy

Rule: In case of a multiline template the content of the first line including its terminating line break is ignored, if and only if it is empty of contains whitespace only. Futhermore, in case of a multiline template the content of the last line including its preceding line break (last one within the template) is ignored, if and only if it is empty of contains whitespace only. Thus, the result of all of the following invocations is identical and equal to generatedContent.

 expandToNode`generatedContent`
 expandToNode`generatedContent
 `
 expandToNode`
   generatedContent`
 expandToNode`
   generatedContent
 `
Copy

In addition, a second rule is applied in the handling of line breaks: If a line's last substitution contributes undefined or an object of type GeneratorNode, the subsequent line break will be appended via CompositeGeneratorNode.appendNewLineIfNotEmpty. Hence, if all other segments of that line contribute whitespace characters only, the entire line will be omitted while rendering the desired output. Otherwise, linebreaks will be added via CompositeGeneratorNode.appendNewLine. That holds in particular, if the last substitution contributes an empty string. In consequence, adding ${''} to the end of a line consisting of whitespace and substitions only enforces the line break to be rendered, no matter what the substitions actually contribute.