littoral-templates 0.4.0-rc.3 → 0.4.0

package/CHANGELOG.md

@@ -5,11 +5,21 @@
 * Thunks returning a `Template` are now `Template`s as well.
 * The 3rd (Curried) argument of `indentWith`, and the 2nd (Curried) argument of `when` are now variadic.
 * The EOL style can be taken from the OS, using the asynchronous `setEOLStyleFromOS` function.
-  The `asString` returns a string that uses that EOL style *exclusively*.
+  The `asString` function now returns a string that uses that EOL style *exclusively*.
   Multi-line strings inside a template are therefore now split on `/\r*\n/` rather than just `/\n/`, so that `asString` effectively normalizes EOL style.
 * The `withNewlineAppended` function has been renamed to `withEmptyLineAppended`.
   (The former is kept as a legacy alias.)
 * An object constant `commonIndentations` is added and exposed which holds the most common indentation styles: “2 spaces”, “4 spaces”, and “1 tab”.
+* Updated the [README](./README.md) significantly!
+
+*Note*: `asString` now behaves more consistently on EOLs, meaning that existing templates might behave differently, particularly when using multi-line strings (nested) inside templates.
+(Also see the updated [README](./README.md).)
+Specifically: it’s no longer necessary – or even useful/desirable – to have multi-line strings ending in a bare EOL in your template code, because you shouldn't expect the following to evaluate to `"foo\n"`:
+
+```javascript
+asString([`foo
+`])
+```
 
 
 ## 0.3.0

package/README.md

@@ -39,6 +39,7 @@ console.log(
 
 The `indent` function is a function that takes one argument: the indentation level — let’s call that _n_.
 It then returns a *template function* that takes a template as its argument, and returns a template that is indented to indentation level _n_, using 2 spaces for each indentation.
+(A _template function_ is any function that produces an instance of `Template`.)
 Defining the `indent` function uses the `indentWith` function.
 
 This code produces the following text on the JavaScript console:
@@ -136,9 +137,7 @@ An example of that would be to keep track of imports that have to appear before
 
 Other convenience functions are:
 
-* `withEmptyLineAppended`: Wrap this around a template function (see definition below) to produce a template function that adds an empty line after any item fed to the original template function.
-
-    A _template function_ is any function that produces an instance of `Template`.
+* `withEmptyLineAppended`: Wrap this around a template function to produce a template function that adds an empty line after any item fed to the original template function.
 
     An example of the usage of `withEmptyLineAppended` is
 
@@ -167,8 +166,8 @@ Other convenience functions are:
 
 ### EOLs
 
-EOLs – AKA “newlines” or “line endings” – vary between OS's: Windows uses `crlf` EOL style – `\r\n` –, while essentially all other mainstream OS's use `lf` style – `\n`.
-Not taking that into account can cause content being generated differently across OS's, potentially confusing tools like Git — especially if these are not configured correctly.
+EOLs – AKA “newlines” or “line endings” – vary between OS’s: Windows uses `crlf` EOL style – `\r\n` –, while essentially all other mainstream OS’s use `lf` style – `\n`.
+Not taking that into account can cause content being generated differently across OS’s, potentially confusing tools like Git — especially if these are not configured correctly.
 Since generated content is often large, this causes additional confusion and friction in the software development process.
 
 To prevent such issues, you can set the EOL style by calling the `setEOLStyleFromOS` function before any calls to `asString`.
@@ -198,6 +197,8 @@ asString([`foo
 ```
 
 evaluates to `"foo<eol><eol>"`.
+Because of this, it’s usually not a good idea to have multi-line strings ending with EOLs of their own in your template code.
+Moreover, because multi-line strings break indentation, they’re probably not great to have anyway.
 
 Splitting is done on *EOLs of any style*, so this *effectively normalizes* EOLs, meaning that even if multi-line strings use different EOL, `asString` will only use the set EOL style.
 
@@ -207,7 +208,7 @@ Templates **compose** nicely, and predictably, e.g.:
 asString([t1, t2]) === `${asString(t1)}${asString(t2)}`
 ```
 
-The expression `asString([])` evaluates to the empty string, which both satisfies the property above, and is useful as a “nil” template that doesn't result in a new/empty line in the output.
+The expression `asString([])` evaluates to the empty string, which both satisfies the property above, and is useful as a “nil” template that doesn’t result in a new/empty line in the output.
 
 
 ## Package name

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "littoral-templates",
-    "version": "0.4.0-rc.3",
+    "version": "0.4.0",
     "description": "A small JavaScript/TypeScript framework to do templating comfortably using the template literal syntax in either JavaScript or TypeScript.",
     "type": "module",
     "main": "dist/index.js",

package/.editorconfig

@@ -1,9 +0,0 @@
-# Help: https://EditorConfig.org`
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_style = space
-indent_size = 4
-